WebSockets-ondersteuning in ASP.NET Core

In dit artikel wordt uitgelegd hoe u aan de slag gaat met WebSockets in ASP.NET Core. WebSocket (RFC 6455) is een protocol waarmee permanente communicatiekanalen in twee richtingen via TCP-verbindingen mogelijk zijn. Het wordt gebruikt in apps die profiteren van snelle, realtime communicatie, zoals chatten, dashboard en game-apps.

Voorbeeldcode weergeven of downloaden (downloaden, uitvoeren).

Ondersteuning voor Http/2 WebSockets

Het gebruik van WebSockets via HTTP/2 maakt gebruik van nieuwe functies, zoals:

• Headercompressie.
• Multiplexing, wat de tijd en resources vermindert die nodig zijn bij het indienen van meerdere aanvragen naar de server.

Deze ondersteunde functies zijn beschikbaar in Kestrel op alle platforms waarvoor HTTP/2 is ingeschakeld. De versieonderhandeling is automatisch in browsers en Kestrel, dus er zijn geen nieuwe API's nodig.

.NET 7 heeft WebSockets geïntroduceerd via HTTP/2-ondersteuning voor Kestrel, de SignalR JavaScript-client en SignalR met Blazor WebAssembly.

WebSockets zijn oorspronkelijk ontworpen voor HTTP/1.1, maar zijn sindsdien aangepast voor gebruik via HTTP/2. (RFC 8441)

SignalR

ASP.NET Core SignalR is een bibliotheek die het toevoegen van realtime webfunctionaliteit aan apps vereenvoudigt. Het maakt waar mogelijk gebruik van WebSockets.

Voor de meeste toepassingen raden we u aan SignalR in plaats van onbewerkte WebSockets. SignalR:

• Biedt terugval naar transport voor omgevingen waar WebSockets niet beschikbaar is.
• Biedt een eenvoudig model voor een afstandsprocedureoproep-app.
• Heeft geen significant prestatienadelen vergeleken met het gebruik van onbewerkte WebSockets in de meeste scenario's.

WebSockets via HTTP/2 worden ondersteund voor:

• ASP.NET Core SignalR JavaScript-client
• ASP.NET Core SignalR met Blazor WebAssembly

Voor sommige apps biedt gRPC op .NET een alternatief voor WebSockets.

Prerequisites

• Elk besturingssysteem dat ondersteuning biedt voor ASP.NET Core:
  • Windows 7/ Windows Server 2008 of hoger
  • Linux
  • macOS
• Als de app wordt uitgevoerd in Windows met IIS:
  • Windows 8/Windows Server 2012 of hoger
  • IIS 8 / IIS 8 Express
  • WebSockets moeten zijn ingeschakeld. Zie de sectie ondersteuning voor IIS/IIS Express .
• Als de app wordt uitgevoerd op HTTP.sys:
  • Windows 8/Windows Server 2012 of hoger
• Zie Kan ik gebruiken voor ondersteunde browsers.

De middleware configureren

Voeg de WebSockets-middleware toe aan Program.cs:

app.UseWebSockets();

De volgende instellingen kunnen worden geconfigureerd:

• KeepAliveInterval - Hoe vaak 'ping'-frames naar de client worden verzonden om ervoor te zorgen dat proxy's de verbinding open houden. De standaardwaarde is twee minuten.
• AllowedOrigins - Een lijst met toegestane Origin-headerwaarden voor WebSocket-aanvragen. Standaard zijn alle oorsprongen toegestaan. Zie WebSocket Origin-beperking in dit artikel voor meer informatie.

var webSocketOptions = new WebSocketOptions
{
    KeepAliveInterval = TimeSpan.FromMinutes(2)
};

app.UseWebSockets(webSocketOptions);

WebSocket-aanvragen accepteren

Ergens later in de levenscyclus van de aanvraag (later in Program.cs of in een actiemethode, bijvoorbeeld) controleert u of het een WebSocket-aanvraag is en accepteert u de WebSocket-aanvraag.

Het volgende voorbeeld is van later in Program.cs:

app.Use(async (context, next) =>
{
    if (context.Request.Path == "/ws")
    {
        if (context.WebSockets.IsWebSocketRequest)
        {
            using var webSocket = await context.WebSockets.AcceptWebSocketAsync();
            await Echo(webSocket);
        }
        else
        {
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
        }
    }
    else
    {
        await next(context);
    }

});

Een WebSocket-aanvraag kan op elke URL binnenkomen, maar deze voorbeeldcode accepteert alleen aanvragen voor /ws.

Een vergelijkbare benadering kan worden gebruikt in een controllermethode:

public class WebSocketController : ControllerBase
{
    [Route("/ws")]
    public async Task Get()
    {
        if (HttpContext.WebSockets.IsWebSocketRequest)
        {
            using var webSocket = await HttpContext.WebSockets.AcceptWebSocketAsync();
            await Echo(webSocket);
        }
        else
        {
            HttpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
        }
    }

Wanneer u een WebSocket gebruikt, moet u de middleware-pijplijn actief houden voor de duur van de verbinding. Als u probeert een WebSocket-bericht te verzenden of te ontvangen nadat de middleware-pijplijn is beëindigd, krijgt u mogelijk een uitzondering als de volgende:

System.Net.WebSockets.WebSocketException (0x80004005): The remote party closed the WebSocket connection without completing the close handshake. ---> System.ObjectDisposedException: Cannot write to the response body, the response has completed.
Object name: 'HttpResponseStream'.

Als u een achtergrondservice gebruikt om gegevens naar een WebSocket te schrijven, moet u ervoor zorgen dat de middleware-pijplijn actief blijft. Doe dit met behulp van een TaskCompletionSource<TResult>. Geef de TaskCompletionSource aan uw achtergrondservice door en laat deze aanroepen TrySetResult wanneer u klaar bent met de WebSocket. Stel vervolgens await de Task eigenschap in tijdens de aanvraag, zoals wordt weergegeven in het volgende voorbeeld:

app.Run(async (context) =>
{
    using var webSocket = await context.WebSockets.AcceptWebSocketAsync();
    var socketFinishedTcs = new TaskCompletionSource<object>();

    BackgroundSocketProcessor.AddSocket(webSocket, socketFinishedTcs);

    await socketFinishedTcs.Task;
});

De WebSocket-gesloten-exceptie kan ook optreden wanneer er te vroeg wordt teruggekeerd vanuit een actiemethode. Wanneer u een socket in een actiemethode accepteert, wacht u tot de code die gebruikmaakt van de socket is voltooid voordat u uit de actiemethode terugkeert.

Gebruik nooit Task.Wait, Task.Result of soortgelijke blokkerende aanroepen om te wachten tot de socket is voltooid, omdat dit ernstige problemen met threading kan veroorzaken. Gebruik altijd await.

HTTP/2 WebSockets-ondersteuning toevoegen voor bestaande controllers

.NET 7 heeft WebSockets geïntroduceerd via HTTP/2-ondersteuning voor Kestrel, de SignalR JavaScript-client en SignalR met Blazor WebAssembly. HTTP/2 WebSockets gebruiken CONNECT-aanvragen in plaats van GET. Als u eerder [HttpGet("/path")] hebt gebruikt voor de actiemethode van de controller voor Websocket-aanvragen, werkt u deze bij om [Route("/path")] te gebruiken.

public class WebSocketController : ControllerBase
{
    [Route("/ws")]
    public async Task Get()
    {
        if (HttpContext.WebSockets.IsWebSocketRequest)
        {
            using var webSocket = await HttpContext.WebSockets.AcceptWebSocketAsync();
            await Echo(webSocket);
        }
        else
        {
            HttpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
        }
    }

Compression

Als compressie van berichten via WebSockets gewenst is, moet de acceptcode opgeven dat compressie als volgt is toegestaan:

using (var webSocket = await context.WebSockets.AcceptWebSocketAsync(
    new WebSocketAcceptContext { DangerousEnableCompression = true }))
{

}

WebSocketAcceptContext.ServerMaxWindowBits en WebSocketAcceptContext.DisableServerContextTakeover zijn geavanceerde opties die bepalen hoe de compressie werkt.

Compressie wordt onderhandeld tussen de client en de server bij het tot stand brengen van een verbinding. Meer informatie over de onderhandeling vindt u in de compressie-extensies voor WebSocket RFC.

Berichten verzenden en ontvangen

De AcceptWebSocketAsync methode werkt de TCP-verbinding bij naar een WebSocket-verbinding en biedt een WebSocket object. Gebruik het WebSocket object om berichten te verzenden en te ontvangen.

De code die eerder is weergegeven die de WebSocket-aanvraag accepteert, geeft het WebSocket object door aan een Echo methode. De code ontvangt een bericht en stuurt onmiddellijk hetzelfde bericht terug. Berichten worden verzonden en ontvangen in een lus totdat de client de verbinding sluit:

private static async Task Echo(WebSocket webSocket)
{
    var buffer = new byte[1024 * 4];
    var receiveResult = await webSocket.ReceiveAsync(
        new ArraySegment<byte>(buffer), CancellationToken.None);

    while (!receiveResult.CloseStatus.HasValue)
    {
        await webSocket.SendAsync(
            new ArraySegment<byte>(buffer, 0, receiveResult.Count),
            receiveResult.MessageType,
            receiveResult.EndOfMessage,
            CancellationToken.None);

        receiveResult = await webSocket.ReceiveAsync(
            new ArraySegment<byte>(buffer), CancellationToken.None);
    }

    await webSocket.CloseAsync(
        receiveResult.CloseStatus.Value,
        receiveResult.CloseStatusDescription,
        CancellationToken.None);
}

Wanneer u de WebSocket-verbinding accepteert voordat de lus wordt gestart, eindigt de middleware-pijplijn. Na het sluiten van de socket rolt de pijplijn zich op. Dat wil gezegd, de aanvraag stopt met verdergaan in de pijplijn wanneer de WebSocket wordt geaccepteerd. Wanneer de lus is voltooid en de socket is gesloten, gaat de aanvraag terug naar de pijplijn.

Beheer clientverbindingen bij verbreking

De server wordt niet automatisch geïnformeerd wanneer de verbinding met de client wordt verbroken door verlies van connectiviteit. De server ontvangt alleen een ontkoppelbericht als de client het verzendt, wat niet mogelijk is als de internetverbinding is weggevallen. Als u actie wilt ondernemen wanneer dat gebeurt, stelt u een time-out in nadat er binnen een bepaald tijdvenster niets van de client is ontvangen.

Als de client niet altijd berichten verzendt en u geen time-out wilt maken omdat de verbinding niet actief is, laat de client een timer gebruiken om elke X seconden een pingbericht te verzenden. Als op de server een bericht niet binnen 2*X seconden na de vorige is aangekomen, beëindigt u de verbinding en meldt u dat de verbinding met de client is verbroken. Wacht twee keer zo lang als het verwachte tijdsinterval om extra tijd te geven voor netwerkvertragingen die het pingbericht kunnen vertragen.

WebSocket oorsprongsbeperking

De beveiligingen van CORS zijn niet van toepassing op WebSockets. Browsers doen het volgende niet:

• VOER CORS-aanvragen vooraf uit.
• Respecteer de beperkingen die zijn opgegeven in Access-Control headers bij het maken van WebSocket-aanvragen.

Browsers verzenden echter wel de header bij het Origin uitgeven van WebSocket-aanvragen. Toepassingen moeten worden geconfigureerd om deze headers te valideren om ervoor te zorgen dat alleen WebSockets die afkomstig zijn van de verwachte oorsprongen zijn toegestaan.

Als u uw server host op "https://server.com" en uw client host op "https://client.com", voeg "https://client.com"" toe aan de lijst AllowedOrigins voor WebSockets om te verifiëren.

var webSocketOptions = new WebSocketOptions
{
    KeepAliveInterval = TimeSpan.FromMinutes(2)
};

webSocketOptions.AllowedOrigins.Add("https://client.com");
webSocketOptions.AllowedOrigins.Add("https://www.client.com");

app.UseWebSockets(webSocketOptions);

Ondersteuning voor IIS/IIS Express

Windows Server 2012 of hoger en Windows 8 of hoger met IIS/IIS Express 8 of hoger biedt ondersteuning voor het WebSocket-protocol, maar niet voor WebSockets via HTTP/2.

WebSockets inschakelen in IIS

Ondersteuning voor het WebSocket-protocol op Windows Server 2012 of hoger inschakelen:

1. Gebruik de wizard Functies en Onderdelen Toevoegen vanuit het Beheren-menu of de koppeling in Serverbeheer.
2. Selecteer rolgebaseerde of functiegebaseerde installatie. Kies Volgende.
3. Selecteer de juiste server (de lokale server is standaard geselecteerd). Kies Volgende.
4. Vouw Webserver (IIS) uit in de structuur Functies , vouw Webserver uit en vouw vervolgens Toepassingsontwikkeling uit.
5. Selecteer WebSocket Protocol. Kies Volgende.
6. Als er geen extra functies nodig zijn, selecteert u Volgende.
7. Selecteer Installeren.
8. Wanneer de installatie is voltooid, selecteert u Sluiten om de wizard af te sluiten.

Ondersteuning inschakelen voor het WebSocket-protocol in Windows 8 of hoger:

1. Ga naar Configuratiescherm>Programma's>Programma's en onderdelen>Windows-onderdelen in- of uitschakelen (links op het scherm).
2. Open de volgende knooppunten: Internetinformatieservices>World Wide Web-services>Kenmerken voor applicatieontwikkeling.
3. Selecteer de functie WebSocket Protocol. Kies OK.

WebSocket uitschakelen bij het gebruik van socket.io op Node.js

Als u de WebSocket-ondersteuning in socket.io op Node.jsgebruikt, schakelt u de standaard IIS WebSocket-module uit met behulp van het webSocket element in web.config of applicationHost.config. Als deze stap niet wordt uitgevoerd, probeert de IIS WebSocket-module de WebSocket-communicatie te verwerken in plaats van Node.js en de app.

<system.webServer>
  <webSocket enabled="false" />
</system.webServer>

Voorbeeld-app

De voorbeeld-app die bij dit artikel hoort, is een echo-app. Het bevat een webpagina die WebSocket-verbindingen maakt en de server alle berichten die het ontvangt, opnieuw verzendt naar de client. De voorbeeld-app ondersteunt WebSockets via HTTP/2 wanneer u een doelframework van .NET 7 of hoger gebruikt.

Voer de app uit:

• App uitvoeren in Visual Studio: Open het voorbeeldproject in Visual Studio en druk op Ctrl+F5 om uit te voeren zonder het foutopsporingsprogramma.
• De app uitvoeren in een opdrachtshell: voer de opdracht dotnet run uit en navigeer in een browser naar http://localhost:<port>.

Op de webpagina wordt de verbindingsstatus weergegeven:

Selecteer Verbinding maken om een WebSocket-aanvraag naar de weergegeven URL te verzenden. Voer een testbericht in en selecteer Verzenden. Wanneer u klaar bent, selecteert u Socket sluiten. De sectie Communicatielogboek rapporteert elke geopende, verzonden en gesloten actie wanneer dit gebeurt.

In dit artikel wordt uitgelegd hoe u aan de slag gaat met WebSockets in ASP.NET Core. WebSocket (RFC 6455) is een protocol waarmee permanente communicatiekanalen in twee richtingen via TCP-verbindingen mogelijk zijn. Het wordt gebruikt in apps die profiteren van snelle, realtime communicatie, zoals chatten, dashboard en game-apps.

Voorbeeldcode weergeven of downloaden (downloaden, uitvoeren).

Ondersteuning voor Http/2 WebSockets

Het gebruik van WebSockets via HTTP/2 maakt gebruik van nieuwe functies, zoals:

• Headercompressie.
• Multiplexing, wat de tijd en resources vermindert die nodig zijn bij het indienen van meerdere aanvragen naar de server.

Deze ondersteunde functies zijn beschikbaar in Kestrel op alle platforms waarvoor HTTP/2 is ingeschakeld. De versieonderhandeling is automatisch in browsers en Kestrel, dus er zijn geen nieuwe API's nodig.

.NET 7 heeft WebSockets geïntroduceerd via HTTP/2-ondersteuning voor Kestrel, de SignalR JavaScript-client en SignalR met Blazor WebAssembly.

WebSockets zijn oorspronkelijk ontworpen voor HTTP/1.1, maar zijn sindsdien aangepast voor gebruik via HTTP/2. (RFC 8441)

SignalR

ASP.NET Core SignalR is een bibliotheek die het toevoegen van realtime webfunctionaliteit aan apps vereenvoudigt. Het maakt waar mogelijk gebruik van WebSockets.

Voor de meeste toepassingen raden we u aan SignalR in plaats van onbewerkte WebSockets. SignalR:

• Biedt terugval naar transport voor omgevingen waar WebSockets niet beschikbaar is.
• Biedt een eenvoudig model voor een afstandsprocedureoproep-app.
• Heeft geen significant prestatienadelen vergeleken met het gebruik van onbewerkte WebSockets in de meeste scenario's.

WebSockets via HTTP/2 worden ondersteund voor:

• ASP.NET Core SignalR JavaScript-client
• ASP.NET Core SignalR met Blazor WebAssembly

Voor sommige apps biedt gRPC op .NET een alternatief voor WebSockets.

Prerequisites

• Elk besturingssysteem dat ondersteuning biedt voor ASP.NET Core:
  • Windows 7/ Windows Server 2008 of hoger
  • Linux
  • macOS
• Als de app wordt uitgevoerd in Windows met IIS:
  • Windows 8/Windows Server 2012 of hoger
  • IIS 8 / IIS 8 Express
  • WebSockets moeten zijn ingeschakeld. Zie de sectie ondersteuning voor IIS/IIS Express .
• Als de app wordt uitgevoerd op HTTP.sys:
  • Windows 8/Windows Server 2012 of hoger
• Zie Kan ik gebruiken voor ondersteunde browsers.

De middleware configureren

Voeg de WebSockets-middleware toe aan Program.cs:

app.UseWebSockets();

De volgende instellingen kunnen worden geconfigureerd:

• KeepAliveInterval - Hoe vaak 'ping'-frames naar de client worden verzonden om ervoor te zorgen dat proxy's de verbinding open houden. De standaardwaarde is twee minuten.
• AllowedOrigins - Een lijst met toegestane Origin-headerwaarden voor WebSocket-aanvragen. Standaard zijn alle oorsprongen toegestaan. Zie WebSocket Origin-beperking in dit artikel voor meer informatie.

var webSocketOptions = new WebSocketOptions
{
    KeepAliveInterval = TimeSpan.FromMinutes(2)
};

app.UseWebSockets(webSocketOptions);

WebSocket-aanvragen accepteren

Ergens later in de levenscyclus van de aanvraag (later in Program.cs of in een actiemethode, bijvoorbeeld) controleert u of het een WebSocket-aanvraag is en accepteert u de WebSocket-aanvraag.

Het volgende voorbeeld is van later in Program.cs:

app.Use(async (context, next) =>
{
    if (context.Request.Path == "/ws")
    {
        if (context.WebSockets.IsWebSocketRequest)
        {
            using var webSocket = await context.WebSockets.AcceptWebSocketAsync();
            await Echo(webSocket);
        }
        else
        {
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
        }
    }
    else
    {
        await next(context);
    }

});

Een WebSocket-aanvraag kan op elke URL binnenkomen, maar deze voorbeeldcode accepteert alleen aanvragen voor /ws.

Een vergelijkbare benadering kan worden gebruikt in een controllermethode:

public class WebSocketController : ControllerBase
{
    [Route("/ws")]
    public async Task Get()
    {
        if (HttpContext.WebSockets.IsWebSocketRequest)
        {
            using var webSocket = await HttpContext.WebSockets.AcceptWebSocketAsync();
            await Echo(webSocket);
        }
        else
        {
            HttpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
        }
    }

Wanneer u een WebSocket gebruikt, moet u de middleware-pijplijn actief houden voor de duur van de verbinding. Als u probeert een WebSocket-bericht te verzenden of te ontvangen nadat de middleware-pijplijn is beëindigd, krijgt u mogelijk een uitzondering als de volgende:

System.Net.WebSockets.WebSocketException (0x80004005): The remote party closed the WebSocket connection without completing the close handshake. ---> System.ObjectDisposedException: Cannot write to the response body, the response has completed.
Object name: 'HttpResponseStream'.

Als u een achtergrondservice gebruikt om gegevens naar een WebSocket te schrijven, moet u ervoor zorgen dat de middleware-pijplijn actief blijft. Doe dit met behulp van een TaskCompletionSource<TResult>. Geef de TaskCompletionSource aan uw achtergrondservice door en laat deze aanroepen TrySetResult wanneer u klaar bent met de WebSocket. Stel vervolgens await de Task eigenschap in tijdens de aanvraag, zoals wordt weergegeven in het volgende voorbeeld:

app.Run(async (context) =>
{
    using var webSocket = await context.WebSockets.AcceptWebSocketAsync();
    var socketFinishedTcs = new TaskCompletionSource<object>();

    BackgroundSocketProcessor.AddSocket(webSocket, socketFinishedTcs);

    await socketFinishedTcs.Task;
});

De WebSocket-gesloten-exceptie kan ook optreden wanneer er te vroeg wordt teruggekeerd vanuit een actiemethode. Wanneer u een socket in een actiemethode accepteert, wacht u tot de code die gebruikmaakt van de socket is voltooid voordat u uit de actiemethode terugkeert.

Gebruik nooit Task.Wait, Task.Result of soortgelijke blokkerende aanroepen om te wachten tot de socket is voltooid, omdat dit ernstige problemen met threading kan veroorzaken. Gebruik altijd await.

HTTP/2 WebSockets-ondersteuning toevoegen voor bestaande controllers

.NET 7 heeft WebSockets geïntroduceerd via HTTP/2-ondersteuning voor Kestrel, de SignalR JavaScript-client en SignalR met Blazor WebAssembly. HTTP/2 WebSockets gebruiken CONNECT-aanvragen in plaats van GET. Als u eerder [HttpGet("/path")] hebt gebruikt voor de actiemethode van de controller voor Websocket-aanvragen, werkt u deze bij om [Route("/path")] te gebruiken.

public class WebSocketController : ControllerBase
{
    [Route("/ws")]
    public async Task Get()
    {
        if (HttpContext.WebSockets.IsWebSocketRequest)
        {
            using var webSocket = await HttpContext.WebSockets.AcceptWebSocketAsync();
            await Echo(webSocket);
        }
        else
        {
            HttpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
        }
    }

Compression

Als compressie van berichten via WebSockets gewenst is, moet de acceptcode opgeven dat compressie als volgt is toegestaan:

using (var webSocket = await context.WebSockets.AcceptWebSocketAsync(
    new WebSocketAcceptContext { DangerousEnableCompression = true }))
{

}

WebSocketAcceptContext.ServerMaxWindowBits en WebSocketAcceptContext.DisableServerContextTakeover zijn geavanceerde opties die bepalen hoe de compressie werkt.

Compressie wordt onderhandeld tussen de client en de server bij het tot stand brengen van een verbinding. Meer informatie over de onderhandeling vindt u in de compressie-extensies voor WebSocket RFC.

Berichten verzenden en ontvangen

De AcceptWebSocketAsync methode werkt de TCP-verbinding bij naar een WebSocket-verbinding en biedt een WebSocket object. Gebruik het WebSocket object om berichten te verzenden en te ontvangen.

De code die eerder is weergegeven die de WebSocket-aanvraag accepteert, geeft het WebSocket object door aan een Echo methode. De code ontvangt een bericht en stuurt onmiddellijk hetzelfde bericht terug. Berichten worden verzonden en ontvangen in een lus totdat de client de verbinding sluit:

private static async Task Echo(WebSocket webSocket)
{
    var buffer = new byte[1024 * 4];
    var receiveResult = await webSocket.ReceiveAsync(
        new ArraySegment<byte>(buffer), CancellationToken.None);

    while (!receiveResult.CloseStatus.HasValue)
    {
        await webSocket.SendAsync(
            new ArraySegment<byte>(buffer, 0, receiveResult.Count),
            receiveResult.MessageType,
            receiveResult.EndOfMessage,
            CancellationToken.None);

        receiveResult = await webSocket.ReceiveAsync(
            new ArraySegment<byte>(buffer), CancellationToken.None);
    }

    await webSocket.CloseAsync(
        receiveResult.CloseStatus.Value,
        receiveResult.CloseStatusDescription,
        CancellationToken.None);
}

Wanneer u de WebSocket-verbinding accepteert voordat de lus wordt gestart, eindigt de middleware-pijplijn. Na het sluiten van de socket rolt de pijplijn zich op. Dat wil gezegd, de aanvraag stopt met verdergaan in de pijplijn wanneer de WebSocket wordt geaccepteerd. Wanneer de lus is voltooid en de socket is gesloten, gaat de aanvraag terug naar de pijplijn.

Beheer clientverbindingen bij verbreking

De server wordt niet automatisch geïnformeerd wanneer de verbinding met de client wordt verbroken door verlies van connectiviteit. De server ontvangt alleen een ontkoppelbericht als de client het verzendt, wat niet mogelijk is als de internetverbinding is weggevallen. Als u actie wilt ondernemen wanneer dat gebeurt, stelt u een time-out in nadat er binnen een bepaald tijdvenster niets van de client is ontvangen.

Als de client niet altijd berichten verzendt en u geen time-out wilt maken omdat de verbinding niet actief is, laat de client een timer gebruiken om elke X seconden een pingbericht te verzenden. Als op de server een bericht niet binnen 2*X seconden na de vorige is aangekomen, beëindigt u de verbinding en meldt u dat de verbinding met de client is verbroken. Wacht twee keer zo lang als het verwachte tijdsinterval om extra tijd te geven voor netwerkvertragingen die het pingbericht kunnen vertragen.

WebSocket oorsprongsbeperking

De beveiligingen van CORS zijn niet van toepassing op WebSockets. Browsers doen het volgende niet:

• VOER CORS-aanvragen vooraf uit.
• Respecteer de beperkingen die zijn opgegeven in Access-Control headers bij het maken van WebSocket-aanvragen.

Browsers verzenden echter wel de header bij het Origin uitgeven van WebSocket-aanvragen. Toepassingen moeten worden geconfigureerd om deze headers te valideren om ervoor te zorgen dat alleen WebSockets die afkomstig zijn van de verwachte oorsprongen zijn toegestaan.

Als u uw server host op "https://server.com" en uw client host op "https://client.com", voeg "https://client.com"" toe aan de lijst AllowedOrigins voor WebSockets om te verifiëren.

var webSocketOptions = new WebSocketOptions
{
    KeepAliveInterval = TimeSpan.FromMinutes(2)
};

webSocketOptions.AllowedOrigins.Add("https://client.com");
webSocketOptions.AllowedOrigins.Add("https://www.client.com");

app.UseWebSockets(webSocketOptions);

Ondersteuning voor IIS/IIS Express

Windows Server 2012 of hoger en Windows 8 of hoger met IIS/IIS Express 8 of hoger biedt ondersteuning voor het WebSocket-protocol, maar niet voor WebSockets via HTTP/2.

WebSockets inschakelen in IIS

Ondersteuning voor het WebSocket-protocol op Windows Server 2012 of hoger inschakelen:

1. Gebruik de wizard Functies en Onderdelen Toevoegen vanuit het Beheren-menu of de koppeling in Serverbeheer.
2. Selecteer rolgebaseerde of functiegebaseerde installatie. Kies Volgende.
3. Selecteer de juiste server (de lokale server is standaard geselecteerd). Kies Volgende.
4. Vouw Webserver (IIS) uit in de structuur Functies , vouw Webserver uit en vouw vervolgens Toepassingsontwikkeling uit.
5. Selecteer WebSocket Protocol. Kies Volgende.
6. Als er geen extra functies nodig zijn, selecteert u Volgende.
7. Selecteer Installeren.
8. Wanneer de installatie is voltooid, selecteert u Sluiten om de wizard af te sluiten.

Ondersteuning inschakelen voor het WebSocket-protocol in Windows 8 of hoger:

1. Ga naar Configuratiescherm>Programma's>Programma's en onderdelen>Windows-onderdelen in- of uitschakelen (links op het scherm).
2. Open de volgende knooppunten: Internetinformatieservices>World Wide Web-services>Kenmerken voor applicatieontwikkeling.
3. Selecteer de functie WebSocket Protocol. Kies OK.

WebSocket uitschakelen bij het gebruik van socket.io op Node.js

Als u de WebSocket-ondersteuning in socket.io op Node.jsgebruikt, schakelt u de standaard IIS WebSocket-module uit met behulp van het webSocket element in web.config of applicationHost.config. Als deze stap niet wordt uitgevoerd, probeert de IIS WebSocket-module de WebSocket-communicatie te verwerken in plaats van Node.js en de app.

<system.webServer>
  <webSocket enabled="false" />
</system.webServer>

Voorbeeld-app

De voorbeeld-app die bij dit artikel hoort, is een echo-app. Het bevat een webpagina die WebSocket-verbindingen maakt en de server alle berichten die het ontvangt, opnieuw verzendt naar de client. De voorbeeld-app ondersteunt WebSockets via HTTP/2 wanneer u een doelframework van .NET 7 of hoger gebruikt.

Voer de app uit:

• App uitvoeren in Visual Studio: Open het voorbeeldproject in Visual Studio en druk op Ctrl+F5 om uit te voeren zonder het foutopsporingsprogramma.
• De app uitvoeren in een opdrachtshell: voer de opdracht dotnet run uit en navigeer in een browser naar http://localhost:<port>.

Op de webpagina wordt de verbindingsstatus weergegeven:

Selecteer Verbinding maken om een WebSocket-aanvraag naar de weergegeven URL te verzenden. Voer een testbericht in en selecteer Verzenden. Wanneer u klaar bent, selecteert u Socket sluiten. De sectie Communicatielogboek rapporteert elke geopende, verzonden en gesloten actie wanneer dit gebeurt.

In dit artikel wordt uitgelegd hoe u aan de slag gaat met WebSockets in ASP.NET Core. WebSocket (RFC 6455) is een protocol waarmee permanente communicatiekanalen in twee richtingen via TCP-verbindingen mogelijk zijn. Het wordt gebruikt in apps die profiteren van snelle, realtime communicatie, zoals chatten, dashboard en game-apps.

Voorbeeldcode weergeven of downloaden (downloaden, uitvoeren).

Ondersteuning voor Http/2 WebSockets

Het gebruik van WebSockets via HTTP/2 maakt gebruik van nieuwe functies, zoals:

• Headercompressie.
• Multiplexing, wat de tijd en resources vermindert die nodig zijn bij het indienen van meerdere aanvragen naar de server.

Deze ondersteunde functies zijn beschikbaar in Kestrel op alle platforms waarvoor HTTP/2 is ingeschakeld. De versieonderhandeling is automatisch in browsers en Kestrel, dus er zijn geen nieuwe API's nodig.

.NET 7 heeft WebSockets geïntroduceerd via HTTP/2-ondersteuning voor Kestrel, de SignalR JavaScript-client en SignalR met Blazor WebAssembly.

WebSockets zijn oorspronkelijk ontworpen voor HTTP/1.1, maar zijn sindsdien aangepast voor gebruik via HTTP/2. (RFC 8441)

SignalR

ASP.NET Core SignalR is een bibliotheek die het toevoegen van realtime webfunctionaliteit aan apps vereenvoudigt. Het maakt waar mogelijk gebruik van WebSockets.

Voor de meeste toepassingen raden we u aan SignalR in plaats van onbewerkte WebSockets. SignalR:

• Biedt terugval naar transport voor omgevingen waar WebSockets niet beschikbaar is.
• Biedt een eenvoudig model voor een afstandsprocedureoproep-app.
• Heeft geen significant prestatienadelen vergeleken met het gebruik van onbewerkte WebSockets in de meeste scenario's.

WebSockets via HTTP/2 worden ondersteund voor:

• ASP.NET Core SignalR JavaScript-client
• ASP.NET Core SignalR met Blazor WebAssembly

Voor sommige apps biedt gRPC op .NET een alternatief voor WebSockets.

Prerequisites

• Elk besturingssysteem dat ondersteuning biedt voor ASP.NET Core:
  • Windows 7/ Windows Server 2008 of hoger
  • Linux
  • macOS
• Als de app wordt uitgevoerd in Windows met IIS:
  • Windows 8/Windows Server 2012 of hoger
  • IIS 8 / IIS 8 Express
  • WebSockets moeten zijn ingeschakeld. Zie de sectie ondersteuning voor IIS/IIS Express .
• Als de app wordt uitgevoerd op HTTP.sys:
  • Windows 8/Windows Server 2012 of hoger
• Zie Kan ik gebruiken voor ondersteunde browsers.

De middleware configureren

Voeg de WebSockets-middleware toe aan Program.cs:

app.UseWebSockets();

De volgende instellingen kunnen worden geconfigureerd:

• KeepAliveInterval - Hoe vaak 'ping'-frames naar de client worden verzonden om ervoor te zorgen dat proxy's de verbinding open houden. De standaardwaarde is twee minuten.
• AllowedOrigins - Een lijst met toegestane Origin-headerwaarden voor WebSocket-aanvragen. Standaard zijn alle oorsprongen toegestaan. Zie WebSocket Origin-beperking in dit artikel voor meer informatie.

var webSocketOptions = new WebSocketOptions
{
    KeepAliveInterval = TimeSpan.FromMinutes(2)
};

app.UseWebSockets(webSocketOptions);

WebSocket-aanvragen accepteren

Ergens later in de levenscyclus van de aanvraag (later in Program.cs of in een actiemethode, bijvoorbeeld) controleert u of het een WebSocket-aanvraag is en accepteert u de WebSocket-aanvraag.

Het volgende voorbeeld is van later in Program.cs:

app.Use(async (context, next) =>
{
    if (context.Request.Path == "/ws")
    {
        if (context.WebSockets.IsWebSocketRequest)
        {
            using var webSocket = await context.WebSockets.AcceptWebSocketAsync();
            await Echo(webSocket);
        }
        else
        {
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
        }
    }
    else
    {
        await next(context);
    }

});

Een WebSocket-aanvraag kan op elke URL binnenkomen, maar deze voorbeeldcode accepteert alleen aanvragen voor /ws.

Een vergelijkbare benadering kan worden gebruikt in een controllermethode:

public class WebSocketController : ControllerBase
{
    [Route("/ws")]
    public async Task Get()
    {
        if (HttpContext.WebSockets.IsWebSocketRequest)
        {
            using var webSocket = await HttpContext.WebSockets.AcceptWebSocketAsync();
            await Echo(webSocket);
        }
        else
        {
            HttpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
        }
    }

Wanneer u een WebSocket gebruikt, moet u de middleware-pijplijn actief houden voor de duur van de verbinding. Als u probeert een WebSocket-bericht te verzenden of te ontvangen nadat de middleware-pijplijn is beëindigd, krijgt u mogelijk een uitzondering als de volgende:

System.Net.WebSockets.WebSocketException (0x80004005): The remote party closed the WebSocket connection without completing the close handshake. ---> System.ObjectDisposedException: Cannot write to the response body, the response has completed.
Object name: 'HttpResponseStream'.

Als u een achtergrondservice gebruikt om gegevens naar een WebSocket te schrijven, moet u ervoor zorgen dat de middleware-pijplijn actief blijft. Doe dit met behulp van een TaskCompletionSource<TResult>. Geef de TaskCompletionSource aan uw achtergrondservice door en laat deze aanroepen TrySetResult wanneer u klaar bent met de WebSocket. Stel vervolgens await de Task eigenschap in tijdens de aanvraag, zoals wordt weergegeven in het volgende voorbeeld:

app.Run(async (context) =>
{
    using var webSocket = await context.WebSockets.AcceptWebSocketAsync();
    var socketFinishedTcs = new TaskCompletionSource<object>();

    BackgroundSocketProcessor.AddSocket(webSocket, socketFinishedTcs);

    await socketFinishedTcs.Task;
});

De WebSocket-gesloten-exceptie kan ook optreden wanneer er te vroeg wordt teruggekeerd vanuit een actiemethode. Wanneer u een socket in een actiemethode accepteert, wacht u tot de code die gebruikmaakt van de socket is voltooid voordat u uit de actiemethode terugkeert.

Gebruik nooit Task.Wait, Task.Result of soortgelijke blokkerende aanroepen om te wachten tot de socket is voltooid, omdat dit ernstige problemen met threading kan veroorzaken. Gebruik altijd await.

HTTP/2 WebSockets-ondersteuning toevoegen voor bestaande controllers

.NET 7 heeft WebSockets geïntroduceerd via HTTP/2-ondersteuning voor Kestrel, de SignalR JavaScript-client en SignalR met Blazor WebAssembly. HTTP/2 WebSockets gebruiken CONNECT-aanvragen in plaats van GET. Als u eerder [HttpGet("/path")] hebt gebruikt voor de actiemethode van de controller voor Websocket-aanvragen, werkt u deze bij om [Route("/path")] te gebruiken.

public class WebSocketController : ControllerBase
{
    [Route("/ws")]
    public async Task Get()
    {
        if (HttpContext.WebSockets.IsWebSocketRequest)
        {
            using var webSocket = await HttpContext.WebSockets.AcceptWebSocketAsync();
            await Echo(webSocket);
        }
        else
        {
            HttpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
        }
    }

Compression

Als compressie van berichten via WebSockets gewenst is, moet de acceptcode opgeven dat compressie als volgt is toegestaan:

using (var webSocket = await context.WebSockets.AcceptWebSocketAsync(
    new WebSocketAcceptContext { DangerousEnableCompression = true }))
{

}

WebSocketAcceptContext.ServerMaxWindowBits en WebSocketAcceptContext.DisableServerContextTakeover zijn geavanceerde opties die bepalen hoe de compressie werkt.

Compressie wordt onderhandeld tussen de client en de server bij het tot stand brengen van een verbinding. Meer informatie over de onderhandeling vindt u in de compressie-extensies voor WebSocket RFC.

Berichten verzenden en ontvangen

De AcceptWebSocketAsync methode werkt de TCP-verbinding bij naar een WebSocket-verbinding en biedt een WebSocket object. Gebruik het WebSocket object om berichten te verzenden en te ontvangen.

De code die eerder is weergegeven die de WebSocket-aanvraag accepteert, geeft het WebSocket object door aan een Echo methode. De code ontvangt een bericht en stuurt onmiddellijk hetzelfde bericht terug. Berichten worden verzonden en ontvangen in een lus totdat de client de verbinding sluit:

private static async Task Echo(WebSocket webSocket)
{
    var buffer = new byte[1024 * 4];
    var receiveResult = await webSocket.ReceiveAsync(
        new ArraySegment<byte>(buffer), CancellationToken.None);

    while (!receiveResult.CloseStatus.HasValue)
    {
        await webSocket.SendAsync(
            new ArraySegment<byte>(buffer, 0, receiveResult.Count),
            receiveResult.MessageType,
            receiveResult.EndOfMessage,
            CancellationToken.None);

        receiveResult = await webSocket.ReceiveAsync(
            new ArraySegment<byte>(buffer), CancellationToken.None);
    }

    await webSocket.CloseAsync(
        receiveResult.CloseStatus.Value,
        receiveResult.CloseStatusDescription,
        CancellationToken.None);
}

Wanneer u de WebSocket-verbinding accepteert voordat de lus wordt gestart, eindigt de middleware-pijplijn. Na het sluiten van de socket rolt de pijplijn zich op. Dat wil gezegd, de aanvraag stopt met verdergaan in de pijplijn wanneer de WebSocket wordt geaccepteerd. Wanneer de lus is voltooid en de socket is gesloten, gaat de aanvraag terug naar de pijplijn.

Beheer clientverbindingen bij verbreking

De server wordt niet automatisch geïnformeerd wanneer de verbinding met de client wordt verbroken door verlies van connectiviteit. De server ontvangt alleen een ontkoppelbericht als de client het verzendt, wat niet mogelijk is als de internetverbinding is weggevallen. Als u actie wilt ondernemen wanneer dat gebeurt, stelt u een time-out in nadat er binnen een bepaald tijdvenster niets van de client is ontvangen.

Als de client niet altijd berichten verzendt en u geen time-out wilt maken omdat de verbinding niet actief is, laat de client een timer gebruiken om elke X seconden een pingbericht te verzenden. Als op de server een bericht niet binnen 2*X seconden na de vorige is aangekomen, beëindigt u de verbinding en meldt u dat de verbinding met de client is verbroken. Wacht twee keer zo lang als het verwachte tijdsinterval om extra tijd te geven voor netwerkvertragingen die het pingbericht kunnen vertragen.

WebSocket oorsprongsbeperking

De beveiligingen van CORS zijn niet van toepassing op WebSockets. Browsers doen het volgende niet:

• VOER CORS-aanvragen vooraf uit.
• Respecteer de beperkingen die zijn opgegeven in Access-Control headers bij het maken van WebSocket-aanvragen.

Browsers verzenden echter wel de header bij het Origin uitgeven van WebSocket-aanvragen. Toepassingen moeten worden geconfigureerd om deze headers te valideren om ervoor te zorgen dat alleen WebSockets die afkomstig zijn van de verwachte oorsprongen zijn toegestaan.

Als u uw server host op "https://server.com" en uw client host op "https://client.com", voeg "https://client.com"" toe aan de lijst AllowedOrigins voor WebSockets om te verifiëren.

var webSocketOptions = new WebSocketOptions
{
    KeepAliveInterval = TimeSpan.FromMinutes(2)
};

webSocketOptions.AllowedOrigins.Add("https://client.com");
webSocketOptions.AllowedOrigins.Add("https://www.client.com");

app.UseWebSockets(webSocketOptions);

Ondersteuning voor IIS/IIS Express

Windows Server 2012 of hoger en Windows 8 of hoger met IIS/IIS Express 8 of hoger biedt ondersteuning voor het WebSocket-protocol, maar niet voor WebSockets via HTTP/2.

WebSockets inschakelen in IIS

Ondersteuning voor het WebSocket-protocol op Windows Server 2012 of hoger inschakelen:

1. Gebruik de wizard Functies en Onderdelen Toevoegen vanuit het Beheren-menu of de koppeling in Serverbeheer.
2. Selecteer rolgebaseerde of functiegebaseerde installatie. Kies Volgende.
3. Selecteer de juiste server (de lokale server is standaard geselecteerd). Kies Volgende.
4. Vouw Webserver (IIS) uit in de structuur Functies , vouw Webserver uit en vouw vervolgens Toepassingsontwikkeling uit.
5. Selecteer WebSocket Protocol. Kies Volgende.
6. Als er geen extra functies nodig zijn, selecteert u Volgende.
7. Selecteer Installeren.
8. Wanneer de installatie is voltooid, selecteert u Sluiten om de wizard af te sluiten.

Ondersteuning inschakelen voor het WebSocket-protocol in Windows 8 of hoger:

1. Ga naar Configuratiescherm>Programma's>Programma's en onderdelen>Windows-onderdelen in- of uitschakelen (links op het scherm).
2. Open de volgende knooppunten: Internetinformatieservices>World Wide Web-services>Kenmerken voor applicatieontwikkeling.
3. Selecteer de functie WebSocket Protocol. Kies OK.

WebSocket uitschakelen bij het gebruik van socket.io op Node.js

Als u de WebSocket-ondersteuning in socket.io op Node.jsgebruikt, schakelt u de standaard IIS WebSocket-module uit met behulp van het webSocket element in web.config of applicationHost.config. Als deze stap niet wordt uitgevoerd, probeert de IIS WebSocket-module de WebSocket-communicatie te verwerken in plaats van Node.js en de app.

<system.webServer>
  <webSocket enabled="false" />
</system.webServer>

Voorbeeld-app

De voorbeeld-app die bij dit artikel hoort, is een echo-app. Het bevat een webpagina die WebSocket-verbindingen maakt en de server alle berichten die het ontvangt, opnieuw verzendt naar de client. De voorbeeld-app ondersteunt WebSockets via HTTP/2 wanneer u een doelframework van .NET 7 of hoger gebruikt.

Voer de app uit:

• App uitvoeren in Visual Studio: Open het voorbeeldproject in Visual Studio en druk op Ctrl+F5 om uit te voeren zonder het foutopsporingsprogramma.
• De app uitvoeren in een opdrachtshell: voer de opdracht dotnet run uit en navigeer in een browser naar http://localhost:<port>.

Op de webpagina wordt de verbindingsstatus weergegeven:

Selecteer Verbinding maken om een WebSocket-aanvraag naar de weergegeven URL te verzenden. Voer een testbericht in en selecteer Verzenden. Wanneer u klaar bent, selecteert u Socket sluiten. De sectie Communicatielogboek rapporteert elke geopende, verzonden en gesloten actie wanneer dit gebeurt.

In dit artikel wordt uitgelegd hoe u aan de slag gaat met WebSockets in ASP.NET Core. WebSocket (RFC 6455) is een protocol waarmee permanente communicatiekanalen in twee richtingen via TCP-verbindingen mogelijk zijn. Het wordt gebruikt in apps die profiteren van snelle, realtime communicatie, zoals chatten, dashboard en game-apps.

Voorbeeldcode weergeven of downloaden (downloaden, uitvoeren).

SignalR

ASP.NET Core SignalR is een bibliotheek die het toevoegen van realtime webfunctionaliteit aan apps vereenvoudigt. Het maakt waar mogelijk gebruik van WebSockets.

Voor de meeste toepassingen raden we aan om over onbewerkte WebSockets te gaan SignalR . SignalR biedt terugval naar transport voor omgevingen waar WebSockets niet beschikbaar is. Het biedt ook een eenvoudig model voor een basis toepassing voor het aanroepen van externe procedures. En in de meeste scenario's heeft SignalR geen significant prestatienadeel ten opzichte van het gebruik van onbewerkte WebSockets.

Voor sommige apps biedt gRPC op .NET een alternatief voor WebSockets.

Prerequisites

• Elk besturingssysteem dat ondersteuning biedt voor ASP.NET Core:
  • Windows 7/ Windows Server 2008 of hoger
  • Linux
  • macOS
• Als de app wordt uitgevoerd in Windows met IIS:
  • Windows 8/Windows Server 2012 of hoger
  • IIS 8 / IIS 8 Express
  • WebSockets moeten zijn ingeschakeld. Zie de sectie ondersteuning voor IIS/IIS Express .
• Als de app wordt uitgevoerd op HTTP.sys:
  • Windows 8/Windows Server 2012 of hoger
• Zie Kan ik gebruiken voor ondersteunde browsers.

De middleware configureren

Voeg de WebSockets-middleware toe aan Program.cs:

app.UseWebSockets();

De volgende instellingen kunnen worden geconfigureerd:

• KeepAliveInterval - Hoe vaak 'ping'-frames naar de client worden verzonden om ervoor te zorgen dat proxy's de verbinding open houden. De standaardwaarde is twee minuten.
• AllowedOrigins - Een lijst met toegestane Origin-headerwaarden voor WebSocket-aanvragen. Standaard zijn alle oorsprongen toegestaan. Zie WebSocket Origin-beperking in dit artikel voor meer informatie.

var webSocketOptions = new WebSocketOptions
{
    KeepAliveInterval = TimeSpan.FromMinutes(2)
};

app.UseWebSockets(webSocketOptions);

WebSocket-aanvragen accepteren

Ergens later in de levenscyclus van de aanvraag (later in Program.cs of in een actiemethode, bijvoorbeeld) controleert u of het een WebSocket-aanvraag is en accepteert u de WebSocket-aanvraag.

Het volgende voorbeeld is van later in Program.cs:

app.Use(async (context, next) =>
{
    if (context.Request.Path == "/ws")
    {
        if (context.WebSockets.IsWebSocketRequest)
        {
            using var webSocket = await context.WebSockets.AcceptWebSocketAsync();
            await Echo(webSocket);
        }
        else
        {
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
        }
    }
    else
    {
        await next(context);
    }

});

Een WebSocket-aanvraag kan op elke URL binnenkomen, maar deze voorbeeldcode accepteert alleen aanvragen voor /ws.

Een vergelijkbare benadering kan worden gebruikt in een controllermethode:

public class WebSocketController : ControllerBase
{
    [HttpGet("/ws")]
    public async Task Get()
    {
        if (HttpContext.WebSockets.IsWebSocketRequest)
        {
            using var webSocket = await HttpContext.WebSockets.AcceptWebSocketAsync();
            await Echo(webSocket);
        }
        else
        {
            HttpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
        }
    }

Wanneer u een WebSocket gebruikt, moet u de middleware-pijplijn actief houden voor de duur van de verbinding. Als u probeert een WebSocket-bericht te verzenden of te ontvangen nadat de middleware-pijplijn is beëindigd, krijgt u mogelijk een uitzondering als de volgende:

System.Net.WebSockets.WebSocketException (0x80004005): The remote party closed the WebSocket connection without completing the close handshake. ---> System.ObjectDisposedException: Cannot write to the response body, the response has completed.
Object name: 'HttpResponseStream'.

Als u een achtergrondservice gebruikt om gegevens naar een WebSocket te schrijven, moet u ervoor zorgen dat de middleware-pijplijn actief blijft. Doe dit met behulp van een TaskCompletionSource<TResult>. Geef de TaskCompletionSource aan uw achtergrondservice door en laat deze aanroepen TrySetResult wanneer u klaar bent met de WebSocket. Stel vervolgens await de Task eigenschap in tijdens de aanvraag, zoals wordt weergegeven in het volgende voorbeeld:

app.Run(async (context) =>
{
    using var webSocket = await context.WebSockets.AcceptWebSocketAsync();
    var socketFinishedTcs = new TaskCompletionSource<object>();

    BackgroundSocketProcessor.AddSocket(webSocket, socketFinishedTcs);

    await socketFinishedTcs.Task;
});

De WebSocket-gesloten-exceptie kan ook optreden wanneer er te vroeg wordt teruggekeerd vanuit een actiemethode. Wanneer u een socket in een actiemethode accepteert, wacht u tot de code die gebruikmaakt van de socket is voltooid voordat u uit de actiemethode terugkeert.

Gebruik nooit Task.Wait, Task.Result of soortgelijke blokkerende aanroepen om te wachten tot de socket is voltooid, omdat dit ernstige problemen met threading kan veroorzaken. Gebruik altijd await.

Compression

Als compressie van berichten via WebSockets gewenst is, moet de acceptcode opgeven dat compressie als volgt is toegestaan:

using (var webSocket = await context.WebSockets.AcceptWebSocketAsync(
    new WebSocketAcceptContext { DangerousEnableCompression = true }))
{

}

WebSocketAcceptContext.ServerMaxWindowBits en WebSocketAcceptContext.DisableServerContextTakeover zijn geavanceerde opties die bepalen hoe de compressie werkt.

Compressie wordt onderhandeld tussen de client en de server bij het tot stand brengen van een verbinding. Meer informatie over de onderhandeling vindt u in de compressie-extensies voor WebSocket RFC.

Berichten verzenden en ontvangen

De AcceptWebSocketAsync methode werkt de TCP-verbinding bij naar een WebSocket-verbinding en biedt een WebSocket object. Gebruik het WebSocket object om berichten te verzenden en te ontvangen.

De code die eerder is weergegeven die de WebSocket-aanvraag accepteert, geeft het WebSocket object door aan een Echo methode. De code ontvangt een bericht en stuurt onmiddellijk hetzelfde bericht terug. Berichten worden verzonden en ontvangen in een lus totdat de client de verbinding sluit:

private static async Task Echo(WebSocket webSocket)
{
    var buffer = new byte[1024 * 4];
    var receiveResult = await webSocket.ReceiveAsync(
        new ArraySegment<byte>(buffer), CancellationToken.None);

    while (!receiveResult.CloseStatus.HasValue)
    {
        await webSocket.SendAsync(
            new ArraySegment<byte>(buffer, 0, receiveResult.Count),
            receiveResult.MessageType,
            receiveResult.EndOfMessage,
            CancellationToken.None);

        receiveResult = await webSocket.ReceiveAsync(
            new ArraySegment<byte>(buffer), CancellationToken.None);
    }

    await webSocket.CloseAsync(
        receiveResult.CloseStatus.Value,
        receiveResult.CloseStatusDescription,
        CancellationToken.None);
}

Wanneer u de WebSocket-verbinding accepteert voordat de lus wordt gestart, eindigt de middleware-pijplijn. Na het sluiten van de socket rolt de pijplijn zich op. Dat wil gezegd, de aanvraag stopt met verdergaan in de pijplijn wanneer de WebSocket wordt geaccepteerd. Wanneer de lus is voltooid en de socket is gesloten, gaat de aanvraag terug naar de pijplijn.

Beheer clientverbindingen bij verbreking

De server wordt niet automatisch geïnformeerd wanneer de verbinding met de client wordt verbroken door verlies van connectiviteit. De server ontvangt alleen een ontkoppelbericht als de client het verzendt, wat niet mogelijk is als de internetverbinding is weggevallen. Als u actie wilt ondernemen wanneer dat gebeurt, stelt u een time-out in nadat er binnen een bepaald tijdvenster niets van de client is ontvangen.

Als de client niet altijd berichten verzendt en u geen time-out wilt maken omdat de verbinding niet actief is, laat de client een timer gebruiken om elke X seconden een pingbericht te verzenden. Als op de server een bericht niet binnen 2*X seconden na de vorige is aangekomen, beëindigt u de verbinding en meldt u dat de verbinding met de client is verbroken. Wacht twee keer zo lang als het verwachte tijdsinterval om extra tijd te geven voor netwerkvertragingen die het pingbericht kunnen vertragen.

WebSocket oorsprongsbeperking

De beveiligingen van CORS zijn niet van toepassing op WebSockets. Browsers doen het volgende niet:

• VOER CORS-aanvragen vooraf uit.
• Respecteer de beperkingen die zijn opgegeven in Access-Control headers bij het maken van WebSocket-aanvragen.

Browsers verzenden echter wel de header bij het Origin uitgeven van WebSocket-aanvragen. Toepassingen moeten worden geconfigureerd om deze headers te valideren om ervoor te zorgen dat alleen WebSockets die afkomstig zijn van de verwachte oorsprongen zijn toegestaan.

Als u uw server host op "https://server.com" en uw client host op "https://client.com", voeg "https://client.com"" toe aan de lijst AllowedOrigins voor WebSockets om te verifiëren.

var webSocketOptions = new WebSocketOptions
{
    KeepAliveInterval = TimeSpan.FromMinutes(2)
};

webSocketOptions.AllowedOrigins.Add("https://client.com");
webSocketOptions.AllowedOrigins.Add("https://www.client.com");

app.UseWebSockets(webSocketOptions);

Ondersteuning voor IIS/IIS Express

Windows Server 2012 of hoger en Windows 8 of hoger met IIS/IIS Express 8 of hoger biedt ondersteuning voor het WebSocket-protocol.

WebSockets inschakelen in IIS

Ondersteuning voor het WebSocket-protocol op Windows Server 2012 of hoger inschakelen:

1. Gebruik de wizard Functies en Onderdelen Toevoegen vanuit het Beheren-menu of de koppeling in Serverbeheer.
2. Selecteer rolgebaseerde of functiegebaseerde installatie. Kies Volgende.
3. Selecteer de juiste server (de lokale server is standaard geselecteerd). Kies Volgende.
4. Vouw Webserver (IIS) uit in de structuur Functies , vouw Webserver uit en vouw vervolgens Toepassingsontwikkeling uit.
5. Selecteer WebSocket Protocol. Kies Volgende.
6. Als er geen extra functies nodig zijn, selecteert u Volgende.
7. Selecteer Installeren.
8. Wanneer de installatie is voltooid, selecteert u Sluiten om de wizard af te sluiten.

Ondersteuning inschakelen voor het WebSocket-protocol in Windows 8 of hoger:

1. Ga naar Configuratiescherm>Programma's>Programma's en onderdelen>Windows-onderdelen in- of uitschakelen (links op het scherm).
2. Open de volgende knooppunten: Internetinformatieservices>World Wide Web-services>Kenmerken voor applicatieontwikkeling.
3. Selecteer de functie WebSocket Protocol. Kies OK.

WebSocket uitschakelen bij het gebruik van socket.io op Node.js

Als u de WebSocket-ondersteuning in socket.io op Node.jsgebruikt, schakelt u de standaard IIS WebSocket-module uit met behulp van het webSocket element in web.config of applicationHost.config. Als deze stap niet wordt uitgevoerd, probeert de IIS WebSocket-module de WebSocket-communicatie te verwerken in plaats van Node.js en de app.

<system.webServer>
  <webSocket enabled="false" />
</system.webServer>

Voorbeeld-app

De voorbeeld-app die bij dit artikel hoort, is een echo-app. Het bevat een webpagina die WebSocket-verbindingen maakt en de server alle berichten die het ontvangt, opnieuw verzendt naar de client. De voorbeeld-app is niet geconfigureerd voor uitvoering vanuit Visual Studio met IIS Express, dus voer de app uit in een opdrachtshell met dotnet run en navigeer in een browser naar http://localhost:<port>. Op de webpagina wordt de verbindingsstatus weergegeven:

Selecteer Verbinding maken om een WebSocket-aanvraag naar de weergegeven URL te verzenden. Voer een testbericht in en selecteer Verzenden. Wanneer u klaar bent, selecteert u Socket sluiten. De sectie Communicatielogboek rapporteert elke geopende, verzonden en gesloten actie wanneer dit gebeurt.

In dit artikel wordt uitgelegd hoe u aan de slag gaat met WebSockets in ASP.NET Core. WebSocket (RFC 6455) is een protocol waarmee permanente communicatiekanalen in twee richtingen via TCP-verbindingen mogelijk zijn. Het wordt gebruikt in apps die profiteren van snelle, realtime communicatie, zoals chatten, dashboard en game-apps.

Voorbeeldcode bekijken of downloaden (hoe u kunt downloaden). Hoe kan ik het uitvoeren.

SignalR

ASP.NET Core SignalR is een bibliotheek die het toevoegen van realtime webfunctionaliteit aan apps vereenvoudigt. Het maakt waar mogelijk gebruik van WebSockets.

Voor de meeste toepassingen raden we aan om over onbewerkte WebSockets te gaan SignalR . SignalR biedt terugval naar transport voor omgevingen waar WebSockets niet beschikbaar is. Het biedt ook een eenvoudig model voor een basis toepassing voor het aanroepen van externe procedures. En in de meeste scenario's heeft SignalR geen significant prestatienadeel ten opzichte van het gebruik van onbewerkte WebSockets.

Voor sommige apps biedt gRPC op .NET een alternatief voor WebSockets.

Prerequisites

• Elk besturingssysteem dat ondersteuning biedt voor ASP.NET Core:
  • Windows 7/ Windows Server 2008 of hoger
  • Linux
  • macOS
• Als de app wordt uitgevoerd in Windows met IIS:
  • Windows 8/Windows Server 2012 of hoger
  • IIS 8 / IIS 8 Express
  • WebSockets moeten zijn ingeschakeld. Zie de sectie ondersteuning voor IIS/IIS Express .
• Als de app wordt uitgevoerd op HTTP.sys:
  • Windows 8/Windows Server 2012 of hoger
• Zie Kan ik gebruiken voor ondersteunde browsers.

De middleware configureren

Voeg de WebSockets-middleware toe in de Configure methode van de Startup klasse:

app.UseWebSockets();

De volgende instellingen kunnen worden geconfigureerd:

• KeepAliveInterval - Hoe vaak 'ping'-frames naar de client worden verzonden om ervoor te zorgen dat proxy's de verbinding open houden. De standaardwaarde is twee minuten.
• AllowedOrigins - Een lijst met toegestane Origin-headerwaarden voor WebSocket-aanvragen. Standaard zijn alle oorsprongen toegestaan. Zie 'WebSocket origin restriction' hieronder voor meer informatie.

var webSocketOptions = new WebSocketOptions()
{
    KeepAliveInterval = TimeSpan.FromSeconds(120),
};

app.UseWebSockets(webSocketOptions);

WebSocket-aanvragen accepteren

Ergens later in de levenscyclus van de aanvraag (later in de Configure methode of in een actiemethode) controleert u of het een WebSocket-aanvraag is en accepteert u de WebSocket-aanvraag.

Het volgende voorbeeld is van later in de Configure methode:

app.Use(async (context, next) =>
{
    if (context.Request.Path == "/ws")
    {
        if (context.WebSockets.IsWebSocketRequest)
        {
            using (WebSocket webSocket = await context.WebSockets.AcceptWebSocketAsync())
            {
                await Echo(context, webSocket);
            }
        }
        else
        {
            context.Response.StatusCode = (int) HttpStatusCode.BadRequest;
        }
    }
    else
    {
        await next();
    }

});

Een WebSocket-aanvraag kan op elke URL binnenkomen, maar deze voorbeeldcode accepteert alleen aanvragen voor /ws.

Een vergelijkbare benadering kan worden gebruikt in een controllermethode:

public class WebSocketController : ControllerBase
{
    [HttpGet("/ws")]
    public async Task Get()
    {
        if (HttpContext.WebSockets.IsWebSocketRequest)
        {
            using var webSocket = await HttpContext.WebSockets.AcceptWebSocketAsync();
            await Echo(webSocket);
        }
        else
        {
            HttpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
        }
    }

Wanneer u een WebSocket gebruikt, moet u de middleware-pijplijn actief houden voor de duur van de verbinding. Als u probeert een WebSocket-bericht te verzenden of te ontvangen nadat de middleware-pijplijn is beëindigd, krijgt u mogelijk een uitzondering als de volgende:

System.Net.WebSockets.WebSocketException (0x80004005): The remote party closed the WebSocket connection without completing the close handshake. ---> System.ObjectDisposedException: Cannot write to the response body, the response has completed.
Object name: 'HttpResponseStream'.

Als u een achtergrondservice gebruikt om gegevens naar een WebSocket te schrijven, moet u ervoor zorgen dat de middleware-pijplijn actief blijft. Doe dit met behulp van een TaskCompletionSource<TResult>. Geef de TaskCompletionSource aan uw achtergrondservice door en laat deze aanroepen TrySetResult wanneer u klaar bent met de WebSocket. Stel vervolgens await de Task eigenschap in tijdens de aanvraag, zoals wordt weergegeven in het volgende voorbeeld:

app.Use(async (context, next) =>
{
    using (WebSocket webSocket = await context.WebSockets.AcceptWebSocketAsync())
    {
        var socketFinishedTcs = new TaskCompletionSource<object>();

        BackgroundSocketProcessor.AddSocket(webSocket, socketFinishedTcs);

        await socketFinishedTcs.Task;
    }
});

De WebSocket-gesloten-exceptie kan ook optreden wanneer er te vroeg wordt teruggekeerd vanuit een actiemethode. Wanneer u een socket in een actiemethode accepteert, wacht u tot de code die gebruikmaakt van de socket is voltooid voordat u uit de actiemethode terugkeert.

Gebruik nooit Task.Wait, Task.Result of soortgelijke blokkerende aanroepen om te wachten tot de socket is voltooid, omdat dit ernstige problemen met threading kan veroorzaken. Gebruik altijd await.

Berichten verzenden en ontvangen

De AcceptWebSocketAsync methode werkt de TCP-verbinding bij naar een WebSocket-verbinding en biedt een WebSocket object. Gebruik het WebSocket object om berichten te verzenden en te ontvangen.

De code die eerder is weergegeven die de WebSocket-aanvraag accepteert, geeft het WebSocket object door aan een Echo methode. De code ontvangt een bericht en stuurt onmiddellijk hetzelfde bericht terug. Berichten worden verzonden en ontvangen in een lus totdat de client de verbinding sluit:

private async Task Echo(HttpContext context, WebSocket webSocket)
{
    var buffer = new byte[1024 * 4];
    WebSocketReceiveResult result = await webSocket.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
    while (!result.CloseStatus.HasValue)
    {
        await webSocket.SendAsync(new ArraySegment<byte>(buffer, 0, result.Count), result.MessageType, result.EndOfMessage, CancellationToken.None);

        result = await webSocket.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
    }
    await webSocket.CloseAsync(result.CloseStatus.Value, result.CloseStatusDescription, CancellationToken.None);
}

Wanneer u de WebSocket-verbinding accepteert voordat de lus wordt gestart, eindigt de middleware-pijplijn. Na het sluiten van de socket rolt de pijplijn zich op. Dat wil gezegd, de aanvraag stopt met verdergaan in de pijplijn wanneer de WebSocket wordt geaccepteerd. Wanneer de lus is voltooid en de socket is gesloten, gaat de aanvraag terug naar de pijplijn.

Beheer clientverbindingen bij verbreking

De server wordt niet automatisch geïnformeerd wanneer de verbinding met de client wordt verbroken door verlies van connectiviteit. De server ontvangt alleen een ontkoppelbericht als de client het verzendt, wat niet mogelijk is als de internetverbinding is weggevallen. Als u actie wilt ondernemen wanneer dat gebeurt, stelt u een time-out in nadat er binnen een bepaald tijdvenster niets van de client is ontvangen.

Als de client niet altijd berichten verzendt en u geen time-out wilt maken omdat de verbinding niet actief is, laat de client een timer gebruiken om elke X seconden een pingbericht te verzenden. Als op de server een bericht niet binnen 2*X seconden na de vorige is aangekomen, beëindigt u de verbinding en meldt u dat de verbinding met de client is verbroken. Wacht twee keer zo lang als het verwachte tijdsinterval om extra tijd te geven voor netwerkvertragingen die het pingbericht kunnen vertragen.

WebSocket oorsprongsbeperking

De beveiligingen van CORS zijn niet van toepassing op WebSockets. Browsers doen het volgende niet:

• VOER CORS-aanvragen vooraf uit.
• Respecteer de beperkingen die zijn opgegeven in Access-Control headers bij het maken van WebSocket-aanvragen.

Browsers verzenden echter wel de header bij het Origin uitgeven van WebSocket-aanvragen. Toepassingen moeten worden geconfigureerd om deze headers te valideren om ervoor te zorgen dat alleen WebSockets die afkomstig zijn van de verwachte oorsprongen zijn toegestaan.

Als u uw server host op "https://server.com" en uw client host op "https://client.com", voeg "https://client.com"" toe aan de lijst AllowedOrigins voor WebSockets om te verifiëren.

var webSocketOptions = new WebSocketOptions()
{
    KeepAliveInterval = TimeSpan.FromSeconds(120),
};
webSocketOptions.AllowedOrigins.Add("https://client.com");
webSocketOptions.AllowedOrigins.Add("https://www.client.com");

app.UseWebSockets(webSocketOptions);

Ondersteuning voor IIS/IIS Express

Windows Server 2012 of hoger en Windows 8 of hoger met IIS/IIS Express 8 of hoger biedt ondersteuning voor het WebSocket-protocol.

WebSockets inschakelen in IIS

Ondersteuning voor het WebSocket-protocol op Windows Server 2012 of hoger inschakelen:

1. Gebruik de wizard Functies en Onderdelen Toevoegen vanuit het Beheren-menu of de koppeling in Serverbeheer.
2. Selecteer rolgebaseerde of functiegebaseerde installatie. Kies Volgende.
3. Selecteer de juiste server (de lokale server is standaard geselecteerd). Kies Volgende.
4. Vouw Webserver (IIS) uit in de structuur Functies , vouw Webserver uit en vouw vervolgens Toepassingsontwikkeling uit.
5. Selecteer WebSocket Protocol. Kies Volgende.
6. Als er geen extra functies nodig zijn, selecteert u Volgende.
7. Selecteer Installeren.
8. Wanneer de installatie is voltooid, selecteert u Sluiten om de wizard af te sluiten.

Ondersteuning inschakelen voor het WebSocket-protocol in Windows 8 of hoger:

1. Ga naar Configuratiescherm>Programma's>Programma's en onderdelen>Windows-onderdelen in- of uitschakelen (links op het scherm).
2. Open de volgende knooppunten: Internetinformatieservices>World Wide Web-services>Kenmerken voor applicatieontwikkeling.
3. Selecteer de functie WebSocket Protocol. Kies OK.

WebSocket uitschakelen bij het gebruik van socket.io op Node.js

Als u de WebSocket-ondersteuning in socket.io op Node.jsgebruikt, schakelt u de standaard IIS WebSocket-module uit met behulp van het webSocket element in web.config of applicationHost.config. Als deze stap niet wordt uitgevoerd, probeert de IIS WebSocket-module de WebSocket-communicatie te verwerken in plaats van Node.js en de app.

<system.webServer>
  <webSocket enabled="false" />
</system.webServer>

Voorbeeld-app

De voorbeeld-app die bij dit artikel hoort, is een echo-app. Het bevat een webpagina die WebSocket-verbindingen maakt en de server alle berichten die het ontvangt, opnieuw verzendt naar de client. De voorbeeld-app is niet geconfigureerd voor uitvoering vanuit Visual Studio met IIS Express, dus voer de app uit in een opdrachtshell met dotnet run en navigeer in een browser naar http://localhost:5000. Op de webpagina wordt de verbindingsstatus weergegeven:

Selecteer Verbinding maken om een WebSocket-aanvraag naar de weergegeven URL te verzenden. Voer een testbericht in en selecteer Verzenden. Wanneer u klaar bent, selecteert u Socket sluiten. De sectie Communicatielogboek rapporteert elke geopende, verzonden en gesloten actie wanneer dit gebeurt.