URI Endpoint

Demonstrates using a pre-built System.Uri with Add-KrEndpoint -Uri instead of separately specifying -Port, -IPAddress, and related parameters. This can simplify scenarios where the endpoint is already expressed as a string or comes from configuration.

Full source

File: pwsh/tutorial/examples/7.7-Uri-Endpoint.ps1

<#
    Sample Kestrun Server - Basic Server
    This script demonstrates the minimal steps to run a Kestrun server
    with a single HTTP listener and one PowerShell route.
    FileName: 7.1-Basic-Server.ps1
#>
param(
    [int]$Port = 5000,
    [IPAddress]$IPAddress = [IPAddress]::Loopback
)
$uri = [uri]::new("http://$($IPAddress.ToString()):$Port")
# (Optional) Configure console logging so we can see events
New-KrLogger |
    Add-KrSinkConsole |
    Register-KrLogger -Name 'console' -SetAsDefault | Out-Null

# Create a new Kestrun server
New-KrServer -Name 'Endpoints Basic'

# Add a listener on the specified port and IP address
Add-KrEndpoint -Uri $uri

# Enable Kestrun configuration
Enable-KrConfiguration

# Map the route
Add-KrMapRoute -Verbs Get -Pattern '/hello' -ScriptBlock {
    Write-KrLog -Level Information -Message 'Processing /hello request'
    Write-KrTextResponse -InputObject 'Hello from basic server' -StatusCode 200
}

# Initial informational log
Write-KrLog -Level Information -Message 'Server {Name} configured.' -Values 'Endpoints Basic'

# Start the server asynchronously
Start-KrServer -CloseLogsOnExit

When to use -Uri

  • You receive endpoints as strings (e.g. JSON/YAML config) and want a single parse step.
  • You need IPv6 loopback (http://[::1]:5000) or custom host binding expressed directly.
  • You want to reduce positional parameter ambiguity in scripts.

Add-KrEndpoint -Uri will infer scheme (HTTP/HTTPS) and port from the provided System.Uri instance. For HTTPS you still need either a certificate (-CertPath, -Certificate) or -SelfSignedCert.

Step-by-step

  1. Configure optional console logger.
  2. Create the server.
  3. Add a listener with -Uri ([uri]::new('http://localhost:5000')) and override address family (example shows InterNetworkV6).
  4. Enable configuration to lock in server + listener.
  5. Map a /hello route that writes a text response.
  6. Log a startup message.
  7. Start the server.

Try it 

Invoke-WebRequest -Uri 'http://localhost:5000/hello'

Should return body:

Hello from basic server

Or with curl:

curl http://localhost:5000/hello

IPv6 example 

Add-KrEndpoint -Uri ([uri]::new('http://[::1]:5005'))

References

Troubleshooting

Symptom Cause Fix
404 on /hello Route added too early Ensure runtime then Enable-KrConfiguration before mapping
Port already in use Another process bound Change port in the URI or stop conflicting process
IPv6 not reachable OS/network disabled IPv6 Use IPv4 (127.0.0.1) or enable IPv6 stack
HTTPS fails (no cert) No certificate supplied Add -SelfSignedCert or specify a certificate parameters

See also: Basic Server · Multiple Listeners · HTTPS

Previous / Next