Dns.GetHostEntryAsync Método

Definição

Namespace:

System.Net

Assembly:

System.Net.NameResolution.dll

Resolve um nome de host ou endereço IP para uma instância de IPHostEntry como uma operação assíncrona.

Sobrecargas

GetHostEntryAsync(IPAddress)	Resolve um endereço IP para uma instância IPHostEntry como uma operação assíncrona.
GetHostEntryAsync(String)	Resolve um nome de host ou endereço IP para uma instância de IPHostEntry como uma operação assíncrona.
GetHostEntryAsync(String, CancellationToken)	Resolve um nome de host ou endereço IP para uma instância de IPHostEntry como uma operação assíncrona.
GetHostEntryAsync(String, AddressFamily, CancellationToken)	Resolve um nome de host ou endereço IP para uma instância de IPHostEntry como uma operação assíncrona.

GetHostEntryAsync(IPAddress)

Origem:

Dns.cs

Resolve um endereço IP para uma instância IPHostEntry como uma operação assíncrona.

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)

Parâmetros

address

IPAddress

Um endereço IP.

Retornos

Task<IPHostEntry>

O objeto de tarefa que representa a operação assíncrona. A propriedade Result no objeto de tarefa retorna uma instância IPHostEntry que contém informações de endereço sobre o host especificado em address.

Exceções

ArgumentNullException

address é null.

SocketException

Um erro foi encontrado durante a resolução de address.

ArgumentException

address é um endereço IP inválido.

Comentários

Esta operação não será bloqueada. O objeto retornado Task<TResult> será concluído depois que o address tiver sido resolvido.

Esse método consulta um servidor DNS para os endereços IP e aliases associados a um endereço IP.

Os endereços IPv6 serão filtrados dos resultados desse método se o computador local não tiver o IPv6 instalado. Como resultado, é possível recuperar uma instância vazia IPHostEntry se apenas os resultados IPv6 estiverem disponíveis para o address parâmetro.

A Aliases propriedade da IPHostEntry instância retornada não é preenchida por esse método e sempre estará vazia.

Observação

Esse membro emite informações de rastreamento quando você habilita o rastreamento de rede em seu aplicativo. Para obter mais informações, consulte Rastreamento de rede no .NET Framework.

Esse método armazena na tarefa que retorna todas as exceções de não uso que a contraparte síncrona do método pode gerar. Se uma exceção for armazenada na tarefa retornada, essa exceção será gerada quando a tarefa for aguardada. Exceções de uso, como ArgumentException, ainda são geradas de forma síncrona. Para as exceções armazenadas, consulte as exceções geradas por GetHostEntry(IPAddress).

GetHostEntryAsync(String)

Origem:

Dns.cs

Resolve um nome de host ou endereço IP para uma instância de IPHostEntry como uma operação assíncrona.

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)

Parâmetros

hostNameOrAddress

String

O nome do host ou endereço IP a ser resolvido.

Retornos

Task<IPHostEntry>

O objeto de tarefa que representa a operação assíncrona. A propriedade Result no objeto de tarefa retorna uma instância IPHostEntry que contém informações de endereço sobre o host especificado em hostNameOrAddress.

Exceções

ArgumentNullException

O parâmetro hostNameOrAddress é null.

ArgumentOutOfRangeException

O tamanho do parâmetro hostNameOrAddress é maior que 255 caracteres.

SocketException

Erro ao resolver o parâmetro hostNameOrAddress.

ArgumentException

O parâmetro hostNameOrAddress é um endereço IP inválido.

Comentários

Esta operação não será bloqueada. O objeto retornado Task<TResult> será concluído depois que o hostNameOrAddress tiver sido resolvido.

Esse método consulta um servidor DNS para o endereço IP associado a um nome de host ou endereço IP.

Se uma cadeia de caracteres vazia for passada como o hostNameOrAddress argumento , esse método retornará os endereços IPv4 e IPv6 do host local.

Se o nome do host não puder ser encontrado, a SocketException exceção será retornada com um valor 11001 (erro do Windows Sockets WSAHOST_NOT_FOUND). Essa exceção poderá ser retornada se o servidor DNS não responder. Essa exceção também poderá ser retornada se o nome não for um nome de host oficial ou alias ou não puder ser encontrado nos bancos de dados que estão sendo consultados.

A ArgumentException exceção também será retornada se o hostNameOrAddress parâmetro contiver Any ou IPv6Any.

Esse método pressupõe que, se uma cadeia de caracteres literal de IP for passada no hostNameOrAddress parâmetro que o aplicativo deseja que uma IPHostEntry instância retorne com todas as propriedades definidas. Essas propriedades incluem , AddressListAliasese HostName. Como resultado, a implementação desse método exibe o seguinte comportamento quando um literal de cadeia de caracteres IP é passado:

1. O método tenta analisar o endereço. Se o hostNameOrAddress parâmetro contiver um literal de cadeia de caracteres IP legal, a primeira fase terá êxito.

2. Uma pesquisa inversa usando o endereço IP do literal da cadeia de caracteres IP é tentada para obter o nome do host. Esse resultado é definido como a HostName propriedade .

3. O nome do host dessa pesquisa inversa é usado novamente para obter todos os endereços IP possíveis associados ao nome e definidos como a AddressList propriedade .

Para um literal de cadeia de caracteres IPv4, todas as três etapas acima podem ter êxito. Mas é possível que um registro DNS obsoleto para um endereço IPv4 que realmente pertence a um host diferente seja retornado. Isso pode fazer com que a etapa 3 falhe e gere uma exceção (há um registro PTR DNS para o endereço IPv4, mas nenhum registro DNS A para o endereço IPv4).

Para IPv6, a etapa 2 acima pode falhar, pois a maioria das implantações IPv6 não registra o registro inverso (PTR) para um endereço IPv6. Portanto, esse método pode retornar a cadeia de caracteres IPv6 literal como o nome de host de domínio totalmente qualificado (FQDN) na HostName propriedade .

O GetHostAddresses método tem um comportamento diferente em relação aos literais de IP. Se a etapa nº 1 acima for bem-sucedida (ela analisará com êxito como um endereço IP), esse endereço será retornado imediatamente como resultado. Não há nenhuma tentativa de pesquisa inversa.

Os endereços IPv6 serão filtrados dos resultados desse método se o computador local não tiver o IPv6 instalado. Como resultado, é possível recuperar uma instância vazia IPHostEntry se apenas os resultados IPv6 estiverem disponíveis para o hostNameOrAddressparâmetro .

A Aliases propriedade da IPHostEntry instância retornada não é preenchida por esse método e sempre estará vazia.

Esse método é implementado usando as APIs de resolução de nomes do sistema operacional subjacente (como a API do Win32 getaddrinfo no Windows e APIs equivalentes em outras plataformas). Se um host for descrito no hosts arquivo, o endereço IP ou os endereços lá serão retornados sem consultar o servidor DNS.

Observação

Esse membro emite informações de rastreamento quando você habilita o rastreamento de rede em seu aplicativo. Para obter mais informações, consulte Rastreamento de rede no .NET Framework.

Esse método armazena na tarefa que retorna todas as exceções de não uso que a contraparte síncrona do método pode gerar. Se uma exceção for armazenada na tarefa retornada, essa exceção será gerada quando a tarefa for aguardada. Exceções de uso, como ArgumentException, ainda são geradas de forma síncrona. Para as exceções armazenadas, consulte as exceções geradas por GetHostEntry(String).

GetHostEntryAsync(String, CancellationToken)

Origem:

Dns.cs

Resolve um nome de host ou endereço IP para uma instância de IPHostEntry como uma operação assíncrona.

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)

Parâmetros

hostNameOrAddress

String

O nome do host ou endereço IP a ser resolvido.

cancellationToken

CancellationToken

Um token de cancelamento que pode ser usado para sinalizar que a operação assíncrona deve ser cancelada.

Retornos

Task<IPHostEntry>

O objeto de tarefa que representa a operação assíncrona. A Result propriedade no objeto de tarefa retorna uma IPHostEntry instância que contém as informações de endereço sobre o host especificado em hostNameOrAddress.

Exceções

OperationCanceledException

O token de cancelamento foi cancelado. Essa exceção é armazenada na tarefa retornada.

Comentários

Esse método armazena na tarefa que retorna todas as exceções de não uso que a contraparte síncrona do método pode gerar. Se uma exceção for armazenada na tarefa retornada, essa exceção será gerada quando a tarefa for aguardada. Exceções de uso, como ArgumentException, ainda são geradas de forma síncrona. Para as exceções armazenadas, consulte as exceções geradas por GetHostEntry(String).

GetHostEntryAsync(String, AddressFamily, CancellationToken)

Origem:

Dns.cs

Resolve um nome de host ou endereço IP para uma instância de IPHostEntry como uma operação assíncrona.

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)

Parâmetros

hostNameOrAddress

String

O nome do host ou endereço IP a ser resolvido.

family

AddressFamily

A família de endereços para a qual os IPs devem ser recuperados. Se Unspecified, recupere todos os IPs, independentemente da família de endereços.

cancellationToken

CancellationToken

Um token de cancelamento que pode ser usado para sinalizar que a operação assíncrona deve ser cancelada.

Retornos

Task<IPHostEntry>

O objeto de tarefa que representa a operação assíncrona. A Result propriedade no objeto de tarefa retorna uma IPHostEntry instância que contém as informações de endereço sobre o host especificado em hostNameOrAddress.

Exceções

OperationCanceledException

O token de cancelamento foi cancelado. Essa exceção é armazenada na tarefa retornada.

Comentários

Esse método armazena na tarefa que retorna todas as exceções de não uso que a contraparte síncrona do método pode gerar. Se uma exceção for armazenada na tarefa retornada, essa exceção será gerada quando a tarefa for aguardada. Exceções de uso, como ArgumentException, ainda são geradas de forma síncrona. Para as exceções armazenadas, consulte as exceções geradas por GetHostEntry(String, AddressFamily).