GenHTTP Webserver

Internal

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Full Package on NuGet GenHTTP.Core Package on NuGet

This is the default HTTP implementation provided by the GenHTTP framework. It relies only on code written in C# and tries to reduce dependencies to third-party libraries and the environment it runs in as much as possible, therefore making it a good choice for embedding a webservice into another application (e.g. WPF or Windows Forms) or hosting a small service as a Docker container.

Request API

Mon, 01 Jan 0001 00:00:00 +0000

Request API

To handle incoming HTTP requests, GenHTTP uses the IRequest abstraction, which - besides granting access to infrastructure components such as the IServer, IEndPoint or IClientConnection, is intended to represent the data on the wire as it was received by the connected client.

The core entry points to handle requests are handlers and concerns. The server host is passed a handler instance (known as root handler) which is then responsible for handling all incoming requests. If needed, it can use other handlers to delegate work (see layouting as a starting point).

Routing

Mon, 01 Jan 0001 00:00:00 +0000

When the server receives a request from the client, it passes it to the root handler specified by your application. Depending on the requested path, this handler may invoke additional handlers to actually produce a response. The tree of handlers available in your application is called handler chain. As requests are passed from one handler to another, they need to track, which segments of the requested path have already been considered and which still need to be evaluated, effectively decoupling them from each other. This capability is provided by the routing feature of the framework.

Upgrade to 10.x

Mon, 01 Jan 0001 00:00:00 +0000

This document is intended to guide you when upgrading from GenHTTP 9.x to GenHTTP 10.

Dependency Injection

In GenHTTP 10, support for dependency injection has been added. If you are using custom mechanisms to achieve dependency injection, you might want to switch to the new, built-in way.

API Cleanup

The following types have been moved into their corresponding module packages as they are too specific to be part of the API.

Webservices

Mon, 01 Jan 0001 00:00:00 +0000

The webservice module provides an easy way to implement RESTful services that can be consumed by clients as needed.

Hosting an API

To host an API using this framework you can define a new class that hosts your operations as dedicated methods. The signature of those methods will define how your API can be called via HTTP.

Adapters

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP is both a web server and a web application development framework. Adapters allow to re-use the functionality of the GenHTTP modules in other server frameworks such as ASP.NET Core.

ASP.NET Core

GenHTTP.Adapters.AspNetCore Package on NuGet

This adapter allows to plug in any GenHTTP handler into an existing ASP.NET Core application. The following example will use the listing module to render a graphical file listing when accessing http://localhost:5000/files/ in the browser.

Functional Handlers

Mon, 01 Jan 0001 00:00:00 +0000

With this module, requests can be handled in a functional manner, reducing the boilerplate code to be written by a web application developer.

Hosting an API

To host an API using this framework you can create an Inline handler and add your operations as needed.

 C#
 
 
using GenHTTP.Engine.Internal;

using GenHTTP.Modules.ApiBrowsing;
using GenHTTP.Modules.Functional;
using GenHTTP.Modules.Layouting;
using GenHTTP.Modules.OpenApi;
using GenHTTP.Modules.Security;

var bookService = Inline.Create() 
 // GET http://localhost:8080/books/?page=1&pageSize=20
 .Get((int page, int pageSize) => /* ... */)
 // GET http://localhost:8080/books/4711
 .Get(":id", (int id) => /* ... */) 
 // PUT http://localhost:8080/books/
 .Put((Book book) => /* ... */) 
 // POST http://localhost:8080/books/
 .Post((Book book) => /* ... */) 
 // DELETE http://localhost:8080/books/4711
 .Delete(":id", (int id) => /* ... */);

var api = Layout.Create()
 .Add("books", bookService)
 .Add(CorsPolicy.Permissive())
 .AddOpenApi() // http://localhost:8080/openapi.json
 .AddRedoc(); // http://localhost:8080/redoc/

await Host.Create()
 .Handler(api)
 .Development()
 .RunAsync();

Further Resources

The following capabilities are shared by various application frameworks:

Kestrel

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Full.Kestrel Package on NuGet GenHTTP.Core.Kestrel Package on NuGet

Kestrel is a web server developed by Microsoft and the engine that runs ASP.NET applications. As it is maintained by Microsoft, this engine is a good choice when you have high performance and security requirements.

Method Definitions

Mon, 01 Jan 0001 00:00:00 +0000

All API frameworks share a common base provided by the Reflection and Conversion modules which define some of the capabilities that can be used when defining an API method signature.

Injection

This section describes how parameters of your methods are initialized and which kind of types can be used.

Primitives

By default, a parameter type can be used within a method definition if it is either string, bool, an enum, one of DateTime, DateTimeOffset, DateOnly, TimeOnly or TimeSpan, or implements IUtf8SpanFormattable (which covers the numeric primitives such as int, long or Guid).

Upgrade to 11.x

Mon, 01 Jan 0001 00:00:00 +0000

This document is intended to guide you when upgrading from GenHTTP 10.x to GenHTTP 11.

Target Frameworks

This version is shipped with the release of .NET 11. Following the support policy from Microsoft, support for .NET 8 and 9 has been dropped.

Packaging

In previous versions, you would reference both GenHTTP.Core as well as any module you wanted to use within your application. While this is still recommended for deployments, you can now use the GenHTTP.Full package (which also exist for Kestrel and Ioxide) which bundles all available modules for convenience.

Code Generation

Mon, 01 Jan 0001 00:00:00 +0000

By default, the server compiles a delegate for each webservice method that fetches the input arguments from the request, executes the method, and maps the result into an HTTP response - this is faster than analyzing and invoking the method via the reflection APIs on every request. The delegate is compiled once, during PrepareAsync (i.e. server start), so it does not add any latency to the first request handled by the endpoint.

Controllers

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.Controllers Package on NuGet

This framework allows to create APIs by defining and implementing controller classes. In contrast to ASP.NET, you cannot use this framework to dynamically render HTML pages in an MVC style project, so this is just another flavor of defining a web API.

ioxide

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Full.Ioxide Package on NuGet GenHTTP.Core.Ioxide Package on NuGet

As ioxide depends on io_uring which is a capability of the Linux kernel, it cannot run on other platforms, such as Windows or macOS. Kernel version 6.1 or higher is required.

Logging

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP uses the default logging mechanism of .NET Core and allows to create loggers via the IServer interface. By default, the host will add a console logger.

Logging Information

The following code shows to obtain a logger from the server instance in a custom IHandler implementation. It is recommended to create the logger once in the preparation phase and store the reference somewhere. You can use this pattern anywhere where you have access to IServer (e.g. via request.Server).

Websockets

Thu, 11 Dec 2025 00:27:41 +0200

Websockets allow to create a bidirectional connection between your clients and your server, allowing both sides to push content without the need of sending HTTP requests.

Flavors

There are three different flavors that you can use to host a web socket endpoint. They do not differ in functionality. In this section we will spawn a simple websocket server that will relay incoming messages to all other connected clients (so basically a simple chat application). In the “Client” section you will find a simple HTML file that can be opened in a browser to connect to your server.

Endpoints and Ports

Mon, 01 Jan 0001 00:00:00 +0000

By default, the server will listen on port 8080 for incoming IPv4 or IPv6 connections on any interface. To simply change the port the server will listen on, you can use the Port() directive of the host. Please note, that hosting a server on ports below 1024 will require additional permissions on some operating systems.

 C#
 
 
var host = Host.Create()
 .Handler(...)
 .Port(80);

To configure the server to listen on specific interfaces only, you can Bind() those endpoints explicitly.

Response Content

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.IO Package on NuGet

When sending content in response to a client request, IResponseBuilder has a single entry point for it: Content(IResponseContent? content). Everything about the content itself - its Length, Type and encoding - is a property of the IResponseContent implementation being passed in, not something configured separately on the builder. Length is the number of bytes the content will produce; if it is not known, chunked transfer encoding is applied.

Resources

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.IO Package on NuGet

GenHTTP provides a thin abstraction layer to control access of binary resources (such as files or blobs). This allows to re-use file-dependent handlers, independent from whether the data comes from the file system, a database or somewhere else.

Security

Mon, 01 Jan 0001 00:00:00 +0000

This page summarizes security considerations and configuration options when running GenHTTP applications.

General Considerations

GenHTTP is designed to be used as an application server behind a reverse proxy, and therefore does not provide built-in DoS protection (such as IP connection limits or Slowloris prevention). However, compared to many other web service frameworks for C#, it is hardened against - and explicitly tested for - typical attack vectors such as request smuggling, header injection, or malformed chunk attacks.

Single Page Applications (SPA)

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.SinglePageApplications Package on NuGet

This handler provides an easy way to serve a single page application (for example a Vue.js, React, or Angular app) to your clients.

Dependency Injection

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.DependencyInjection Package on NuGet

This optional module allows to use Microsoft’s abstraction layer to inject dependencies into handlers, concerns and framework classes as well as their methods.

Static Websites

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.StaticWebsites Package on NuGet

This handler provides an easy way to serve a static website such as a Hugo application to your clients.

Custom Frameworks

Mon, 01 Jan 0001 00:00:00 +0000

The framework layer of GenHTTP allows application frameworks (such as webservices or controllers) to host a set of operations (put simply a route with a piece of C# code to be executed). This way the application framework itself is only a very thin layer - it analyzes the given scope (such as a controller class) and derives operations from it which are then handled by the generic framework part. This way, all application frameworks share the same feature level and can support things like parameter binding, serialization, async execution or code generation. To give an example, the webservice handler which provides the whole webservice framework consists of 70 lines of code only - everything else is done by the underlying framework layer.

Features

Tue, 01 Sep 2026 09:35:41 +0200

Frameworks

GenHTTP provides several frameworks to develop and host web services (e.g. service classes, controller-style or functional-style). Additionally, you can easily host static websites or a single page app. Besides this, the framework comes with a rich set of features:

Automatically generated Open API specifications
Various authentication methods (e.g. API key, JWT, Client Certificates or Basic Auth)
Support for Websockets and Server Sent Events (SSE)
Automatic response compression and request decompression
Client caching directives and automatic eTag handling
Range support to fetch byte ranges
Security relevant features (such as automatic redirection to HTTPS)

Server Performance

According to HTTP Arena, GenHTTP is currently the fastest web server for HTTP/1.1. The following excerpt shows how GenHTTP compares to other C# servers in the field:

Support

Tue, 02 Dec 2025 17:10:41 +0200

Getting Support

If you have questions or run into issues while building applications with the GenHTTP webserver framework, our community is here to help. You can reach us through:

GitHub discussions and issue tracking
Our community Discord channel

Both platforms are actively monitored and are great places to get guidance, report problems, or exchange ideas with other GenHTTP users.

Legal

Thu, 20 Jun 2024 14:10:41 +0200

Imprint

Andreas Nägeli

Kientzheimer Str. 1, 79238 Ehrenkirchen, Germany

solutions@genhttp.org

If you would like to report a bug or ask a question, please visit our GitHub page.

Data Privacy

This website is intended to provide information about the GenHTTP web server project. Personal data and cookies are not required for this, but your IP address is logged by the server for the purpose of technical operation with every request sent by your browser. This information will reside on the server until it is restarted. Besides this, no other personal data will be collected.

API Browsing

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.ApiBrowsing Package on NuGet

This module adds JavaScript based applications to visualize an Open API definition such as Swagger UI, Redoc or Scalar to your app. All resources required by those apps are hosted locally so no internet connection is required.

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.Authentication Package on NuGet

The authentication module allows to restrict access to sections provided by handlers to authenticated users only. Independent from the kind of authentication used, the identified user can be read from the request in the following manner:

Client Caching (Policy)

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.ClientCaching Package on NuGet

This concern allows to instruct clients to cache responses generated by the server for some duration by adding the Expires HTTP header. The following example will cause the static website to be cached for one week:

Client Caching (Validation)

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.ClientCaching Package on NuGet

This concern adds an eTag header to every response generated by the server so that clients send a If-None-Match header to validate their cache. If the content did not change on the server, the handler will generate a 304 Not Modified response, causing the client to re-use the locally cached data. This way, clients revisiting your web application load faster and the load on your server is reduced.

Compression

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.Compression Package on NuGet

The compression concern compresses content sent to the clients, if applicable. By default, gzip, Brotli and Zstandard (on .NET 11) are supported.

Content

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.IO Package on NuGet

This handler provides the content of a resource such as a file or a text resource to a requesting client. In contrast to a download, the handler does not instruct the client to download and store the file but just serves it.

CORS

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.Security Package on NuGet

Cross-Origin Resource Sharing allows to control which resources browsers are allowed to access and how they are allowed to do so. For example, if you would like to access a webservice from a website hosted on another domain, the browser will send the Origin header along with requests to the webservice and analyze the response to determine, whether the server allows clients to access the resource from this origin.

Decompression

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.Compression Package on NuGet

This concern will analyze incoming requests for compressed content and will automatically decompress the body using a suitable decompression algorithm.

Defaults

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.Practices Package on NuGet

The Defaults() method provided by the practices module adds some useful concerns to your web server to enable features such as compression or client side caching. This way, you will have a well configured server instance without the need of adding everything by yourself.

Directory Browsing

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.DirectoryBrowsing Package on NuGet

The directory listing provider serves a simple web UI allowing users to browse directories and files read from a resource tree below the specified path.

Error Handling

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.ErrorHandling Package on NuGet

If an exception occurs while a request is handled, the server will render the exception into a structured response (JSON, XML, … depending on what the client accepts) via ErrorHandler.Default(), which is an alias for ErrorHandler.Structured(). To customize the serialization used, pass a SerializationBuilder to Structured(...).

Files

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.Files Package on NuGet

The Files module serves resources to clients, either one at a time with a fixed path or as a whole browsable directory tree. The content type of a file is automatically determined by its extension unless overridden.

Hardening

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.Security Package on NuGet

Besides CORS, the security module provides a few concerns that harden a web application against common transport-level issues. All three are added automatically by Defaults() (with preventSniffing off), or can be added together via Harden() (which also enables preventSniffing by default):

Inspection

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.Inspection Package on NuGet

When developing client applications, you will sometimes have trouble to understand, why you are getting a specific response from a webserver. The inspection concern allows you to add the query param ?inspect to any request and will respond with a detailed summary of how the received request looked like and what response was generated by the server.

Layouting

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.Layouting Package on NuGet

Layouts are a basic mechanism that allows you to assemble your web application from different parts. They define which URLs are made available by the server and what the URL structure of your app will look like.

Liquid Pages

Mon, 01 Jan 0001 00:00:00 +0000

Kinetq.LiquidPages.GenHTTP Package on NuGet Kinetq.LiquidPages Package on NuGet

This is a third-party integration maintained by Kinetq, not part of the GenHTTP project. Questions and issues regarding the package are best directed at its maintainers.

Load Balancer

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.LoadBalancing Package on NuGet

Allows to distribute incoming requests to multiple nodes, either by using a reverse proxy or by redirecting the client.

Localization

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.I18n Package on NuGet

The localization concern analyzes incoming requests for language preferences and allows the application logic to serve content based on those.

Open API

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.OpenApi Package on NuGet

This concern dynamically generates and serves an Open API v3 specification using NSwag for all detected API endpoints.

Pages

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.Pages Package on NuGet

The pages module allows the server to generate HTML pages (e.g. error messages or the directory listing) and can be used to render custom pages from a template, using Cottle as a rendering engine. Support for rendering websites in GenHTTP is minimalistic, so you should not use this for a website project.

Range Support

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.IO Package on NuGet

Partial responses allow clients to fetch a specified portion of a requested resource which can be helpful for download managers to pause and resume downloads. As this functionality is not needed by every web application, range support is disabled by default.

Redirects

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.Redirects Package on NuGet

The redirect provider allows to inform the client that the location of the actual resource is different than the requested URI.

Reverse Proxies

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.ReverseProxy Package on NuGet

The reverse proxy content provider allows to embed content from another web server into your application.

Server Sent Events (SSE)

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.ServerSentEvents Package on NuGet

Server Sent Events (SSE) allow client applications such as browsers to subscribe to a stream of relevant events without the overhead added by the bi-directional connection of websockets. Therefore, they are useful whenever the server would like to notify the client about changes. This article describes how to host an event source in C# using the GenHTTP web server.

Virtual Hosts

Mon, 01 Jan 0001 00:00:00 +0000

GenHTTP.Modules.VirtualHosting Package on NuGet

The virtual host handler can be used to deliver different content depending on the host requested by the client. Note, that the handler can be used anywhere in the handler chain, but usually it is most beneficial as the main handler.

GenHTTP Webserver

Internal

Request API

Request API

Routing

Upgrade to 10.x

Dependency Injection

API Cleanup

Webservices

Hosting an API

Adapters

ASP.NET Core

Functional Handlers

Hosting an API

Further Resources

Kestrel

Method Definitions

Injection

Primitives

Upgrade to 11.x

Target Frameworks

Packaging

Code Generation

Controllers

ioxide

Logging

Logging Information

Websockets

Flavors

Endpoints and Ports

Response Content

Resources

Security

General Considerations

Single Page Applications (SPA)

Dependency Injection

Static Websites

Custom Frameworks

Features

Frameworks

Server Performance

Support

Getting Support

Legal

Imprint

Data Privacy

Links

GenHTTP Gateway

MockH

API Browsing

Authentication

Client Caching (Policy)

Client Caching (Validation)

Compression

Content

CORS

Decompression

Defaults

Directory Browsing

Error Handling

Files

Hardening

Inspection

Layouting

Liquid Pages

Load Balancer

Localization

Open API

Pages

Range Support

Redirects

Reverse Proxies

Server Sent Events (SSE)

Virtual Hosts