Edit

CultureAndRegionInfoBuilder class

  • Article

This article provides supplementary remarks to the reference documentation for this API.

Note

The CultureAndRegionInfoBuilder class is useful only for Windows operating systems. The generated .nlp files aren't supported on non-Windows operating systems. Also, even on Windows, the generated .nlp files are supported only on .NET Framework (or in .NET Core when using NLS globalization mode).

The CultureInfo class holds culture-specific information, such as the associated language, sublanguage, country/region, calendar, and cultural conventions. This class also provides culture-specific instances of the DateTimeFormatInfo, NumberFormatInfo, CompareInfo, and TextInfo classes, which are required for culture-specific operations such as casing, formatting and parsing dates and numbers, and comparing strings.

By default, .NET supports CultureInfo objects that represent a predefined set of cultures. For a list of these cultures available on Windows systems, see the Language tag column in the list of language/region names supported by Windows. Culture names follow the standard defined by BCP 47. The CultureAndRegionInfoBuilder class enables you to create a custom culture that is completely new or that overrides a predefined culture. When a custom culture is installed and registered on a particular computer, it becomes indistinguishable from predefined CultureInfo objects, and can be instantiated and used just like those objects.

Important

The CultureAndRegionInfoBuilder class is found in an assembly named sysglobl.dll. To successfully compile code that uses this type, you must add a reference to sysglobl.dll.

A custom culture can be registered on a computer only by a user who has administrative rights on that computer. Consequently, apps typically do not create and install custom cultures. Instead, you can use the CultureAndRegionInfoBuilder class to create a special-purpose tool that an administrator can use to create, install, and register a custom culture. After the custom culture is registered on a computer, you can use the CultureInfo class in your app to create instances of the custom culture just as you would for a predefined culture.

If you parse date and time strings generated for a custom culture, you should use the DateTime.ParseExact or DateTime.TryParseExact method instead of the DateTime.Parse or DateTime.TryParse method to improve the probability that the parse operation will succeed. A date and time string for a custom culture can be complicated and therefore difficult to parse. The Parse and TryParse methods try to parse a string with several implicit parse patterns, all of which might fail. The TryParseExact method, in contrast, requires the application to explicitly designate one or more exact parse patterns that are likely to succeed.

Define and create a custom culture

You use the CultureAndRegionInfoBuilder class to define and name a custom culture. The custom culture can be an entirely new culture, a new culture that is based on an existing culture (that is, a supplemental culture), or a culture that replaces an existing .NET culture. In each case, the basic steps are the same:

  1. Instantiate a CultureAndRegionInfoBuilder object by calling its CultureAndRegionInfoBuilder(String, CultureAndRegionModifiers) constructor. To replace an existing culture, pass that culture's name and the CultureAndRegionModifiers.Replacement enumeration value to the constructor. To create a new culture or a supplemental culture, pass a unique culture name and either the CultureAndRegionModifiers.Neutral or CultureAndRegionModifiers.None enumeration value.

    Note

    If you use the CultureAndRegionModifiers.Replacement enumeration value to instantiate a CultureAndRegionInfoBuilder object, the CultureAndRegionInfoBuilder object's properties are automatically populated with values from the CultureInfo object to be replaced.

  2. If you're creating a new or supplemental culture:

  3. Modify the properties of the CultureAndRegionInfoBuilder object as necessary.

  4. If you are planning to register the custom culture in a separate routine, call the Save method. This generates an XML file that you can load and register in a separate custom culture installation routine.

Register a custom culture

If you are developing a registration application for a custom culture that is separate from the application that creates the culture, you call the CreateFromLdml method to load the XML file that contains the custom culture's definition and instantiate the CultureAndRegionInfoBuilder object. To handle the registration, call the Register method. For the registration to succeed, the application that registers the custom culture must be running with administrative privileges on the target system; otherwise, the call to Register throws an UnauthorizedAccessException exception.

Warning

Culture data can differ between systems. If you're using the CultureAndRegionInfoBuilder class to create a custom culture that is uniform across multiple systems and you are creating your custom culture by loading data from existing CultureInfo and RegionInfo objects and customizing it, you should develop two different utilities. The first creates the custom culture and saves it to an XML file. The second uses the CreateFromLdml method to load the custom culture from an XML file and register it on the target computer.

The registration process performs the following tasks:

  • Creates an .nlp file that contains the information that's defined in the CultureAndRegionInfoBuilder object.
  • Stores the .nlp file in the %windir%\Globalization system directory on the target computer. This enables the custom culture's settings to persist between sessions. (The CultureAndRegionInfoBuilder method requires administrative privileges because the .nlp file is stored in a system directory.)
  • Prepares .NET to search the %windir%\Globalization system directory instead of an internal cache the next time there's a request to create your new custom culture.

When a custom culture is successfully registered, it's indistinguishable from the cultures that are predefined by .NET. The custom culture is available until a call to the CultureAndRegionInfoBuilder method removes the .nlp file from the local computer.

Instantiate a custom culture

You can create an instance of the custom culture in one of the following ways:

In addition, the array of CultureInfo objects that is returned by the CultureInfo.GetCultures method includes the custom culture.