Chilkat.Dns Class Overview
Chilkat.Dns provides DNS lookup and DNS record-query functionality. It allows an application to manage the nameservers used by Chilkat, perform DNS queries for common record types, configure DNS-over-TLS preference, and inspect diagnostic information when a query fails.
What the Class Is Used For
Use Chilkat.Dns when an application needs to query DNS records directly or customize the nameservers used by Chilkat for DNS lookups. The configured nameserver list is used globally by Chilkat DNS resolution across classes such as HTTP, Email, FTP, SSH, and others.
DNS Record Queries
Query record types such as A,
AAAA, MX,
TXT, NS,
SOA, CAA, and
ALIAS.
Nameserver Management
Add, remove, inspect, or restore the nameservers used by Chilkat for DNS
queries and domain-to-IP lookups.
DNS over TLS
Prefer or require DNS-over-TLS when nameservers are added with TLS support.
Timeout and Diagnostics
Control DNS query timeout behavior with MaxWaitMs
and inspect LastErrorText after failures.
Typical Workflow
- Optionally clear the current nameserver list with RemoveAllNameservers if the application wants to use a custom set of nameservers.
- Add one or more nameservers using AddNameserver. For DNS-over-TLS-capable nameservers, pass supportsTls = true.
- Set TlsPref if DNS-over-TLS should be preferred or required.
- Set MaxWaitMs to control how long a DNS query may wait for an answer.
- Call Query with a record type and domain name. The DNS answer is returned in a JsonObject.
- If the query fails or behaves unexpectedly, inspect LastErrorText for detailed diagnostic information.
Core Concepts
| Concept | Meaning | Important Members |
|---|---|---|
| Global Nameserver List | The nameservers configured through this class are used by Chilkat for DNS queries and domain-to-IP address lookups across Chilkat objects/classes. | AddNameserver, RemoveNameserver, RemoveAllNameservers, NumNameservers |
| Default Nameservers | Chilkat can use the default auto-assigned nameservers. These can be explicitly added back after custom changes. | AddDefaultNameservers |
| DNS Query Result | DNS answers are returned in a JsonObject, allowing applications to inspect structured record data. | Query |
| DNS over TLS | DNS queries can use TLS when nameservers are added with TLS support and TlsPref is configured to prefer or require TLS. | TlsPref, AddNameserver |
| Query Timeout | DNS lookups wait up to MaxWaitMs milliseconds for an answer. | MaxWaitMs |
| Diagnostics | Diagnostic text is available after method calls, including failed or unexpected DNS operations. | LastErrorText |
Properties
| Property | Purpose | Default / Notes |
|---|---|---|
| HeartbeatMs | Controls the interval, in milliseconds, between AbortCheck event callbacks. | Defaults to 0, meaning no AbortCheck callbacks are triggered. |
| LastErrorText | Provides detailed information about the last method call or property access. | Check this after failures or unexpected behavior. |
| MaxWaitMs | Maximum number of milliseconds to wait for a DNS query answer. | Default is 10000. A value of 0 waits indefinitely, but this is not recommended. Values below 1000 are also discouraged. |
| NumNameservers | Indicates how many nameservers are currently configured for Chilkat DNS queries and domain-to-IP address lookups. | Read-only. |
| TlsPref | Specifies the DNS-over-TLS preference. | 0 = no TLS, 1 = prefer TLS if possible, 2 = require TLS. Default is 0. |
| UncommonOptions | Catch-all property for uncommon or specialized options. | Defaults to the empty string and should usually remain empty. |
Nameserver Management
| Task | Method | Guidance |
|---|---|---|
| Add default nameservers | AddDefaultNameservers | Adds the default auto-assigned nameservers to the nameserver collection. |
| Add a custom nameserver | AddNameserver | Adds an IPv4 nameserver address. The supportsTls argument indicates whether that nameserver supports DNS over TLS. |
| Inspect a nameserver by index | GetNameserver | Returns the IP address of the Nth nameserver. Indexing begins at 0. |
| Remove a specific nameserver | RemoveNameserver | Removes the nameserver matching the supplied IPv4 address. |
| Remove all configured nameservers | RemoveAllNameservers | Clears the nameserver collection. If Chilkat later needs DNS resolution, auto-assigned nameserver IP addresses are automatically restored. |
Shared configuration:
Nameserver changes affect DNS queries and domain-to-IP lookups used by Chilkat
generally, not only the current Dns object.
DNS Querying
The primary lookup method is Query. It accepts a DNS record type, a domain, and a JsonObject that receives the structured answer.
| Record Type | Typical Meaning | Example Use |
|---|---|---|
| A | IPv4 address record. | Resolve a hostname to one or more IPv4 addresses. |
| AAAA | IPv6 address record. | Resolve a hostname to one or more IPv6 addresses. |
| MX | Mail exchanger record. | Find mail servers responsible for a domain. |
| TXT | Text record. | Read records used for SPF, DKIM, DMARC, verification tokens, and other text data. |
| NS | Name server record. | Find authoritative nameservers for a domain. |
| SOA | Start of Authority record. | Inspect authoritative zone metadata. |
| CAA | Certification Authority Authorization record. | Determine which certificate authorities are authorized to issue certificates. |
| ALIAS | Alias-style DNS record. | Query alias records where supported. |
Extensibility note:
The reference lists A,
AAAA, ALIAS,
CAA, MX,
NS, SOA, and
TXT. Additional record types can be added as needed.
DNS over TLS
DNS over TLS can be used when the application adds nameservers that support it. The DNS-over-TLS preference is controlled by TlsPref.
| TlsPref Value | Behavior | When to Use |
|---|---|---|
| 0 | No TLS is used for DNS queries. | Default behavior. Use when encrypted DNS is not required. |
| 1 | Prefer TLS-capable nameservers first. If none succeed, Chilkat falls back to UDP/TCP DNS. | Use when encrypted DNS is preferred but not mandatory. |
| 2 | Require TLS. Only TLS-capable nameservers are tried, and all DNS queries use TLS. | Use when DNS queries must be encrypted. |
Setup requirement:
To use DNS over TLS, first call AddNameserver once
for each nameserver and pass supportsTls = true.
DNS over TLS uses port 853.
Timeouts and Diagnostics
| Need | Member | Recommendation |
|---|---|---|
| Control DNS query wait time | MaxWaitMs | Use a reasonable timeout such as the default 10000 milliseconds. Avoid 0 unless an infinite wait is truly intended. |
| Allow AbortCheck callbacks | HeartbeatMs | Set to a nonzero interval when the calling environment supports event callbacks and the application wants an opportunity to abort. |
| Diagnose failures | LastErrorText | Check after a failed query or unexpected result. Diagnostic text is available regardless of whether the last call succeeded or failed. |
Best Practices
| Recommendation | Reason |
|---|---|
| Use MaxWaitMs instead of waiting indefinitely. | DNS infrastructure can fail or become unreachable. A finite timeout prevents the application from hanging indefinitely. |
| Keep nameserver changes deliberate. | The configured nameserver collection is shared by Chilkat DNS operations across multiple classes. |
| Call RemoveAllNameservers before adding a custom-only nameserver set. | This avoids mixing default and custom DNS servers unintentionally. |
| Use AddDefaultNameservers to restore default behavior explicitly. | This returns Chilkat to using the default auto-assigned DNS servers. |
| Set TlsPref = 1 when encrypted DNS is preferred but fallback is acceptable. | This tries TLS-capable nameservers first while preserving compatibility if TLS lookup fails. |
| Set TlsPref = 2 only when TLS-capable nameservers are configured. | Requiring TLS without TLS-capable nameservers prevents ordinary UDP/TCP DNS fallback. |
| Inspect DNS answers through the returned JsonObject. | Structured JSON output is easier to parse reliably than raw DNS text. |
| Check LastErrorText after failures. | It provides the most useful diagnostic details for support and troubleshooting. |
Summary
Chilkat.Dns is a focused class for DNS configuration and DNS record querying. It allows applications to control the nameservers used by Chilkat, query common DNS record types into JSON, configure DNS-over-TLS preference, set DNS query timeouts, and obtain useful diagnostics through LastErrorText.
Because nameserver settings affect DNS resolution across Chilkat classes, treat nameserver changes as application-wide configuration rather than object-local state.