[Breaking change]: Renaming the config switch environment variable from CLR_ICU_VERSION_OVERRIDE to DOTNET_ICU_VERSION_OVERRIDE

[tarekgh]

Description

.NET has long supported a configuration switch environment variable called CLR_ICU_VERSION_OVERRIDE, which allows users to specify the preferred ICU library version for apps running on Linux. In .NET, this environment variable has been renamed to DOTNET_ICU_VERSION_OVERRIDE to align with the naming convention of other configuration switch environment variables in .NET.

Version

.NET 10 Preview 1

Previous behavior

The CLR_ICU_VERSION_OVERRIDE environment variable is used to specify the preferred ICU version to be loaded in the application.

New behavior

The DOTNET_ICU_VERSION_OVERRIDE environment variable is used to specify the preferred ICU version to be loaded in the application.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

This change ensures the environment variable is consistent with the naming convention used for all .NET environment variables.

Recommended action

Users running .NET 10 apps who previously used the CLR_ICU_VERSION_OVERRIDE environment variable will now need to use DOTNET_ICU_VERSION_OVERRIDE instead.

Feature area

Globalization

Affected APIs

No response

[jkotas]

We should mention CLR_OPENSSL_VERSION_OVERRIDE -> DOTNET_OPENSSL_VERSION_OVERRIDE rename as well.

[tarekgh]

Thanks for the catch @jkotas

[tarekgh]

@bartonjs could you please provide the breaking change text related to DOTNET_OPENSSL_VERSION_OVERRIDE. I won't mention anything wrong here.

[am11]

Maybe we should add a separate section Loading behavior before or after https://learn.microsoft.com/en-us/dotnet/core/extensions/globalization-icu#macos-behavior. Note that source build skips OpenSSL loading.

I think it should cover:

• When it is applicable: only on unix/windows from non-source build? On source-build DOTNET_OPENSSL_VERSION_OVERRIDE has no effect, because opsnessl shim is not compiled.
• What are all the valid values, e.g. ICU supports a magic value: DOTNET_ICU_VERSION_OVERRIDE=build
• Quirks: DOTNET_ICU_VERSION_OVERRIDE accepts Libressl versions as well (since openssl and libressl are ABI compatible). We used it on Void Linux musl.

It's a tribal knowledge, none of which was ever documented.

[tarekgh]

@am11 This doesn't need to be included in the breaking change documentation. I'll try to update the public documentation when I get a chance—unless you're open to helping with that.

[am11]

This doesn't need to be included in the breaking change documentation.

Without those points, someone installed dotnet from package manager dnf install dotnet-sdk on fedora or apt install dotnet-sdk on ubuntu/debian etc. won't see a difference when setting DOTNET_OPENSSL_VERSION_OVERRIDE e.g.. I think we should document when they are applicable (only Microsoft build, official container or dotnet-install script).

[tarekgh]

@am11 sorry I was talking about DOTNET_ICU_VERSION_OVERRIDE only.