Clarify the Encoding.GetEncoding(0) and Encoding.Default behavior

[tarekgh]

In .NET Framework, Encoding.Default behaves the same as Encoding.GetEncoding(0), which returns the encoding corresponding to the system’s active code page in Windows.

In .NET (Core and later), this behavior was changed to encourage the use of Unicode encodings for a better experience:

• Encoding.Default always returns UTF-8.

• Encoding.GetEncoding(0) depends on the encoding configuration of the application:

  • No encoding provider registered → returns UTF-8, same as Encoding.Default.

  • CodePageEncodingProvider registered →

    • On Windows, returns the encoding that matches the system’s active code page (same as .NET Framework).
    • On non-Windows platforms, always returns UTF-8.

  • A different provider registered → behavior is determined by that provider. Consult its documentation for details.

We need to add remarks to the following pages to ensure the behavior is clear to all users:

• https://learn.microsoft.com/en-us/dotnet/api/system.text.encoding.getencoding?view=net-9.0#system-text-encoding-getencoding(system-int32)
• https://learn.microsoft.com/en-us/dotnet/api/system.text.encoding.default?view=net-9.0
• https://learn.microsoft.com/en-us/dotnet/api/system.text.encoding.registerprovider?view=net-7.0
• https://learn.microsoft.com/en-us/dotnet/api/system.text.codepagesencodingprovider?view=net-7.0
• https://learn.microsoft.com/en-us/dotnet/api/system.text.codepagesencodingprovider.getencoding?view=net-7.0#system-text-codepagesencodingprovider-getencoding(system-int32)

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-text-encoding