Skip to content

DnsClientX is an async C# library for DNS over UDP, TCP, HTTPS (DoH), and TLS (DoT). It also has a PowerShell module that can be used to query DNS records. It provides a simple way to query DNS records using multiple DNS providers. It supports multiple DNS record types and parallel queries.

Notifications You must be signed in to change notification settings

EvotecIT/DnsClientX

Repository files navigation

DnsClientX - DnsClient for .NET and PowerShell

DnsClientX is available as NuGet from the Nuget Gallery and as PowerShell module from PSGallery

nuget downloads nuget version

What it's all about

DnsClientX is an async C# library for DNS over UDP, TCP, HTTPS (DoH), and TLS (DoT). It also has a PowerShell module that can be used to query DNS records. It provides a simple way to query DNS records using multiple DNS providers. It supports multiple DNS record types and parallel queries. It's available for .NET 6, .NET 7, .NET 8, .NET Standard 2.0, and .NET 4.7.2.

It provides querying multiple DNS Providers.

If you want to learn about DNS:

Warning

We try to unify the responses as much as possible for common use cases by translating on the fly. This is because different providers do not store it always the same way. If you find disprepencies please open an issue or better pull request.

Supported .NET Versions

This library supports multiple NET versions:

  • .NET 6
    • No dependencies
  • .NET 7
    • No dependencies
  • .NET 8
    • No dependencies
  • .NET Standard 2.0
    • System.Text.Json
  • .NET 4.7.2
    • System.Text.Json

Build Status

Platform Status Test Report Code Coverage .NET
Windows .NET 4.7.2, NET 4.8, .NET 6.0, .NET 7.0, .NET 8.0, .NET Standard 2.0
Linux .NET 6.0, .NET 7.0, .NET Standard 2.0, .NET 8.0
MacOs .NET 6.0, .NET 7.0, .NET Standard 2.0, .NET 8.0

Features

  • Supports multiple built-in DNS Providers (System, Cloudflare, Google, Quad9, OpenDNS, etc.)
  • Supports both JSON and Wireformat
  • Supports DNS over HTTPS (DoH) using GET and POST methods
  • Supports DNS over TLS (DoT)
  • Supports DNS over UDP, and switches to TCP if needed
  • Supports DNS over TCP
  • Supports DNSSEC
  • Supports multiple DNS record types
  • Supports parallel queries
  • No external dependencies on .NET 6, .NET 7 and .NET 8
  • Minimal dependencies on .NET Standard 2.0 and .NET 4.7.2

TO DO

Important

This library is still in development and there are things that need to be done, tested and fixed. If you would like to help, please do so by opening an issue or a pull request. Things may and will change, as I'm not quite sure what I am doing :-)

  • Add more providers
  • Add more tests
  • Go thru all additional parameters and make sure they have proper responses

Usage in .NET

There are multiple ways to use DnsClientX.

using DnsClientX;

Below are some examples.

Querying DNS over HTTPS via provided hostname that uses /dns-query endpoint and JSON format

var data = await ClientX.QueryDns("evotec.pl", DnsRecordType.A, "1.1.1.1", DnsRequestFormat.JSON);
data.Answers

Querying DNS over HTTPS via defined endpoint using QueryDns

var data = await ClientX.QueryDns("evotec.pl", DnsRecordType.A, DnsEndpoint.CloudflareWireFormat);
data.Answers

Querying DNS over HTTPS via full Uri using QueryDNS and JSON format

var data = await ClientX.QueryDns("evotec.pl", DnsRecordType.A, new Uri("https://1.1.1.1/dns-query"), DnsRequestFormat.JSON);
data.Answers

Querying DNS over HTTPS via defined endpoint using ResolveAll

var Client = new ClientX(DnsEndpoint.OpenDNS);
var data = await Client.ResolveAll(domainName, type);
data

Querying DNS over HTTPS with single endpoint using ResolveAll

var Client = new ClientX(DnsEndpoint.OpenDNS);
var data = await Client.ResolveAll(domainName, type);
data

Querying DNS over HTTPS with multiple endpoints using Resolve

var dnsEndpoints = new List<DnsEndpoint> {
    DnsEndpoint.Cloudflare,
    DnsEndpoint.CloudflareSecurity,
    DnsEndpoint.CloudflareFamily,
    DnsEndpoint.CloudflareWireFormat,
    DnsEndpoint.Google,
    DnsEndpoint.Quad9,
    DnsEndpoint.Quad9ECS,
    DnsEndpoint.Quad9Unsecure,
    DnsEndpoint.OpenDNS,
    DnsEndpoint.OpenDNSFamily
};

// List of endpoints to exclude
var excludeEndpoints = new List<DnsEndpoint> {

};

var domains = new List<string> {
    "github.com",
    "microsoft.com",
    "evotec.xyz"
};

// List of record types to query
var recordTypes = new List<DnsRecordType> {
    DnsRecordType.A,
    DnsRecordType.TXT,
    DnsRecordType.AAAA,
    DnsRecordType.MX,
    DnsRecordType.NS,
    DnsRecordType.SOA,
    DnsRecordType.DNSKEY,
    DnsRecordType.NSEC
};

foreach (var endpoint in dnsEndpoints) {
    if (excludeEndpoints.Contains(endpoint)) {
        continue; // Skip this iteration if the endpoint is in the exclude list
    }

    // Create a new client for each endpoint
    var client = new ClientX(endpoint) {
        Debug = false
    };

    foreach (var domain in domains) {
        foreach (var recordType in recordTypes) {
            DnsResponse? response = await client.Resolve(domain, recordType);
            response.DisplayToConsole();
        }
    }
}

Usage in PowerShell

DnsClientX is also available as a PowerShell module. Below are some examples.

Resolve-DnsQuery -Name 'evotec.pl' -Type A | Format-Table
Resolve-DnsQuery -Name 'evotec.pl' -Type A -DnsProvider Cloudflare -Verbose | Format-Table
Resolve-DnsQuery -Name 'evotec.pl' -Type TXT -DnsProvider System -Verbose | Format-Table
Resolve-DnsQuery -Name 'github.com', 'evotec.pl', 'google.com' -Type TXT -DnsProvider System -Verbose | Format-Table

It can also deliver more detailed information.

$Output = Resolve-DnsQuery -Name '_25._tcp.mail.ietf.org' -Type TLSA -DnsProvider Cloudflare -Verbose -FullResponse
$Output.Questions | Format-Table
$Output.AnswersMinimal | Format-Table

$Output = Resolve-DnsQuery -Name 'github.com', 'evotec.pl', 'google.com' -Type TXT -DnsProvider Google -Verbose -FullResponse
$Output.Questions | Format-Table
$Output.AnswersMinimal | Format-Table

$Output = Resolve-DnsQuery -Name 'github.com', 'evotec.pl', 'google.com' -Type TXT -DnsProvider Cloudflare -Verbose -FullResponse
$Output.Questions | Format-Table
$Output.AnswersMinimal | Format-Table

$Output = Resolve-DnsQuery -Name 'github.com', 'evotec.pl', 'google.com' -Type TXT, A -Verbose -Server "192.168.241.5" -FullResponse
$Output.Questions | Format-Table
$Output.AnswersMinimal | Format-Table

Please share with the community

Please consider sharing a post about DnsClientX and the value it provides. It really does help!

Share on reddit Share on hacker news Share on twitter Share on facebook Share on linkedin

Credits

This project general idea is based on DnsOverHttps by @akac which was an inspiration for DnsClientX.

Other libraries

  • DnsClient.NET - DnsClient is a simple yet very powerful and high performant open source library for the .NET Framework to do DNS lookups. If you need standard DNS support - this one is for you.
  • DnsOverHttps - DnsOverHttps is a simple yet very powerful and high performant open source library for the .NET Framework to do DNS lookups over HTTPS using Cloudflare. If you only need Cloudflare support and target newer .NET versions - this one is for you.
  • DinoDNS - another DNS library with a lot of features.

About

DnsClientX is an async C# library for DNS over UDP, TCP, HTTPS (DoH), and TLS (DoT). It also has a PowerShell module that can be used to query DNS records. It provides a simple way to query DNS records using multiple DNS providers. It supports multiple DNS record types and parallel queries.

Topics

Resources

Stars

Watchers

Forks