.NET Framework

This section describes enhancements to the .NET Framework classes, paying particular attention to the System.Globalization namespace.

New IdnMapping Class

The IdnMapping class provides support for international domain names. See the "International Domain Name Mapping" section of Chapter 6, "Globalization."

String Identifiers for Alternate Sort Orders

Some cultures support more than one solution for sorting data. The .NET Framework 1.1 allows these alternate sort orders to be specified when a new CultureInfo is created by providing the locale ID (LCID), which represents the language, region, and sort order. The following code creates a CultureInfo object for Spanish in Spain using the traditional sort order:

 CultureInfo cultureInfo = new CultureInfo(0x0000040A); 

This is still supported in the .NET Framework 2.0, but the .NET Framework 2.0 supports an alternative solution when the language, region, and sort order can be specified as a string:

 CultureInfo cultureInfo = new CultureInfo("es-ES_tradnl"); 

You can see from this example that the sort order ("TRadnl") is a suffix of the region ("ES"). The sort order can be specified for only alternate sort ordersin other words, you cannot specify the Spanish default International (Modern) sort order using "es-ES-Intl". The complete list of alternate sort order identifiers is listed in the "Alternate Sort Orders" section of Chapter 6.

This enhancement is an important one because it enables developers to support a single data type (i.e., string) for storing and transmitting culture identifiers. Without this enhancement, developers must support both string and integer data types to be able to represent all cultures with all sort orders.

CultureInfo.GetCultures and CultureTypes Enumeration

The CultureTypes enumeration has four new members: FrameworkCultures, ReplacementCultures, UserCustomCulture, and WindowsOnlyCultures, which are used in CultureInfo.GetCultures. See the "CultureInfo.GetCultures and CultureTypes Enumeration" section in Chapter 6.

New CultureInfo Properties

CultureInfo has a new property, IetfLanguageTag, which gets the RFC 3066(bis) standard identification for a language.

New CultureInfo Methods

CultureInfo has a new method called GetCultureInfo, which provides caching support for CultureInfo objects. The first call to CultureInfo.GetCultureInfo creates a CultureInfo method as normal, but subsequent calls for the same CultureInfo get the cached copy. The benefit is better performance. However, all cached cultures are read-only and, more important, do not accept user overrides (accepting user overrides is a recommended practice); if you want to accept user overrides, you should not use this method. CultureInfo has a similar method called GetCultureInfoByIetfLanguageTag that performs the same operation but accepts an IETF language tag instead of a culture name.

String.Compare and StringComparison Enumeration

The String.Compare method has a new overload, String.Compare(string, string, StringComparison), which accepts a StringComparison enumeration. This provides a more convenient way of specifying how a string comparison should be performed instead of having to remember what String.Compare or String.CompareTo overload to call.

New DateTime Properties

DateTime has a new property called Kind, which is a DateTimeKind enumeration. This enables developers to specify whether the DateTime is local time, coordinated universal time (UTC), or unspecified (the default). This is used in conjunction with the new "K" DateTime format specifier, and it provides developers with control over the serialization of dates that include time zones.

New DateTimeFormatInfo Properties

DateTimeFormatInfo has two new properties, AbbreviatedMonthGenitiveNames and MonthGenitiveNames, which surface the names of months when they are used in their genitive form (see the "Genitive Date Support" section in Chapter 6). The .NET Framework 1.1 supports genitive month names but does not expose the names for you to use for your own purposes.

DateTimeFormatInfo also has a new ShortestDayName property, which returns an array of the shortest day names (e.g., "Su", "Mo", "Tu", "We", "Th", "Fr", "Sa").

New DateTime Methods

Two new methods, tryParse and tryParseExact, are siblings of the Parse and ParseExact methods. They enable you to attempt to parse a date without throwing an exception. Both methods return a Boolean indicating the success of the parsing operation.

New Calendars

The .NET Framework 2.0 adds eight new Calendar classes: EastAsianLunisolar-Calendar (abstract), ChineseLunisolarCalendar, JapaneseLunisolar Calendar, KoreanLunisolarCalendar, TaiwanLunisolarCalendar, Jalaali Calendar, PersianCalendar, and UmAlQuraCalendar. See the "Calendars" section in Chapter 6.

New Calendar Properties

Calendar.AlgorithmType is a read-only property that enables you to determine whether the calendar is a solar calendar, a lunar calendar, or both. Calendar.IsReadOnly is a read-only property indicating whether the calendar's properties are read-only.

Calendar.MaxSupportedDateTime and Calendar.MinSupportedDateTime are read-only properties indicating the upper and lower bounds of the calendar.

New Calendar Methods

Calendar.GetLeapMonth returns a month number of the leap month in a given year and, optionally, an era. The month number is 0 if the year does not have a leap month. Calendar.ReadOnly is a static method that returns a read-only calendar object.

New CompareInfo Properties

CompareInfo has a new Name property, which provides a string identifier for the CompareInfo. Typically, this name is the same culture string used to identify a CultureInfo (e.g., "es-ES" for Spanish (Spain) international sort), but for alternate sort orders, this includes the sort suffix (e.g., "es-ES_tradnl" for Spanish (Spain) TRaditional sort).

New CompareInfo Methods

CompareInfo has a new static method, IsSortable, which returns true if a character or string is sortable. A character or string is sortable if all its characters are known to the .NET Framework's sort tables. In this situation, String.Compare compares all characters in the string. However, if a string contains characters that are not known to the .NET Framework's sort tables, String.Compare simply ignores those characters. In this situation, a more accurate test for equality can be achieved using String.CompareOrdinal, which compares the Unicode code points of all characters, regardless of their presence or absence in the .NET Framework's sort tables.

New RegionInfo Properties

RegionInfo has new properties to help with internationalizing currency names: CurrencyEnglishName and CurrencyNativeName. RegionInfo.GeoId is a numeric geographical identifier for the region. It is useful for uniquely identifying a region and also for use with the Win32 GetGeoInfo function. See the "Geographical Information" section in Chapter 6. RegionInfo.NativeName returns the name of the region that is used in that region.

New TextInfo Properties

TextInfo.CultureName returns the name of the culture to which the TextInfo is attached. TextInfo.IsReadOnly indicates whether the TextInfo object is read-only. TextInfo.IsRightToLeft indicates whether the associated language is a right-to-left language (in the .NET Framework 1.1, this is achievable only by hard-coding a known list of right-to-left cultures). TextInfo.LCID is the locale ID of the associated language.

New TextInfo Methods

TextInfo.ReadOnly is a static method that returns a read-only TextInfo object.

New NumberFormatInfo Properties

NumberFormatInfo has two new properties, DigitSubstitution and Native Digits, which provide information about the digit systems used for formatting. DigitSubstitution is a DigitShapes enumeration that is either None, Context, or NativeNational. NativeDigits is an array of strings of the digits used for number formatting. Both properties are purely informational and have no effect in the .NET Framework 2.0. They exist for you to use for your own purposes and in expectation of better support in a future version of the .NET Framework. The following code shows their values for English (United States) and Arabic (Saudi Arabia):

 CultureInfo cultureInfo = new CultureInfo("en-US"); textBox1.Text +=     cultureInfo.NumberFormat.DigitSubstitution.ToString() +     ":- " +     ArrayToString(cultureInfo.NumberFormat.NativeDigits) +     System.Environment.NewLine; cultureInfo = new CultureInfo("ar-SA"); textBox1.Text +=     cultureInfo.NumberFormat.DigitSubstitution.ToString() +     ":- " +     ArrayToString(cultureInfo.NumberFormat.NativeDigits) +     System.Environment.NewLine; 

(ArrayToString is a simple custom method to convert an array to a string.) The result is this:

 None:- 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 Context:  

DigitSubstitution is None for all cultures except for Arabic, Kyrgyz, Mongolian, and Persian-specific cultures.

New ResourceReader Methods

ResourceReader has a new method called GetresourceData, which reads a resource as an array of bytes. The purpose of this method is to allow data of any type to be read from a .resources file. The problem that it solves is that it is not normally possible to read data from a .resources file if the data cannot be deserialized. Typically, data cannot be deserialized if the type is unknown to the application that is deserializing the data. So if one application stores, say, a BusinessObject type in a .resources file and the application reading the file does not have a reference to the assembly containing the BusinessObject type, the attempt to deserialize the BusinessObject will fail. However, the GeTResourceData method allows the data for this resource to be retrieved as an array of bytes. The following example retrieves a resource entry called "String1" from "Form1Resources.resources":

 ResourceReader reader =     new ResourceReader("Form1Resources.resources"); string resourceType; byte[] resourceData; reader.GetResourceData(     "String1", out resourceType, out resourceData); textBox1.Text +=     "ResourceType: " + resourceType + System.Environment.NewLine +     "ResourceData: " +     System.Text.Encoding.UTF8.GetString(resourceData); 

The result is this:

 ResourceType: ResourceTypeCode.String ResourceData: &This is the resource value for String1 

Of course, this particular exercise is unnecessary because the string type can always be deserialized, but it shows the method's behaviour.

New ResXResourceReader Properties

ResXResourceReader has a new property, BasePath, which specifies the path where files referenced in relative file references can be found. ResX file references exist in both the .NET Framework 1.1 and 2.0, and are described in the "ResX File References" section in Chapter 10. Another new property, UseResXDataNodes, is a Boolean value indicating whether the resource entries' values are the simple values that they are in the .NET Framework 1.1 or are ResXDataNode objects. The default is false, so it is compatible with the .NET Framework 1.1. The benefit of the ResXDataNode objects is that they contain comments and file references. See the "ResXDataNodes and Comments" section in Chapter 10.

New ResXResourceReader Methods

ResXResourceReader has a new method called GetMetadataEnumerator. This method returns an enumerator for a resx's metadata. The Form.Localizable property is treated as data in the .NET Framework 1.1 but as metadata in the .NET Framework 2.0. The GetMetaDataEnumerator method provides a means by which these metadata values can be retrieved. See the "ResX Changes Break Code That Uses ResXResourceReader" section of this appendix for more details.

New ResXResourceWriter Methods

ResXResourceWriter has a new method called AddAlias, which adds an assembly alias to the resx file. After ResXResourceWriter.Generate is called, the resx file contains a corresponding assembly element:

 <assembly alias="System.Windows.Forms" name="System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" /> 

Subsequent entries in the resx file need to refer to only the alias instead of the full assembly name:

 <data name="button1.ImeMode" type="System.Windows.Forms.ImeMode, System.Windows.Forms">   <value>NoControl</value> </data> 

The result is a smaller resx file.

In addition, ResXResourceWriter has a new method called AddMetadata, which adds metadata entries to a resx file. Such entries are intended to be used for design-time properties such as Form.Localizable. Metadata entries are read using the new ResXResourceReader.GetMetadataEnumerator method.

New String and StringInfo Methods

String has two new methods, Normalize and IsNormalized, which are used to normalize strings. The problem that they solve comes from the fact that some Unicode characters can be represented in more than one way (by using several combined Uni-code characters). The binary representations are different, but the characters that they represent are the same. If their binary representations were compared, they would appear to be different, even though they result in the same character. Unicode supports a concept called normalization that resolves these representations to a simpler form, and the Normalize and IsNormalized methods implement this process.

The String and StringInfo classes also have a new property, LengthInText-Elements, and a method, SubstringByTextElements, which together enable you to process strings in terms of their text elements instead of their characters. Many scripts (e.g., Japanese Hiragana) combine characters to form text elements, and it is often meaningless to process individual characters in such scripts.

The String.Compare method has several new overloads that accept a new StringComparison enumeration that simplifies string comparisons. For example, calling String.Compare with the StringComparison.Ordinal value is the same as calling String.CompareOrdinal. Microsoft now recommends using ordinal comparisons for culture-insensitive comparisons. See the "Sort Orders" section of Chapter 6 for more details on ordinal comparisons.

New CharUnicodeInfo Class

The .NET Framework 2.0 introduces a new class, CharUnicodeInfo, which provides information about a Unicode character. The information is drawn from the Unicode Character Database for Unicode 4.1. It has four static methods (GetdecimalDigitValue, GeTDigitValue, GetNumericValue, and GetUnicodeCate-gory) to retrieve various kinds of information about a character. Putting aside the 0 to 9 digits that we already know about, Unicode defines numerous code points for characters that have a numeric meaning. For example, the Unicode character ½ (U+00BD) is one half, so CharUnicodeInfo.GetNumericValue returns 0.5 for this character. A similar effect is true for Roman numerals (e.g.,"I" is 1), Tamil characters (e.g., U+0BF2 is 1000), and Tibetan characters (e.g., U+0F32 is half nine).

resx Files and File References

resx files in both the .NET Framework 1.1 and 2.0 support file references. This means that a file can be referred to instead of being embedded in the resx file. The resulting resource in the resource assembly is exactly the same as for a resource that is embedded, however, so this is simply a development issue. The important point here is that file references are now the default for the Visual Studio 2005 Resource Editor, so any file that you add to a resource, by default, simply has a reference to the file. A copy of the file is added to a local Resources folder (in a Windows Forms application) or the App_ GlobalResources or App_LocalResources folder (in an ASP.NET application), and the reference is to the file in this folder instead of the original file. In addition, the file reference is a relative reference instead of an absolute reference.

New ResourceManager Methods

ResourceManager has a new method called GetStream, which returns an UnmanagedMemoryStream for a resource given the name of that resource. The method is not CLS compliant.

Customizing the Fallback Process

The .NET Framework 2.0 enables you to specify that the location of the fallback resources is a satellite assembly. In the .NET Framework 1.1, the only choice was that fallback resources were in the invariant or fallback assembly. The downside to this approach is that there is no separation between resources and code. See the "NeutralResourcesLanguageAttribute and UltimateResourceFallback Location" section in Chapter 3, "An Introduction to Internationalization."

ResView and ResExtract (Managed Resource Viewer)

The Base Class Library Samples includes two new utilities for manipulating resources, which are collectively referred to as the Managed Resource Viewer. Although they are not specific to the .NET Framework 2.0, they were released during the same time period, so I have included them in this appendix. ResView is a resource viewer, and ResExtract exTRacts resources from a resource assembly. See http://msdn.microsoft.com/netframework/downloads/samples/bclsamples/ for more details.