Basic Server

Minimal server: one HTTP listener (loopback:5000) + a single PowerShell route returning text.

Prerequisites: see Introduction.

Full source

File: pwsh/tutorial/examples/7.1-Basic-Server.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 = $env:PORT ?? 5000
)

# (Optional) Configure console logging so we can see events
New-KrLogger | Set-KrLoggerLevel -Value Debug |
    Add-KrSinkConsole |
    Register-KrLogger -Name 'console' -SetAsDefault | Out-Null

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

# Add a listener on the configured port and IP address
Add-KrEndpoint -Port $Port

# 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 and close all the loggers when the server stops
# This is equivalent to calling Close-KrLogger after Start-KrServer
Start-KrServer -CloseLogsOnExit

Step-by-step

  1. Server: New-KrServer creates a named instance.
  2. Listener: Add-KrEndpoint -Port 5000 -IPAddress Loopback binds HTTP.
  3. Commit: Enable-KrConfiguration applies staged configuration.
  4. Route: Add-KrMapRoute registers /hello using Write-KrTextResponse.
  5. Start: Start-KrServer begins processing (Ctrl+C to stop).
  6. Logging (optional): console logger shows Write-KrLog events.

Environment-based binding

If you omit -Port, -IPAddress, -HostName, and -Uri, Add-KrEndpoint can resolve the binding from environment variables. This is useful when the hosting platform injects the listen address or port.

$env:PORT = '8080'

New-KrServer -Name 'Endpoints Basic'
Add-KrEndpoint
Enable-KrConfiguration

You can also use ASPNETCORE_URLS:

$env:ASPNETCORE_URLS = 'http://localhost:5000'

New-KrServer -Name 'Endpoints Basic'
Add-KrEndpoint
Enable-KrConfiguration

Precedence is explicit parameters first, then ASPNETCORE_URLS, then PORT.

-PassThru for route endpoint specs

If you want to bind routes to a specific listener later, Add-KrEndpoint -PassThru returns endpoint spec strings that can be passed directly into Add-KrMapRoute -Endpoints.

New-KrServer -Name 'Endpoints Basic'
$endpointSpecs = Add-KrEndpoint -Port 5000 -PassThru
Enable-KrConfiguration

Add-KrMapRoute -Pattern '/hello' -Verbs Get -Endpoints $endpointSpecs -ScriptBlock {
    Write-KrTextResponse 'Hello from one listener only'
}

This is safer than manually writing "localhost:5000" or "127.0.0.1:5000" in the route definition.

Try it 

curl http://127.0.0.1:5000/hello
Invoke-WebRequest -Uri http://127.0.0.1:5000/hello | Select-Object -ExpandProperty Content

Expected: Hello from basic server.

References

Troubleshooting

Symptom Cause Fix
404 Not Found Wrong route pattern Ensure pattern starts with / and matches request
Port in use Another process bound to 5000 Use a different port (-Port 5001)
No logs shown Logger not default Add logger and -SetAsDefault

See also: Routes · Simple Logging

Previous / Next

Previous: Certificates Next: Multiple Listeners