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
| Name | Description |
|---|---|
| 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.csInitializes a new instance of the DnsClient class.
public DnsClient(string server, DnsClientProtocol protocol)Parameters
serverstring- The DNS server address (IP address, hostname, or URL for DNS over HTTPS).
protocolDnsClientProtocol- The DNS transport protocol to use.
DnsClient(string, DnsClientProtocol, DnsClientOptions?)
DnsClient.csInitializes a new instance of the DnsClient class.
public DnsClient(string server, DnsClientProtocol protocol, DnsClientOptions? options)Parameters
serverstring- The DNS server address (IP address, hostname, or URL for DNS over HTTPS).
protocolDnsClientProtocol- The DNS transport protocol to use.
optionsDnsClientOptions?- Optional configuration options.
Methods
| Name | Description |
|---|---|
| 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.csReleases the resources used by this instance.
public void Dispose()QueryAsync overloads
QueryAsync(string, DnsQueryType, DnsQueryClass, CancellationToken)
DnsClient.csSends 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
namestring- The domain name to query. Unicode names are automatically converted to punycode.
typeDnsQueryType- The DNS record type to query.
queryClassDnsQueryClass- The DNS query class.
cancellationTokenCancellationToken- 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.
TimeoutExceptionDnsClientOptions.Timeoutelapsed before a response arrived.OperationCanceledExceptioncancellationTokenwas cancelled.ObjectDisposedException- The client has been disposed.
QueryAsync(string, DnsQueryType, CancellationToken)
DnsClient.csSends a DNS query for the specified domain name and record type.
public Task<DnsResponseMessage> QueryAsync(string name, DnsQueryType type, CancellationToken cancellationToken = default)Parameters
namestring- The domain name to query. Unicode names are automatically converted to punycode.
typeDnsQueryType- The DNS record type to query.
cancellationTokenCancellationToken- A cancellation token.
Returns
Task<DnsResponseMessage> The DNS response message.
ReverseLookupAsync(IPAddress, CancellationToken)
DnsClient.csPerforms a reverse DNS lookup for the specified IP address.
public Task<DnsResponseMessage> ReverseLookupAsync(IPAddress address, CancellationToken cancellationToken = default)Parameters
addressIPAddress- The IP address to look up (IPv4 or IPv6).
cancellationTokenCancellationToken- A cancellation token.
Returns
Task<DnsResponseMessage> The DNS response message containing PTR records.
SendAsync(DnsQueryMessage, CancellationToken)
DnsClient.csSends 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
messageDnsQueryMessage- The DNS query message to send.
cancellationTokenCancellationToken- 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.
TimeoutExceptionDnsClientOptions.Timeoutelapsed before a response arrived.OperationCanceledExceptioncancellationTokenwas 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.csTransfers 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
zoneNamestring- The name of the zone. Unicode names are automatically converted to punycode.
cancellationTokenCancellationToken- 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.
TimeoutExceptionDnsClientOptions.Timeoutelapsed before a message arrived.OperationCanceledExceptioncancellationTokenwas 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.csTransfers 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
zoneNamestring- The name of the zone. Unicode names are automatically converted to punycode.
currentSerialuint- The serial of the version of the zone the client has.
cancellationTokenCancellationToken- 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.
TimeoutExceptionDnsClientOptions.Timeoutelapsed before a message arrived.OperationCanceledExceptioncancellationTokenwas cancelled.ObjectDisposedException- The client has been disposed.
Remarks
DnsClientOptions.Timeout applies to each message, not to the whole transfer.