Kestrun 1.0.0-alpha.3

██╗  ██╗███████╗███████╗████████╗██████╗ ██╗   ██╗███╗   ██╗
██║ ██╔╝██╔════╝██╔════╝╚══██╔══╝██╔══██╗██║   ██║████╗  ██║
█████╔╝ █████╗  ███████╗   ██║   ██████╔╝██║   ██║██╔██╗ ██║
██╔═██╗ ██╔══╝  ╚════██║   ██║   ██╔██╗  ██║   ██║██║╚██╗██║
██║  ██╗███████╗███████║   ██║   ██║ ██╗ ╚██████╔╝██║ ╚████║
╚═╝  ╚═╝╚══════╝╚══════╝   ╚═╝   ╚═╝ ╚═╝  ╚═════╝ ╚═╝  ╚═══╝
Kestrun — PowerShell brains. Kestrel speed.

Kestrun is a hybrid web framework that combines the speed and scalability of ASP.NET Core (Kestrel) with the flexibility and scripting power of PowerShell. It enables you to build web APIs, automation endpoints, and dynamic services using both C# and PowerShell in a single, integrated environment.

Rich Documentation and Tutorial

Full documentation and tutorial for Kestrun is available online at docs.kestrun.dev. You can find guides, API references, and usage examples to help you get started and explore advanced features.

Core Capabilities

• 🚀 Fast, cross-platform web server Powered by ASP.NET Core (Kestrel) with full access to advanced HTTP/2, header compression, and TLS options.

• 🐚 Native PowerShell integration Routes can be backed by PowerShell scripts with isolated, pooled runspaces and dynamic $Context.Request / $Context.Response variables.

• 🧠 Multi-language script routing Register HTTP routes using:

  • 🐚 PowerShell For Building:

  • .NET 8 SDK AND .NET 9 SDK (solution multi-targets net8.0 + net9.0)

  • PowerShell 7.4+ (7.4 / 7.5 run on .NET 8; 7.6 preview runs on .NET 9)

  • Invoke-Build and Pester PowerShell modules:

  Install-PSResource -Name 'InvokeBuild','Pester' -Scope CurrentUser
  

  For Runtime (Run Only):

  If you're only running Kestrun apps (not building from source), install the ASP.NET Core Runtime matching the PowerShell version you are using:

  PowerShell Version	Install (Run-only)	Rationale
  7.4 / 7.5	.NET 8 ASP.NET Core Runtime	Bundles Microsoft.NETCore.App + Microsoft.AspNetCore.App 8.x
  7.6 (preview)	.NET 9 ASP.NET Core Runtime	Preview runtime aligning with PS 7.6 build

  Installing the .NET SDK already gives you the corresponding runtimes. For run-only scenarios the ASP.NET Core Runtime alone is sufficient (it includes the base .NET runtime).

  Download PowerShell from the official PowerShell Releases.

  Verify installation

  # List SDKs (expect 8.x and 9.x if building from source)
  dotnet --list-sdks
  
  # List runtimes (look for Microsoft.NETCore.App and Microsoft.AspNetCore.App)
  dotnet --list-runtimes | Where-Object { $_ -match 'Microsoft.(AspNetCore|NETCore).App' }
  

  Expected (abbreviated):

  Microsoft.NETCore.App 8.0.x
  Microsoft.AspNetCore.App 8.0.x
  Microsoft.NETCore.App 9.0.x
  Microsoft.AspNetCore.App 9.0.x
  

  If something is missing, install the matching ASP.NET Core Runtime from the download links above.

  Build & Run

  Clone the repository:

  git clone https://github.com/Kestrun/Kestrun.git
  cd Kestrun
  

• 🛠️ CI/CD ready

  • Build- and run-time configurable
  • Works in containerized / headless environments
  • Supports Dev/Prod fallback module path detection

• 🛡️ Optional Add-ons Add via fluent extensions:

  • AddAntiforgery() middleware
  • AddStaticFiles(), AddDefaultFiles(), AddFileServer()
  • AddCors(policy) or AddCorsAllowAll()
  • AddSignalR<T>() for real-time hubs
  • AddAuthentication() with multiple schemes (Windows, Basic, JWT, Certificate, etc.)
  • Ready for Swagger, gRPC, custom middleware hooks

• ⚡ Task Scheduling & Background Jobs

  • Cron-based scheduling: Full cron expression support via Cronos
  • Multi-language job support: Schedule PowerShell, C#, and VB.NET scripts as background jobs
  • Job management: Start, stop, and monitor scheduled tasks with detailed logging

Deployment & Extensibility

This section summarizes extension capabilities (see earlier sections for build & run instructions).

Using the PowerShell Module

Import the module (from source):

Import-Module ./src/PowerShell/Kestrun/Kestrun.psm1

Running Tests

Using Invoke-Build (Recommended)

The project includes an Invoke-Build script that automatically handles both C# (xUnit) and PowerShell (Pester) tests:

Invoke-Build Test

Manual Test Execution

C# Tests

Invoke-Build Kestrun.Tests

PowerShell Tests

Invoke-Build Test-Pester

Documentation and Tutorial

Kestrun docs are built with Just-the-Docs. All new documentation must be compatible (front matter, parent, nav_order, etc.).

See docs/ for structure.

Project Structure

• src/CSharp/ — C# core libraries and web server
  • Kestrun/Authentication — authentication handlers and schemes
  • Kestrun/Certificates — certificate management utilities
  • Kestrun/Hosting — host configuration and extensions
  • Kestrun/Languages — multi-language scripting support (C#, VB.NET, etc.)
  • Kestrun/Logging — Serilog integration and logging helpers
  • Kestrun/Middleware — custom middleware components
  • Kestrun/Models — request/response classes and data models
  • Kestrun/Razor — Razor Pages integration with PowerShell
  • Kestrun/Scheduling — task scheduling and background job support
  • Kestrun/Scripting — script execution and validation
  • Kestrun/Security — security utilities and helpers
  • Kestrun/SharedState — thread-safe global state management
  • Kestrun/Utilities — shared utility functions
• src/PowerShell/ — PowerShell module and scripts
• examples/ — Example projects and demonstrations
  • CSharp/Authentication — authentication examples
  • CSharp/Certificates — certificate usage examples
  • CSharp/HtmlTemplate — HTML templating examples
  • CSharp/MultiRoutes — multi-route examples
  • CSharp/RazorSample — Razor Pages examples
  • CSharp/Scheduling — task scheduling examples
  • CSharp/SharedState — shared state examples
  • PowerShell/ — PowerShell examples
  • Files/ — test files and resources
• tests/ — Test projects (C#, PowerShell)
• docs/ — Documentation files (Just-the-Docs)
• Utility/ — Build and maintenance scripts
• .github/ — GitHub Actions workflows
• Lint/ — Code analysis rules

Contributing

Contributions of all sizes are welcome — from docs improvements to new feature modules. See CONTRIBUTING.md and the online guide at https://docs.kestrun.dev/contributing.

License

Licensed under the MIT License. See LICENSE.

Acknowledgements

Documentation

• Just-the-Docs for documentation

Code Quality

• ReportGenerator for code coverage reporting
• codefactor for code quality analysis
• coveralls for code coverage tracking

AI Assistance

• ChatGPT for conversational AI support
• Copilot for AI-powered code suggestions

Collaboration and Version Control

• GitHub for version control and collaboration
• NuGet for package management
• PowerShell Gallery for PowerShell modules

Scripting and Automation

• PowerShell for scripting and automation
• .NET for the underlying framework
• Pester for PowerShell testing