We\u2019re excited to announce experimental support for the WebTransport over HTTP\/3 protocol as part of .NET 7 RC1.<\/p>\n
This feature and blog post were written by our excellent intern Daniel Genkin<\/a>!<\/p>\n WebTransport is a new draft specification<\/a> for a transport protocol similar to WebSockets that allows the usage of multiple streams per connection.<\/p>\n WebSockets<\/a> allowed upgrading a whole HTTP TCP\/TLS connection to a bidirectional data stream. If you needed to open more streams you’d spend additional time and resources establishing new TCP and TLS sessions. WebSockets over HTTP\/2<\/a> streamlined this by allowing multiple WebSocket streams to be established over one HTTP\/2 TCP\/TLS session. The downside here is that because this was still based on TCP, any packets lost from one stream would cause delays for every stream on the connection.<\/p>\n With the introduction of HTTP\/3 and QUIC, which uses UDP rather than TCP, WebTransport can be used to establish multiple streams on one connection without them blocking each other. For example, consider an online game where the game state is transmitted on one bidirectional stream, the players’ voices for the game’s voice chat feature on another bidirectional stream, and the player’s controls are transmitted on a unidirectional stream. With WebSockets, these would all need to be put on separate connections or squashed into a single stream. With WebTransport, you can keep all the traffic on one connection but separate them into their own streams and, if one stream were to drop network packets, the others could continue uninterrupted.<\/p>\n You can enable WebTransport support in ASP.NET Core by setting To setup a WebTransport connection, you first need to configure a web host to listen on a port over HTTP\/3:<\/p>\n WebTransport uses HTTP\/3, so you must select the The default Kestrel development certificate cannot be used for WebTransport connections. For local testing you can use the workaround described in the Obtaining a test certificate section<\/a>.<\/p>\n Next, we define the code that will run when Kestrel receives a connection.<\/p>\n The Calling Once the session has been established both the client and server can create streams for that session.<\/p>\n This example accepts a session, waits for a bidirectional stream, reads some data, reverse it, and then writes it back to the stream.<\/p>\n This example opens a new stream from the server side and then sends data.<\/p>\n To showcase the functionality of the WebTransport support in Kestrel, we also created two sample apps: an interactive<\/a> one and a console-based<\/a> one. You can run them in Visual Studio via the F5 run options.<\/p>\n The current Kestrel development certificate cannot be used for WebTransport connections as it does not meet the requirements needed for WebTransport over HTTP\/3. You can generate a new certificate for testing via the following C# (this function will also automatically handle certificate rotation every time one expires):<\/p>\n WebTransport offers exciting new possibilities for real-time app developers, making it easier and more efficient to stream multiple kinds of data back and forth with the client.<\/p>\nWhat is WebTransport<\/h2>\n
Enabling WebTransport<\/h2>\n
EnablePreviewFeatures<\/code> to True<\/code> and adding the following RuntimeHostConfigurationOption<\/code> item in your project’s .csproj<\/code> file:<\/p>\n<Project Sdk=\"Microsoft.NET.Sdk.Web\">\r\n <PropertyGroup>\r\n <EnablePreviewFeatures>True<\/EnablePreviewFeatures>\r\n <\/PropertyGroup>\r\n\r\n <ItemGroup>\r\n <RuntimeHostConfigurationOption Include=\"Microsoft.AspNetCore.Server.Kestrel.Experimental.WebTransportAndH3Datagrams\" Value=\"true\" \/>\r\n <\/ItemGroup>\r\n<\/Project><\/code><\/pre>\nSetting up a Server<\/h2>\n
var builder = WebApplication.CreateBuilder(args);\r\nbuilder.WebHost.ConfigureKestrel((context, options) =>\r\n{\r\n \/\/ Port configured for WebTransport\r\n options.ListenAnyIP([SOME PORT], listenOptions =>\r\n {\r\n listenOptions.UseHttps(GenerateManualCertificate());\r\n listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;\r\n });\r\n});\r\nvar app = builder.Build();<\/code><\/pre>\nlistenOptions.UseHttps<\/code> setting as well as set the listenOptions.Protocols<\/code> to include HTTP\/3.<\/p>\napp.Run(async (context) =>\r\n{\r\n var feature = context.Features.GetRequiredFeature<IHttpWebTransportFeature>();\r\n if (!feature.IsWebTransportRequest)\r\n {\r\n return;\r\n }\r\n var session = await feature.AcceptAsync(CancellationToken.None);\r\n\r\n \/\/ Use WebTransport via the newly established session.\r\n});\r\n\r\nawait app.RunAsync();<\/code><\/pre>\nRun<\/code> method is triggered every time there is a connection request. The IsWebTransportRequest<\/code> property on the IHttpWebTransportFeature<\/code> indicates if the current request is a WebTransport request. Once a WebTransport request is received, calling IHttpWebTransportFeature.AcceptAsync()<\/code> accepts the WebTransport session so you can interact with the client. This original request must be kept alive for the durration of the session or else all streams associated with that session will be closed.<\/p>\nawait app.RunAsync()<\/code> starts the server, which can then start accepting connections.<\/p>\nInteracting with a WebTransport Session<\/h2>\n
app.Run(async (context) =>\r\n{\r\n var feature = context.Features.GetRequiredFeature<IHttpWebTransportFeature>();\r\n if (!feature.IsWebTransportRequest)\r\n {\r\n return;\r\n }\r\n var session = await feature.AcceptAsync(CancellationToken.None);\r\n\r\n ConnectionContext? stream = null;\r\n IStreamDirectionFeature? direction = null;\r\n while (true)\r\n {\r\n \/\/ wait until we get a stream\r\n stream = await session.AcceptStreamAsync(CancellationToken.None);\r\n if (stream is null)\r\n {\r\n \/\/ if a stream is null, this means that the session failed to get the next one.\r\n \/\/ Thus, the session has ended, or some other issue has occurred. We end the\r\n \/\/ connection in this case.\r\n return;\r\n }\r\n\r\n \/\/ check that the stream is bidirectional. If yes, keep going, otherwise\r\n \/\/ dispose its resources and keep waiting.\r\n direction = stream.Features.GetRequiredFeature<IStreamDirectionFeature>();\r\n if (direction.CanRead && direction.CanWrite)\r\n {\r\n break;\r\n }\r\n else\r\n {\r\n await stream.DisposeAsync();\r\n }\r\n }\r\n\r\n var inputPipe = stream!.Transport.Input;\r\n var outputPipe = stream!.Transport.Output;\r\n\r\n \/\/ read some data from the stream into the memory\r\n var length = await inputPipe.AsStream().ReadAsync(memory);\r\n\r\n \/\/ slice to only keep the relevant parts of the memory\r\n var outputMemory = memory[..length];\r\n\r\n \/\/ do some operations on the contents of the data\r\n outputMemory.Span.Reverse();\r\n\r\n \/\/ write back the data to the stream\r\n await outputPipe.WriteAsync(outputMemory);\r\n});\r\n\r\nawait app.RunAsync();<\/code><\/pre>\napp.Run(async (context) =>\r\n{\r\n var feature = context.Features.GetRequiredFeature<IHttpWebTransportFeature>();\r\n if (!feature.IsWebTransportRequest)\r\n {\r\n return;\r\n }\r\n var session = await feature.AcceptAsync(CancellationToken.None);\r\n\r\n \/\/ open a new stream from the server to the client\r\n var stream = await session.OpenUnidirectionalStreamAsync(CancellationToken.None);\r\n\r\n if (stream is not null)\r\n {\r\n \/\/ write data to the stream\r\n var outputPipe = stream.Transport.Output;\r\n await outputPipe.WriteAsync(new Memory<byte>(new byte[] { 65, 66, 67, 68, 69 }), CancellationToken.None);\r\n await outputPipe.FlushAsync(CancellationToken.None);\r\n }\r\n});\r\n\r\nawait app.RunAsync();<\/code><\/pre>\nSample Apps<\/h2>\n
Obtaining a test certificate<\/h2>\n
static X509Certificate2 GenerateManualCertificate()\r\n{\r\n X509Certificate2 cert = null;\r\n var store = new X509Store(\"KestrelWebTransportCertificates\", StoreLocation.CurrentUser);\r\n store.Open(OpenFlags.ReadWrite);\r\n if (store.Certificates.Count > 0)\r\n {\r\n cert = store.Certificates[^1];\r\n\r\n \/\/ rotate key after it expires\r\n if (DateTime.Parse(cert.GetExpirationDateString(), null) < DateTimeOffset.UtcNow)\r\n {\r\n cert = null;\r\n }\r\n }\r\n if (cert == null)\r\n {\r\n \/\/ generate a new cert\r\n var now = DateTimeOffset.UtcNow;\r\n SubjectAlternativeNameBuilder sanBuilder = new();\r\n sanBuilder.AddDnsName(\"localhost\");\r\n using var ec = ECDsa.Create(ECCurve.NamedCurves.nistP256);\r\n CertificateRequest req = new(\"CN=localhost\", ec, HashAlgorithmName.SHA256);\r\n \/\/ Adds purpose\r\n req.CertificateExtensions.Add(new X509EnhancedKeyUsageExtension(new OidCollection\r\n {\r\n new(\"1.3.6.1.5.5.7.3.1\") \/\/ serverAuth\r\n }, false));\r\n \/\/ Adds usage\r\n req.CertificateExtensions.Add(new X509KeyUsageExtension(X509KeyUsageFlags.DigitalSignature, false));\r\n \/\/ Adds subject alternate names\r\n req.CertificateExtensions.Add(sanBuilder.Build());\r\n \/\/ Sign\r\n using var crt = req.CreateSelfSigned(now, now.AddDays(14)); \/\/ 14 days is the max duration of a certificate for this\r\n cert = new(crt.Export(X509ContentType.Pfx));\r\n\r\n \/\/ Save\r\n store.Add(cert);\r\n }\r\n store.Close();\r\n\r\n var hash = SHA256.HashData(cert.RawData);\r\n var certStr = Convert.ToBase64String(hash);\r\n Console.WriteLine($\"\\n\\n\\n\\n\\nCertificate: {certStr}\\n\\n\\n\\n\"); \/\/ <-- you will need to put this output into the JS API call to allow the connection\r\n return cert;\r\n}\r\n\/\/ Adapted from: https:\/\/github.com\/wegylexy\/webtransport<\/code><\/pre>\nGoing Forward<\/h2>\n