# michaco/dnsclient.net architecture

> Architecture diagram of the GitHub repository michaco/dnsclient.net, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/michaco/dnsclient.net
- Repository: https://github.com/michaco/dnsclient.net

## Overview

DnsClient.NET is a .NET DNS lookup library. An application creates or configures a LookupClient, submits a typed query, and receives DNS records and response metadata. LookupClient owns server selection, retries, caching, and transport dispatch; message handlers encode requests and parse replies over UDP or TCP. Name-server auto-discovery and the library’s broad DNS record support are additional capabilities. Relationships among core modules are based on the README, excerpts, and SOURCE INDEX references; unsampled internals are not assumed beyond those references.

Main entry points: [`src/DnsClient/LookupClient.cs`](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/LookupClient.cs) (Lookup client), [`src/DnsClient/DnsMessageHandler.cs`](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsMessageHandler.cs) (Message handler), [`src/DnsClient/NameServer.cs`](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/NameServer.cs) (Name servers), [`src/DnsClient/DnsRequestMessage.cs`](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsRequestMessage.cs) (Request message)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Query API"]
  node_lookup["Lookup client<br/>[LookupClient.cs]"]
  node_queryapi["Query API<br/>[IDnsQuery.cs]"]
  node_queryextensions["Query extensions"]
  node_options["Query options<br/>[DnsQueryOptions.cs]"]
end

subgraph group_resolve["Resolution"]
  node_nameservers["Name servers<br/>[NameServer.cs]"]
  node_platformconfig["Platform DNS config"]
  node_cache["Response cache<br/>[ResponseCache.cs]"]
end

subgraph group_wire["DNS Protocol"]
  node_request["Request message"]
  node_question["DNS question<br/>[DnsQuestion.cs]"]
  node_messagehandler["Message handler"]
  node_udp["UDP transport"]
  node_tcp["TCP transport"]
end

subgraph group_records["Responses and Records"]
  node_responsemessage["Response message"]
  node_response["Query response"]
  node_recordfactory["Record factory"]
  node_recordtypes["DNS resource records"]
end

node_application(("Application"))
node_dnsserver(("DNS server"))

node_application -->|"queries"| node_lookup
node_lookup -->|"implements"| node_queryapi
node_queryextensions -->|"extends"| node_queryapi
node_lookup -->|"uses settings"| node_options
node_lookup -->|"selects servers"| node_nameservers
node_nameservers -->|"discovers from"| node_platformconfig
node_lookup -->|"checks cache"| node_cache
node_lookup -->|"builds request"| node_request
node_request -->|"contains"| node_question
node_lookup -->|"dispatches"| node_messagehandler
node_messagehandler -->|"uses transport"| node_udp
node_messagehandler -->|"uses transport"| node_tcp
node_udp -.->|"sends query"| node_dnsserver
node_tcp -.->|"sends query"| node_dnsserver
node_messagehandler -->|"parses reply"| node_responsemessage
node_messagehandler -->|"decodes records"| node_recordfactory
node_recordfactory -.->|"creates records"| node_recordtypes
node_responsemessage -->|"projects result"| node_response
node_response -->|"returns records"| node_application

click node_lookup "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/LookupClient.cs"
click node_queryapi "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/IDnsQuery.cs"
click node_queryextensions "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsQueryExtensions.cs"
click node_options "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsQueryOptions.cs"
click node_nameservers "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/NameServer.cs"
click node_platformconfig "https://github.com/michaco/dnsclient.net/tree/dev/src/DnsClient/Interop"
click node_cache "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/ResponseCache.cs"
click node_request "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsRequestMessage.cs"
click node_question "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsQuestion.cs"
click node_messagehandler "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsMessageHandler.cs"
click node_udp "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsUdpMessageHandler.cs"
click node_tcp "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsTcpMessageHandler.cs"
click node_responsemessage "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsResponseMessage.cs"
click node_response "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsQueryResponse.cs"
click node_recordfactory "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsRecordFactory.cs"
click node_recordtypes "https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/Protocol/DnsResourceRecord.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lookup,node_queryapi,node_queryextensions,node_options toneBlue
class node_nameservers,node_platformconfig,node_cache toneAmber
class node_request,node_question,node_messagehandler,node_udp,node_tcp,node_dnsserver toneMint
class node_responsemessage,node_response,node_recordfactory,node_recordtypes toneRose
class node_application toneIndigo
```

## Components

### Query API

- [Lookup client](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/LookupClient.cs): `src/DnsClient/LookupClient.cs`
- [Query API](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/IDnsQuery.cs): `src/DnsClient/IDnsQuery.cs`
- [Query extensions](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsQueryExtensions.cs): `src/DnsClient/DnsQueryExtensions.cs`
- [Query options](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsQueryOptions.cs): `src/DnsClient/DnsQueryOptions.cs`

### Resolution

- [Name servers](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/NameServer.cs): `src/DnsClient/NameServer.cs`
- [Platform DNS config](https://github.com/michaco/dnsclient.net/tree/dev/src/DnsClient/Interop): `src/DnsClient/Interop`
- [Response cache](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/ResponseCache.cs): `src/DnsClient/ResponseCache.cs`

### DNS Protocol

- [Request message](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsRequestMessage.cs): `src/DnsClient/DnsRequestMessage.cs`
- [DNS question](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsQuestion.cs): `src/DnsClient/DnsQuestion.cs`
- [Message handler](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsMessageHandler.cs): `src/DnsClient/DnsMessageHandler.cs`
- [UDP transport](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsUdpMessageHandler.cs): `src/DnsClient/DnsUdpMessageHandler.cs`
- [TCP transport](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsTcpMessageHandler.cs): `src/DnsClient/DnsTcpMessageHandler.cs`

### Responses and Records

- [Response message](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsResponseMessage.cs): `src/DnsClient/DnsResponseMessage.cs`
- [Query response](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsQueryResponse.cs): `src/DnsClient/DnsQueryResponse.cs`
- [Record factory](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/DnsRecordFactory.cs): `src/DnsClient/DnsRecordFactory.cs`
- [DNS resource records](https://github.com/michaco/dnsclient.net/blob/dev/src/DnsClient/Protocol/DnsResourceRecord.cs): `src/DnsClient/Protocol/DnsResourceRecord.cs`

### Other components

- **Application**
- **DNS server**

## Connections

- Application → Lookup client: queries
- Lookup client → Query API: implements (evidence: `src/DnsClient/LookupClient.cs`)
- Query extensions → Query API: extends (evidence: `src/DnsClient/DnsQueryExtensions.cs`)
- Lookup client → Query options: uses settings (evidence: `src/DnsClient/LookupClient.cs`)
- Lookup client → Name servers: selects servers (evidence: `src/DnsClient/LookupClient.cs`)
- Name servers → Platform DNS config: discovers from (evidence: `src/DnsClient/NameServer.cs`)
- Lookup client → Response cache: checks cache (evidence: `src/DnsClient/LookupClient.cs`)
- Lookup client → Request message: builds request (evidence: `src/DnsClient/LookupClient.cs`)
- Request message → DNS question: contains (evidence: `src/DnsClient/DnsRequestMessage.cs`)
- Lookup client → Message handler: dispatches (evidence: `src/DnsClient/LookupClient.cs`)
- Message handler → UDP transport: uses transport (evidence: `src/DnsClient/DnsUdpMessageHandler.cs`)
- Message handler → TCP transport: uses transport (evidence: `src/DnsClient/DnsTcpMessageHandler.cs`)
- UDP transport → DNS server: sends query (evidence: `src/DnsClient/DnsUdpMessageHandler.cs`)
- TCP transport → DNS server: sends query (evidence: `src/DnsClient/DnsTcpMessageHandler.cs`)
- Message handler → Response message: parses reply (evidence: `src/DnsClient/DnsMessageHandler.cs`)
- Message handler → Record factory: decodes records (evidence: `src/DnsClient/DnsMessageHandler.cs`)
- Record factory → DNS resource records: creates records
- Response message → Query response: projects result (evidence: `src/DnsClient/DnsQueryResponse.cs`)
- Query response → Application: returns records
