DNS Resolution and the DnsResolver API
Objective
Every HttpClient call and every Socket.ConnectAsync to a host name starts
with a lookup, and for fifteen years .NET offered one answer: Dns.GetHostEntryAsync,
which asks the operating system for addresses and nothing else. It cannot ask
for an SRV record (the standard way to publish "this service lives on these
hosts and ports, with this priority and weight"), a TXT or an MX, it does not
tell you the TTL, and it cannot be pointed at a specific DNS server. .NET 11
adds DnsResolver and typed Dns.Resolve* methods in System.Net that speak
DNS themselves. This concept measures both paths against a CoreDNS container
started only for the test, with a zone holding A, AAAA, CNAME, SRV, TXT and MX
records: what each API sees, how an SRV answer turns into a destination, what
NXDOMAIN, "no data" and a dead server look like, and where the new API stops.
Versions: .NET SDK 11.0.100, runtime 11.0.0, TFM net11.0, no NuGet packages
(System.Net.NameResolution is part of the shared framework), CoreDNS 1.15.0
in Docker, macOS arm64 (Apple M4 Max). DnsResolver does not exist in the
10.0.100 SDK (CS0246).
Use Cases
- Client-side service discovery: resolve
_http._tcp.orders.internalto hosts, ports, priorities and weights, then pick a destination. - Reading TXT records for domain verification or configuration, and MX for mail routing, without a third-party DNS library.
- Tests and tools that must query a specific DNS server (a local CoreDNS, an internal resolver) instead of whatever the machine is configured with.
Deep Dive
What Dns.GetHostEntryAsync does and does not do
csharpvar e = await Dns.GetHostEntryAsync("localhost"); // ::1, 127.0.0.1
await Dns.GetHostEntryAsync("api.exemplo.test"); // SocketExceptionThe documentation says it is implemented with the operating system's name
resolution APIs (getaddrinfo on Windows, equivalents elsewhere), and that
entries in the hosts file are returned without querying DNS. That is why it
honors /etc/hosts, the search domains and mDNS, and also why it is limited
to what getaddrinfo returns: addresses. Measured on macOS, with the test
zone served only by my container:
textlocalhost: ::1,127.0.0.1 [7 ms] api.exemplo.test: SocketException: nodename nor servname provided, or not known [32 ms] _http._tcp.exemplo.test: SocketException: nodename nor servname provided, or not known [31 ms]
The system resolver does not know my zone, so api.exemplo.test fails, and a
name starting with _http._tcp is just another host name that has no address.
There is no overload to choose the server, to read a TTL or to ask for a
record type. The call also returns A and AAAA together, in the order the OS
chose.
DnsResolver: the typed API of .NET 11
DnsResolver and DnsResolverOptions are in System.Net (assembly
System.Net.NameResolution, no [Experimental] attribute, [UnsupportedOSPlatform("wasi")]).
Servers is an IList<IPEndPoint>, so a non-standard port is fine. Every
method returns a DnsResult<T> with ResponseCode, Records and
NegativeCacheTtl:
csharpusing var r = new DnsResolver(new DnsResolverOptions
{ Servers = { new IPEndPoint(IPAddress.Loopback, 6980) } });
var a = await r.ResolveAddressesAsync("api.exemplo.test", CancellationToken.None);
var srv = await r.ResolveSrvAsync("_http._tcp.exemplo.test", CancellationToken.None);
var txt = await r.ResolveTxtAsync("info.exemplo.test", CancellationToken.None);textA+AAAA: code=NoError negTtl=00:00:00 10.0.0.10 ttl=00:05:00 10.0.0.11 ttl=00:05:00 fd00::10 ttl=00:05:00 AAAA only: fd00::10 TXT: [v=1 | region=eu-central] ttl=00:05:00 MX: pref=10 mx1.exemplo.test CNAME: api.exemplo.test A via CNAME web: 10.0.0.10,10.0.0.11,fd00::10
The record types are readonly structs: AddressRecord (Address, Ttl),
SrvRecord, MxRecord (Exchange, Preference), TxtRecord (Values, a
list of strings, one per quoted chunk in the zone), CNameRecord, PtrRecord
and NsRecord. ResolveAddresses takes an optional AddressFamily (the AAAA
only line above) and follows the CNAME on its own. The static Dns.ResolveSrv,
ResolveTxt, ResolveMx and friends (plus Async variants) return the same
types but use the platform resolver configuration. I confirmed that: the static
Dns.ResolveSrvAsync("_http._tcp.exemplo.test") came back NxDomain with 0
records, because it asked the machine's own DNS server, not mine. Use the
instance API when you need to choose the server. The release notes say both
now work on Linux as well as Windows and macOS (docs only, not run here).
SRV: from records to a destination
textSRV: code=NoError prio=10 weight=60 a.exemplo.test:8080 ttl=00:05:00 addrs=[10.0.1.1] prio=10 weight=40 b.exemplo.test:8081 ttl=00:05:00 addrs=[10.0.1.2] prio=20 weight=100 backup.exemplo.test:9090 ttl=00:05:00 addrs=[10.0.1.3]
SrvRecord carries Target, Port, Priority, Weight, Ttl and
Addresses. The addresses came in the same response (CoreDNS logged a single
SRV query, no follow-up for a.exemplo.test), so one round trip gave host,
port and IP. The rule from RFC 2782: use only the lowest priority number that
is reachable; among equal priorities pick randomly in proportion to weight;
move to the next priority only when the whole group fails. The resolver
returns the records and leaves the choice to you:
csharpvar best = srv.Records.Min(x => x.Priority);
var group = srv.Records.Where(x => x.Priority == best).ToList();
var pick = Random.Shared.Next(group.Sum(x => x.Weight));
foreach (var c in group) { if (pick < c.Weight) return c; pick -= c.Weight; }Ten thousand picks with a fixed seed gave a=5984, b=4016 (weights 60 and 40)
and never backup, which is priority 20 and is the failover target. This is
the piece Dns.GetHostEntryAsync cannot give you: it has no notion of a port
or a weight. In ASP.NET Core and Aspire, the Microsoft.Extensions.ServiceDiscovery
package normally does this for HttpClient (see Aspire AppHost and ServiceDefaults
and HttpClient and IHttpClientFactory, which
measured the configuration-based provider). A DNS
SRV provider lives in the separate Microsoft.Extensions.ServiceDiscovery.Dns
package (AddDnsSrvServiceEndpointProvider, read from its XML docs, not run
here).
NXDOMAIN, "no data" and a server that never answers
The answer is part of the result, not an exception, so check ResponseCode:
textnope A: code=NxDomain records=0 negTtl=00:01:00 api TXT: code=NoError records=0 negTtl=00:01:00 _ftp SRV: code=NxDomain records=0 outside the zone: code=Refused records=0
NxDomain means the name does not exist. NoError with zero records means
the name exists but has no record of that type ("NODATA", here api has no
TXT), and treating the two the same hides bugs. NegativeCacheTtl is the
zone's SOA minimum (60 s in my zone), the time a caller may remember "not
found". Refused is CoreDNS declining a zone it does not serve. Failures of
the transport are exceptions:
textsilent server: TimeoutException: The operation has timed out. [9007 ms] closed port 6989: SocketException: Connection refused [0 ms] silent, then good server: NoError 3 records [9007 ms] silent, token 500ms: OperationCanceledException: The operation was canceled. [502 ms]
A server that receives and never answers cost 9 s before the
TimeoutException, and with the dead server listed first and a good one second
the call still took 9 s before succeeding: it exhausted its attempts on the
first server before moving on. DnsResolverOptions has only Servers, so no
timeout setting exists to lower that. Pass a CancellationToken with your own
deadline (500 ms above, cancelled after 502 ms), the same rule the
sockets concept applies to every network call.
No cache, no retry policy of its own
Five calls in a row for the same name took 4.19, 1.49, 1.77, 1.54 and 1.11 ms,
and the CoreDNS log showed every call arriving (A and AAAA queried separately,
so 5 calls meant 5 A and 5 AAAA queries). The result exposes TTLs but I saw no
caching in DnsResolver: if you resolve in a hot path, cache by Ttl
yourself, or you send two queries per call.
Book vs today
Older .NET texts show Dns.GetHostEntry as "the DNS API", and for SRV or TXT
point to DnsClient.NET or Heijden.DNS. Those libraries are still
there and I did not compare features with them, but since .NET 11 the base
library covers the common record types with a typed result and no dependency.
Dns.GetHostByName and Dns.Resolve are still exposed and marked [Obsolete]
("Use GetHostEntry instead"), so new code uses GetHostEntryAsync. The getaddrinfo path stays correct for "connect to this
name the way the machine would", because only it honors the hosts file and the
OS configuration.
Trade-offs
Dns.GetHostEntryAsyncversusDnsResolver. The first follows the OS (hosts file, search domains, VPN split DNS) and returns only addresses; the second returns every common record type with TTLs but ignores the hosts file and, with an instance, the OS server list. Connecting to a name: OS path. Reading SRV or TXT:DnsResolver.- You build the selection. The resolver returns SRV records; priority and weight logic (about 5 lines above) is yours, plus health checks. Use the service discovery package when you can.
- Failure is a code, not an exception. NXDOMAIN and
Refusedcome back as results, so a call that "worked" can hold zero records. Timeouts and refused ports are exceptions. - Nine seconds is a long default. Always pass a token with a deadline, and
do not put a dead server first in
Servers. - No cache. Every call is a network round trip (about 1 to 4 ms to a loopback container, more to a real server), so cache by TTL on hot paths.
- Local DNS has limits. Loopback measured nothing about real latency, UDP truncation or DNS over TCP, and I did not test Linux or Windows.
Documentation Links
- What's new in .NET 11 libraries, Microsoft Learn
- DnsResolver Class, Microsoft Learn
- DnsResolverOptions Class, Microsoft Learn
- DnsResult Struct, Microsoft Learn
- SrvRecord Struct, Microsoft Learn
- Dns.GetHostEntryAsync, Microsoft Learn
- Service discovery in .NET, Microsoft Learn
- RFC 2782, A DNS RR for specifying the location of services (DNS SRV), IETF