docs
docs copied to clipboard
dotnet
[Breaking change]: .NET 7 to enable using ICU on Windows Server 2019
Description
Since .NET 5.0, .NET switched using ICU library for globalization support instead of NLS Win32 APIs when running on Windows. This change was applied to Windows 10 clients but was not applied to Windows Server 2019. This breaking change is in .NET 7.0, ICU libraries will be used on Windows Server 2019 by default. The doc .NET globalization and ICU has more information about the globalization behavior difference between ICU and NLS and the expected breaking cases. This doc describe how to revert back to old behavior using NLS if needed too.
Version
.NET 7 RC 1
Previous behavior
When using .NET 5.0 and .NET 6.0 on Windows Server 2019, the globalization support was done by using NLS Win32 APIs.
New behavior
Starting from .NET 7.0 and running on Windows Server 2019, the globalization support by default will be using ICU libraries instead of NLS APIs.
Type of breaking change
- [ ] Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
- [ ] Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.
Reason for change
- .NET introduced some APIs which depend on ICU libraries. TimeZoneInfo.TryConvertIanaIdToWindowsId(String, String) is example of such APIs. Users who want to use such APIs on Windows Server 2019 were required to manually deploy ICU libraries with their binaries using the ICU App Local feature. This was not the best solution for such users because the code can be in a library which cannot control forcing installing the ICU libraries with whatever app or service using such library.
- If Windows Server 2019 is automatically provided by a cloud platform (like Azure), the deployed service not necessarily know is going to run on such server. And the service owner has to manage when to deploy ICU binaries and when not. Also, every service deployed to the cloud using Windows 2019 and want to use the new .NET ICU dependent APIs, will need to deploy the ICU binaries with the service. This can bloat the size on the disk on such server.
- Some users prefer using ICU by default because it is more conforming to the Unicode Standard.
Recommended action
Users using .NET 7.0 on Windows Server 2019 will need to test their apps or services before shipping it to ensure the behavior and not breaking any users. Apps or services want to revert back to the old behavior, they can Use NLS instead of ICU to do that.
Feature area
Globalization
Affected APIs
All Globalization APIs include string comparisons, culture data, date/time/number formatting and parsing, string normalization, and resources lookup.
