Rediger

Del via


Runtime configuration options for globalization

Invariant mode

  • Determines whether a .NET Core app runs in globalization-invariant mode without access to culture-specific data and behavior.
  • If you omit this setting, the app runs with access to cultural data. This is equivalent to setting the value to false.
  • For more information, see .NET Core globalization invariant mode.
Setting name Values
runtimeconfig.json System.Globalization.Invariant false - access to cultural data
true - run in invariant mode
MSBuild property InvariantGlobalization false - access to cultural data
true - run in invariant mode
Environment variable DOTNET_SYSTEM_GLOBALIZATION_INVARIANT 0 - access to cultural data
1 - run in invariant mode

Examples

runtimeconfig.json file:

{
   "runtimeOptions": {
      "configProperties": {
         "System.Globalization.Invariant": true
      }
   }
}

runtimeconfig.template.json file:

{
   "configProperties": {
      "System.Globalization.Invariant": true
   }
}

Project file:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <InvariantGlobalization>true</InvariantGlobalization>
  </PropertyGroup>

</Project>

Era year ranges

Setting name Values
runtimeconfig.json Switch.System.Globalization.EnforceJapaneseEraYearRanges false - relaxed range checks
true - overflows cause an exception
Environment variable N/A N/A

This configuration setting doesn't have a specific MSBuild property. However, you can add a RuntimeHostConfigurationOption MSBuild item instead. Use the runtimeconfig.json setting name as the value of the Include attribute. For an example, see MSBuild properties.

Japanese date parsing

  • Determines whether a string that contains either "1" or "Gannen" as the year parses successfully or whether only "1" is supported.
  • If you omit this setting, strings that contain either "1" or "Gannen" as the year parse successfully. This is equivalent to setting the value to false.
  • For more information, see Represent dates in calendars with multiple eras.
Setting name Values
runtimeconfig.json Switch.System.Globalization.EnforceLegacyJapaneseDateParsing false - "Gannen" or "1" is supported
true - only "1" is supported
Environment variable N/A N/A

This configuration setting doesn't have a specific MSBuild property. However, you can add a RuntimeHostConfigurationOption MSBuild item instead. Use the runtimeconfig.json setting name as the value of the Include attribute. For an example, see MSBuild properties.

Japanese year format

  • Determines whether the first year of a Japanese calendar era is formatted as "Gannen" or as a number.
  • If you omit this setting, the first year is formatted as "Gannen". This is equivalent to setting the value to false.
  • For more information, see Represent dates in calendars with multiple eras.
Setting name Values
runtimeconfig.json Switch.System.Globalization.FormatJapaneseFirstYearAsANumber false - format as "Gannen"
true - format as number
Environment variable N/A N/A

This configuration setting doesn't have a specific MSBuild property. However, you can add a RuntimeHostConfigurationOption MSBuild item instead. Use the runtimeconfig.json setting name as the value of the Include attribute. For an example, see MSBuild properties.

NLS

  • Determines whether .NET uses National Language Support (NLS) or International Components for Unicode (ICU) globalization APIs for Windows apps. .NET 5 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.
Setting name Values Introduced
runtimeconfig.json System.Globalization.UseNls false - Use ICU globalization APIs
true - Use NLS globalization APIs
.NET 5
Environment variable DOTNET_SYSTEM_GLOBALIZATION_USENLS false - Use ICU globalization APIs
true - Use NLS globalization APIs
.NET 5

This configuration setting doesn't have a specific MSBuild property. However, you can add a RuntimeHostConfigurationOption MSBuild item instead. Use the runtimeconfig.json setting name as the value of the Include attribute. For an example, see MSBuild properties.

Predefined cultures

Setting name Values Introduced
runtimeconfig.json System.Globalization.PredefinedCulturesOnly true - In globalization-invariant mode, don't allow creation of any culture except the invariant culture.
false - Allow creation of any culture.
.NET 6
MSBuild property PredefinedCulturesOnly true - In globalization-invariant mode, don't allow creation of any culture except the invariant culture.
false - Allow creation of any culture.
.NET 6
Environment variable DOTNET_SYSTEM_GLOBALIZATION_PREDEFINED_CULTURES_ONLY true - In globalization-invariant mode, don't allow creation of any culture except the invariant culture.
false - Allow creation of any culture.
.NET 6