Dns.GetHostEntryAsync 方法

定义

命名空间:

System.Net

程序集:

System.Net.NameResolution.dll

将主机名或 IP 地址解析为 IPHostEntry 实例以作为异步操作。

重载

GetHostEntryAsync(IPAddress)	将 IP 地址解析为 IPHostEntry 实例以作为异步操作。
GetHostEntryAsync(String)	将主机名或 IP 地址解析为 IPHostEntry 实例以作为异步操作。
GetHostEntryAsync(String, CancellationToken)	将主机名或 IP 地址解析为 IPHostEntry 实例以作为异步操作。
GetHostEntryAsync(String, AddressFamily, CancellationToken)	将主机名或 IP 地址解析为 IPHostEntry 实例以作为异步操作。

GetHostEntryAsync(IPAddress)

Source:

Dns.cs

将 IP 地址解析为 IPHostEntry 实例以作为异步操作。

public:
 static System::Threading::Tasks::Task<System::Net::IPHostEntry ^> ^ GetHostEntryAsync(System::Net::IPAddress ^ address);

public static System.Threading.Tasks.Task<System.Net.IPHostEntry> GetHostEntryAsync (System.Net.IPAddress address);

static member GetHostEntryAsync : System.Net.IPAddress -> System.Threading.Tasks.Task<System.Net.IPHostEntry>

Public Shared Function GetHostEntryAsync (address As IPAddress) As Task(Of IPHostEntry)

参数

address

IPAddress

IP 地址。

返回

Task<IPHostEntry>

表示异步操作的任务对象。 任务对象上的 Result 属性返回 IPHostEntry 实例，该实例包含有关 address 中指定的主机的地址信息。

例外

ArgumentNullException

address 为 null。

SocketException

解析 address 时遇到错误。

ArgumentException

address 是无效的 IP 地址。

注解

此操作不会阻止。 解析 后，address返回Task<TResult>的对象将完成。

此方法在 DNS 服务器中查询与 IP 地址关联的 IP 地址和别名。

如果本地计算机未安装 IPv6，将从此方法的结果中筛选 IPv6 地址。 因此，如果只有 IPv6 结果可用于 address 参数，则有可能返回空IPHostEntry实例。

此方法 Aliases 不填充返回的 IPHostEntry 实例的 属性，并且始终为空。

备注

在应用程序中启用网络跟踪时，此成员发出跟踪信息。 有关详细信息，请参阅.NET Framework中的网络跟踪。

此方法存储在任务中，它返回该方法的同步对应项可能引发的所有非使用异常。 如果异常存储在返回的任务中，则在等待任务时将引发该异常。 使用异常（如 ArgumentException）仍会同步引发。 有关存储的异常，请参阅 引发的 GetHostEntry(IPAddress)异常。

GetHostEntryAsync(String)

Source:

Dns.cs

将主机名或 IP 地址解析为 IPHostEntry 实例以作为异步操作。

public:
 static System::Threading::Tasks::Task<System::Net::IPHostEntry ^> ^ GetHostEntryAsync(System::String ^ hostNameOrAddress);

public static System.Threading.Tasks.Task<System.Net.IPHostEntry> GetHostEntryAsync (string hostNameOrAddress);

static member GetHostEntryAsync : string -> System.Threading.Tasks.Task<System.Net.IPHostEntry>

Public Shared Function GetHostEntryAsync (hostNameOrAddress As String) As Task(Of IPHostEntry)

参数

hostNameOrAddress

String

要解析的主机名或 IP 地址。

返回

Task<IPHostEntry>

表示异步操作的任务对象。 任务对象上的 Result 属性返回 IPHostEntry 实例，该实例包含有关 hostNameOrAddress 中指定的主机的地址信息。

例外

ArgumentNullException

hostNameOrAddress 参数为 null。

ArgumentOutOfRangeException

hostNameOrAddress 参数的长度大于 255 个字符。

SocketException

解析 hostNameOrAddress 参数时遇到错误。

ArgumentException

hostNameOrAddress 参数是无效的 IP 地址。

注解

此操作不会阻止。 解析 后，hostNameOrAddress返回Task<TResult>的对象将完成。

此方法在 DNS 服务器中查询与主机名或 IP 地址关联的 IP 地址。

如果空字符串作为 hostNameOrAddress 参数传递，则此方法返回本地主机的 IPv4 和 IPv6 地址。

如果找不到主机名，则会 SocketException 返回值为 11001 的异常， (Windows 套接字错误WSAHOST_NOT_FOUND) 。 如果 DNS 服务器不响应，则可能会返回此异常。 如果名称不是官方主机名或别名，或者无法 (查询的数据库) 中找到此异常，则也可以返回此异常。

ArgumentException如果 hostNameOrAddress 参数包含 Any 或 IPv6Any，则也会返回异常。

此方法假定如果在 参数中 hostNameOrAddress 传递了 IP 文本字符串，则应用程序希望返回具有 IPHostEntry 所有属性集的实例。 这些属性包括 AddressList、 Aliases和 HostName。 因此，在传递 IP 字符串文本时，此方法的实现表现出以下行为：

1. 方法尝试分析地址。 hostNameOrAddress如果 参数包含合法 IP 字符串文本，则第一阶段成功。

2. 尝试使用 IP 字符串文本的 IP 地址进行反向查找以获取主机名。 此结果设置为 HostName 属性。

3. 此反向查找中的主机名再次用于获取与名称关联的所有可能的 IP 地址，并将其设置为 AddressList 属性。

对于 IPv4 字符串文本，上述所有三个步骤都可能成功。 但可能会返回实际属于不同主机的 IPv4 地址的过时 DNS 记录。 这可能会导致步骤 3 失败并引发异常， (IPv4 地址有 DNS PTR 记录，但 IPv4 地址) 没有 DNS A 记录。

对于 IPv6，上述步骤 2 可能会失败，因为大多数 IPv6 部署不会为 IPv6 地址注册反向 (PTR) 记录。 因此，此方法可能会返回字符串 IPv6 文本作为完全限定域 (FQDN) 属性中的 HostName 主机名。

方法 GetHostAddresses 在 IP 文本方面具有不同的行为。 如果上面的步骤 #1 成功 (成功分析为 IP 地址) ，则结果会立即返回该地址。 不会尝试反向查找。

如果本地计算机未安装 IPv6，将从此方法的结果中筛选 IPv6 地址。 因此，如果只有 IPv6 结果可用于 hostNameOrAddress.参数，则可能会返回空IPHostEntry实例。

此方法 Aliases 不填充返回的 IPHostEntry 实例的 属性，并且始终为空。

此方法使用基础操作系统的名称解析 API (（例如 Windows 上的 Win32 API getaddrinfo）和其他平台上) 的等效 API 来实现。 如果文件中描述了 hosts 主机，则会返回一个或多个 IP 地址，而无需查询 DNS 服务器。

备注

在应用程序中启用网络跟踪时，此成员发出跟踪信息。 有关详细信息，请参阅.NET Framework中的网络跟踪。

此方法存储在任务中，它返回该方法的同步对应项可能引发的所有非使用异常。 如果异常存储在返回的任务中，则在等待任务时将引发该异常。 使用异常（如 ArgumentException）仍会同步引发。 有关存储的异常，请参阅 引发的 GetHostEntry(String)异常。

GetHostEntryAsync(String, CancellationToken)

Source:

Dns.cs

将主机名或 IP 地址解析为 IPHostEntry 实例以作为异步操作。

public:
 static System::Threading::Tasks::Task<System::Net::IPHostEntry ^> ^ GetHostEntryAsync(System::String ^ hostNameOrAddress, System::Threading::CancellationToken cancellationToken);

public static System.Threading.Tasks.Task<System.Net.IPHostEntry> GetHostEntryAsync (string hostNameOrAddress, System.Threading.CancellationToken cancellationToken);

static member GetHostEntryAsync : string * System.Threading.CancellationToken -> System.Threading.Tasks.Task<System.Net.IPHostEntry>

Public Shared Function GetHostEntryAsync (hostNameOrAddress As String, cancellationToken As CancellationToken) As Task(Of IPHostEntry)

参数

hostNameOrAddress

String

要解析的主机名或 IP 地址。

cancellationToken

CancellationToken

应取消可用于指示异步操作的取消令牌。

返回

Task<IPHostEntry>

表示异步操作的任务对象。 Result任务对象上的 属性返回一个IPHostEntry实例，该实例包含有关 中指定的主机的hostNameOrAddress地址信息。

例外

OperationCanceledException

取消令牌已取消。 此异常存储在返回的任务中。

注解

此方法存储在任务中，它返回该方法的同步对应项可能引发的所有非使用异常。 如果异常存储在返回的任务中，则在等待任务时将引发该异常。 使用异常（如 ArgumentException）仍会同步引发。 有关存储的异常，请参阅 引发的 GetHostEntry(String)异常。

GetHostEntryAsync(String, AddressFamily, CancellationToken)

Source:

Dns.cs

将主机名或 IP 地址解析为 IPHostEntry 实例以作为异步操作。

public static System.Threading.Tasks.Task<System.Net.IPHostEntry> GetHostEntryAsync (string hostNameOrAddress, System.Net.Sockets.AddressFamily family, System.Threading.CancellationToken cancellationToken = default);

static member GetHostEntryAsync : string * System.Net.Sockets.AddressFamily * System.Threading.CancellationToken -> System.Threading.Tasks.Task<System.Net.IPHostEntry>

Public Shared Function GetHostEntryAsync (hostNameOrAddress As String, family As AddressFamily, Optional cancellationToken As CancellationToken = Nothing) As Task(Of IPHostEntry)

参数

hostNameOrAddress

String

要解析的主机名或 IP 地址。

family

AddressFamily

应检索其 IP 的地址系列。 如果 Unspecified为 ，则检索所有 IP，而不考虑地址系列。

cancellationToken

CancellationToken

应取消可用于指示异步操作的取消令牌。

返回

Task<IPHostEntry>

表示异步操作的任务对象。 Result任务对象上的 属性返回一个IPHostEntry实例，该实例包含有关 中指定的主机的hostNameOrAddress地址信息。

例外

OperationCanceledException

取消令牌已取消。 此异常存储在返回的任务中。

注解

此方法存储在任务中，它返回该方法的同步对应项可能引发的所有非使用异常。 如果异常存储在返回的任务中，则在等待任务时将引发该异常。 使用异常（如 ArgumentException）仍会同步引发。 有关存储的异常，请参阅 引发的 GetHostEntry(String, AddressFamily)异常。