.NET Framework Class Library
CultureAndRegionInfoBuilder Class

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.

Inheritance Hierarchy
SystemObject
  System.GlobalizationCultureAndRegionInfoBuilder

Namespace:   System.Globalization
Assembly:  sysglobl (in sysglobl.dll)
Syntax
<[%$TOPIC/b08z9aad_en-us_VS_110_2_0_0_0_0%](False)> _
Public NotInheritable Class CultureAndRegionInfoBuilder
[[%$TOPIC/b08z9aad_en-us_VS_110_2_0_1_0_0%](false)]
public sealed class CultureAndRegionInfoBuilder
[[%$TOPIC/b08z9aad_en-us_VS_110_2_0_2_0_0%](false)]
public ref class CultureAndRegionInfoBuilder sealed
[<[%$TOPIC/b08z9aad_en-us_VS_110_2_0_3_0_0%]>]
[<[%$TOPIC/b08z9aad_en-us_VS_110_2_0_3_0_1%](false)>]
type CultureAndRegionInfoBuilder =  class end
public final class CultureAndRegionInfoBuilder

The CultureAndRegionInfoBuilder type exposes the following members.

Constructors
  NameDescription
Public method CultureAndRegionInfoBuilderInitializes a new instance of the CultureAndRegionInfoBuilder class.
Top
Properties
  NameDescription
Public property AvailableCalendarsGets or sets an array of calendars that are supported by this CultureAndRegionInfoBuilder object.
Public property CompareInfoGets or sets the CompareInfo object that defines how to compare strings for the culture.
Public property ConsoleFallbackUICultureGets or sets an alternate user interface culture suitable for console applications when the default graphic user interface culture is inappropriate.
Public property CultureEnglishNameGets or sets the culture name in English.
Public property CultureNameGets the name of the culture being created.
Public property CultureNativeNameGets or sets the culture name in the format and language that the culture is set to display.
Public property CultureTypesGets the CultureTypes value that describes the culture represented by the current CultureAndRegionInfoBuilder object.
Public property CurrencyEnglishNameGets or sets the name, in English, of the currency used in the country/region represented by the current CultureAndRegionInfoBuilder object.
Public property CurrencyNativeNameGets or sets the native name of the currency used in the country/region represented by the current CultureAndRegionInfoBuilder object.
Public property GeoIdGets or sets a unique identification number for a geographical region, country, city, or location.
Public property GregorianDateTimeFormatGets or sets a DateTimeFormatInfo object that defines the format of dates and times according to the Gregorian calendar.
Public property IetfLanguageTagGets or sets a culture name formatted according to the RFC 4646 standard, "Tags for the Identification of Languages."
Public property IsMetricGets or sets a value indicating whether the country/region uses the metric system for measurements.
Public property ISOCurrencySymbolGets or sets the three-character ISO 4217 currency symbol associated with the country/region.
Public property IsRightToLeftGets or sets the predominant direction of lines of text in the writing system associated with the current CultureAndRegionInfoBuilder object.
Public property KeyboardLayoutIdGets or sets the active input locale identifier.
Public property LCIDGets the culture identifier for the current CultureAndRegionInfoBuilder object.
Public property NumberFormatGets or sets a NumberFormatInfo object that defines the culturally appropriate format of displaying numbers, currency, and percentage.
Public property ParentGets or sets the CultureInfo object that represents the parent culture of the current custom culture.
Public property RegionEnglishNameGets or sets the full name of the country/region in English.
Public property RegionNameGets the name of the country/region for the current CultureAndRegionInfoBuilder object.
Public property RegionNativeNameGets or sets the full name of the country/region as known by the people of this custom culture.
Public property TextInfoGets or sets the TextInfo object that defines the writing system associated with this custom culture.
Public property ThreeLetterISOLanguageNameGets or sets the ISO 639-2 three-letter code for the language of this custom culture.
Public property ThreeLetterISORegionNameGets or sets the three-letter code defined in ISO 3166 for the country/region.
Public property ThreeLetterWindowsLanguageNameGets or sets the three-letter code for the language as defined in the Windows API.
Public property ThreeLetterWindowsRegionNameGets or sets the three-letter code assigned by Windows to the country/region represented by the current custom culture.
Public property TwoLetterISOLanguageNameGets or sets the ISO 639-1 two-letter code for the language of the current CultureInfo object.
Public property TwoLetterISORegionNameGets or sets the two-letter code defined in ISO 3166 for the country/region.
Top
Methods
  NameDescription
Public method Static member CreateFromLdmlReconstitutes a CultureAndRegionInfoBuilder object from a specified XML file that contains a representation of the object.
Public method Equals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Public method GetHashCodeServes as the default hash function. (Inherited from Object.)
Public method GetTypeGets the Type of the current instance. (Inherited from Object.)
Public method LoadDataFromCultureInfoSets the properties of the current CultureAndRegionInfoBuilder object with the corresponding properties of the specified CultureInfo object.
Public method LoadDataFromRegionInfoSets the properties of the current CultureAndRegionInfoBuilder object with the corresponding properties of the specified RegionInfo object.
Public method RegisterPersists the current CultureAndRegionInfoBuilder object as a custom culture on the local computer and makes that culture available to applications. Requires administrative privileges.
Public method SaveWrites an XML representation of the current CultureAndRegionInfoBuilder object to the specified file.
Public method ToStringReturns a string that represents the current object. (Inherited from Object.)
Public method Static member UnregisterDeletes a custom culture from the local computer.
Top
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, see the National Language Support (NLS) API Reference at the Go Global Developer Center. 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 noteImportant

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 DateTimeParseExact or DateTimeTryParseExact method instead of the DateTimeParse or DateTimeTryParse 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:

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

    NoteNote

    If you use the CultureAndRegionModifiersReplacement 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 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.

  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.

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.

Caution noteCaution

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:

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

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 thread culture.

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
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
Version Information

.NET Framework

Supported in: 4.6, 4.5, 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.