Dela via

Använda Azure SignalR Management SDK

  • Artikel

Azure SignalR Management SDK hjälper dig att hantera SignalR-klienter via Azure SignalR Service direkt, till exempel sändningsmeddelanden. Därför kan denna SDK vara men inte begränsad till att användas i serverlösa miljöer. Du kan använda denna SDK för att hantera SignalR-klienter som är anslutna till din Azure SignalR Service i valfri miljö, till exempel i en konsolapp, i en Azure-funktion eller på en webbserver.

Kommentar

Om du vill se guider för SDK version 1.9.x och tidigare går du till Azure SignalR Service Management SDK (Legacy). Du kanske också vill läsa migreringsvägledning.

Viktigt!

Råa anslutningssträng visas endast i den här artikeln i demonstrationssyfte.

En anslutningssträng innehåller den auktoriseringsinformation som krävs för att ditt program ska få åtkomst till Azure SignalR Service. Åtkomstnyckeln i anslutningssträng liknar ett rotlösenord för din tjänst. Skydda alltid dina åtkomstnycklar i produktionsmiljöer. Använd Azure Key Vault för att hantera och rotera dina nycklar på ett säkert sätt och skydda dina anslutningssträng med hjälp av Microsoft Entra-ID och auktorisera åtkomst med Microsoft Entra-ID.

Undvik att distribuera åtkomstnycklar till andra användare, hårdkoda dem eller spara dem var som helst i oformaterad text som är tillgänglig för andra. Rotera dina nycklar om du tror att de har komprometterats.

Funktioner

Funktion Tillfälligt Permanent
Sändning ✔️ ✔️
Sändning utom vissa klienter ✔️ ✔️
Skicka till en klient ✔️ ✔️
Skicka till klienter ✔️ ✔️
Skicka till en användare ✔️ ✔️
Skicka till användare ✔️ ✔️
Skicka till en grupp ✔️ ✔️
Skicka till grupper ✔️ ✔️
Skicka till en grupp förutom vissa klienter ✔️ ✔️
Lägga till en användare i en grupp ✔️ ✔️
Ta bort en användare från en grupp ✔️ ✔️
Kontrollera om en användare i en grupp ✔️ ✔️
Stöd för flera SignalR-tjänstinstanser ❌ ✔️
Stöd för MessagePack-klienter sedan v1.21.0 sedan v1.20.0
Försök igen med tillfälligt fel sedan v1.22.0 ❌

Funktioner levereras endast med nytt API

Funktion Tillfälligt Permanent
Kontrollera om det finns en anslutning ✔️ Sedan v1.11
Kontrollera om det finns en grupp ✔️ Sedan v1.11
Kontrollera om en användare finns ✔️ Sedan v1.11
Stäng en klientanslutning ✔️ Sedan v1.11

  • Mer information om olika lägen finns här.

  • Ett fullständigt exempel på hanterings-SDK finns här.

Förbrukning

Det här avsnittet visar hur du använder Hanterings-SDK.

Skapa Service Manager

Skapa din instans av ServiceManager från en ServiceManagerBuilder.

Råa anslutningssträng visas endast i den här artikeln i demonstrationssyfte. Skydda alltid dina åtkomstnycklar i produktionsmiljöer. Använd Azure Key Vault för att hantera och rotera dina nycklar på ett säkert sätt och skydda dina anslutningssträng med hjälp av Microsoft Entra-ID och auktorisera åtkomst med Microsoft Entra-ID.


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

Du kan använda ServiceManager för att kontrollera Azure SignalR-slutpunktens hälsa och skapa tjänsthubbens kontext. Följande avsnitt innehåller information om hur du skapar en tjänsthubbkontext.

Om du vill kontrollera Azure SignalR-slutpunktshälsan kan du använda ServiceManager.IsServiceHealthy metoden. Om du har flera Azure SignalR-slutpunkter kontrolleras endast den första slutpunkten.

var health = await serviceManager.IsServiceHealthy(cancellationToken);

Skapa Service Hub-kontext

Skapa din instans av ServiceHubContext från en ServiceManager:

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

Förhandling

I standardläge exponeras en slutpunkt /<Your Hub Name>/negotiate för förhandling av Azure SignalR Service SDK. SignalR-klienter når den här slutpunkten och omdirigerar sedan till Azure SignalR Service senare.

I serverlöst läge rekommenderar vi att du är värd för en förhandlingsslutpunkt för att hantera SignalR-klienternas förhandlingsbegäran och omdirigera klienterna till Azure SignalR Service.

Dricks

Läs mer om omdirigeringen i SignalR:s förhandlingsprotokoll.

Både slutpunkts- och åtkomsttoken är användbara när du vill omdirigera SignalR-klienter till Din Azure SignalR Service.

Du kan använda instansen av ServiceHubContext för att generera slutpunkts-URL:en och motsvarande åtkomsttoken för SignalR-klienter för att ansluta till Din Azure SignalR Service.

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

Anta att hubbens slutpunkt är http://<Your Host Name>/<Your Hub Name>och att förhandlingsslutpunkten är http://<Your Host Name>/<Your Hub Name>/negotiate. När du är värd för förhandlingsslutpunkten kan du använda SignalR-klienterna för att ansluta till din hubb så här:

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

Exempel på hur du använder Management SDK för att omdirigera SignalR-klienter till Azure SignalR Service finns här.

Skicka meddelanden och hantera grupper

Vi ServiceHubContext bygger från ServiceHubContextBuilder är en klass som implementerar och utökar IServiceHubContext. Du kan använda den för att skicka meddelanden till dina klienter och hantera dina grupper.

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();
}

Starkt skriven hubb

En starkt typad hubb är en programmeringsmodell som du kan extrahera dina klientmetoder till ett gränssnitt, så att du undviker fel som att felstava metodnamnet eller skicka fel parametertyper.

Anta att vi har en klientmetod som heter ReceivedMessage med två strängparametrar. Utan starkt inskrivna hubbar sänder du till klienter via hubContext.Clients.All.SendAsync("ReceivedMessage", user, message). Med starkt skrivna hubbar definierar du först ett gränssnitt som det här:

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

Och sedan skapar du en starkt typad hubbkontext, som implementerar IHubContext<Hub<T>, T>, T är ditt klientmetodgränssnitt:

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

Slutligen kan du anropa metoden direkt:

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

Förutom skillnaden med att skicka meddelanden kan du förhandla eller hantera grupper med ServiceHubContext<T> precis som ServiceHubContext.

Läs mer om starkt inskrivna hubbar i ASP.NET Core-dokumenten här.

Transporttyp

Denna SDK kan kommunicera med Azure SignalR Service med två transporttyper:

  • Tillfälligt: Skapa en HTTP-begäran för Azure SignalR Service för varje meddelande som skickas. SDK:n avslutar helt enkelt Azure SignalR Service REST API i tillfälligt läge. Det är användbart när du inte kan upprätta en WebSockets-anslutning.
  • Beständiga: Skapa en WebSockets-anslutning först och skicka sedan alla meddelanden i den här anslutningen. Det är användbart när du skickar ett stort antal meddelanden.

Sammanfattning av serialiseringsbeteenden för argumenten i meddelanden

Serialisering Tillfälligt Permanent
JSON-standardbibliotek Newtonsoft.Json Samma som ASP.NET Core SignalR:
Newtonsoft.Json för .NET Standard 2.0;
System.Text.Json för .NET Core App 3.1 och senare
Stöd för MessagePack-klienter sedan v1.21.0 sedan v1.20.0

JSON-serialisering

I Hanterings-SDK serialiseras metodargumenten som skickas till klienter till JSON. Vi har flera sätt att anpassa JSON-serialisering. Vi visar alla sätt i den ordning från de mest rekommenderade till de minst rekommenderade.

ServiceManagerOptions.UseJsonObjectSerializer(ObjectSerializer objectSerializer)

Det mest rekommenderade sättet är att använda en allmän abstrakt klass ObjectSerializer, eftersom den stöder olika JSON-serialiseringsbibliotek som System.Text.Json och Newtonsoft.Json gäller för alla transporttyper. Vanligtvis behöver du inte implementera ObjectSerializer dig själv, eftersom praktiska JSON-implementeringar för System.Text.Json och Newtonsoft.Json redan tillhandahålls.

  • När du använder System.Text.Json som JSON-bearbetningsbibliotek Används det inbyggda JsonObjectSerializer System.Text.Json.JsonSerializer för serialisering/deserialisering. Här är ett exempel på hur du använder namngivning av kamelfall för JSON-serialisering:

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

  • När du använder Newtonsoft.Json som JSON-bearbetningsbibliotek installerar du först paketet Microsoft.Azure.Core.NewtonsoftJson från NuGet med hjälp av .NET CLI:

    dotnet add package Microsoft.Azure.Core.NewtonsoftJson

    Här är ett exempel på hur du använder namngivning av kamelfall med NewtonsoftJsonObjectSerializer:

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

  • När du använder andra JSON-bearbetningsbibliotek

    Du kan också implementera ObjectSerializer på egen hand. Följande länkar kan vara till hjälp:

ServiceManagerBuilder.WithNewtonsoftJson(Action<NewtonsoftServiceHubProtocolOptions> configure)

Den här metoden är endast för Newtonsoft.Json användare. Här är ett exempel på hur du använder namngivning av kamelfall:

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

Den här metoden gäller endast för tillfälliga transporttyper. Använd inte detta.

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

Serialisering av meddelandepaket

  1. Du måste installera Microsoft.AspNetCore.SignalR.Protocols.MessagePack paketet.

  2. Så här lägger du till ett MessagePack-protokoll sida vid sida med JSON-standardprotokollet:

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

  3. Om du vill kontrollera hubbprotokollen fullt ut kan du använda

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

    WithHubProtocols rensar först befintliga protokoll och lägger sedan till de nya protokollen. Du kan också använda den här metoden för att ta bort JSON-protokollet och endast använda MessagePack.

För tillfälligt läge konverterar tjänstsidan som standard JSON-nyttolasten till MessagePack-nyttolast och det är det äldre sättet att stödja MessagePack. Vi rekommenderar dock att du lägger till ett MessagePack Hub-protokoll explicit eftersom det äldre sättet kanske inte fungerar som förväntat.

HTTP-begäranden försöker igen

För det tillfälliga läget ger denna SDK möjlighet att automatiskt skicka begäranden igen när tillfälliga fel inträffar, så länge begärandena är idempotent. Om du vill aktivera den här funktionen kan du använda egenskapen ServiceManagerOptions.RetryOptions .

I synnerhet görs följande typer av begäranden på nytt:

  • För meddelandebegäranden som skickar meddelanden till SignalR-klienter försöker SDK:t skicka begäran igen om HTTP-svarsstatuskoden är större än 500. När HTTP-svarskoden är lika med 500 kan det tyda på en timeout på tjänstsidan, och om du försöker igen kan det resultera i dubbletter av meddelanden.

  • För andra typer av begäranden, till exempel att lägga till en anslutning till en grupp, försöker SDK:t begäran igen under följande villkor:

    1. Statuskoden för HTTP-svar ligger i 5xx-intervallet, eller så uppnåddes tidsgränsen för begäran med statuskoden 408 (tidsgräns för begäran).
    2. Tidsgränsen för begäran uppnåddes med en varaktighet som varar längre än den tidsgräns som konfigurerades i ServiceManagerOptions.HttpClientTimeout.

SDK:n kan bara försöka utföra idempotentbegäranden igen, vilket är begäranden som inte har någon annan effekt om de upprepas. Om dina begäranden inte är idempotent kan du behöva hantera återförsök manuellt.

Nästa steg

I den här artikeln får du lära dig hur du använder SignalR Service i dina program. Läs följande artiklar om du vill veta mer om SignalR Service.

Azure SignalR Service – internt

Snabbstart: Skapa ett chattrum med hjälp av SignalR Service