Add globalization API breaking change (dotnet#18492)

* fixes dotnet#18423 Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com>
brook-source · May 19, 2020 · 57ac4c9 · 57ac4c9
1 parent b6c79b5
commit 57ac4c9
Show file tree

Hide file tree

Showing 4 changed files with 64 additions and 1 deletion.
diff --git a/docs/core/compatibility/3.1-5.0.md b/docs/core/compatibility/3.1-5.0.md
@@ -66,11 +66,16 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v
 ## Globalization
 
 - [StringInfo and TextElementEnumerator are now UAX29-compliant](#stringinfo-and-textelementenumerator-are-now-uax29-compliant)
+- [Globalization APIs use ICU libraries on Windows](#globalization-apis-use-icu-libraries-on-windows)
 
 [!INCLUDE [uax29-compliant-grapheme-enumeration](../../../includes/core-changes/globalization/5.0/uax29-compliant-grapheme-enumeration.md)]
 
 ***
 
+[!INCLUDE [icu-globalization-api](../../../includes/core-changes/globalization/5.0/icu-globalization-api.md)]
+
+***
+
 ## Windows Forms
 
 - [Removed status bar controls](#removed-status-bar-controls)

diff --git a/docs/core/compatibility/globalization.md b/docs/core/compatibility/globalization.md
@@ -9,11 +9,16 @@ The following breaking changes are documented on this page:
 
 | Breaking change | Version introduced |
 | - | :-: |
+| [Globalization APIs use ICU libraries on Windows](#globalization-apis-use-icu-libraries-on-windows) | 5.0 |
 | [StringInfo and TextElementEnumerator are now UAX29-compliant](#stringinfo-and-textelementenumerator-are-now-uax29-compliant) | 5.0 |
 | ["C" locale maps to the invariant locale](#c-locale-maps-to-the-invariant-locale) | 3.0 |
 
 ## .NET 5.0
 
+[!INCLUDE [icu-globalization-api](../../../includes/core-changes/globalization/5.0/icu-globalization-api.md)]
+
+***
+
 [!INCLUDE [uax29-compliant-grapheme-enumeration](../../../includes/core-changes/globalization/5.0/uax29-compliant-grapheme-enumeration.md)]
 
 ***

diff --git a/docs/core/run-time-config/globalization.md b/docs/core/run-time-config/globalization.md
@@ -1,7 +1,7 @@
 ---
 title: Globalization config settings
 description: Learn about run-time settings that configure globalization aspects of a .NET Core app, for example, how it parses Japanese dates.
-ms.date: 11/27/2019
+ms.date: 05/18/2020
 ms.topic: reference
 ---
 # Run-time configuration options for globalization
@@ -76,3 +76,14 @@ Project file:
 | - | - | - |
 | **runtimeconfig.json** | `Switch.System.Globalization.FormatJapaneseFirstYearAsANumber` | `false` - format as "Gannen"<br/>`true` - format as number |
 | **Environment variable** | N/A | N/A |
+
+## NLS
+
+- Determines whether .NET uses National Language Support (NLS) or International Components for Unicode (ICU) globalization APIs for Windows apps. .NET 5.0 and later versions use ICU globalization APIs by default on Windows 10 May 2019 Update and later versions.
+- If you omit this setting, .NET uses ICU globalization APIs by default. This is equivalent to setting the value to `false`.
+- For more information, see [Globalization APIs use ICU libraries on Windows](../compatibility/3.1-5.0.md#globalization-apis-use-icu-libraries-on-windows).
+
+| | Setting name | Values | Introduced |
+| - | - | - | - |
+| **runtimeconfig.json** | `System.Globalization.UseNls` | `false` - Use ICU globalization APIs<br/>`true` - Use NLS globalization APIs | .NET 5.0 |
+| **Environment variable** | `DOTNET_SYSTEM_GLOBALIZATION_USENLS` | `false` - Use ICU globalization APIs<br/>`true` - Use NLS globalization APIs | .NET 5.0 |
diff --git a/includes/core-changes/globalization/5.0/icu-globalization-api.md b/includes/core-changes/globalization/5.0/icu-globalization-api.md
@@ -0,0 +1,42 @@
+### Globalization APIs use ICU libraries on Windows
+
+.NET 5.0 and later versions use [International Components for Unicode (ICU)](http://site.icu-project.org/home) libraries for globalization functionality when running on Windows 10 May 2019 Update or later.
+
+#### Change description
+
+Previously, .NET libraries used [National Language Support (NLS)](/windows/win32/intl/national-language-support) APIs for globalization functionality. For example, NLS functions were used to get culture data, such as date and time format patterns, compare strings, and perform string casing in the appropriate culture.
+
+Starting in .NET 5.0, if an app is running on Windows 10 May 2019 Update or later, .NET libraries use [ICU](http://site.icu-project.org/home) globalization APIs. Windows 10 May 2019 Update and later versions ship with the ICU native library. If the .NET runtime can't load ICU, it uses NLS instead.
+
+This change was introduced for two reasons:
+
+- Apps have the same globalization behavior across platforms, including Linux, macOS, and Windows.
+- Apps can control globalization behavior by using custom ICU libraries.
+
+#### Version introduced
+
+.NET 5.0 Preview 4
+
+#### Recommended action
+
+No action is required on the part of the developer. However, if you wish to continue using NLS globalization APIs, you can set a [run-time switch](../../../../docs/core/run-time-config/globalization.md#nls) to revert to that behavior.
+
+#### Category
+
+Globalization
+
+#### Affected APIs
+
+- <xref:System.Span%601?displayProperty=fullName>
+- <xref:System.String?displayProperty=fullName>
+- Most types in the <xref:System.Globalization?displayProperty=fullName> namespace
+
+<!--
+
+#### Affected APIs
+
+- `T:System.Span%601`
+- `T:System.String`
+- `N:System.Globalization`
+
+-->