https://github.com/kestrun/kestrun
PowerShell brains. Kestrel speed.
https://github.com/kestrun/kestrun
automation cross-platform csharp dotnet-core kestrel kestrun nuget powershell psgallery razor-pages scripting server-framework vb-net web-framework
Last synced: 3 months ago
JSON representation
PowerShell brains. Kestrel speed.
- Host: GitHub
- URL: https://github.com/kestrun/kestrun
- Owner: Kestrun
- License: mit
- Created: 2025-07-10T23:01:22.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-10-03T18:19:40.000Z (3 months ago)
- Last Synced: 2025-10-03T18:22:59.923Z (3 months ago)
- Topics: automation, cross-platform, csharp, dotnet-core, kestrel, kestrun, nuget, powershell, psgallery, razor-pages, scripting, server-framework, vb-net, web-framework
- Language: C#
- Homepage: https://www.kestrun.dev
- Size: 37 MB
- Stars: 6
- Watchers: 2
- Forks: 0
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
```text
██╗ ██╗███████╗███████╗████████╗██████╗ ██╗ ██╗███╗ ██╗
██║ ██╔╝██╔════╝██╔════╝╚══██╔══╝██╔══██╗██║ ██║████╗ ██║
█████╔╝ █████╗ ███████╗ ██║ ██████╔╝██║ ██║██╔██╗ ██║
██╔═██╗ ██╔══╝ ╚════██║ ██║ ██╔██╗ ██║ ██║██║╚██╗██║
██║ ██╗███████╗███████║ ██║ ██║ ██╗ ╚██████╔╝██║ ╚████║
╚═╝ ╚═╝╚══════╝╚══════╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═══╝
Kestrun — PowerShell brains. Kestrel speed.
```
---
[](https://github.com/Kestrun/Kestrun/actions/workflows/ci-main.yml)
[](https://github.com/kestrun/kestrun/actions/workflows/codeql.yml)
[](https://github.com/kestrun/kestrun/actions/workflows/clam-av-main.yml)
[](https://github.com/kestrun/kestrun/actions/workflows/lint-main.yml)
[](https://www.codefactor.io/repository/github/kestrun/kestrun/overview/main)
[](https://coveralls.io/github/Kestrun/Kestrun?branch=main)
[](https://coverage.kestrun.dev)
[](https://github.com/Kestrun/Kestrun/actions)
[](https://github.com/Kestrun/Kestrun/actions)
[](https://github.com/Kestrun/Kestrun/actions)
[](https://github.com/Kestrun/Kestrun/actions)
[](https://github.com/Kestrun/Kestrun/actions)
[](https://dotnet.microsoft.com/download/dotnet/8.0)
[](https://dotnet.microsoft.com/download/dotnet/9.0)
[](https://github.com/PowerShell/PowerShell/releases/tag/v7.4.0)
[](https://github.com/PowerShell/PowerShell/releases/tag/v7.5.0)
[-blue)](https://github.com/PowerShell/PowerShell/releases/tag/v7.6.0-preview.4)
[](CONTRIBUTING.md)
[](https://github.com/Kestrun/Kestrun/releases)
[](https://docs.kestrun.dev)
[](https://www.nuget.org/packages/Kestrun/)
[](https://www.powershellgallery.com/packages/Kestrun)
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](https://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](https://dotnet.microsoft.com/download/dotnet/8.0) **AND**
[.NET 9 SDK](https://dotnet.microsoft.com/download/dotnet/9.0)
(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:
```powershell
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](https://dotnet.microsoft.com/download/dotnet/8.0) | Bundles Microsoft.NETCore.App + Microsoft.AspNetCore.App 8.x |
| 7.6 (preview) | [.NET 9 ASP.NET Core Runtime](https://dotnet.microsoft.com/download/dotnet/9.0) | 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](https://github.com/PowerShell/PowerShell/releases).
### Verify installation
```powershell
# 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):
```text
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:
```powershell
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()` 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):
```powershell
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:
```powershell
Invoke-Build Test
```
### Manual Test Execution
#### C# Tests
```powershell
Invoke-Build Kestrun.Tests
```
#### PowerShell Tests
```powershell
Invoke-Build Test-Pester
```
## Documentation and Tutorial
Kestrun docs are built with [Just-the-Docs](https://github.com/just-the-docs/just-the-docs).
All new documentation **must be compatible** (front matter, `parent`, `nav_order`, etc.).
See [docs/](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](CONTRIBUTING.md) and the online guide at .
## License
Licensed under the MIT License. See [LICENSE](LICENSE).
## Acknowledgements
### Documentation
- [Just-the-Docs](https://github.com/just-the-docs/just-the-docs) for documentation
### Code Quality
- [ReportGenerator](https://github.com/danielpalme/ReportGenerator) for code coverage reporting
- [codefactor](https://www.codefactor.io/) for code quality analysis
- [coveralls](https://coveralls.io/) for code coverage tracking
### AI Assistance
- [ChatGPT](https://openai.com/chatgpt) for conversational AI support
- [Copilot](https://github.com/features/copilot) for AI-powered code suggestions
### Collaboration and Version Control
- [GitHub](https://github.com/) for version control and collaboration
- [NuGet](https://www.nuget.org/) for package management
- [PowerShell Gallery](https://www.powershellgallery.com/) for PowerShell modules
### Scripting and Automation
- [PowerShell](https://github.com/PowerShell/PowerShell) for scripting and automation
- [.NET](https://dotnet.microsoft.com/) for the underlying framework
- [Pester](https://pester.dev/) for PowerShell testing
### Logging and Serialization
- [PoShLog](https://github.com/PoShLog/PoShLog) — inspiration and portions of code for logging (MIT License)
- [powershell-yaml](https://github.com/cloudbase/powershell-yaml) — adapted tests and implementation code for YAML serialization (Apache-2.0 License)