Export (0) Print
Expand All
1 out of 1 rated this helpful - Rate this topic

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.

System.Object
  System.Globalization.CultureAndRegionInfoBuilder

Namespace:  System.Globalization
Assembly:  sysglobl (in sysglobl.dll)
[ComVisibleAttribute(false)]
public sealed class CultureAndRegionInfoBuilder

The CultureAndRegionInfoBuilder type exposes the following members.

  NameDescription
Public methodCultureAndRegionInfoBuilderInitializes a new instance of the CultureAndRegionInfoBuilder class.
Top
  NameDescription
Public propertyAvailableCalendarsGets or sets an array of calendars that are supported by this CultureAndRegionInfoBuilder object.
Public propertyCompareInfoGets or sets the CompareInfo object that defines how to compare strings for the culture.
Public propertyConsoleFallbackUICultureGets or sets an alternate user interface culture suitable for console applications when the default graphic user interface culture is inappropriate.
Public propertyCultureEnglishNameGets or sets the culture name in English.
Public propertyCultureNameGets the name of the culture being created.
Public propertyCultureNativeNameGets or sets the culture name in the format and language that the culture is set to display.
Public propertyCultureTypesGets the CultureTypes value that describes the culture represented by the current CultureAndRegionInfoBuilder object.
Public propertyCurrencyEnglishNameGets or sets the name, in English, of the currency used in the country/region represented by the current CultureAndRegionInfoBuilder object.
Public propertyCurrencyNativeNameGets or sets the native name of the currency used in the country/region represented by the current CultureAndRegionInfoBuilder object.
Public propertyGeoIdGets or sets a unique identification number for a geographical region, country, city, or location.
Public propertyGregorianDateTimeFormatGets or sets a DateTimeFormatInfo object that defines the format of dates and times according to the Gregorian calendar.
Public propertyIetfLanguageTagGets or sets a culture name formatted according to the RFC 4646 standard, "Tags for the Identification of Languages."
Public propertyIsMetricGets or sets a value indicating whether the country/region uses the metric system for measurements.
Public propertyISOCurrencySymbolGets or sets the three-character ISO 4217 currency symbol associated with the country/region.
Public propertyIsRightToLeftGets or sets the predominant direction of lines of text in the writing system associated with the current CultureAndRegionInfoBuilder object.
Public propertyKeyboardLayoutIdGets or sets the active input locale identifier.
Public propertyLCIDGets the culture identifier for the current CultureAndRegionInfoBuilder object.
Public propertyNumberFormatGets or sets a NumberFormatInfo object that defines the culturally appropriate format of displaying numbers, currency, and percentage.
Public propertyParentGets or sets the CultureInfo object that represents the parent culture of the current custom culture.
Public propertyRegionEnglishNameGets or sets the full name of the country/region in English.
Public propertyRegionNameGets the name of the country/region for the current CultureAndRegionInfoBuilder object.
Public propertyRegionNativeNameGets or sets the full name of the country/region as known by the people of this custom culture.
Public propertyTextInfoGets or sets the TextInfo object that defines the writing system associated with this custom culture.
Public propertyThreeLetterISOLanguageNameGets or sets the ISO 639-2 three-letter code for the language of this custom culture.
Public propertyThreeLetterISORegionNameGets or sets the three-letter code defined in ISO 3166 for the country/region.
Public propertyThreeLetterWindowsLanguageNameGets or sets the three-letter code for the language as defined in the Windows API.
Public propertyThreeLetterWindowsRegionNameGets or sets the three-letter code assigned by Windows to the country/region represented by the current custom culture.
Public propertyTwoLetterISOLanguageNameGets or sets the ISO 639-1 two-letter code for the language of the current CultureInfo object.
Public propertyTwoLetterISORegionNameGets or sets the two-letter code defined in ISO 3166 for the country/region.
Top
  NameDescription
Public methodStatic memberCreateFromLdmlReconstitutes a CultureAndRegionInfoBuilder object from a specified XML file that contains a representation of the object.
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodLoadDataFromCultureInfoSets the properties of the current CultureAndRegionInfoBuilder object with the corresponding properties of the specified CultureInfo object.
Public methodLoadDataFromRegionInfoSets the properties of the current CultureAndRegionInfoBuilder object with the corresponding properties of the specified RegionInfo object.
Public methodRegisterPersists the current CultureAndRegionInfoBuilder object as a custom culture on the local computer and makes that culture available to applications. Requires administrative privileges.
Public methodSaveWrites an XML representation of the current CultureAndRegionInfoBuilder object to the specified file.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Public methodStatic memberUnregisterDeletes a custom culture from the local computer.
Top

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.

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:

  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.

    NoteNote

    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 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 CultureInfo.GetCultures method includes the custom culture.

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.

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

.NET Framework

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

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.