Dns.GetHostEntryAsync 方法
定义
将主机名或 IP 地址解析为 IPHostEntry 实例以作为异步操作。Resolves a host name or IP address to an IPHostEntry instance as an asynchronous operation.
重载
| GetHostEntryAsync(IPAddress) |
将 IP 地址解析为 IPHostEntry 实例以作为异步操作。Resolves an IP address to an IPHostEntry instance as an asynchronous operation. |
| GetHostEntryAsync(String) |
将主机名或 IP 地址解析为 IPHostEntry 实例以作为异步操作。Resolves a host name or IP address to an IPHostEntry instance as an asynchronous operation. |
GetHostEntryAsync(IPAddress)
将 IP 地址解析为 IPHostEntry 实例以作为异步操作。Resolves an IP address to an IPHostEntry instance as an asynchronous operation.
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 地址。An IP address.
返回
表示异步操作的任务对象。The task object representing the asynchronous operation. 任务对象上的 Result 属性返回 IPHostEntry 实例,该实例包含有关 address 中指定的主机的地址信息。The Result property on the task object returns an IPHostEntry instance that contains address information about the host specified in address.
例外
address 为 null。address is null.
解析 address 时遇到错误。An error is encountered when resolving address.
address 是无效的 IP 地址。address is an invalid IP address.
注解
此操作不会阻止。This operation will not block. 解析后,返回的 Task<TResult> 对象将完成 address 。The returned Task<TResult> object will complete after the address has been resolved.
此方法在 DNS 服务器中查询与 IP 地址关联的 IP 地址和别名。This method queries a DNS server for the IP addresses and aliases associated with an IP address.
如果本地计算机未安装 IPv6,则将根据此方法的结果筛选 IPv6 地址。IPv6 addresses are filtered from the results of this method if the local computer does not have IPv6 installed. 因此, IPHostEntry 如果只有 IPv6 结果可用于参数,则可以返回空实例 address 。As a result, it is possible to get back an empty IPHostEntry instance if only IPv6 results where available for the address parameter.
Aliases返回的实例的属性 IPHostEntry 不由此方法填充,并且将始终为空。The Aliases property of the IPHostEntry instance returned is not populated by this method and will always be empty.
备注
在应用程序中启用网络跟踪后,此成员将发出跟踪信息。This member emits trace information when you enable network tracing in your application. 有关详细信息,请参阅 .NET Framework 中的网络跟踪。For more information, see Network Tracing in the .NET Framework.
适用于
GetHostEntryAsync(String)
将主机名或 IP 地址解析为 IPHostEntry 实例以作为异步操作。Resolves a host name or IP address to an IPHostEntry instance as an asynchronous operation.
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 地址。The host name or IP address to resolve.
返回
表示异步操作的任务对象。The task object representing the asynchronous operation. 任务对象上的 Result 属性返回 IPHostEntry 实例,该实例包含有关 hostNameOrAddress 中指定的主机的地址信息。The Result property on the task object returns an IPHostEntry instance that contains address information about the host specified in hostNameOrAddress.
例外
hostNameOrAddress 参数为 null。The hostNameOrAddress parameter is null.
hostNameOrAddress 参数的长度大于 255 个字符。The length of hostNameOrAddress parameter is greater than 255 characters.
解析 hostNameOrAddress 参数时遇到错误。An error was encountered when resolving the hostNameOrAddress parameter.
hostNameOrAddress 参数是无效的 IP 地址。The hostNameOrAddress parameter is an invalid IP address.
注解
此操作不会阻止。This operation will not block. 解析后,返回的 Task<TResult> 对象将完成 hostNameOrAddress 。The returned Task<TResult> object will complete after the hostNameOrAddress has been resolved.
此方法在 DNS 服务器中查询与主机名或 IP 地址相关联的 IP 地址。This method queries a DNS server for the IP address that is associated with a host name or IP address.
如果将空字符串作为 hostNameOrAddress 参数传递,则此方法返回本地主机的 IPv4 和 IPv6 地址。If an empty string is passed as the hostNameOrAddress argument, then this method returns the IPv4 and IPv6 addresses of the local host.
如果找不到主机名,则返回的 SocketException 异常的值为 11001 (Windows 套接字错误 WSAHOST_NOT_FOUND) 。If the host name could not be found, the SocketException exception is returned with a value of 11001 (Windows Sockets error WSAHOST_NOT_FOUND). 如果 DNS 服务器没有响应,则可以返回此异常。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.
ArgumentException如果 hostNameOrAddress 参数包含或,也将返回异常 Any IPv6Any 。The ArgumentException exception is also returned if the hostNameOrAddress parameter contains Any or IPv6Any.
此方法假定,如果在应用程序所需的参数中传递了 IP 文本字符串,则该字符串将 hostNameOrAddress IPHostEntry 包含所有属性集。This 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. 这些属性包括 AddressList 、 Aliases 和 HostName 。These properties include the AddressList, Aliases, and HostName. 因此,在传递 IP 字符串时,此方法的实现表现如下:As a result, the implementation of this method exhibits the following behavior when an IP string literal is passed:
此方法尝试分析地址。The method tries to parse the address. 如果
hostNameOrAddress参数包含合法 IP 字符串,则第一阶段成功。If thehostNameOrAddressparameter contains a legal IP string literal, then the first phase succeeds.尝试使用 IP 字符串的 IP 地址的反向查找获取主机名。A reverse lookup using the IP address of the IP string literal is attempted to obtain the host name. 此结果设置为 HostName 属性。This result is set as the HostName property.
此反向查找中的主机名将再次用于获取与该名称关联的所有可能的 IP 地址,并将其设置为 AddressList 属性。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.
对于 IPv4 字符串,上述三个步骤可能会成功。For an IPv4 string literal, all three steps above may succeed. 但对于实际属于不同主机的 IPv4 地址,可以使用陈旧的 DNS 记录。But it is possible for a stale DNS record for an IPv4 address that actually belongs to a different host to be returned. 这可能会导致步骤 #3 失败并引发异常 (IPv4 地址存在 DNS PTR 记录,但 IPv4 地址) 没有 DNS A 记录。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).
对于 IPv6,以上步骤 #2 可能会失败,因为大多数 IPv6 部署不会为 IPv6 地址注册反向 (PTR) 记录。For IPv6, step #2 above may fail, since most IPv6 deployments do not register the reverse (PTR) record for an IPv6 address. 因此,此方法可能会将字符串 IPv6 文本作为完全限定的域返回, (FQDN) 属性中的主机名 HostName 。So this method may return the string IPv6 literal as the fully-qualified domain (FQDN) host name in the HostName property.
对于 GetHostAddresses IP 文本,该方法具有不同的行为。The GetHostAddresses method has different behavior with respect to IP literals. 如果上面的步骤 #1 成功 (其成功分析为 IP 地址) ,则该地址将立即返回为结果。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,则将根据此方法的结果筛选 IPv6 地址。IPv6 addresses are filtered from the results of this method if the local computer does not have IPv6 installed. 因此, IPHostEntry 如果仅 IPv6 结果可用于. 参数,则可能会返回空实例 hostNameOrAddress 。As a result, it is possible to get back an empty IPHostEntry instance if only IPv6 results where available for the hostNameOrAddress.parameter.
Aliases返回的实例的属性 IPHostEntry 不由此方法填充,并且将始终为空。The Aliases property of the IPHostEntry instance returned is not populated by this method and will always be empty.
此方法使用基础操作系统的名称解析 Api 来实现 (例如,Windows 上的 Win32 API getaddrinfo,以及其他平台上的等效 Api) 。This method is implemented using the underlying operating system's name resolution APIs (such as the Win32 API getaddrinfo on Windows, and equivalent APIs on other platforms). 如果文件中介绍了主机 hosts ,则将返回该 IP 地址,而不会查询 DNS 服务器。If a host is described in the hosts file, the IP address or addresses there will be returned without querying the DNS server.
备注
在应用程序中启用网络跟踪后,此成员将发出跟踪信息。This member emits trace information when you enable network tracing in your application. 有关详细信息,请参阅 .NET Framework 中的网络跟踪。For more information, see Network Tracing in the .NET Framework.