Tutorials
Step-by-step guides to build and ship with Kestrun. This index lists runnable sample scripts and documentation chapters in recommended learning order.
Prerequisites
- PowerShell 7.4, 7.5, or 7.6 (preview)
- .NET (run-only scenarios do NOT require the full SDK)
| PowerShell Version | Install (Run Samples) | Notes |
|---|---|---|
| 7.4 / 7.5 | .NET 8 ASP.NET Core Runtime | Bundles base runtime + ASP.NET Core |
| 7.6 (preview) | .NET 9 ASP.NET Core Runtime | Preview – updates frequently |
If you already have the .NET SDK for those versions installed you don’t need to install the runtime separately.
- Kestrun module: installed or available from this repository at
src/PowerShell/Kestrun/Kestrun.psm1 - Supported OS: same as .NET 8/9 (Windows, Linux, macOS), including ARM/ARM64
Verify (optional):
dotnet --list-runtimes | Where-Object { $_ -match 'Microsoft.(AspNetCore|NETCore).App' }
You should see Microsoft.AspNetCore.App 8.0.x (and 9.0.x if using PS 7.6 preview).
Quick start: run the samples
From the repository root:
# 1) Hello World
pwsh .\examples\PowerShell\Tutorial\1-Hello-World.ps1
Then browse the routes (default listener: http://127.0.0.1:5000): Read the note on each sample for the routes detail.
Stop the server with Ctrl+C in the terminal.
Samples & Chapters Overview
| Order | Topic | Chapter | Sample Script | Focus |
|---|---|---|---|---|
| 1 | Hello World | Hello World | Script | Minimal server + 1 text route |
| 2 | Content Types | Content Types | Script | JSON / XML / YAML helpers |
| 3 | Multi-Language | Multi-Language Routes | Script | C#/VB inline handlers |
| 4 | Route Options | Route Options | Script | MapRouteOptions variations |
| 5 | Static Files | Static Routes | Script | Host static content / wwwroot |
| 6 | File Server | File Server | Script | Directory browsing & file responses |
| 7 | Override Routes | Override Routes | Script | Replace static with dynamic |
| 8 | FavIcon | Add FavIcon | Script | Serve favicon.ico |
| 9 | Shared State | Shared Variables | Script | Share state between routes |
| 10 | Logging Basics | Simple Logging | Script | Console logger, levels |
| 11 | Logging Advanced | Multiple Loggers | Script | Multiple sinks & levels |
| 12 | Logging Enrichment | Enrichment & Correlation | Script | Correlation IDs |
| 13 | Logging Sinks | Sinks | Script | Built-in sinks overview |
| 14 | Logging Sinks Advanced | Sinks Advanced | Script | Custom/advanced sinks |
| 15 | Logging Hot Reload | Hot Reload | Script | Reconfigure without restart |
| 16 | Certificates: Self-Signed | Self-Signed | Script | Dev cert generation |
| 17 | Certificates: CSR | CSR | Script | Create signing request |
| 18 | Certificates: Import/Export | Import / Export | Script | Manage PFX lifecycle |
| 19 | Endpoints: Basic Server | Basic Server | Script | Minimal hosting |
| 20 | Endpoints: Multiple Listeners | Multiple Listeners | Script | Several ports |
| 21 | Endpoints: HTTPS | HTTPS | Script | TLS listener |
| 22 | Endpoints: Named Pipes | Named Pipes | Script | Windows IPC |
| 23 | Endpoints: Unix Sockets | Unix Sockets | Script | Unix IPC / proxy |
| 24 | Responses: Text & JSON | Text & JSON | Script | Basic text & JSON helpers |
| 25 | Responses: Structured | Structured Formats | Script | XML / YAML / CSV |
| 26 | Responses: Binary & Stream | Binary & Stream | Script | Binary bytes vs streaming |
| 27 | Responses: HTML & Files | HTML & Files | Script | Templates & file download |
| 28 | Responses: BSON / CBOR | BSON / CBOR | Script | Compact binary encodings |
| 29 | Responses: Redirects | Redirects | Script | 3xx location responses |
| 30 | Responses: Errors | Errors | Script | Consistent error payloads |
| 31 | Responses: Caching | Caching & Revalidation | Script | Cache-Control & ETag handling |
| 32 | Responses: Content Negotiation | Content Negotiation | Script | Auto format selection via Accept |
| 33 | Responses: Low-Level Stream | Low-Level Response | Script | Raw stream writing |
| 34 | Middleware: Antiforgery | Antiforgery Protection | Script | CSRF token + cookie validation |
| 35 | Authentication: Basic (PS) | Basic (PS) | Script | Basic scheme script block |
| 36 | Authentication: Basic (C#/VB) | Basic (C#/VB) | Script | Multi-language validation |
| 37 | Authentication: API Key | API Key | Script | Header key variants |
| 38 | Authentication: JWT | JWT Tokens | Script | Issue & validate bearer |
| 39 | Authentication: Cookies | Cookies | Script | Session cookie login |
| 40 | Authentication: Windows | Windows Authentication | Script | Integrated Windows auth |
| 41 | Authentication: Claims | Claims & Policies | Script | Claim policy enforcement |
| 42 | Authentication: Multiple | Multiple Schemes | Script | Combine schemes |
| 43 | Authentication: Full Demo | Full Auth Demo | Script | Integrated auth server |
| 44 | Server Configuration: Limits | Server Limits | Script | Size & rate limits |
| 45 | Server Configuration: Options | Server Options | Script | Headers & runspaces |
| 46 | Lifecycle: Start/Stop | Start / Stop | Script | Non-blocking lifecycle |
| 47 | Demo: Full Server | Full Server Demo | Script | Integrated scenario |
| 48 | Health: Quickstart | Health Quickstart | Script | Endpoint + basic probes |
| 49 | Health: Script Probe | Script Probe | Script | Custom latency script |
| 50 | Health: HTTP Probe | HTTP Probe | Script | Internal route check |
| 51 | Health: Process Probe | Process Probe | Script | External tool validation |
| 52 | Health: C# Inline Probe | C# Inline Probe | Script | Inline .NET logic |
| 53 | Health: Disk Probe | Disk Probe | Script | Disk space thresholds |
| 54 | Scheduler: Quickstart | Scheduling Quickstart | Script | Enable scheduler, jobs, report |
| 55 | Scheduler: CRON | Scheduling with CRON | Script | CRON expressions with seconds |
| 56 | Scheduler: Report | Scheduling Report | Script | Report endpoint and timezone |
| 57 | Status Code Pages: Default | Default Status Pages | Script | Basic error page middleware |
| 58 | Status Code Pages: Options | Custom Options | Script | StatusCodePagesOptions config |
| 59 | Status Code Pages: Handler | Custom Handler | Script | Delegate function handling |
| 60 | Status Code Pages: Script | PowerShell Script | Script | PowerShell error page generation |
| 61 | Status Code Pages: Format | Content Format | Script | Custom content type & body format |
| 62 | Status Code Pages: Redirects | Redirect Pages | Script | Redirect to error page URLs |
| 63 | Status Code Pages: Re-execute | Re-execute Pipeline | Script | Re-execute with alternate paths |
| 64 | Middleware: Sessions | Sessions | Script | Cookie-based session state |
| 65 | Middleware: Sessions (Redis) | Sessions with Redis | Script | Redis-backed session storage |
| 66 | Middleware: Sessions (SQL) | Sessions with SQL Server | Script | SQL-backed session storage |
Static chapters and scripts are all linked directly above for quick navigation.