Route Parameters & Request Data

Read data from different parts of the incoming HTTP request: path (route) parameters, query string, body (form / JSON), headers, and cookies.

Prerequisites: see Introduction.

Full source 

<#
    Sample Kestrun Server on how to use route parameters.
    These examples demonstrate how to access route parameters and query strings in a Kestrun server.
    FileName: 2.3-Route-Parameters.ps1
#>

# Import the Kestrun module
Install-PSResource -Name Kestrun

# Create a new Kestrun server
New-KrServer -Name "Simple Server"

# Add a listener on port 5000 and IP address 127.0.0.1 (localhost)
Add-KrListener -Port 5000 -IPAddress ([IPAddress]::Loopback)

# Add the PowerShell runtime
# !!!!Important!!!! this step is required to process PowerShell routes and middlewares
Add-KrPowerShellRuntime

# Enable Kestrun configuration
Enable-KrConfiguration

# Path parameter example
Add-KrMapRoute -Verbs Get -Pattern "/input/{value}" -ScriptBlock {
    $value = Get-KrRequestRouteParam -Name 'value'
    Write-KrTextResponse -InputObject "The Path Parameter 'value' was: $value" -StatusCode 200
}

# Query string example
Add-KrMapRoute -Verbs Patch -Pattern "/input" -ScriptBlock {
    $value = Get-KrRequestQuery -Name 'value'
    Write-KrTextResponse -InputObject "The Query String 'value' was: $value" -StatusCode 200
}

# Body parameter example
Add-KrMapRoute -Verbs Post -ScriptBlock {
    $body = Get-KrRequestBody
    Write-KrTextResponse -InputObject "The Body Parameter 'value' was: $($body.value)" -StatusCode 200
}

# Header parameter example
Add-KrMapRoute -Verbs Put -Pattern "/input" -ScriptBlock {
    $value = Get-KrRequestHeader -Name 'value'
    Write-KrTextResponse -InputObject "The Header Parameter 'value' was: $value" -StatusCode 200
}

# Cookie parameter example
Add-KrMapRoute -Verbs Delete -Pattern "/input" -ScriptBlock {
    $value = Get-KrRequestCookie -Name 'value'
    Write-KrTextResponse -InputObject "The Cookie Parameter 'value' was: $value" -StatusCode 200
}

# Start the server asynchronously
Start-KrServer

Step-by-step

  1. Base setup (module install, server, listener, PowerShell runtime, configuration) matches earlier chapters.
  2. Path (route) parameter: pattern /input/{value} declares a placeholder. Retrieve it with Get-KrRequestRouteParam. Missing names return $null.
  3. Query string: same logical resource at /input but reading ?value=something via Get-KrRequestQuery.
  4. Body: POST /input with (e.g.) JSON { "value": "BodyData" } or form data; read with Get-KrRequestBody.
  5. Header: GET /input with custom header value: HeaderData; read via Get-KrRequestHeader.
  6. Cookie: send a cookie value=CookieData; read via Get-KrRequestCookie.
  7. Response helper: all examples use Write-KrTextResponse for a plain text 200 OK response.

Route overlap note: If multiple GET routes share the identical pattern and Method. Only one can ultimately match; the last registered with the same verb typically wins.

Try it

Start the server 

. .\examples\PowerShell\Tutorial\2.3-Route-Parameters.ps1

Path parameter 

curl http://127.0.0.1:5000/input/HelloPath
Invoke-WebRequest -Uri 'http://127.0.0.1:5000/input/HelloPath' | Select-Object -ExpandProperty Content

Query string 

curl -X PATCH "http://127.0.0.1:5000/input?value=HelloQuery"
Invoke-WebRequest -Method Patch -Uri 'http://127.0.0.1:5000/input?value=HelloQuery' | Select-Object -ExpandProperty Content

Body (POST JSON) 

curl -X POST http://127.0.0.1:5000/input -H "Content-Type: application/json" -d '{"value":"HelloBody"}'
Invoke-RestMethod -Method Post -Uri 'http://127.0.0.1:5000/input' -Body (@{ value = 'HelloBody' } | ConvertTo-Json) -ContentType 'application/json'

curl -X PUT -H "value: HelloHeader" http://127.0.0.1:5000/input
Invoke-WebRequest -Method Put -Uri 'http://127.0.0.1:5000/input' -Headers @{ value = 'HelloHeader' } | Select-Object -ExpandProperty Content

curl -X DELETE --cookie "value=HelloCookie" http://127.0.0.1:5000/input
# PowerShell (Invoke-WebRequest doesn't have a simple inline cookie flag; use Headers if server also accepts header or a WebSession):
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$cookie = New-Object System.Net.Cookie 'value','HelloCookie','/','127.0.0.1'
$session.Cookies.Add($cookie)
Invoke-WebRequest -Method Delete -Uri 'http://127.0.0.1:5000/input' -WebSession $session | Select-Object -ExpandProperty Content

Cmdlet / API references

Troubleshooting

Symptom Likely Cause Fix
Path value is $null Typo in {value} segment or used /input instead of /input/<value> Call the correct URL or match placeholder name exactly.
Query value is $null Missing ?value= param Append ?value=YourData to the URL.
Body value is $null Wrong content type or JSON property name Send Content-Type: application/json and match property casing.
Header value is $null Header not sent or case mismatch Add -H "value: Data"; header names are case‑insensitive but spelling matters.
Cookie value is $null Cookie not sent to server domain/path Ensure cookie domain matches listener (127.0.0.1) and path /.
Only one GET /input test works Duplicate GET routes with same pattern override Use distinct patterns (see adjustments) or different verbs.

Next

Continue to Route Options or explore more advanced patterns with middleware later in the tutorial.