DnsResolver

0.1

en-US/DnsResolver.dll-Help.xml

<?xml version="1.0" encoding="utf-8"?>
<helpItems xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" schema="maml" xmlns="http://msh">
  <command:command>
    <command:details>
      <command:name>Resolve-DnsRecord</command:name>
      <maml:description>
        <maml:para>Resolves DNS records for one or more names using the cross-platform .NET DNS resolver.</maml:para>
      </maml:description>
      <command:verb>Resolve</command:verb>
      <command:noun>DnsRecord</command:noun>
    </command:details>
    <maml:description>
      <maml:para>The `Resolve-DnsRecord` cmdlet queries DNS servers for records of the requested types by using `System.Net.DnsResolver`, which is available in .NET 11 on Windows, Linux, and macOS.</maml:para>
      <maml:para>When `-Type` is omitted, the cmdlet queries A and AAAA records. When the name is an IP address, it performs a reverse (PTR) lookup instead.</maml:para>
      <maml:para>Each record is returned as a typed object that derives from `DnsResolver.DnsRecord` and exposes `Name`, `Type`, `Ttl`, and `Data`, plus properties specific to the record type.</maml:para>
      <maml:para>DNS failures such as NXDOMAIN or SERVFAIL are written as non-terminating errors. The exception is a `DnsResolver.DnsResponseException` whose `ResponseCode` property contains the DNS response code. An NXDOMAIN response is reported once per name, even when several record types were requested.</maml:para>
      <maml:para>Queries for all names and record types run concurrently, up to `-ThrottleLimit` at a time. Results are written in input order.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Resolve-DnsRecord</maml:name>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>Name</maml:name>
          <maml:description>
            <maml:para>The DNS names to resolve. When a value is an IP address and `-Type` is not specified, a reverse
(PTR) lookup is performed.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.String[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>Server</maml:name>
          <maml:description>
            <maml:para>The DNS servers to query instead of the system-configured servers. Accepts an IP address
(`1.1.1.1`), an IP address and port (`1.1.1.1:53`, `[2606:4700::1111]:53`), or a host name
(`dns.google`), which is resolved with the system resolver. The default port is 53.</maml:para>
            <maml:para>On Windows, only port 53 is supported. Specifying another port causes a terminating error.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>ThrottleLimit</maml:name>
          <maml:description>
            <maml:para>The maximum number of DNS queries that run at the same time, from 1 to 256. The default is 16.
Queries for all names and record types run concurrently, but results are always written in input
order.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Int32</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>TimeoutSec</maml:name>
          <maml:description>
            <maml:para>The maximum time, in seconds, to wait for each query, from 1 to 3600. A query that times out writes
a non-terminating `System.TimeoutException` error. By default, the resolver's own timeout applies.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Int32</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none">
          <maml:name>Type</maml:name>
          <maml:description>
            <maml:para>The record types to query. When omitted, A and AAAA records are queried, or PTR when the name is
an IP address. When both A and AAAA are specified, they are resolved in a single query.</maml:para>
            <maml:para>`All` queries every applicable type concurrently: A, AAAA, CNAME, MX, NS, and TXT, plus SRV for
service names that start with an underscore, or only PTR for IP addresses and `.arpa` names. It
can be combined with other types.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">DnsResolver.DnsRecordType[]</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
        <maml:name>Name</maml:name>
        <maml:description>
          <maml:para>The DNS names to resolve. When a value is an IP address and `-Type` is not specified, a reverse
(PTR) lookup is performed.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.String[]</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Server</maml:name>
        <maml:description>
          <maml:para>The DNS servers to query instead of the system-configured servers. Accepts an IP address
(`1.1.1.1`), an IP address and port (`1.1.1.1:53`, `[2606:4700::1111]:53`), or a host name
(`dns.google`), which is resolved with the system resolver. The default port is 53.</maml:para>
          <maml:para>On Windows, only port 53 is supported. Specifying another port causes a terminating error.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>ThrottleLimit</maml:name>
        <maml:description>
          <maml:para>The maximum number of DNS queries that run at the same time, from 1 to 256. The default is 16.
Queries for all names and record types run concurrently, but results are always written in input
order.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.Int32</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>TimeoutSec</maml:name>
        <maml:description>
          <maml:para>The maximum time, in seconds, to wait for each query, from 1 to 3600. A query that times out writes
a non-terminating `System.TimeoutException` error. By default, the resolver's own timeout applies.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.Int32</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none">
        <maml:name>Type</maml:name>
        <maml:description>
          <maml:para>The record types to query. When omitted, A and AAAA records are queried, or PTR when the name is
an IP address. When both A and AAAA are specified, they are resolved in a single query.</maml:para>
          <maml:para>`All` queries every applicable type concurrently: A, AAAA, CNAME, MX, NS, and TXT, plus SRV for
service names that start with an underscore, or only PTR for IP addresses and `.arpa` names. It
can be combined with other types.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">DnsResolver.DnsRecordType[]</command:parameterValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes>
      <command:inputType>
        <dev:type>
          <dev:name>System.String</dev:name>
        </dev:type>
        <maml:description>
          <maml:para>You can pipe DNS names to this cmdlet.</maml:para>
        </maml:description>
      </command:inputType>
      <command:inputType>
        <dev:type>
          <dev:name>System.String</dev:name>
        </dev:type>
        <maml:description>
          <maml:para>You can pipe objects that have a `Name`, `HostName`, or `ComputerName` property.</maml:para>
        </maml:description>
      </command:inputType>
    </command:inputTypes>
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <dev:name>DnsResolver.DnsRecord</dev:name>
        </dev:type>
        <maml:description>
          <maml:para>The base type of all records. The actual type depends on the record:
 
- `DnsResolver.AddressRecord` (A, AAAA): `IPAddress`
- `DnsResolver.CNameRecord`: `CanonicalName`
- `DnsResolver.MxRecord`: `Exchange`, `Preference`
- `DnsResolver.NsRecord`: `NameServer`
- `DnsResolver.PtrRecord`: `HostName`
- `DnsResolver.SrvRecord`: `Target`, `Port`, `Priority`, `Weight`, `Addresses`
- `DnsResolver.TxtRecord`: `Values`, `Text`</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para>Requires PowerShell 7.7 or later running on .NET 11.
 
Press Ctrl+C to cancel a query in progress.</maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- Example 1: Resolve the addresses of a host ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
Resolve-DnsRecord -Name github.com
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```Output
Name Type TTL Data
---- ---- --- ----
github.com A 60 140.82.121.3
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Queries A and AAAA records with the system-configured DNS servers.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 2: Query several record types against a specific server ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
Resolve-DnsRecord -Name google.com -Type MX, NS, TXT -Server 1.1.1.1
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Queries MX, NS, and TXT records from Cloudflare's public resolver.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 3: Query all record types for a name ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
Resolve-DnsRecord -Name google.com -Type All
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Queries A, AAAA, CNAME, MX, NS, and TXT records concurrently and returns every record found.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 4: Perform a reverse lookup ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
Resolve-DnsRecord -Name 1.1.1.1
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```Output
Name Type TTL Data
---- ---- --- ----
1.1.1.1 PTR 1800 one.one.one.one
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>An IP address is resolved with a PTR query when `-Type` is not specified.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 5: Resolve names from the pipeline and use typed properties ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
'contoso.com', 'fabrikam.com' | Resolve-DnsRecord -Type MX |
    Sort-Object Preference |
    Select-Object Name, Preference, Exchange
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>MX records expose `Exchange` and `Preference` properties that can be sorted and selected.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 6: Find the endpoints of a service ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
Resolve-DnsRecord -Name _ldap._tcp.contoso.com -Type SRV | Select-Object Target, Port, Priority, Weight
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>SRV records expose `Target`, `Port`, `Priority`, `Weight`, and `Addresses`.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 7: Handle a nonexistent name ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
Resolve-DnsRecord -Name does-not-exist.invalid -ErrorAction SilentlyContinue -ErrorVariable dnsError
$dnsError[0].Exception.ResponseCode
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```Output
NxDomain
```</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>Test-DnsRecord</maml:linkText>
        <command:uri>Test-DnsRecord.md</command:uri>
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>Test-DnsRecord</command:name>
      <maml:description>
        <maml:para>Tests whether DNS names resolve to at least one record.</maml:para>
      </maml:description>
      <command:verb>Test</command:verb>
      <command:noun>DnsRecord</command:noun>
    </command:details>
    <maml:description>
      <maml:para>The `Test-DnsRecord` cmdlet returns `$true` for each name that resolves with a NOERROR response and at least one record of the requested type, and `$false` otherwise.</maml:para>
      <maml:para>DNS failures and timeouts return `$false` instead of writing errors. Use `-Verbose` to see the response code or failure reason. An invalid `-Server` value still causes a terminating error.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Test-DnsRecord</maml:name>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>Name</maml:name>
          <maml:description>
            <maml:para>The DNS names to test. When a value is an IP address and `-Type` is not specified, a reverse
(PTR) lookup is tested.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="true">System.String[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>Server</maml:name>
          <maml:description>
            <maml:para>The DNS servers to query instead of the system-configured servers. Accepts an IP address
(`1.1.1.1`), an IP address and port (`1.1.1.1:53`, `[2606:4700::1111]:53`), or a host name
(`dns.google`), which is resolved with the system resolver. The default port is 53.</maml:para>
            <maml:para>On Windows, only port 53 is supported. Specifying another port causes a terminating error.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>ThrottleLimit</maml:name>
          <maml:description>
            <maml:para>The maximum number of DNS queries that run at the same time, from 1 to 256. The default is 16.
Names are tested concurrently, but results are always written in input order.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Int32</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>TimeoutSec</maml:name>
          <maml:description>
            <maml:para>The maximum time, in seconds, to wait for each query, from 1 to 3600. A query that times out
returns `$false`. By default, the resolver's own timeout applies.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Int32</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none">
          <maml:name>Type</maml:name>
          <maml:description>
            <maml:para>The record type to test for. When omitted, the name passes if it has either an A or AAAA record,
or a PTR record when the name is an IP address.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Nullable`1[DnsResolver.DnsRecordType]</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
        <maml:name>Name</maml:name>
        <maml:description>
          <maml:para>The DNS names to test. When a value is an IP address and `-Type` is not specified, a reverse
(PTR) lookup is tested.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.String[]</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Server</maml:name>
        <maml:description>
          <maml:para>The DNS servers to query instead of the system-configured servers. Accepts an IP address
(`1.1.1.1`), an IP address and port (`1.1.1.1:53`, `[2606:4700::1111]:53`), or a host name
(`dns.google`), which is resolved with the system resolver. The default port is 53.</maml:para>
          <maml:para>On Windows, only port 53 is supported. Specifying another port causes a terminating error.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>ThrottleLimit</maml:name>
        <maml:description>
          <maml:para>The maximum number of DNS queries that run at the same time, from 1 to 256. The default is 16.
Names are tested concurrently, but results are always written in input order.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.Int32</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>TimeoutSec</maml:name>
        <maml:description>
          <maml:para>The maximum time, in seconds, to wait for each query, from 1 to 3600. A query that times out
returns `$false`. By default, the resolver's own timeout applies.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.Int32</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none">
        <maml:name>Type</maml:name>
        <maml:description>
          <maml:para>The record type to test for. When omitted, the name passes if it has either an A or AAAA record,
or a PTR record when the name is an IP address.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.Nullable`1[DnsResolver.DnsRecordType]</command:parameterValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes>
      <command:inputType>
        <dev:type>
          <dev:name>System.String</dev:name>
        </dev:type>
        <maml:description>
          <maml:para>You can pipe DNS names to this cmdlet.</maml:para>
        </maml:description>
      </command:inputType>
      <command:inputType>
        <dev:type>
          <dev:name>System.String</dev:name>
        </dev:type>
        <maml:description>
          <maml:para>You can pipe objects that have a `Name`, `HostName`, or `ComputerName` property.</maml:para>
        </maml:description>
      </command:inputType>
    </command:inputTypes>
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <dev:name>System.Boolean</dev:name>
        </dev:type>
        <maml:description>
          <maml:para>One value per input name: `$true` if the name resolved to at least one record, otherwise `$false`.</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para>Requires PowerShell 7.7 or later running on .NET 11.</maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- Example 1: Test whether a host name resolves ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
Test-DnsRecord -Name github.com
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```Output
True
```</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 2: Test several names from the pipeline ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
'github.com', 'does-not-exist.invalid' | Test-DnsRecord
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```Output
True
False
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>One Boolean is returned per name, in input order.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 3: Test whether a domain accepts mail ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
if (Test-DnsRecord -Name contoso.com -Type MX -Server 1.1.1.1 -TimeoutSec 5) {
    'contoso.com has MX records'
}
```</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>Resolve-DnsRecord</maml:linkText>
        <command:uri>Resolve-DnsRecord.md</command:uri>
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
</helpItems>