Skip to content

Commit

Permalink
Add day of week abbreviation difference (dotnet#41833)
Browse files Browse the repository at this point in the history
  • Loading branch information
gewarren authored and Evangelink committed Jul 24, 2024
1 parent a603d0b commit 7df4dc1
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 10 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,13 @@ string text = string.Format("{0:C}", 100);
- In .NET Core 3.1 and earlier versions on Windows, the value of text is `"100,00 €"`.
- In .NET 5 and later versions on Windows 19H1 and later versions, the value of text is `"100,00 ¤"`, which uses the international currency symbol instead of the euro. In ICU, the design is that a currency is a property of a country or region, not a language.

### Day-of-week abbreviations

The <xref:System.Globalization.DateTimeFormatInfo.GetShortestDayName(System.DayOfWeek)?displayProperty=nameWithType> method obtains the shortest abbreviated day name for a specified day of the week.

- In .NET Core 3.1 and earlier versions on Windows, these day-of-week abbreviations consisted of two characters, for example, "Su".
- In .NET 5 and later versions, these day-of-week abbreviations consist of only one character, for example, "S".

## Reason for change

This change was introduced to unify .NET's globalization behavior across all supported operating systems. It also provides the ability for applications to bundle their own globalization libraries rather than depend on the operating system's built-in libraries.
Expand Down
27 changes: 17 additions & 10 deletions docs/core/extensions/globalization-icu.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,12 @@ Windows now incorporates a preinstalled [icu.dll](/windows/win32/intl/internatio

The following table shows which versions of .NET are capable of loading the ICU library across different Windows client and server versions:

.NET version| Windows version
---|---
.NET 5 or .NET 6|Windows client 10 version 1903 or later
.NET 5 or .NET 6|Windows Server 2022 or later
.NET 7 or later|Windows client 10 version 1703 or later
.NET 7 or later|Windows Server 2019 or later
| .NET version | Windows version |
|------------------|-----------------------------------------|
| .NET 5 or .NET 6 | Windows client 10 version 1903 or later |
| .NET 5 or .NET 6 | Windows Server 2022 or later |
| .NET 7 or later | Windows client 10 version 1703 or later |
| .NET 7 or later | Windows Server 2019 or later |

> [!NOTE]
> .NET 7 and later versions have the capability to load ICU on older Windows versions, in contrast to .NET 6 and .NET 5.
Expand Down Expand Up @@ -120,26 +120,33 @@ Console.WriteLine(foo.StartsWith('\0'));
> False
> ```
To avoid this behavior, use the `char` parameter overload or `StringComparison.Oridinal`.
To avoid this behavior, use the `char` parameter overload or `StringComparison.Ordinal`.

#### TimeZoneInfo.FindSystemTimeZoneById

ICU provides the flexibility to create <xref:System.TimeZoneInfo> instances using [IANA](https://www.iana.org/time-zones) time zone IDs, even when the application is running on Windows. Similarly, you can create <xref:System.TimeZoneInfo> instances with Windows time zone IDs, even when running on non-Windows platforms. However, it's important to note that this functionality isn't available when using [NLS mode](#use-nls-instead-of-icu) or [globalization invariant mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md).

#### ICU dependent APIs
#### Day-of-week abbreviations

The <xref:System.Globalization.DateTimeFormatInfo.GetShortestDayName(System.DayOfWeek)?displayProperty=nameWithType> method obtains the shortest abbreviated day name for a specified day of the week.

- In .NET Core 3.1 and earlier versions on Windows, these day-of-week abbreviations consisted of two characters, for example, "Su".
- In .NET 5 and later versions, these day-of-week abbreviations consist of only one character, for example, "S".

#### ICU-dependent APIs

.NET introduced APIs that are dependent on ICU. These APIs can succeed only when using ICU. Here are some examples:

- <xref:System.TimeZoneInfo.TryConvertIanaIdToWindowsId(System.String,System.String@)>
- <xref:System.TimeZoneInfo.TryConvertWindowsIdToIanaId%2A>

On the Windows versions listed in the [ICU on Windows](#icu-on-windows) section table, the mentioned APIs will consistently succeed. However, on older versions of Windows, these APIs will consistently fail. In such cases, you can enable the [app-local ICU](#app-local-icu) feature to ensure the success of these APIs. On non-Windows platforms, these APIs will always succeed regardless of the version.
On the Windows versions listed in the [ICU on Windows](#icu-on-windows) section table, the mentioned APIs succeed. However, on older versions of Windows, these APIs fail. In such cases, you can enable the [app-local ICU](#app-local-icu) feature to ensure the success of these APIs. On non-Windows platforms, these APIs always succeed regardless of the version.

In addition, it's crucial for apps to ensure that they're not running in [globalization invariant mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md) or [NLS mode](#use-nls-instead-of-icu) to guarantee the success of these APIs.

### Use NLS instead of ICU

Using ICU instead of NLS might result in behavioral differences with some globalization-related operations. To revert back to using NLS, a developer can opt out of the ICU implementation. Applications can enable NLS mode in any of the following ways:
Using ICU instead of NLS might result in behavioral differences with some globalization-related operations. To revert back to using NLS, you can opt out of the ICU implementation. Applications can enable NLS mode in any of the following ways:

- In the project file:

Expand Down

0 comments on commit 7df4dc1

Please sign in to comment.