IdnMapping Class

Reference

Definition

Namespace:: System.Globalization

Assemblies:: mscorlib.dll, System.Globalization.Extensions.dll

Assembly:: System.Runtime.dll

Assembly:: System.Globalization.Extensions.dll

Assembly:: mscorlib.dll

Assembly:: netstandard.dll

Source:: IdnMapping.cs

Source:: IdnMapping.cs

Source:: IdnMapping.cs

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.

Supports the use of non-ASCII characters for Internet domain names. This class cannot be inherited.

public ref class IdnMapping sealed

public sealed class IdnMapping

type IdnMapping = class

Public NotInheritable Class IdnMapping

Inheritance: Object
IdnMapping

Examples

The following example uses the GetAscii(String, Int32, Int32) method to convert an array of internationalized domain names to Punycode. The GetUnicode method then converts the Punycode domain name back to the original domain name, but replaces the original label separators with the standard label separator.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      string[] names = { "bücher.com", "мойдомен.рф", "παράδειγμα.δοκιμή",
                         "mycharity\u3002org",
                         "prose\u0000ware.com", "proseware..com", "a.org",
                         "my_company.com" };
      IdnMapping idn = new IdnMapping();

      foreach (var name in names) {
         try {
            string punyCode = idn.GetAscii(name);
            string name2 = idn.GetUnicode(punyCode);
            Console.WriteLine("{0} --> {1} --> {2}", name, punyCode, name2);
            Console.WriteLine("Original: {0}", ShowCodePoints(name));
            Console.WriteLine("Restored: {0}", ShowCodePoints(name2));
         }
         catch (ArgumentException) {
            Console.WriteLine("{0} is not a valid domain name.", name);
         }
         Console.WriteLine();
      }
   }

   private static string ShowCodePoints(string str1)
   {
      string output = "";
      foreach (var ch in str1)
         output += $"U+{(ushort)ch:X4} ";

      return output;
   }
}
// The example displays the following output:
//    bücher.com --> xn--bcher-kva.com --> bücher.com
//    Original: U+0062 U+00FC U+0063 U+0068 U+0065 U+0072 U+002E U+0063 U+006F U+006D
//    Restored: U+0062 U+00FC U+0063 U+0068 U+0065 U+0072 U+002E U+0063 U+006F U+006D
//
//    мойдомен.рф --> xn--d1acklchcc.xn--p1ai --> мойдомен.рф
//    Original: U+043C U+043E U+0439 U+0434 U+043E U+043C U+0435 U+043D U+002E U+0440 U+0444
//    Restored: U+043C U+043E U+0439 U+0434 U+043E U+043C U+0435 U+043D U+002E U+0440 U+0444
//
//    παράδειγμα.δοκιμή --> xn--hxajbheg2az3al.xn--jxalpdlp --> παράδειγμα.δοκιμή
//    Original: U+03C0 U+03B1 U+03C1 U+03AC U+03B4 U+03B5 U+03B9 U+03B3 U+03BC U+03B1 U+002E U+03B4 U+03BF U+03BA U+03B9 U+03BC U+03AE
//    Restored: U+03C0 U+03B1 U+03C1 U+03AC U+03B4 U+03B5 U+03B9 U+03B3 U+03BC U+03B1 U+002E U+03B4 U+03BF U+03BA U+03B9 U+03BC U+03AE
//
//    mycharity。org --> mycharity.org --> mycharity.org
//    Original: U+006D U+0079 U+0063 U+0068 U+0061 U+0072 U+0069 U+0074 U+0079 U+3002 U+006F U+0072 U+0067
//    Restored: U+006D U+0079 U+0063 U+0068 U+0061 U+0072 U+0069 U+0074 U+0079 U+002E U+006F U+0072 U+0067
//
//    prose ware.com is not a valid domain name.
//
//    proseware..com is not a valid domain name.
//
//    a.org --> a.org --> a.org
//    Original: U+0061 U+002E U+006F U+0072 U+0067
//    Restored: U+0061 U+002E U+006F U+0072 U+0067
//
//    my_company.com --> my_company.com --> my_company.com
//    Original: U+006D U+0079 U+005F U+0063 U+006F U+006D U+0070 U+0061 U+006E U+0079 U+002E U+0063 U+006F U+006D
//    Restored: U+006D U+0079 U+005F U+0063 U+006F U+006D U+0070 U+0061 U+006E U+0079 U+002E U+0063 U+006F U+006D

Imports System.Globalization

Module Example
   Public Sub Main()
      Dim names() As String = { "bücher.com", "мойдомен.рф", "παράδειγμα.δοκιμή",
                                "mycharity" + ChrW(&h3002) + "org",
                                "prose" + ChrW(0) + "ware.com", "proseware..com", "a.org", 
                                "my_company.com" }
      Dim idn As New IdnMapping()
      
      For Each name In names
         Try
            Dim punyCode As String = idn.GetAscii(name)
            Dim name2 As String = idn.GetUnicode(punyCode)
            Console.WriteLine("{0} --> {1} --> {2}", name, punyCode, name2) 
            Console.WriteLine("Original: {0}", ShowCodePoints(name))
            Console.WriteLine("Restored: {0}", ShowCodePoints(name2))
         Catch e As ArgumentException 
            Console.WriteLine("{0} is not a valid domain name.", name)
         End Try
         Console.WriteLine()
      Next   
   End Sub
   
   Private Function ShowCodePoints(str1 As String) As String
      Dim output As String = ""
      For Each ch In str1
         output += String.Format("U+{0} ", Convert.ToUInt16(ch).ToString("X4"))
      Next
      Return output
   End Function
End Module
' The example displays the following output:
'    bücher.com --> xn--bcher-kva.com --> bücher.com
'    Original: U+0062 U+00FC U+0063 U+0068 U+0065 U+0072 U+002E U+0063 U+006F U+006D
'    Restored: U+0062 U+00FC U+0063 U+0068 U+0065 U+0072 U+002E U+0063 U+006F U+006D
'    
'    мойдомен.рф --> xn--d1acklchcc.xn--p1ai --> мойдомен.рф
'    Original: U+043C U+043E U+0439 U+0434 U+043E U+043C U+0435 U+043D U+002E U+0440 U+0444
'    Restored: U+043C U+043E U+0439 U+0434 U+043E U+043C U+0435 U+043D U+002E U+0440 U+0444
'    
'    παράδειγμα.δοκιμή --> xn--hxajbheg2az3al.xn--jxalpdlp --> παράδειγμα.δοκιμή
'    Original: U+03C0 U+03B1 U+03C1 U+03AC U+03B4 U+03B5 U+03B9 U+03B3 U+03BC U+03B1 U+002E U+03B4 U+03BF U+03BA U+03B9 U+03BC U+03AE
'    Restored: U+03C0 U+03B1 U+03C1 U+03AC U+03B4 U+03B5 U+03B9 U+03B3 U+03BC U+03B1 U+002E U+03B4 U+03BF U+03BA U+03B9 U+03BC U+03AE
'    
'    mycharity。org --> mycharity.org --> mycharity.org
'    Original: U+006D U+0079 U+0063 U+0068 U+0061 U+0072 U+0069 U+0074 U+0079 U+3002 U+006F U+0072 U+0067
'    Restored: U+006D U+0079 U+0063 U+0068 U+0061 U+0072 U+0069 U+0074 U+0079 U+002E U+006F U+0072 U+0067
'    
'    prose ware.com is not a valid domain name.
'    
'    proseware..com is not a valid domain name.
'    
'    a.org --> a.org --> a.org
'    Original: U+0061 U+002E U+006F U+0072 U+0067
'    Restored: U+0061 U+002E U+006F U+0072 U+0067
'    
'    my_company.com --> my_company.com --> my_company.com
'    Original: U+006D U+0079 U+005F U+0063 U+006F U+006D U+0070 U+0061 U+006E U+0079 U+002E U+0063 U+006F U+006D
'    Restored: U+006D U+0079 U+005F U+0063 U+006F U+006D U+0070 U+0061 U+006E U+0079 U+002E U+0063 U+006F U+006D

Remarks

An Internet domain name consists of one or more parts, called domain name labels, separated by label separators. For example, the domain name "www.proseware.com" consists of the labels, "www", "proseware", and "com", separated by periods. Standard domain names consist of designated characters in the US-ASCII (or Basic Latin) character range, from U+0021 to U+007E. To facilitate Internet usage in cultures that do not use the US-ASCII character set, the Internationalizing Domain Names in Applications (IDNA) standard was adopted in 2003 to support the inclusion of Unicode characters outside the US-ASCII character range. However, name servers and domain name resolution continue to rely on characters within the US-ASCII character range.

The IDNA mechanism uses Punycode to map an internationalized domain name that contains Unicode characters outside the US-ASCII character range to the US-ASCII character range supported by the domain name system. The IDNA mechanism is used to convert only domain names, not data transmitted over the Internet.

Important

In the .NET Framework 4.5, the IdnMapping class supports different versions of the IDNA standard, depending on the operating system in use:

When run on Windows 8, it supports the 2008 version of the IDNA standard outlined by RFC 5891: Internationalized Domain Names in Applications (IDNA): Protocol.
When run on earlier versions of the Windows operating system, it supports the 2003 version of the standard outlined by RFC 3490: Internationalizing Domain Names in Applications (IDNA).

See Unicode Technical Standard #46: IDNA Compatibility Processing for the differences in the way these standards handle particular sets of characters.

The IdnMapping.GetAscii method normalizes a domain name, converts the normalized name to a representation that consists of displayable Unicode characters in the US-ASCII code point range (U+0020 to U+007E), and prepends an ASCII-compatible encoding (ACE) prefix ("xn--") to each label. The IdnMapping.GetUnicode method restores the domain name labels converted by the GetAscii method.

If the string to be converted includes the label separator characters IDEOGRAPHIC FULL STOP (U+3002), FULLWIDTH FULL STOP (U+FF0E), and HALFWIDTH IDEOGRAPHIC FULL STOP (U+FF61), the GetAscii method converts them to the label separator FULL STOP (period, U+002E). The GetUnicode method, however, does not restore the original label separator character.

Constructors

IdnMapping()

Initializes a new instance of the IdnMapping class.

Properties

AllowUnassigned	Gets or sets a value that indicates whether unassigned Unicode code points are used in operations performed by members of the current IdnMapping object.
UseStd3AsciiRules	Gets or sets a value that indicates whether standard or relaxed naming conventions are used in operations performed by members of the current IdnMapping object.

Methods

Equals(Object)	Indicates whether a specified object and the current IdnMapping object are equal.
GetAscii(String, Int32, Int32)	Encodes the specified number of characters in a substring of domain name labels that include Unicode characters outside the US-ASCII character range. The substring is converted to a string of displayable Unicode characters in the US-ASCII character range and is formatted according to the IDNA standard.
GetAscii(String, Int32)	Encodes a substring of domain name labels that include Unicode characters outside the US-ASCII character range. The substring is converted to a string of displayable Unicode characters in the US-ASCII character range and is formatted according to the IDNA standard.
GetAscii(String)	Encodes a string of domain name labels that consist of Unicode characters to a string of displayable Unicode characters in the US-ASCII character range. The string is formatted according to the IDNA standard.
GetHashCode()	Returns a hash code for this IdnMapping object.
GetType()	Gets the Type of the current instance. (Inherited from Object)
GetUnicode(String, Int32, Int32)	Decodes a substring of a specified length that contains one or more domain name labels, encoded according to the IDNA standard, to a string of Unicode characters.
GetUnicode(String, Int32)	Decodes a substring of one or more domain name labels, encoded according to the IDNA standard, to a string of Unicode characters.
GetUnicode(String)	Decodes a string of one or more domain name labels, encoded according to the IDNA standard, to a string of Unicode characters.
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
ToString()	Returns a string that represents the current object. (Inherited from Object)

Applies to

Thread Safety

All public methods of IdnMapping are thread-safe and may be used concurrently from multiple threads, as long as the IdnMapping instance's properties are not also set concurrently.

Jaa