⭐ 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;
}
}
} Reading from a POST body as a dictionary (application/x-www-form-urlencoded)
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);
} Reading from a POST body as a JSON payload (application/json)
For reading a JSON payload and deserialize it to an object from an HTTP Request body you can use GetRequestDataAsync. This method works directly from IHttpContext 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);
} Reading from a POST body as a FormData (multipart/form-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.
To YourKit for supports open source projects with its full-featured .NET Profiler, an amazing tool to profile CPU and Memory!
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4