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)

來源:

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 屬性會傳回包含 address 中所指定主機之位址資訊的 IPHostEntry 執行個體。

例外狀況

ArgumentNullException

address 為 null。

SocketException

當解析 address 時，發生錯誤。

ArgumentException

address 為無效的 IP 位址。

備註

這項作業不會封鎖。 傳回 Task<TResult> 的物件會在 解析之後 address 完成。

此方法會查詢 DNS 伺服器，以取得與 IP 位址相關聯的 IP 位址和別名。

如果本機計算機未安裝 IPv6，則會從此方法的結果篩選 IPv6 位址。 因此，如果只有 IPv6 結果可供參數使用，就可以傳回空 IPHostEntry 的 address 實例。

Aliases這個方法不會填入傳回之實例的 IPHostEntry 屬性，而且一律為空白。

注意

當您在應用程式中啟用網路追蹤時，此成員會發出追蹤資訊。 如需詳細資訊，請參閱 .NET Framework 中的網路追蹤。

這個方法會儲存在工作中，它會傳回方法同步對應專案可以擲回的所有非使用例外狀況。 如果例外狀況儲存在傳回的工作中，則會在等候工作時擲回該例外狀況。 使用例外狀況，例如 ArgumentException仍會同步擲回。 如需預存例外狀況，請參閱 擲回的 GetHostEntry(IPAddress)例外狀況。

GetHostEntryAsync(String)

來源:

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 屬性會傳回包含 hostNameOrAddress 中所指定主機之位址資訊的 IPHostEntry 執行個體。

例外狀況

ArgumentNullException

hostNameOrAddress 參數為 null。

ArgumentOutOfRangeException

hostNameOrAddress 參數的長度大於 255 個字元。

SocketException

解析 hostNameOrAddress 參數時發生錯誤。

ArgumentException

hostNameOrAddress 參數是無效的 IP 位址。

備註

這項作業不會封鎖。 傳回 Task<TResult> 的物件會在 解析之後 hostNameOrAddress 完成。

此方法會查詢 DNS 伺服器，以取得與主機名或 IP 位址相關聯的 IP 位址。

如果將空字串當做 hostNameOrAddress 自變數傳遞，則此方法會傳回本機主機的 IPv4 和 IPv6 位址。

如果找不到主機名，則會 SocketException 傳回值為 11001 (Windows Sockets 錯誤WSAHOST_NOT_FOUND) 例外状况。 如果 DNS 伺服器沒有回應，則可以傳回此例外狀況。 如果名稱不是官方主機名或別名，或無法在查詢 () 資料庫中找到，也可以傳回這個例外狀況。

如果 hostNameOrAddress 參數包含 Any 或 IPv6Any，ArgumentException也會傳回例外狀況。

這個方法假設如果IP常值字串傳遞至 hostNameOrAddress 應用程式想要 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 常值做為屬性中 HostName FQDN (完整網域) 主機名。

方法 GetHostAddresses 對於IP常值有不同的行為。 如果上述步驟 #1 成功 (成功剖析為IP位址) ，則會立即傳回該位址作為結果。 在反向對應時不會嘗試。

如果本機計算機未安裝 IPv6，則會從此方法的結果篩選 IPv6 位址。 因此，如果只有 IPv6 結果可供 .parameter 使用，就可以取回空 IPHostEntry 的 hostNameOrAddress實例。

Aliases這個方法不會填入傳回之實例的 IPHostEntry 屬性，而且一律為空白。

此方法是使用基礎操作系統的名稱解析 API 來實作， (例如 Windows 上的 Win32 API getaddrinfo，以及其他平臺上的對等 API) 。 如果檔案中 hosts 描述主機，則會傳回IP位址或位址，而不需查詢 DNS 伺服器。

注意

當您在應用程式中啟用網路追蹤時，此成員會發出追蹤資訊。 如需詳細資訊，請參閱 .NET Framework 中的網路追蹤。

這個方法會儲存在工作中，它會傳回方法同步對應專案可以擲回的所有非使用例外狀況。 如果例外狀況儲存在傳回的工作中，則會在等候工作時擲回該例外狀況。 使用例外狀況，例如 ArgumentException仍會同步擲回。 如需預存例外狀況，請參閱 擲回的 GetHostEntry(String)例外狀況。

GetHostEntryAsync(String, CancellationToken)

來源:

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)

來源:

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)例外狀況。