:star: Please star this project if you find it useful!
This README is for EmbedIO v3.x. Click here if you are still using EmbedIO v2.x.
A tiny, cross-platform, module based, MIT-licensed web server for .NET Framework and .NET Core.
HttpListener
or internal Http Listener based on Mono/websocket-sharp projectsThe major version 3.0 includes a lot of changes in how the webserver process the incoming request and the pipeline of the Web Modules. You can check a complete list of changes and a upgrade guide for v2 users here.
You can start using EmbedIO by just downloading the nuget.
PM> Install-Package EmbedIO
> dotnet add package EmbedIO
Working with EmbedIO is pretty simple, check the follow sections to start coding right away. You can find more useful recipes and implementation details in the Cookbook.
Please note the comments are the important part here. More info is available in the samples.
namespace Unosquare
{
using System;
using EmbedIO;
using EmbedIO.WebApi;
class Program
{
/// <summary>
/// Defines the entry point of the application.
/// </summary>
/// <param name="args">The arguments.</param>
static void Main(string[] args)
{
var url = "http://localhost:9696/";
if (args.Length > 0)
url = args[0];
// Our web server is disposable.
using (var server = CreateWebServer(url))
{
// Once we've registered our modules and configured them, we call the RunAsync() method.
server.RunAsync();
var browser = new System.Diagnostics.Process()
{
StartInfo = new System.Diagnostics.ProcessStartInfo(url) { UseShellExecute = true }
};
browser.Start();
// Wait for any key to be pressed before disposing of our web server.
// In a service, we'd manage the lifecycle of our web server using
// something like a BackgroundWorker or a ManualResetEvent.
Console.ReadKey(true);
}
}
// Create and configure our web server.
private static WebServer CreateWebServer(string url)
{
var server = new WebServer(o => o
.WithUrlPrefix(url)
.WithMode(HttpListenerMode.EmbedIO))
// First, we will configure our web server by adding Modules.
.WithLocalSessionManager()
.WithWebApi("/api", m => m
.WithController<PeopleController>())
.WithModule(new WebSocketChatModule("/chat"))
.WithModule(new WebSocketTerminalModule("/terminal"))
.WithStaticFolder("/", HtmlRootPath, true, m => m
.WithContentCaching(UseFileCache)) // Add static files after other modules to avoid conflicts
.WithModule(new ActionModule("/", HttpVerbs.Any, ctx => ctx.SendDataAsync(new { Message = "Error" })));
// Listen for state changes.
server.StateChanged += (s, e) => $"WebServer New State - {e.NewState}".Info();
return server;
}
}
}
For reading a dictionary from an HTTP Request body inside a WebAPI method you can add an argument to your method with the attribute FormData
.
[Route(HttpVerbs.Post, "/data")]
public async Task PostData([FormData] NameValueCollection data)
{
// Perform an operation with the data
await SaveData(data);
}
For reading a JSON payload and deserialize it to an object from an HTTP Request body you can use GetRequestDataAsyncIHttpContext
and returns an object of the type specified in the generic type.
[Route(HttpVerbs.Post, "/data")]
public async Task PostJsonData()
{
var data = HttpContext.GetRequestDataAsync<MyData>();
// Perform an operation with the data
await SaveData(data);
}
EmbedIO doesn't provide the functionality to read from a Multipart FormData stream. But you can check the HttpMultipartParser Nuget and connect the Request input directly to the HttpMultipartParser, very helpful and small library.
A sample code using the previous library:
[Route(HttpVerbs.Post, "/upload")]
public async Task UploadFile()
{
var parser = await MultipartFormDataParser.ParseAsync(Request.InputStream);
// Now you can access parser.Files
}
There is another solution but it requires this Microsoft Nuget.
You can open the Response Output Stream with the extension [OpenResponseStream]().
[Route(HttpVerbs.Get, "/binary")]
public async Task GetBinary()
{
// Call a fictional external source
using (var stream = HttpContext.OpenResponseStream())
await stream.WriteAsync(dataBuffer, 0, 0);
}
Working with WebSocket is pretty simple, you just need to implement the abstract class WebSocketModule
and register the module to your Web server as follow:
server..WithModule(new WebSocketChatModule("/chat"));
And our web sockets server class looks like:
namespace Unosquare
{
using EmbedIO.WebSockets;
/// <summary>
/// Defines a very simple chat server.
/// </summary>
public class WebSocketsChatServer : WebSocketModule
{
public WebSocketsChatServer(string urlPath)
: base(urlPath, true)
{
// placeholder
}
/// <inheritdoc />
protected override Task OnMessageReceivedAsync(
IWebSocketContext context,
byte[] rxBuffer,
IWebSocketReceiveResult rxResult)
=> SendToOthersAsync(context, Encoding.GetString(rxBuffer));
/// <inheritdoc />
protected override Task OnClientConnectedAsync(IWebSocketContext context)
=> Task.WhenAll(
SendAsync(context, "Welcome to the chat room!"),
SendToOthersAsync(context, "Someone joined the chat room."));
/// <inheritdoc />
protected override Task OnClientDisconnectedAsync(IWebSocketContext context)
=> SendToOthersAsync(context, "Someone left the chat room.");
private Task SendToOthersAsync(IWebSocketContext context, string payload)
=> BroadcastAsync(payload, c => c != context);
}
}
Both HTTP listeners (Microsoft and Unosquare) can open a web server using SSL. This support is for Windows only (for now) and you need to manually register your certificate or use the WebServerOptions
class to initialize a new WebServer
instance. This section will provide some examples of how to use SSL but first a brief explanation of how SSL works on Windows.
For Windows Vista or better, Microsoft provides Network Shell (netsh
). This command line tool allows to map an IP-port to a certificate, so incoming HTTP request can upgrade the connection to a secure stream using the provided certificate. EmbedIO can read or register certificates to a default store (My/LocalMachine) and use them against a netsh sslcert
for binding the first https
prefix registered.
For Windows XP and Mono, you can use manually the httpcfg
for registering the binding.
The more practical case to use EmbedIO with SSL is the AutoRegister
option. You need to create a WebServerOptions
instance with the path to a PFX file and the AutoRegister
flag on. This options will try to get or register the certificate to the default certificate store. Then it will use the certificate thumbprint to register with netsh
the FIRST https
prefix registered on the options.
If you already have a certificate on the default certificate store and the binding is also registered in netsh
, you can use Autoload
flag and optionally provide a certificate thumbprint. If the certificate thumbprint is not provided, EmbedIO will read the data from netsh
. After getting successfully the certificate from the store, the raw data is passed to the WebServer.
Name | Author | Description |
---|---|---|
Butterfly.EmbedIO | Fireshark Studios, LLC | Implementation of Butterfly.Core.Channel and Butterfly.Core.WebApi using the EmbedIO server |
embedio-cli | Unosquare | A dotnet global tool that enables start any web folder or EmbedIO assembly (WebAPI or WebSocket) from command line. |
EmbedIO.BearerToken | Unosquare | Allow to authenticate with a Bearer Token. It uses a Token endpoint (at /token path) and with a defined validation delegate create a JsonWebToken. The module can check all incoming requests or a paths |
EmbedIO.LiteLibWebApi | Unosquare | Allow to expose a sqlite database as REST api using EmbedIO WebApi and LiteLib libraries |
EmbedIO.OWIN | Unosquare | EmbedIO can use the OWIN platform in two different approach: You can use EmbedIO as OWIN server and use all OWIN framework with EmbedIO modules. |
Microsoft.AspNetCore.Server.EmbedIO | Dju | EmbedIO web server support for ASP.NET Core, as a drop-in replacement for Kestrel |
SambaFetcher | nddipiazza | A .NET tool to connect a web server with Samba |
To YourKit for supports open source projects with its full-featured .NET Profiler, an amazing tool to profile CPU and Memory!