DNS, Connectivity, Ports, and Network Diagnostics

1. A network request crosses several independent layers

When an endpoint is “down,” the failure can occur before your application ever reaches HTTP. A hostname may fail to resolve, a route may be unavailable, a TCP connection may be refused, a firewall may silently drop packets, TLS may reject a certificate, or the application may return an HTTP error. Reliable troubleshooting separates those layers instead of repeatedly rerunning one command.

UDP is different from TCP: it has no connection handshake, so “port open” is not a universal question for UDP. This lesson focuses on safe DNS, ICMP, and TCP diagnostics.

2. DNS turns names into addresses

The Domain Name System (DNS) maps names such as example.com to IP addresses. An IPv4 address is 32 bits; IPv6 uses 128 bits. A host can legitimately resolve to multiple addresses, and the chosen address can vary by network, geography, or protocol family.

For a cross-platform baseline, .NET exposes DNS resolution directly. This avoids assuming that Windows modules such as DnsClient are installed.

$addresses = [System.Net.Dns]::GetHostAddresses('example.com')
$addresses | ForEach-Object {
    [pscustomobject]@{
        Address = $_.IPAddressToString
        Family  = $_.AddressFamily.ToString()
    }
}

Do not hard-code one resolved address as if it were permanent. DNS is deliberately dynamic.

3. Windows-specific DNS tooling is useful when available

On Windows, the DnsClient module provides Resolve-DnsName, which can query record types and specific DNS servers. It is not the portable PowerShell baseline for Linux/macOS. Detect it before use.

if (Get-Command Resolve-DnsName -ErrorAction SilentlyContinue) {
    Resolve-DnsName -Name 'example.com' -Type A |
        Select-Object Name,Type,IPAddress
} else {
    [System.Net.Dns]::GetHostAddresses('example.com') |
        Select-Object IPAddressToString,AddressFamily
}

4. ICMP answers a narrow reachability question

Test-Connection sends ICMP echo requests—the operation commonly called ping—and returns structured objects. ICMP can be blocked even while HTTPS works, so a failed ping is evidence, not proof that the application is unavailable.

$ping = Test-Connection -TargetName 'example.com' -Count 2 -TimeoutSeconds 2
$ping | Select-Object Address,Latency,Status

Use -Quiet only when a Boolean is genuinely the contract. During diagnosis, the richer object usually contains more useful evidence.

5. A TCP port identifies a listening service endpoint

A port is a transport-layer number used together with an IP address. HTTPS commonly listens on TCP 443, HTTP on TCP 80, and SSH on TCP 22. PowerShell 7.6 Test-Connection can test a TCP port directly and return detailed status, which makes it a portable choice.

$tcp = Test-Connection -TargetName 'example.com' -TcpPort 443 `
    -Count 1 -TimeoutSeconds 3 -Detailed
$tcp | Select-Object Target,Address,Port,Connected,Status,Latency

6. Test-NetConnection is a Windows path, not a universal cmdlet

Test-NetConnection belongs to the Windows NetTCPIP module. It can combine DNS, ping, TCP, and route information, but cross-platform scripts should not assume it exists.

if (Get-Command Test-NetConnection -ErrorAction SilentlyContinue) {
    Test-NetConnection -ComputerName 'example.com' -Port 443 -InformationLevel Detailed
} else {
    Test-Connection -TargetName 'example.com' -TcpPort 443 -Detailed -Count 1
}

7. DNS failure, refusal, and timeout mean different things

Error text varies by operating system and .NET runtime. Diagnose the layer from structured results and exceptions rather than matching one exact English sentence.

8. Turn diagnostics into a reusable health object

Operational automation is easier to compose when a check returns data rather than colored console text. The following function separates DNS and TCP observations and records failures without hiding them.

function Test-EndpointHealth {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)][string]$HostName,
        [ValidateRange(1,65535)][int]$Port = 443,
        [ValidateRange(1,30)][int]$TimeoutSeconds = 3
    )

    $resolved = @()
    $dnsError = $null
    try {
        $resolved = [System.Net.Dns]::GetHostAddresses($HostName)
    }
    catch {
        $dnsError = $_.Exception.Message
    }

    $tcpOk = $false
    if ($resolved.Count -gt 0) {
        $tcpOk = Test-Connection -TargetName $HostName -TcpPort $Port `
            -Count 1 -TimeoutSeconds $TimeoutSeconds -Quiet
    }

    [pscustomobject]@{
        HostName      = $HostName
        Port          = $Port
        Resolved      = $resolved.Count -gt 0
        Addresses     = @($resolved.IPAddressToString)
        TcpReachable  = $tcpOk
        DnsError      = $dnsError
        CheckedUtc    = [datetime]::UtcNow
    }
}

Test-EndpointHealth -HostName 'example.com' -Port 443

9. A diagnostic workflow should narrow the uncertainty

1. Confirm the exact hostname, port, and protocol expected by the application.
2. Resolve the hostname and record the returned address family/address set.
3. Test the intended transport port with a bounded timeout.
4. If transport succeeds, move upward to TLS/HTTP rather than continuing to ping.
5. If transport fails, inspect routing/firewall/listening-service evidence appropriate to the host.
6. Record timestamps and results so repeated tests can be compared.

10. Lab: build a small endpoint-health report

This lab uses the reserved documentation domain example.com and loopback. It does not manipulate packets, firewall rules, or privileged network state.

$targets = @(
    [pscustomobject]@{ Host='example.com'; Port=443 },
    [pscustomobject]@{ Host='localhost';   Port=443 }
)

$report = foreach ($target in $targets) {
    Test-EndpointHealth -HostName $target.Host -Port $target.Port -TimeoutSeconds 2
}

$report | Select-Object HostName,Port,Resolved,TcpReachable,Addresses,DnsError
$report | ConvertTo-Json -Depth 4

The localhost result depends on whether something is actually listening on TCP 443 on your machine. That variability is useful: the lesson is to distinguish “name resolved” from “service accepted a connection.”

11. Verification checklist

• You can describe DNS, IP addresses, TCP/UDP ports, and why they are separate layers.
• You can resolve a hostname without assuming Windows-only modules.
• You can use Test-Connection for ICMP and TCP-port testing.
• You know that ICMP failure does not prove HTTP failure.
• You can explain refusal versus timeout at a practical level.
• Your health check emits a structured object with timestamps and evidence.

12. Common mistakes and failure modes

• Rerunning ping forever: it tests only one layer and may be intentionally blocked.
• Assuming one DNS address is permanent: load balancing and failover can change answers.
• Calling Test-NetConnection everywhere: it creates a Windows-module dependency.
• Treating UDP like TCP: UDP has no connection handshake to prove “connected.”
• Returning only green/red text: downstream automation cannot reliably filter or aggregate it.

13. Knowledge check

14. Summary and next bridge

Network troubleshooting becomes reliable when you separate name resolution, transport reachability, and application behavior. PowerShell can model each observation as data. In Lesson 2, we move above TCP to HTTP itself: URIs, methods, status codes, headers, bodies, TLS, redirects, and timeouts.

15. Authoritative references

• Microsoft Learn — Test-Connection
• Microsoft Learn — Test-NetConnection (Windows NetTCPIP)
• Microsoft Learn — Resolve-DnsName (Windows DnsClient)