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

File: pwsh/tutorial/examples/2.3-Route-Parameters.ps1

<#
    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
#>

param(
    [int]$Port = 5000,
    [IPAddress]$IPAddress = [IPAddress]::Loopback
)

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

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

# Add the PowerShell runtime


# 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 -Pattern "/input" -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. Initialize root and base setup: Initialize-KrRoot -Path $PSScriptRoot, New-KrServer, Add-KrEndpoint -Port 5000 -IPAddress Loopback, then Enable-KrConfiguration.
2. Path (route) parameter:
   • Pattern /input/{value} declares a placeholder.
   • Use Get-KrRequestRouteParam -Name value to retrieve it.
3. Query string:
   • Same resource at /input but read ?value=something via Get-KrRequestQuery.
4. Body (JSON or form):
   • POST /input with JSON { "value": "BodyData" }.
   • Read with Get-KrRequestBody. Ensure Content-Type: application/json for JSON.
5. Header:
   • Send value: HeaderData header; read via Get-KrRequestHeader.
6. Cookie:
   • Send a cookie value=CookieData; read via Get-KrRequestCookie.
7. Response helper:
   • All examples finish with 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

Save the sample locally so it’s easy to run. Copy the contents of pwsh/tutorial/examples/2.3-Route-Parameters.ps1 into a new file in an empty working folder (for example, route-params.ps1), then run:

# From your working folder
pwsh .\route-params.ps1

Now exercise each input type:

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'

Header

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

Cookie

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 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

References

• Add-KrMapRoute
• Get-KrRequestRouteParam
• Get-KrRequestQuery
• Get-KrRequestBody
• Get-KrRequestHeader
• Get-KrRequestCookie
• Write-KrTextResponse
• Start-KrServer
• Enable-KrConfiguration

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.

---

Previous / Next

Go back to Multiple Languages or continue to Route Options.