You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/core/extensions/globalization-icu.md
+18-14Lines changed: 18 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -253,18 +253,21 @@ For framework-dependent apps (not self-contained) where ICU is consumed from a l
253
253
254
254
This must be done for all the ICU binaries for the supported runtimes. Also, the `NuGetPackageId` metadata in the `RuntimeTargetsCopyLocalItems` item group needs to match a NuGet package that the project actually references.
255
255
256
-
## Loading Specific ICU Version on Linux
256
+
## Load specific ICU version on Linux
257
257
258
258
By default, when using ICU on Linux, .NET attempts to load the latest installed version of ICU from the system. However, you can specify a specific version of ICU to load by setting the `DOTNET_ICU_VERSION_OVERRIDE` environment variable. Here's how it works:
259
259
260
-
-**Using the Build-Time ICU Version**
261
-
Setting the environment variable to `build` instructs .NET to use the exact ICU version that was utilized during its build process. This version is typically defined in the ICU C header file `unicode/uvernum.h`, generated during ICU's build process. The version is determined by the constant [U_ICU_VERSION_MAJOR_NUM](https://github.com/microsoft/icu/blob/bfb7d6bd5b03d2f5322389d21efee8fd1a167269/icu/icu4c/source/common/unicode/uvernum.h#L56) in the header file.
260
+
-**Use the build-time ICU version**
262
261
263
-
-**Specifying a Custom ICU Version**
264
-
If the environment variable is set to a specific version number, such as `67.1`, .NET will attempt to load that version of ICU. For example, it will look for the libraries `libicuuc.so.67.1` and `libicui18n.so.67.1`.
262
+
When you set the environment variable to `build`, .NET uses the exact ICU version that was used during its build process. This version is typically defined in the ICU C header file `unicode/uvernum.h`, generated during ICU's build process. The version is determined by the constant [U_ICU_VERSION_MAJOR_NUM](https://github.com/microsoft/icu/blob/bfb7d6bd5b03d2f5322389d21efee8fd1a167269/icu/icu4c/source/common/unicode/uvernum.h#L56) in the header file.
265
263
266
-
-**Fallback Mechanism**
267
-
If the specified version is not found, .NET will fall back to loading the highest installed ICU version from the system.
264
+
-**Specify a custom ICU version**
265
+
266
+
If the environment variable is set to a specific version number, such as `67.1`, .NET attempts to load that version of ICU. For example, .NET looks for the libraries `libicuuc.so.67.1` and `libicui18n.so.67.1`.
267
+
268
+
-**Fallback mechanism**
269
+
270
+
If the specified version isn't found, .NET falls back to loading the highest installed ICU version from the system.
268
271
269
272
This configuration provides flexibility in controlling ICU version usage, ensuring compatibility with application-specific or system-provided ICU versions.
270
273
@@ -324,33 +327,34 @@ The following APIs are supported with limitations:
324
327
325
328
In addition, fewer locales are supported. The supported list can be found in the [dotnet/icu repo](https://github.com/dotnet/icu/blob/dotnet/main/icu-filters/icudt_wasm.json#L7-L195).
326
329
327
-
## Globalization Setup in .NET Applications
330
+
## Globalization setup in .NET apps
328
331
329
332
.NET globalization initialization is a complex process that involves loading the appropriate globalization library, setting up the culture data, and configuring the globalization settings. The following sections describe how globalization initialization works on different platforms.
330
333
331
334
### Windows
332
335
333
336
On Windows, .NET follow the following steps to initialize globalization:
337
+
334
338
- Check whether [Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md) is enabled. When this mode is active, .NET bypasses loading the ICU library and avoids using NLS APIs. Instead, it relies on built-in invariant culture data, ensuring that behavior remains fully independent of the operating system and the ICU library.
335
339
336
340
- Check whether [NLS mode](#use-nls-instead-of-icu) is enabled. If enabled, .NET will skip loading the ICU library and instead rely on Windows [NLS](https://learn.microsoft.com/en-us/windows/win32/intl/national-language-support) APIs for globalization support.
337
341
338
342
- Check whether the [app-local ICU](#app-local-icu) feature is enabled. If it is, .NET will attempt to load the ICU library from the application directory by appending the specified version to the library names. For instance, if the version is 72.1, .NET will first try to load `icuuc72.dll`, `icuin72.dll`, and `icudt72.dll`. If these libraries cannot be loaded, it will then attempt to load `icuuc72.1.dll`, `icuin72.1.dll`, and `icudt72.1.dll`. If none of the libraries are found, the process will terminate with an error message such as: `Failed to load app-local ICU: {library name}`.
339
343
340
-
- If none of the preceding conditions are satisfied, .NET will attempt to load the ICU library from the system directory. It first tries to load `icu.dll`. If this library is unavailable, it will then attempt to load `icuuc.dll` and `icuin.dll`from the system directory. If any of these libraries are not found, the runtime will fall back to using NLS APIs for globalization support.
344
+
- If none of the preceding conditions are satisfied, .NET attempts to load the ICU library from the system directory. It first tries to load `icu.dll`. If this library is unavailable, it then attempts to load `icuuc.dll` and `icuin.dll`from the system directory. If any of these libraries aren't found, the runtime falls back to using NLS APIs for globalization support.
341
345
342
346
> [!NOTE]
343
-
> NLS APIs are always available in all Windows versions, so .NET can always rely falling back on them for globalization support.
347
+
> NLS APIs are always available in all Windows versions, so .NET can always fall back on them for globalization support.
344
348
345
349
### Linux
346
350
347
351
- Check whether [Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md) is enabled. When this mode is active, .NET bypasses loading the ICU library. Instead, it relies on built-in invariant culture data, ensuring that behavior remains fully independent of the operating system and the ICU library.
348
-
- Check whether the [app-local ICU](#app-local-icu) feature is enabled. If it is, .NET will attempt to load the ICU library from the application directory by appending the specified version to the library names. For instance, if the version is 68.2.0.9, .NET will try to load `libicuuc.so.68.2.0.9` and `libicui18n.so.68.2.0.9`. If any of the libraries are found, the process will terminate with an error message such as: `Failed to load app-local ICU: {library name}`.
349
-
- Check if the `DOTNET_ICU_VERSION_OVERRIDE` environment variable is set. If it is, .NET will attempt to load the specified version of ICU as desctibed in [Loading Specific ICU Version on Linux](#loading-specific-icu-version-on-linux).
350
-
- If none of the preceding conditions are satisfied, .NET will attempt to load the highest installed version of the ICU library from the system. It try to load the libraries `libicuuc.so.[version]` and `libicui18n.so.[version]` where `[version]` is the highest installed version of ICU on the system. If the libraries are not found, the process will terminate with an error message such as: `Failed to load system ICU: {library name}`.
352
+
- Check whether the [app-local ICU](#app-local-icu) feature is enabled. If it is, .NET will attempt to load the ICU library from the application directory by appending the specified version to the library names. For instance, if the version is 68.2.0.9, .NET will try to load `libicuuc.so.68.2.0.9` and `libicui18n.so.68.2.0.9`. If none of the libraries are found, the process will terminate with an error message such as: `Failed to load app-local ICU: {library name}`.
353
+
- Check if the `DOTNET_ICU_VERSION_OVERRIDE` environment variable is set. If it is, .NET will attempt to load the specified version of ICU as described in [Load specific ICU version on Linux](#load-specific-icu-version-on-linux).
354
+
- If none of the preceding conditions are satisfied, .NET attempts to load the highest installed version of the ICU library from the system. It tries to load the libraries `libicuuc.so.[version]` and `libicui18n.so.[version]`, where `[version]` is the highest installed version of ICU on the system. If the libraries aren't found, the process terminates with an error message such as: `Failed to load system ICU: {library name}`.
351
355
352
356
### macOS
353
357
354
358
- Check whether [Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md) is enabled. When this mode is active, .NET bypasses loading the ICU library. Instead, it relies on built-in invariant culture data, ensuring that behavior remains fully independent of the operating system and the ICU library.
355
-
- Check whether the [app-local ICU](#app-local-icu) feature is enabled. If it is, .NET will attempt to load the ICU library from the application directory by appending the specified version to the library names. For instance, if the version is 68.2.0.9, .NET will try to load `libicuuc68.2.0.9.dylib` and `libicui18n68.2.0.9.dylib`. If any of the libraries are found, the process will terminate with an error message such as: `Failed to load app-local ICU: {library name}`.
359
+
- Check whether the [app-local ICU](#app-local-icu) feature is enabled. If it is, .NET will attempt to load the ICU library from the application directory by appending the specified version to the library names. For instance, if the version is 68.2.0.9, .NET will try to load `libicuuc68.2.0.9.dylib` and `libicui18n68.2.0.9.dylib`. If none of the libraries are found, the process terminates with an error message such as: `Failed to load app-local ICU: {library name}`.
356
360
- If none of the preceding conditions are satisfied, .NET will attempt to load the installed version of the ICU library as described in [macOS behavior](#macos-behavior).
0 commit comments