Wisp Documentation

Introduction to Wisp

Wisp is a lightweight web framework for .NET, designed with one primary goal: to make it easy to embed an HTTP server directly inside an application without pulling in the entire ASP.NET Core stack. It focuses on simplicity, explicitness, and minimal dependencies while still following established patterns that .NET developers are familiar with, such as dependency injection, configuration, and structured logging.

The design philosophy behind Wisp is pragmatic:

  • No forced conventions or runtime magic – Controllers, routes, and middleware are explicit and discoverable.
  • Minimal runtime dependencies – It avoids heavy abstractions that often make small projects depend on large frameworks.
  • Adaptable backend – The HTTP server itself is pluggable; while Wisp ships with a NetCoreServer backend by default, the core framework is designed to allow swapping the underlying transport if project needs change.
  • Familiar development model – Despite being lightweight, Wisp includes features developers expect from modern frameworks: routing, controller support, template rendering, and configuration binding.

When to Use Wisp

Wisp is a good fit when you need HTTP capabilities inside an application but don't want the overhead of ASP.NET Core, for example:

  • Embedding a control or monitoring API into a desktop or service application
  • Quickly exposing endpoints for local tools or development utilities
  • Building small standalone services where using the full ASP.NET Core SDK would be overkill

It is not intended as a drop-in replacement for ASP.NET Core for large, production-scale web applications. Instead, Wisp is intended to be small, understandable, and easily embeddable.

Design Goals

  1. Lightweight: Minimal external dependencies and no requirement for the ASP.NET Core SDK.
  2. Explicit APIs: No implicit discovery or convention-over-configuration by default. Developers define what exists, and Wisp executes it.
  3. Extensible: Routing, controllers, and even the HTTP backend can be replaced or extended as needed.
  4. Approachable: If you know basic C# and have worked with ASP.NET before, you should feel at home.

How lightweight?

Wisp is intentionally small and avoids pulling in large frameworks by default.
Here is the full list of its runtime dependencies:

Fluid.Core
Microsoft.Extensions.Configuration
Microsoft.Extensions.Configuration.Binder
Microsoft.Extensions.Configuration.Json
Microsoft.Extensions.DependencyInjection
Microsoft.Extensions.Logging.Console
Microsoft.Extensions.Options
NetCoreServer

Okay, there are a few transitive dependencies as well, but it's still very lightweight:

Microsoft.Extensions.Configuration.Abstractions
Microsoft.Extensions.Configuration.FileExtensions
Microsoft.Extensions.DependencyInjection.Abstractions
Microsoft.Extensions.FileProviders.Abstractions
Microsoft.Extensions.FileProviders.Physical
Microsoft.Extensions.FileSystemGlobbing
Microsoft.Extensions.Logging
Microsoft.Extensions.Logging.Abstractions
Microsoft.Extensions.Logging.Configuration
Microsoft.Extensions.Options.ConfigurationExtensions
Microsoft.Extensions.Primitives
Parlot
TimeZoneConverter

For reference, a basic AspNetCore project can pull in up to 150* dependencies, Wisp has 21. That's it. Seriously.

* According to ChatGPT but it sounds about right...