CultureAndRegionInfoBuilder Class

Reference

Definition

Namespace:: System.Globalization

Assembly:: sysglobl.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Defines a custom culture that is new or based on another culture and country/region. The custom culture can be installed on a computer and subsequently used by any application that is running on that computer. This class cannot be inherited.

public ref class CultureAndRegionInfoBuilder sealed

[System.Runtime.InteropServices.ComVisible(false)]
public sealed class CultureAndRegionInfoBuilder

[<System.Runtime.InteropServices.ComVisible(false)>]
type CultureAndRegionInfoBuilder = class

Public NotInheritable Class CultureAndRegionInfoBuilder

Inheritance: Object
CultureAndRegionInfoBuilder

Attributes: ComVisibleAttribute

Examples

The following example defines a custom ru-US culture that represents the Russian language in the United States. The example defines the custom culture by loading settings from the Russian (Russia) CultureInfo object and the U.S. RegionInfo object, and then sets a number of CultureAndRegionInfoBuilder properties. The example registers the custom culture, and then instantiates it and makes it the current culture.

using System;
using System.Globalization;
using System.Threading;

public class Example
{
   public static void Main()
   {
      // Create a custom culture for ru-US.
      CultureAndRegionInfoBuilder car1 = new CultureAndRegionInfoBuilder("ru-US",
                                             CultureAndRegionModifiers.None);
      car1.LoadDataFromCultureInfo(CultureInfo.CreateSpecificCulture("ru-RU"));
      car1.LoadDataFromRegionInfo(new RegionInfo("en-US"));

      car1.CultureEnglishName = "Russian (United States)";
      car1.CultureNativeName = "русский (США)";
      car1.CurrencyNativeName = "Доллар (США)";
      car1.RegionNativeName = "США";

      // Register the culture.
      try {
         car1.Register();
      }
      catch (InvalidOperationException) {
         // Swallow the exception: the culture already is registered.
      }

      // Use the custom culture.
      CultureInfo ci = CultureInfo.CreateSpecificCulture("ru-US");
      Thread.CurrentThread.CurrentCulture = ci;
      Console.WriteLine("Current Culture: {0}",
                        Thread.CurrentThread.CurrentCulture.Name);
      Console.WriteLine("Writing System: {0}",
                        Thread.CurrentThread.CurrentCulture.TextInfo);
   }
}
// The example displays the following output:
//     Current Culture: ru-US
//     Writing System: TextInfo - ru-US

Imports System.Globalization
Imports System.Threading

Module Example
   Public Sub Main()
      ' Create a custom culture for ru-US.
      Dim car1 As New CultureAndRegionInfoBuilder("ru-US", CultureAndRegionModifiers.None)
      car1.LoadDataFromCultureInfo(CultureInfo.CreateSpecificCulture("ru-RU"))
      car1.LoadDataFromRegionInfo(New RegionInfo("en-US"))
      
      car1.CultureEnglishName = "Russian (United States)"
      car1.CultureNativeName = "русский (США)"
      car1.CurrencyNativeName = "Доллар (США)"
      car1.RegionNativeName = "США"

      ' Register the culture.
      Try
         car1.Register()
      Catch e As InvalidOperationException
         ' Swallow the exception: the culture already is registered.
      End Try
      
      ' Use the custom culture.
      Dim ci As CultureInfo = CultureInfo.CreateSpecificCulture("ru-US")
      Thread.CurrentThread.CurrentCulture = ci
      Console.WriteLine("Current Culture: {0}", 
                        Thread.CurrentThread.CurrentCulture.Name)
      Console.WriteLine("Writing System: {0}", 
                        Thread.CurrentThread.CurrentCulture.TextInfo)
   End Sub
End Module
' The example displays the following output:
'     Current Culture: ru-US
'     Writing System: TextInfo - ru-US

Remarks

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, the .NET Framework 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

Note that the CultureAndRegionInfoBuilder class is found in an assembly named sysglobl.dll. Successfully compiling code that uses this type requires that you 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.

Defining and Creating 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 Framework culture. In each case, the basic steps are the same:

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.
If you are creating a new or supplemental culture:
- Populate the CultureAndRegionInfoBuilder object's properties by calling the LoadDataFromCultureInfo method and passing a CultureInfo object whose property values are similar to your new object.
- Populate the CultureAndRegionInfoBuilder object's regional properties by calling the LoadDataFromRegionInfo method and passing a RegionInfo object that represents the region of your custom culture.
Modify the properties of the CultureAndRegionInfoBuilder object as necessary.
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.

Registering 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 are 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 is 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 the .NET Framework to search the %windir%\Globalization system directory instead of an internal cache the next time there is a request to create your new custom culture.

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

Instantiating a Custom Culture

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

By invoking the CultureInfo.CultureInfo constructor with the culture name.
By calling the CultureInfo.CreateSpecificCulture method with the culture name.
By calling the CultureInfo.GetCultureInfo method with the culture name.

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

Constructors

CultureAndRegionInfoBuilder(String, CultureAndRegionModifiers)

Initializes a new instance of the CultureAndRegionInfoBuilder class.

Properties

AvailableCalendars	Gets or sets an array of calendars that are supported by this CultureAndRegionInfoBuilder object.
CompareInfo	Gets or sets the CompareInfo object that defines how to compare strings for the culture.
ConsoleFallbackUICulture	Gets or sets an alternate user interface culture suitable for console applications when the default graphic user interface culture is inappropriate.
CultureEnglishName	Gets or sets the culture name in English.
CultureName	Gets the name of the culture being created.
CultureNativeName	Gets or sets the culture name in the format and language that the culture is set to display.
CultureTypes	Gets the CultureTypes value that describes the culture represented by the current CultureAndRegionInfoBuilder object.
CurrencyEnglishName	Gets or sets the name, in English, of the currency used in the country/region represented by the current CultureAndRegionInfoBuilder object.
CurrencyNativeName	Gets or sets the native name of the currency used in the country/region represented by the current CultureAndRegionInfoBuilder object.
GeoId	Gets or sets a unique identification number for a geographical region, country, city, or location.
GregorianDateTimeFormat	Gets or sets a DateTimeFormatInfo object that defines the format of dates and times according to the Gregorian calendar.
IetfLanguageTag	Gets or sets a culture name formatted according to the RFC 4646 standard, "Tags for the Identification of Languages."
IsMetric	Gets or sets a value indicating whether the country/region uses the metric system for measurements.
ISOCurrencySymbol	Gets or sets the three-character ISO 4217 currency symbol associated with the country/region.
IsRightToLeft	Gets or sets the predominant direction of lines of text in the writing system associated with the current CultureAndRegionInfoBuilder object.
KeyboardLayoutId	Gets or sets the active input locale identifier.
LCID	Gets the culture identifier for the current CultureAndRegionInfoBuilder object.
NumberFormat	Gets or sets a NumberFormatInfo object that defines the culturally appropriate format of displaying numbers, currency, and percentage.
Parent	Gets or sets the CultureInfo object that represents the parent culture of the current custom culture.
RegionEnglishName	Gets or sets the full name of the country/region in English.
RegionName	Gets the name of the country/region for the current CultureAndRegionInfoBuilder object.
RegionNativeName	Gets or sets the full name of the country/region as known by the people of this custom culture.
TextInfo	Gets or sets the TextInfo object that defines the writing system associated with this custom culture.
ThreeLetterISOLanguageName	Gets or sets the ISO 639-2 three-letter code for the language of this custom culture.
ThreeLetterISORegionName	Gets or sets the three-letter code defined in ISO 3166 for the country/region.
ThreeLetterWindowsLanguageName	Gets or sets the three-letter code for the language as defined in the Windows API.
ThreeLetterWindowsRegionName	Gets or sets the three-letter code assigned by Windows to the country/region represented by the current custom culture.
TwoLetterISOLanguageName	Gets or sets the ISO 639-1 two-letter code for the language of the current CultureInfo object.
TwoLetterISORegionName	Gets or sets the two-letter code defined in ISO 3166 for the country/region.

Methods

CreateFromLdml(String)	Reconstitutes a CultureAndRegionInfoBuilder object from a specified XML file that contains a representation of the object.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetType()	Gets the Type of the current instance. (Inherited from Object)
LoadDataFromCultureInfo(CultureInfo)	Sets the properties of the current CultureAndRegionInfoBuilder object with the corresponding properties of the specified CultureInfo object.
LoadDataFromRegionInfo(RegionInfo)	Sets the properties of the current CultureAndRegionInfoBuilder object with the corresponding properties of the specified RegionInfo object.
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
Register()	Persists the current CultureAndRegionInfoBuilder object as a custom culture on the local computer and makes that culture available to applications. Requires administrative privileges.
Save(String)	Writes an XML representation of the current CultureAndRegionInfoBuilder object to the specified file.
ToString()	Returns a string that represents the current object. (Inherited from Object)
Unregister(String)	Deletes a custom culture from the local computer.

Applies to