Dns.GetHostEntry Method

Definition

Namespace:

System.Net

Assembly:

System.Net.NameResolution.dll

Resolves a host name or IP address to an IPHostEntry instance.

Overloads

GetHostEntry(IPAddress)	Resolves an IP address to an IPHostEntry instance.
GetHostEntry(String)	Resolves a host name or IP address to an IPHostEntry instance.
GetHostEntry(String, AddressFamily)	Resolves a host name or IP address to an IPHostEntry instance.

GetHostEntry(IPAddress)

Source:

Dns.cs

Resolves an IP address to an IPHostEntry instance.

public:
 static System::Net::IPHostEntry ^ GetHostEntry(System::Net::IPAddress ^ address);

public static System.Net.IPHostEntry GetHostEntry (System.Net.IPAddress address);

static member GetHostEntry : System.Net.IPAddress -> System.Net.IPHostEntry

Public Shared Function GetHostEntry (address As IPAddress) As IPHostEntry

Parameters

address

IPAddress

An IP address.

Returns

IPHostEntry

An IPHostEntry instance that contains address information about the host specified in address.

Exceptions

ArgumentNullException

address is null.

SocketException

An error is encountered when resolving address.

ArgumentException

address is an invalid IP address.

Examples

The following code example uses the GetHostEntry method to resolve an IP address to an IPHostEntry instance.

public:
    static void DoGetHostEntry(IPAddress^ address)
    {
        IPHostEntry^ host = Dns::GetHostEntry(address);

        Console::WriteLine("GetHostEntry({0}) returns HostName: {1}", address->ToString(), host->HostName);
    }

public static void DoGetHostEntry(IPAddress address)
{
    IPHostEntry host = Dns.GetHostEntry(address);

    Console.WriteLine($"GetHostEntry({address}) returns HostName: {host.HostName}");
}

Public Sub DoGetHostEntry(address As IPAddress)

    Dim host as IPHostEntry = Dns.GetHostEntry(address)

    Console.WriteLine($"GetHostEntry({address}) returns HostName: {host.HostName}")

End Sub

Remarks

The GetHostEntry method queries a DNS server for the IP addresses and aliases associated with an IP address.

IPv6 addresses are filtered from the results of the GetHostEntry method if the local computer does not have IPv6 installed. As a result, it is possible to get back an empty IPHostEntry instance if only IPv6 results were available for the address parameter.

The Aliases property of the IPHostEntry instance returned is not populated by this method and will always be empty.

Note

This member emits trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework.

GetHostEntry(String)

Source:

Dns.cs

Resolves a host name or IP address to an IPHostEntry instance.

public:
 static System::Net::IPHostEntry ^ GetHostEntry(System::String ^ hostNameOrAddress);

public static System.Net.IPHostEntry GetHostEntry (string hostNameOrAddress);

static member GetHostEntry : string -> System.Net.IPHostEntry

Public Shared Function GetHostEntry (hostNameOrAddress As String) As IPHostEntry

Parameters

hostNameOrAddress

String

The host name or IP address to resolve.

Returns

IPHostEntry

An IPHostEntry instance that contains address information about the host specified in hostNameOrAddress.

Exceptions

ArgumentNullException

The hostNameOrAddress parameter is null.

ArgumentOutOfRangeException

The length of hostNameOrAddress parameter is greater than 255 characters.

SocketException

An error was encountered when resolving the hostNameOrAddress parameter.

ArgumentException

The hostNameOrAddress parameter is an invalid IP address.

Examples

The following example uses the GetHostEntry method to resolve an IP address to an IPHostEntry instance.

public:
    static void DoGetHostEntry(String^ hostname)
    {
        IPHostEntry^ host = Dns::GetHostEntry(hostname);

        Console::WriteLine("GetHostEntry({0}) returns:", host->HostName);

        for (int i = 0; i < host->AddressList->Length; i++)
        {
            Console::WriteLine("    {0}", host->AddressList[i]->ToString());			
        }
    }

public static void DoGetHostEntry(string hostname)
{
    IPHostEntry host = Dns.GetHostEntry(hostname);

    Console.WriteLine($"GetHostEntry({hostname}) returns:");

    foreach (IPAddress address in host.AddressList)
    {
        Console.WriteLine($"    {address}");
    }
}

Public Sub DoGetHostEntry(hostName As String)

    Dim host as IPHostEntry = Dns.GetHostEntry(hostname)

    Console.WriteLine($"GetHostEntry({hostname}) returns:")

    Dim addresses As IPAddress() = host.AddressList

    Dim index As Integer
    For index = 0 To addresses.Length - 1
        Console.WriteLine($"    {addresses(index)}")
    Next index

End Sub

Remarks

The GetHostEntry method queries a DNS server for the IP address that is associated with a host name or IP address.

If an empty string is passed as the hostNameOrAddress argument, then this method returns the IPv4 and IPv6 addresses of the local host.

If the host name could not be found, the SocketException exception is returned with a value of 11001 (Windows Sockets error WSAHOST_NOT_FOUND). This exception can be returned if the DNS server does not respond. This exception can also be returned if the name is not an official host name or alias, or it cannot be found in the database(s) being queried.

The ArgumentException exception is also returned if the hostNameOrAddress parameter contains Any or IPv6Any.

The GetHostEntry method assumes that if an IP literal string is passed in the hostNameOrAddress parameter that the application wants an IPHostEntry instance returned with all of the properties set. These properties include the AddressList, Aliases, and HostName. As a result, the implementation of the GetHostEntry method exhibits the following behavior when an IP string literal is passed:

1. The method tries to parse the address. If the hostNameOrAddress parameter contains a legal IP string literal, then the first phase succeeds.

2. A reverse lookup using the IP address of the IP string literal is attempted to obtain the host name. This result is set as the HostName property.

3. The host name from this reverse lookup is used again to obtain all the possible IP addresses associated with the name and set as the AddressList property.

For an IPv4 string literal, all three steps above may succeed. But it is possible for a stale DNS record for an IPv4 address that actually belongs to a different host to be returned. This may cause step #3 to fail and throw an exception (there is a DNS PTR record for the IPv4 address, but no DNS A record for the IPv4 address).

For IPv6, step #2 above may fail, since most IPv6 deployments do not register the reverse (PTR) record for an IPv6 address. So this method may return the string IPv6 literal as the fully-qualified domain (FQDN) host name in the HostName property.

The GetHostAddresses method has different behavior with respect to IP literals. If step #1 above succeeds (it successfully parses as an IP address), that address is immediately returned as the result. There is no attempt at a reverse lookup.

IPv6 addresses are filtered from the results of the GetHostEntry method if the local computer does not have IPv6 installed. As a result, it is possible to get back an empty IPHostEntry instance if only IPv6 results where available for the hostNameOrAddress.parameter.

The Aliases property of the IPHostEntry instance returned is not populated by this method and will always be empty.

Note

This member emits trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework.

GetHostEntry(String, AddressFamily)

Source:

Dns.cs

Resolves a host name or IP address to an IPHostEntry instance.

public:
 static System::Net::IPHostEntry ^ GetHostEntry(System::String ^ hostNameOrAddress, System::Net::Sockets::AddressFamily family);

public static System.Net.IPHostEntry GetHostEntry (string hostNameOrAddress, System.Net.Sockets.AddressFamily family);

static member GetHostEntry : string * System.Net.Sockets.AddressFamily -> System.Net.IPHostEntry

Public Shared Function GetHostEntry (hostNameOrAddress As String, family As AddressFamily) As IPHostEntry

Parameters

hostNameOrAddress

String

The host name or IP address to resolve.

family

AddressFamily

The address family for which IPs should be retrieved. If Unspecified, retrieve all IPs regardless of address family.

Returns

IPHostEntry

An IPHostEntry instance that contains the address information about the host specified in hostNameOrAddress.