Delen via

Azure SignalR Management SDK gebruiken

  • Artikel

Met de Azure SignalR Management SDK kunt u SignalR-clients rechtstreeks beheren via Azure SignalR Service, zoals broadcastberichten. Daarom kan deze SDK worden gebruikt in serverloze omgevingen, maar niet beperkt tot gebruik. U kunt deze SDK gebruiken om SignalR-clients te beheren die zijn verbonden met uw Azure SignalR Service in elke omgeving, zoals in een console-app, in een Azure-functie of op een webserver.

Notitie

Als u handleidingen voor SDK-versie 1.9.x en eerder wilt bekijken, gaat u naar de Azure SignalR Service Management SDK (verouderd). Mogelijk wilt u ook de richtlijnen voor migratie lezen.

Belangrijk

Onbewerkte verbindingsreeks worden alleen in dit artikel weergegeven voor demonstratiedoeleinden.

Een verbindingsreeks bevat de autorisatiegegevens die nodig zijn voor uw toepassing om toegang te krijgen tot Azure SignalR Service. De toegangssleutel in de verbindingsreeks is vergelijkbaar met een hoofdwachtwoord voor uw service. Beveilig uw toegangssleutels altijd in productieomgevingen. Gebruik Azure Key Vault om uw sleutels veilig te beheren en te roteren en uw verbindingsreeks te beveiligen met behulp van Microsoft Entra-id en toegang te autoriseren met Microsoft Entra ID.

Vermijd het distribueren van toegangssleutels naar andere gebruikers, het coderen ervan of het opslaan van ze ergens in tekst zonder opmaak die toegankelijk is voor anderen. Draai uw sleutels als u denkt dat ze mogelijk zijn aangetast.

Functies

Functie Tijdelijk Permanent
Uitzenden ✔️ ✔️
Uitzenden behalve sommige clients ✔️ ✔️
Verzenden naar een client ✔️ ✔️
Verzenden naar clients ✔️ ✔️
Naar een gebruiker verzenden ✔️ ✔️
Verzenden naar gebruikers ✔️ ✔️
Verzenden naar een groep ✔️ ✔️
Verzenden naar groepen ✔️ ✔️
Verzenden naar een groep, met uitzondering van sommige clients ✔️ ✔️
Een gebruiker toevoegen aan een groep ✔️ ✔️
Een gebruiker uit een groep verwijderen ✔️ ✔️
Controleren of een gebruiker in een groep ✔️ ✔️
Ondersteuning voor meerdere SignalR-service-exemplaren ❌ ✔️
Ondersteuning voor MessagePack-clients sinds v1.21.0 sinds v1.20.0
Tijdelijke fout opnieuw proberen sinds v1.22.0 ❌

Functies worden alleen geleverd met nieuwe API

Functie Tijdelijk Permanent
Controleren of er een verbinding bestaat ✔️ Sinds v1.11
Controleren of er een groep bestaat ✔️ Sinds v1.11
Controleren of er een gebruiker bestaat ✔️ Sinds v1.11
Een clientverbinding sluiten ✔️ Sinds v1.11

  • Meer informatie over verschillende modi vindt u hier.

  • Hier vindt u een volledig voorbeeld van de beheer-SDK.

Gebruik

In deze sectie wordt beschreven hoe u de Management SDK gebruikt.

Service Manager maken

Bouw uw exemplaar van ServiceManager een ServiceManagerBuilder.

Onbewerkte verbindingsreeks worden alleen in dit artikel weergegeven voor demonstratiedoeleinden. Beveilig uw toegangssleutels altijd in productieomgevingen. Gebruik Azure Key Vault om uw sleutels veilig te beheren en te roteren en uw verbindingsreeks te beveiligen met behulp van Microsoft Entra-id en toegang te autoriseren met Microsoft Entra ID.


var serviceManager = new ServiceManagerBuilder()
                    .WithOptions(option =>
                    {
                        option.ConnectionString = "<Your Azure SignalR Service Connection String>";
                    })
                    .WithLoggerFactory(loggerFactory)
                    .BuildServiceManager();

U kunt de ServiceManager status van het Azure SignalR-eindpunt controleren en de servicehubcontext maken. In de volgende sectie vindt u meer informatie over het maken van servicehub-context.

Als u de status van het Azure SignalR-eindpunt wilt controleren, kunt u de methode gebruiken ServiceManager.IsServiceHealthy . Als u meerdere Azure SignalR-eindpunten hebt, wordt alleen het eerste eindpunt gecontroleerd.

var health = await serviceManager.IsServiceHealthy(cancellationToken);

Service Hub-context maken

Maak uw exemplaar van ServiceHubContext een ServiceManager:

var serviceHubContext = await serviceManager.CreateHubContextAsync("<Your Hub Name>",cancellationToken);

Onderhandeling

In de standaardmodus wordt een eindpunt /<Your Hub Name>/negotiate beschikbaar gemaakt voor onderhandeling door de Azure SignalR Service SDK. SignalR-clients bereiken dit eindpunt en worden later omgeleid naar Azure SignalR Service.

In de serverloze modus raden we u aan een onderhandelingseindpunt te hosten om de onderhandelingsaanvraag van signalR-clients te verwerken en de clients om te leiden naar Azure SignalR Service.

Tip

Lees meer informatie over de omleiding in het onderhandelingsprotocol van SignalR.

Zowel het eindpunt als het toegangstoken zijn handig als u SignalR-clients wilt omleiden naar uw Azure SignalR-service.

U kunt het exemplaar gebruiken om ServiceHubContext de eindpunt-URL en het bijbehorende toegangstoken voor SignalR-clients te genereren om verbinding te maken met uw Azure SignalR-service.

var negotiationResponse = await serviceHubContext.NegotiateAsync(new (){UserId = "<Your User Id>"});

Stel dat uw hub-eindpunt is http://<Your Host Name>/<Your Hub Name>, dan is http://<Your Host Name>/<Your Hub Name>/negotiateuw onderhandelingseindpunt. Zodra u het onderhandelingseindpunt host, kunt u de SignalR-clients gebruiken om als volgt verbinding te maken met uw hub:

var connection = new HubConnectionBuilder().WithUrl("http://<Your Host Name>/<Your Hub Name>").Build();
await connection.StartAsync();

Hier vindt u het voorbeeld over het gebruik van de Management SDK om SignalR-clients om te leiden naar Azure SignalR Service.

Berichten verzenden en groepen beheren

De ServiceHubContext we bouwen van ServiceHubContextBuilder is een klasse die implementeert en uitbreidt IServiceHubContext. U kunt deze gebruiken om berichten naar uw klanten te verzenden en uw groepen te beheren.

try
{
    // Broadcast
    await hubContext.Clients.All.SendAsync(callbackName, obj1, obj2, ...);

    // Send to user
    await hubContext.Clients.User(userId).SendAsync(callbackName, obj1, obj2, ...);

    // Send to group
    await hubContext.Clients.Group(groupId).SendAsync(callbackName, obj1, obj2, ...);

    // add user to group
    await hubContext.UserGroups.AddToGroupAsync(userId, groupName);

    // remove user from group
    await hubContext.UserGroups.RemoveFromGroupAsync(userId, groupName);
}
finally
{
    await hubContext.DisposeAsync();
}

Sterk getypte hub

Een sterk getypte hub is een programmeermodel dat u uw clientmethoden kunt extraheren in een interface, zodat u fouten zoals het verkeerd spelen van de methodenaam of het doorgeven van de verkeerde parametertypen kunt voorkomen.

Stel dat we een clientmethode hebben die wordt aangeroepen ReceivedMessage met twee tekenreeksparameters. Zonder sterk getypte hubs kunt u uitzenden naar clients via hubContext.Clients.All.SendAsync("ReceivedMessage", user, message). Met sterk getypte hubs definieert u eerst een interface zoals deze:

public interface IChatClient
{
    Task ReceiveMessage(string user, string message);
}

En vervolgens maakt u een sterk getypte hubcontext, die implementeert IHubContext<Hub<T>, T>, T uw clientmethode-interface:

ServiceHubContext<IChatClient> serviceHubContext = await serviceManager.CreateHubContextAsync<IChatClient>(hubName, cancellationToken);

Ten slotte kunt u de methode rechtstreeks aanroepen:

await Clients.All.ReceiveMessage(user, message);

Met uitzondering van het verschil in het verzenden van berichten, kunt u groepen onderhandelen of beheren met ServiceHubContext<T> net als ServiceHubContext.

Lees hier meer over sterk getypte hubs in de ASP.NET Core-documenten.

Transporttype

Deze SDK kan communiceren met Azure SignalR Service met twee transporttypen:

  • Tijdelijk: Maak een HTTP-aanvraag voor Azure SignalR Service voor elk verzonden bericht. De SDK verpakt eenvoudig de REST API van Azure SignalR Service in de tijdelijke modus. Het is handig als u geen WebSockets-verbinding tot stand kunt brengen.
  • Permanent: Maak eerst een WebSockets-verbinding en verzend vervolgens alle berichten in deze verbinding. Dit is handig wanneer u een groot aantal berichten verzendt.

Samenvatting van serialisatiegedrag van de argumenten in berichten

Serialisatie Tijdelijk Permanent
Standaard JSON-bibliotheek Newtonsoft.Json Hetzelfde als ASP.NET Core SignalR:
Newtonsoft.Json voor .NET Standard 2.0;
System.Text.Json voor .NET Core App 3.1 en hoger
Ondersteuning voor MessagePack-clients sinds v1.21.0 sinds v1.20.0

JSON-serialisatie

In de Management SDK worden de methodeargumenten die naar clients worden verzonden, geserialiseerd in JSON. We hebben verschillende manieren om JSON-serialisatie aan te passen. We tonen alle manieren in de volgorde van de aanbevolen tot het minst aanbevolen.

ServiceManagerOptions.UseJsonObjectSerializer(ObjectSerializer objectSerializer)

De meest aanbevolen manier is om een algemene abstracte klasse ObjectSerializerte gebruiken, omdat deze verschillende JSON-serialisatiebibliotheken ondersteunt, zoals System.Text.Json en Newtonsoft.Json van toepassing is op alle transporttypen. Meestal hoeft u zich niet zelf te implementeren ObjectSerializer , zoals handige JSON-implementaties voor System.Text.Json en Newtonsoft.Json zijn al beschikbaar.

  • Bij gebruik System.Text.Json als JSON-verwerkingsbibliotheek gebruikt de ingebouwde System.Text.Json.JsonSerializer JsonObjectSerializer bibliotheek voor serialisatie/deserialisatie. Hier volgt een voorbeeld voor het gebruik van de naamgeving van kameelcases voor JSON-serialisatie:

    var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.ConnectionString = "***";
        o.UseJsonObjectSerializer(new JsonObjectSerializer(new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase
        }));
    })
    .BuildServiceManager();

  • Wanneer u Newtonsoft.Json het pakket als JSON-verwerkingsbibliotheek gebruikt, installeert u het pakket Microsoft.Azure.Core.NewtonsoftJson eerst vanuit NuGet met behulp van .NET CLI:

    dotnet add package Microsoft.Azure.Core.NewtonsoftJson

    Hier volgt een voorbeeld voor het gebruik van naamgeving van kameelcases met NewtonsoftJsonObjectSerializer:

    var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.ConnectionString = "***";
        o.UseJsonObjectSerializer(new NewtonsoftJsonObjectSerializer(new JsonSerializerSettings()
        {
            ContractResolver = new CamelCasePropertyNamesContractResolver()
        }));
    })
    .BuildServiceManager();

  • Wanneer u andere JSON-verwerkingsbibliotheken gebruikt

    U kunt ook zelf implementeren ObjectSerializer . De volgende koppelingen kunnen u helpen:

ServiceManagerBuilder.WithNewtonsoftJson(Action<NewtonsoftServiceHubProtocolOptions> configure)

Deze methode is alleen voor Newtonsoft.Json gebruikers. Hier volgt een voorbeeld voor het gebruik van naamgeving van kameelscenario's:

var serviceManager = new ServiceManagerBuilder()
    .WithNewtonsoftJson(o =>
    {
        o.PayloadSerializerSettings = new JsonSerializerSettings
        {
            ContractResolver = new CamelCasePropertyNamesContractResolver()
        };
    })
    .BuildServiceManager();
ServiceManagerOptions.JsonSerializerSettings (Afgeschaft)

Deze methode is alleen van toepassing op tijdelijk transporttype. Gebruik dit niet.

var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.JsonSerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
    })
    .BuildServiceManager();

Serialisatie van berichtenpakketten

  1. U moet het pakket installeren Microsoft.AspNetCore.SignalR.Protocols.MessagePack .

  2. Een MessagePack-protocol naast het standaard JSON-protocol toevoegen:

    var serviceManagerBuilder = new ServiceManagerBuilder()
    .AddHubProtocol(new MessagePackHubProtocol());

  3. Als u de hubprotocollen volledig wilt beheren, kunt u

        var serviceManagerBuilder = new ServiceManagerBuilder()
        .WithHubProtocols(new MessagePackHubProtocol(), new JsonHubProtocol());

    WithHubProtocols wist eerst de bestaande protocollen en voegt vervolgens de nieuwe protocollen toe. U kunt deze methode ook gebruiken om het JSON-protocol te verwijderen en alleen MessagePack te gebruiken.

Voor de tijdelijke modus converteert de servicezijde standaard JSON-nettolading naar MessagePack-nettolading en is het de verouderde manier om MessagePack te ondersteunen. We raden u echter aan om expliciet een MessagePack-hubprotocol toe te voegen, omdat de verouderde manier mogelijk niet werkt zoals verwacht.

HTTP-aanvragen opnieuw proberen

Voor de tijdelijke modus biedt deze SDK de mogelijkheid om aanvragen automatisch opnieuw te verzenden wanneer tijdelijke fouten optreden, zolang de aanvragen idempotent zijn. Als u deze mogelijkheid wilt inschakelen, kunt u de ServiceManagerOptions.RetryOptions eigenschap gebruiken.

In het bijzonder worden de volgende typen aanvragen opnieuw geprobeerd:

  • Voor berichtaanvragen die berichten verzenden naar SignalR-clients, probeert de SDK de aanvraag opnieuw als de HTTP-antwoordstatuscode groter is dan 500. Wanneer de HTTP-antwoordcode gelijk is aan 500, kan dit duiden op een time-out aan de servicezijde en kan het opnieuw proberen van de aanvraag leiden tot dubbele berichten.

  • Voor andere typen aanvragen, zoals het toevoegen van een verbinding met een groep, probeert de SDK de aanvraag opnieuw uit te voeren onder de volgende voorwaarden:

    1. De HTTP-antwoordstatuscode bevindt zich in het bereik van 5xx of er is een time-out opgetreden voor de aanvraag met een statuscode van 408 (time-out van aanvraag).
    2. Er is een time-out opgetreden voor de aanvraag met een duur die langer is dan de time-outlengte die is geconfigureerd in ServiceManagerOptions.HttpClientTimeout.

De SDK kan alleen idempotente aanvragen opnieuw proberen. Dit zijn aanvragen die geen ander effect hebben als ze worden herhaald. Als uw aanvragen niet idempotent zijn, moet u mogelijk handmatig nieuwe pogingen afhandelen.

Volgende stappen

In dit artikel leert u hoe u SignalR Service gebruikt in uw toepassingen. Raadpleeg de volgende artikelen voor meer informatie over SignalR Service.

Interne werking van Azure SignalR Service

Quickstart: Een chatruimte maken met behulp van SignalR Service