Uri.DnsSafeHost Property

Definition

Namespace:

System

Assembly:

System.Runtime.dll

Source:

Uri.cs

Gets a host name that, after being unescaped if necessary, is safe to use for DNS resolution.

public:
 property System::String ^ DnsSafeHost { System::String ^ get(); };

public string DnsSafeHost { get; }

member this.DnsSafeHost : string

Public ReadOnly Property DnsSafeHost As String

Property Value

String

The host part of the URI in a format suitable for DNS resolution; or the original host string, if it is already suitable for resolution.

Exceptions

InvalidOperationException

This instance represents a relative URI, and this property is valid only for absolute URIs.

Examples

The following example creates a Uri instance from a string. It illustrates the difference between the value returned from Host, which returns the host name or address specified in the URI, and the value returned from DnsSafeHost, which returns an address that is safe to use in DNS resolution.

// Create new Uri using a string address.         
Uri^ address = gcnew Uri( "http://[fe80::200:39ff:fe36:1a2d%254]/temp/example.htm" );

// Make the address DNS safe. 
// The following outputs "[fe80::200:39ff:fe36:1a2d]".
Console::WriteLine( address->Host );

// The following outputs "fe80::200:39ff:fe36:1a2d%254".
Console::WriteLine( address->DnsSafeHost );

// Create new Uri using a string address.
Uri address = new Uri("http://[fe80::200:39ff:fe36:1a2d%254]/temp/example.htm");

// Make the address DNS safe.

// The following outputs "[fe80::200:39ff:fe36:1a2d]".
Console.WriteLine(address.Host);

// The following outputs "fe80::200:39ff:fe36:1a2d%254".
Console.WriteLine(address.DnsSafeHost);

// Create new Uri using a string address.
let address = Uri "http://[fe80::200:39ff:fe36:1a2d%254]/temp/example.htm"

// Make the address DNS safe.

// The following outputs "[fe80::200:39ff:fe36:1a2d]".
printfn $"{address.Host}"

// The following outputs "fe80::200:39ff:fe36:1a2d%254".
printfn $"{address.DnsSafeHost}"

    ' Create new Uri using a string address.         
    Dim address As New Uri("http://[fe80::200:39ff:fe36:1a2d%254]/temp/example.htm")
    
    ' Make the address DNS safe. 
    ' The following outputs "[fe80::200:39ff:fe36:1a2d]".
    Console.WriteLine(address.Host)
    
    ' The following outputs "fe80::200:39ff:fe36:1a2d%254".
    Console.WriteLine(address.DnsSafeHost)

End Sub

As explained in Remarks, unescape the host name before resolving it. You can use the UnescapeDataString method to unescape the host name, and you can resolve it by calling the GetHostEntry method.

Remarks

For IPv6 addresses, the brackets ([]) are removed and the ScopeId property is set, if one was specified when this instance was constructed.

If you used an escaped string to construct this instance (for example, "http://[fe80::200:39ff:fe36:1a2d%254]/temp/example.htm"), then DnsSafeHost returns an escaped string. Unescape any escaped string returned from DnsSafeHost before using that string for DNS resolution (see the Example). If you used an invalid unescaped string to construct this instance (for example, "http://[fe80::200:39ff:fe36:1a2d%4]/temp/example.htm"), then DnsSafeHost returns an unescaped string.

The DnsSafeHost property is dependent on configuration settings in .NET Framework apps, as discussed later in this topic. The IdnHost property is provided as the preferred alternative to using DnsSafeHost, because IdnHost is guaranteed to always be DNS safe.

The DnsSafeHost property was extended in .NET Framework v3.5, 3.0 SP1, and 2.0 SP1 to provide International Resource Identifier (IRI) support based on RFC 3987. However, to ensure application compatibility with prior versions, you must specifically enable it in .NET Framework apps. To enable support for IRI, the following two changes are required:

1. Add the following line to the machine.config file under the .NET Framework 2.0 directory:

   \<section name="uri" type="System.Configuration.UriSection, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />

2. Specify whether you want Internationalized Domain Name (IDN) parsing applied to the domain name and whether IRI parsing rules should be applied. This can be done in the machine.config or in the app.config file. For example, add the following:

   <configuration>
     <uri>
       <idn enabled="All" />
       <iriParsing enabled="true" />
     </uri>
   </configuration>
   

Enabling IDN converts all Unicode labels in a domain name to their Punycode equivalents. Punycode names contain only ASCII characters and always start with the xn-- prefix. The reason for this is to support existing DNS servers on the Internet, since most DNS servers only support ASCII characters (see RFC 3940).

Enabling IDN only affects the value of the DnsSafeHost property.

There are three possible values for IDN depending on the DNS servers that are used:

• idn enabled = All

  This value will convert any Unicode domain names to their Punycode equivalents (IDN names).

• idn enabled = AllExceptIntranet

  This value will convert all external Unicode domain names to use the Punycode equivalents (IDN names). In this case to handle international names on the local Intranet, the DNS servers that are used for the Intranet should support Unicode names.

• idn enabled = None

  This value will not convert any Unicode domain names to use Punycode. This is the default value, which is consistent with the .NET Framework 2.0 behavior.

Enabling IRI parsing (iriParsing enabled = true) normalizes and checks characters according to the IRI rules in RFC 3987. The default value is false and normalizes and checks characters according to RFC 2396 and RFC 2732 (for IPv6 literals).

For more information on IRI support, see the Remarks section for the Uri class.