This project is a custom abstraction layer built on top of System.Net.WebSockets standard implementations, to handle WebSocket lifecycle, parse and convert messages from / to byte arrays. The abstractions are for both client-side and server-side (ASP.NET).
It has full compatibility with NativeAOT and trimming.
Add the NuGet package to the project file:
<ItemGroup>
<PackageReference Include="AlexandreHtrb.WebSocketExtensions" Version="1.2.0" />
</ItemGroup>It's quite simple to use. The WebSocketServerSideConnector and WebSocketClientSideConnector classes receive native WebSocket objects from .NET and take care of all WebSocket's lifecycle, connection and disconnection, receiving and sending messages, and conversion from/to byte arrays.
Inside each connector there is an ExchangedMessagesCollector, which collects the messages sent and received, and makes them available through an IAsyncEnumerable. Thus, the conversation between client and server goes inside an asynchronous await foreach loop. When one of the parties disconnects, the execution leaves the loop.
Before entering the conversation loop, one of the parties must take the initiative to send a message.
WebSocketServerSideConnector wsc = new(ws, collectOnlyClientSideMessages: true);
await foreach (var msg in wsc.ExchangedMessagesCollector!.ReadAllAsync())
{
await wsc.SendMessageAsync(WebSocketMessageType.Text, msg.ReadAsUtf8Text() switch
{
"Hello!" => "Hi!",
"What time is it?" => "Now it's " + DateTime.Now.TimeOfDay,
"Thanks!" => "You're welcome!",
_ => "I don't understand your message!"
}, false);
}using var cws = MakeClientWebSocket();
using var hc = MakeHttpClient(disableSslVerification: true);
Uri uri = new("ws://localhost:5000/test/http1websocket");
WebSocketClientSideConnector wsc = new(collectOnlyServerSideMessages: true);
// Connecting
await wsc.ConnectAsync(cws, hc, uri, cancellationToken);
// Sending first message
await wsc.SendMessageAsync(WebSocketMessageType.Text, "Hello!", false);
// Conversation loop
await foreach (var msg in wsc.ExchangedMessagesCollector!.ReadAllAsync())
{
string? replyTxt = msg.ReadAsUtf8Text() switch
{
"Hi!" => "What time is it?",
string s when s.StartsWith("Now it's") => "Thanks!",
_ => null
};
if (replyTxt != null)
await wsc.SendMessageAsync(WebSocketMessageType.Text, replyTxt, false);
}With the code above, the conversation should go on like this:
Client: Hello!
Server: Hi!
Client: What time is it?
Server: Now it's 11:54:53
Client: Thanks!
Server: You're welcome!
- Enable
app.UseWebSockets():
private static IApplicationBuilder ConfigureApp(this WebApplication app) =>
app.MapTestEndpoints()
.UseWebSockets(new()
{
KeepAliveInterval = TimeSpan.FromMinutes(2)
});- Map the WebSocket endpoint:
public static WebApplication MapTestEndpoints(this WebApplication app)
{
app.MapGet("test/http1websocket", TestHttp1WebSocket);
return app;
}
private static async Task TestHttp1WebSocket(HttpContext httpCtx, ILogger<BackgroundWebSocketsProcessor> logger)
{
if (!httpCtx.WebSockets.IsWebSocketRequest)
{
byte[] txtBytes = Encoding.UTF8.GetBytes("Only WebSockets requests are accepted here!");
httpCtx.Response.StatusCode = (int)HttpStatusCode.BadRequest;
await httpCtx.Response.BodyWriter.WriteAsync(txtBytes);
}
else
{
using var webSocket = await httpCtx.WebSockets.AcceptWebSocketAsync();
TaskCompletionSource<object> socketFinishedTcs = new();
await BackgroundWebSocketsProcessor.RegisterAndProcessAsync(logger, webSocket, socketFinishedTcs);
await socketFinishedTcs.Task;
}
}- Create a WebSocket processor:
using AlexandreHtrb.WebSocketExtensions;
using System.Net.WebSockets;
public static class BackgroundWebSocketsProcessor
{
public static async Task RegisterAndProcessAsync(ILogger<BackgroundWebSocketsProcessor> logger, WebSocket ws, TaskCompletionSource<object> socketFinishedTcs)
{
WebSocketServerSideConnector wsc = new(ws, collectOnlyClientSideMessages: true);
int msgCount = 0;
await foreach (var msg in wsc.ExchangedMessagesCollector!.ReadAllAsync())
{
logger.LogInformation("Message {msgCount}, {direction}: {msgText}", ++msgCount, msg.Direction, msg.FormatForLogging());
// handle messages here
}
socketFinishedTcs.SetResult(true); // finish connection
}
}wsc.OnConnectionChanged = (state, exception) =>
{
logger.LogInformation("Connection state: {state}", state);
logger.LogError(exception, "Connection exception");
};Here we can put connection retries.
Keep-Alive is the mechanism to keep the WebSocket alive, without being cut-off by proxies and middleboxes.
On .NET, we can configure a frequency interval, where the party sends a ping frame, and a timeout period, which the party awaits for a pong response frame after the ping frame has been sent. If a pong is not received, the connection is considered dead.
This topic is covered in more detail on this WebSocket.org page.
ClientWebSocket cws = new();
cws.Options.KeepAliveInterval = TimeSpan.FromSeconds(30);
#if NET10_0_OR_GREATER
cws.Options.KeepAliveTimeout = TimeSpan.FromSeconds(45);
#endif
await wsc.ConnectAsync(cws, hc, uri, default);private static IApplicationBuilder ConfigureApp(this WebApplication app) =>
app.MapTestEndpoints()
.UseWebSockets(new()
{
KeepAliveInterval = TimeSpan.FromSeconds(30),
#if NET10_0_OR_GREATER
KeepAliveTimeout = TimeSpan.FromSeconds(45)
#endif
});WebSocketServerSideConnector wsc = new(ws, collectOnlyClientSideMessages: false);
WebSocketClientSideConnector wsc = new(collectOnlyServerSideMessages: false);The booleans control whether only messages from the opposite side will be collected. Collecting messages from the own side may be interesting for logging.
while (!cancellationToken.IsCancellationRequested)
{
await Task.Delay(TimeSpan.FromSeconds(15), cancellationToken);
await wsc.SendMessageAsync(WebSocketMessageType.Text, "Are you there?", false);
}_ = Task.Run(async () =>
{
await Task.Delay(maximumLifetimePeriod, cancellationToken);
await wsc.DisconnectAsync();
});// don't use 'using'
FileStream fs = new("C:\\Files\my_image.jpg", FileMode.Open);
await wsc.SendMessageAsync(WebSocketMessageType.Binary, fs, false);When using Streams to send messages, don't use the using keyword. The Stream will be disposed further, inside the connector.
Also, when sending files, it may be interesting to set a larger buffer size on the WebSocketConnector. When larger buffers are used, less roundtrips are required to read a Stream, which may make for quicker transmissions.
WebSocketServerSideConnector wsc = new(ws, true, bufferSize: 65_536);
WebSocketClientSideConnector wsc = new(bufferSize: 65_536);ClientWebSocket cws = new();
cws.Options.CollectHttpResponseDetails = true;
await wsc.ConnectAsync(cws, hc, uri, cancellationToken);
var wsHttpStatusCode = wsc.ConnectionHttpStatusCode;
var wsResponseHeaders = wsc.ConnectionHttpHeaders;ClientWebSocket cws = new();
cws.Options.SetRequestHeader("Authorization", "Bearer my_token");
cws.Options.SetRequestHeader("Header1", "Value1");
await wsc.ConnectAsync(cws, hc, uri, cancellationToken);ClientWebSocket cws = new();
cws.Options.AddSubProtocol("subprotocol1");
await wsc.ConnectAsync(cws, hc, uri, cancellationToken);private static async Task TestHttp1WebSocket(HttpContext httpCtx, ILogger<BackgroundWebSocketsProcessor> logger)
{
if (!httpCtx.WebSockets.IsWebSocketRequest)
{
// ...
}
else
{
using var webSocket = await httpCtx.WebSockets.AcceptWebSocketAsync();
TaskCompletionSource<object> socketFinishedTcs = new();
+ string? subprotocol = webSocket.SubProtocol ?? httpCtx.WebSockets.WebSocketRequestedProtocols.FirstOrDefault();
await BackgroundWebSocketsProcessor.RegisterAndProcessAsync(logger, webSocket, subprotocol, socketFinishedTcs);
await socketFinishedTcs.Task;
}
}ClientWebSocket cws = new();
cws.Options.DangerousDeflateOptions = new()
{
ClientContextTakeover = true,
ClientMaxWindowBits = 14,
ServerContextTakeover = true,
ServerMaxWindowBits = 14
};
await wsc.ConnectAsync(cws, hc, uri, cancellationToken);Important: Don't pass secrets and encrypted texts in compressed messages, because there is the risk of BREACH and CRIME attacks. In these cases, disable compression for those messages:
await wsc.SendMessageAsync(
WebSocketMessageType.Text,
$"Encrypted token {token}",
disableCompression: true);ClientWebSocket cws = new();
cws.Options.HttpVersionPolicy = HttpVersionPolicy.RequestVersionExact;
cws.Options.HttpVersion = new(2,0);
await wsc.ConnectAsync(cws, hc, uri, cancellationToken);On HTTP/2 WebSockets, the HTTP method CONNECT is used, instead of GET.
public static WebApplication MapTestEndpoints(this WebApplication app)
{
app.MapMethods("test/http2websocket", new[] { HttpMethods.Connect }, TestHttp2WebSocket);
return app;
}