DnsClient Class

A DNS client supporting UDP, TCP, DNS over TLS, DNS over HTTPS, DNS over QUIC, DNSSEC, EDNS, IDN, reverse lookups, zone transfers, TSIG, and DNS cookies.

public sealed class DnsClient : IDisposable
Implements

Constructors

NameDescription
DnsClient(string, DnsClientProtocol)Initializes a new instance of the DnsClient class.
DnsClient(string, DnsClientProtocol, DnsClientOptions?)Initializes a new instance of the DnsClient class.

DnsClient overloads

DnsClient(string, DnsClientProtocol)

DnsClient.cs

Initializes a new instance of the DnsClient class.

public DnsClient(string server, DnsClientProtocol protocol)
Parameters
server string
The DNS server address (IP address, hostname, or URL for DNS over HTTPS).
protocol DnsClientProtocol
The DNS transport protocol to use.

DnsClient(string, DnsClientProtocol, DnsClientOptions?)

DnsClient.cs

Initializes a new instance of the DnsClient class.

public DnsClient(string server, DnsClientProtocol protocol, DnsClientOptions? options)
Parameters
server string
The DNS server address (IP address, hostname, or URL for DNS over HTTPS).
protocol DnsClientProtocol
The DNS transport protocol to use.
options DnsClientOptions?
Optional configuration options.

Methods

NameDescription
Dispose()Releases the resources used by this instance.
QueryAsync(string, DnsQueryType, DnsQueryClass, CancellationToken)Sends a DNS query for the specified domain name, record type, and class.
QueryAsync(string, DnsQueryType, CancellationToken)Sends a DNS query for the specified domain name and record type.
ReverseLookupAsync(IPAddress, CancellationToken)Performs a reverse DNS lookup for the specified IP address.
SendAsync(DnsQueryMessage, CancellationToken)Sends a DNS query message and returns the response.
TransferZoneAsync(string, CancellationToken)Transfers a whole zone (AXFR, RFC 5936). The transfer goes over TCP for a DnsClientProtocol.Udp or DnsClientProtocol.Tcp client, and over TLS for a DnsClientProtocol.Tls client.
TransferZoneAsync(string, uint, CancellationToken)Transfers the changes of a zone since the version the client has (IXFR, RFC 1995). The transfer goes over TCP for a DnsClientProtocol.Udp or DnsClientProtocol.Tcp client, and over TLS for a DnsClientProtocol.Tls client.

Dispose()

DnsClient.cs

Releases the resources used by this instance.

public void Dispose()

QueryAsync overloads

QueryAsync(string, DnsQueryType, DnsQueryClass, CancellationToken)

DnsClient.cs

Sends a DNS query for the specified domain name, record type, and class.

public Task<DnsResponseMessage> QueryAsync(string name, DnsQueryType type, DnsQueryClass queryClass, CancellationToken cancellationToken = default)
Parameters
name string
The domain name to query. Unicode names are automatically converted to punycode.
type DnsQueryType
The DNS record type to query.
queryClass DnsQueryClass
The DNS query class.
cancellationToken CancellationToken
A cancellation token.
Returns

Task<DnsResponseMessage> The DNS response message.

Exceptions
DnsProtocolException
The response is malformed, or does not answer the query that was sent.
TimeoutException
DnsClientOptions.Timeout elapsed before a response arrived.
OperationCanceledException
cancellationToken was cancelled.
ObjectDisposedException
The client has been disposed.

QueryAsync(string, DnsQueryType, CancellationToken)

DnsClient.cs

Sends a DNS query for the specified domain name and record type.

public Task<DnsResponseMessage> QueryAsync(string name, DnsQueryType type, CancellationToken cancellationToken = default)
Parameters
name string
The domain name to query. Unicode names are automatically converted to punycode.
type DnsQueryType
The DNS record type to query.
cancellationToken CancellationToken
A cancellation token.
Returns

Task<DnsResponseMessage> The DNS response message.

ReverseLookupAsync(IPAddress, CancellationToken)

DnsClient.cs

Performs a reverse DNS lookup for the specified IP address.

public Task<DnsResponseMessage> ReverseLookupAsync(IPAddress address, CancellationToken cancellationToken = default)

Parameters

address IPAddress
The IP address to look up (IPv4 or IPv6).
cancellationToken CancellationToken
A cancellation token.

Returns

Task<DnsResponseMessage> The DNS response message containing PTR records.

SendAsync(DnsQueryMessage, CancellationToken)

DnsClient.cs

Sends a DNS query message and returns the response.

net10.0

public Task<DnsResponseMessage> SendAsync(DnsQueryMessage message, CancellationToken cancellationToken = default)

net11.0

public Task<DnsResponseMessage> SendAsync(DnsQueryMessage message, CancellationToken cancellationToken = default)

Parameters

message DnsQueryMessage
The DNS query message to send.
cancellationToken CancellationToken
A cancellation token.

Returns

Task<DnsResponseMessage> The DNS response message.

Exceptions

DnsProtocolException
The response is malformed, or does not answer the query that was sent.
TimeoutException
DnsClientOptions.Timeout elapsed before a response arrived.
OperationCanceledException
cancellationToken was cancelled.
ObjectDisposedException
The client has been disposed.

Remarks

The message is not modified; the client's options are applied to an internal copy.

TransferZoneAsync overloads

TransferZoneAsync(string, CancellationToken)

DnsClient.ZoneTransfer.cs

Transfers a whole zone (AXFR, RFC 5936). The transfer goes over TCP for a DnsClientProtocol.Udp or DnsClientProtocol.Tcp client, and over TLS for a DnsClientProtocol.Tls client.

public IAsyncEnumerable<DnsResponseMessage> TransferZoneAsync(string zoneName, CancellationToken cancellationToken = default)
Parameters
zoneName string
The name of the zone. Unicode names are automatically converted to punycode.
cancellationToken CancellationToken
A cancellation token.
Returns

IAsyncEnumerable<DnsResponseMessage> The messages of the transfer, as they arrive. The answers of the first message start with the SOA record of the zone, and the last message ends with the same SOA record. When the server refuses the transfer, the only message has its response code.

Exceptions
NotSupportedException
The protocol of the client is DNS over HTTPS or DNS over QUIC.
DnsProtocolException
A message is malformed, does not answer the query, or the server closed the connection before the end of the transfer.
TimeoutException
DnsClientOptions.Timeout elapsed before a message arrived.
OperationCanceledException
cancellationToken was cancelled.
ObjectDisposedException
The client has been disposed.
Remarks

DnsClientOptions.Timeout applies to each message, not to the whole transfer.

TransferZoneAsync(string, uint, CancellationToken)

DnsClient.ZoneTransfer.cs

Transfers the changes of a zone since the version the client has (IXFR, RFC 1995). The transfer goes over TCP for a DnsClientProtocol.Udp or DnsClientProtocol.Tcp client, and over TLS for a DnsClientProtocol.Tls client.

public IAsyncEnumerable<DnsResponseMessage> TransferZoneAsync(string zoneName, uint currentSerial, CancellationToken cancellationToken = default)
Parameters
zoneName string
The name of the zone. Unicode names are automatically converted to punycode.
currentSerial uint
The serial of the version of the zone the client has.
cancellationToken CancellationToken
A cancellation token.
Returns

IAsyncEnumerable<DnsResponseMessage> The messages of the transfer, as they arrive. Their answers start with the SOA record of the current version, then come the differences: for each version, its old SOA record and the deleted records, then its new SOA record and the added records. The last message ends with the SOA record of the current version. A server that does not keep the differences sends the whole zone instead, as DnsClient.TransferZoneAsync does, and a client that is up to date gets the SOA record alone.

Exceptions
NotSupportedException
The protocol of the client is DNS over HTTPS or DNS over QUIC.
DnsProtocolException
A message is malformed, does not answer the query, or the server closed the connection before the end of the transfer.
TimeoutException
DnsClientOptions.Timeout elapsed before a message arrived.
OperationCanceledException
cancellationToken was cancelled.
ObjectDisposedException
The client has been disposed.
Remarks

DnsClientOptions.Timeout applies to each message, not to the whole transfer.