Použití sady AZURE SignalR Management SDK

Sada SDK pro správu Služby Azure SignalR pomáhá spravovat klienty SignalR prostřednictvím služby Azure SignalR Přímo, jako jsou zprávy všesměrového vysílání. Proto se tato sada SDK může používat v bezserverových prostředích, ale nemůže být omezena. Tuto sadu SDK můžete použít ke správě klientů SignalR připojených ke službě Azure SignalR v libovolném prostředí, jako je konzolová aplikace, ve funkci Azure nebo na webovém serveru.

Poznámka:

Pokud chcete zobrazit příručky pro sadu SDK verze 1.9.x a dříve, přejděte do sady SDK pro správu služby Azure SignalR (starší verze). Možná si také budete chtít přečíst pokyny k migraci.

Důležité

Nezpracované připojovací řetězec se v tomto článku zobrazují jenom pro demonstrační účely.

Připojovací řetězec obsahuje autorizační informace potřebné pro vaši aplikaci pro přístup ke službě Azure SignalR. Přístupový klíč uvnitř připojovací řetězec je podobný kořenovému heslu pro vaši službu. V produkčních prostředích vždy chraňte přístupové klíče. Pomocí služby Azure Key Vault můžete bezpečně spravovat a obměňovat klíče a zabezpečit připojovací řetězec pomocí ID Microsoft Entra a autorizovat přístup pomocí Microsoft Entra ID.

Vyhněte se distribuci přístupových klíčů ostatním uživatelům, jejich pevnému kódování nebo jejich uložení kdekoli ve formátu prostého textu, který je přístupný ostatním uživatelům. Otočte klíče, pokud se domníváte, že mohly být ohroženy.

Funkce

Funkce	Přechodná	Trvalý
Vysílání	✔️	✔️
Všesměrové vysílání s výjimkou některých klientů	✔️	✔️
Odeslání klientovi	✔️	✔️
Odesílání klientům	✔️	✔️
Odeslat uživateli	✔️	✔️
Posílání uživatelům	✔️	✔️
Odeslání do skupiny	✔️	✔️
Odeslat do skupin	✔️	✔️
Odeslání skupině s výjimkou některých klientů	✔️	✔️
Přidání uživatele do skupiny	✔️	✔️
Odebrání uživatele ze skupiny	✔️	✔️
Kontrola, jestli uživatel ve skupině	✔️	✔️
Podpora více instancí služby SignalR	❌	✔️
Podpora klientů MessagePack	od verze 1.21.0	od verze 1.20.0
Opakování přechodné chyby	od verze 1.22.0	❌

Funkce se dodávají jenom s novým rozhraním API.

Funkce	Přechodná	Trvalý
Kontrola, jestli připojení existuje	✔️	Od verze 1.11
Kontrola, jestli skupina existuje	✔️	Od verze 1.11
Kontrola, jestli uživatel existuje	✔️	Od verze 1.11
Zavření připojení klienta	✔️	Od verze 1.11

• Další podrobnosti o různých režimech najdete tady.

• Úplnou ukázku sady SDK pro správu najdete tady.

Využití

V této části se dozvíte, jak používat sadu SDK pro správu.

Vytvoření portálu Service Manager

Sestavte instanci z objektu ServiceManager ServiceManagerBuilder.

Nezpracované připojovací řetězec se v tomto článku zobrazují jenom pro demonstrační účely. V produkčních prostředích vždy chraňte přístupové klíče. Pomocí služby Azure Key Vault můžete bezpečně spravovat a obměňovat klíče a zabezpečit připojovací řetězec pomocí ID Microsoft Entra a autorizovat přístup pomocí Microsoft Entra ID.

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

Můžete použít ServiceManager ke kontrole stavu koncového bodu Azure SignalR a vytvoření kontextu centra služeb. Následující část obsahuje podrobnosti o vytváření kontextu centra služeb.

Pokud chcete zkontrolovat stav koncového bodu Azure SignalR, můžete použít ServiceManager.IsServiceHealthy metodu. Pokud máte více koncových bodů Azure SignalR, zkontroluje se jenom první koncový bod.

var health = await serviceManager.IsServiceHealthy(cancellationToken);

Vytvoření kontextu centra služeb

Vytvořte instanci ServiceHubContext z ServiceManager:

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

Vyjednávání

Ve výchozím režimu je koncový bod /<Your Hub Name>/negotiate zpřístupněn pro vyjednávání sadou SDK služby Azure SignalR. Klienti SignalR se dostanou k tomuto koncovému bodu a později přesměrují na službu Azure SignalR.

V bezserverovém režimu doporučujeme hostovat koncový bod vyjednávání, který obsluhuje žádost klientů SignalR a přesměruje klienty do služby Azure SignalR.

Tip

Přečtěte si další podrobnosti o přesměrování v protokolu vyjednávání služby SignalR.

Oba koncové body i přístupový token jsou užitečné, když chcete přesměrovat klienty SignalR do služby Azure SignalR.

Instanci můžete použít ke generování adresy URL koncového ServiceHubContext bodu a odpovídajícího přístupového tokenu pro klienty SignalR pro připojení ke službě Azure SignalR.

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

Předpokládejme, že koncový bod centra je http://<Your Host Name>/<Your Hub Name>, pak je koncový bod http://<Your Host Name>/<Your Hub Name>/negotiatevyjednávání . Jakmile hostujete koncový bod vyjednávání, můžete se pomocí klientů SignalR připojit k centru takto:

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

Tady najdete ukázku použití sady Management SDK k přesměrování klientů SignalR do služby Azure SignalR.

Odesílání zpráv a správa skupin

Vycházíme ServiceHubContext z ServiceHubContextBuilder třídy, která implementuje a rozšiřuje IServiceHubContext. Můžete ho použít k odesílání zpráv klientům a správě skupin.

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

Rozbočovač silného typu

Centrum silného typu je programovací model, který můžete extrahovat klientské metody do rozhraní, aby nedocházelo k chybám, jako je chybně napsaný název metody nebo předání nesprávných typů parametrů.

Řekněme, že máme metodu klienta volanou ReceivedMessage se dvěma řetězcovými parametry. Bez rozbočovačů silného typu budete vysílat klientům prostřednictvím hubContext.Clients.All.SendAsync("ReceivedMessage", user, message). S rozbočovači silného typu nejprve definujete rozhraní takto:

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

A pak vytvoříte kontext centra silného typu, který implementuje IHubContext<Hub<T>, T>, T je rozhraní klientské metody:

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

Nakonec můžete metodu vyvolat přímo:

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

S výjimkou rozdílu při odesílání zpráv můžete vyjednat nebo spravovat skupiny ServiceHubContext<T> stejně jako ServiceHubContext.

Další informace o centrech silného typu najdete v dokumentaci k ASP.NET Core.

Typ přenosu

Tato sada SDK může komunikovat se službou Azure SignalR Service se dvěma typy přenosu:

• Přechodné: Vytvořte pro každou odeslanou zprávu požadavek HTTP služby Azure SignalR. Sada SDK jednoduše zabalí rozhraní REST API služby Azure SignalR v přechodném režimu. Je užitečné, když nemůžete navázat připojení WebSockets.
• Trvalá: Nejprve vytvořte připojení WebSockets a pak odešlete všechny zprávy v tomto připojení. Je užitečné, když odesíláte velký počet zpráv.

Shrnutí chování serializace argumentů ve zprávách

Serializace	Přechodná	Trvalý
Výchozí knihovna JSON	Newtonsoft.Json	Totéž jako ASP.NET Core SignalR: Newtonsoft.Json pro .NET Standard 2.0; System.Text.Json pro .NET Core App 3.1 a novější
Podpora klientů MessagePack	od verze 1.21.0	od verze 1.20.0

Serializace JSON

V sadě Management SDK jsou argumenty metody odeslané klientům serializovány do formátu JSON. Serializace JSON se dá přizpůsobit několika způsoby. Zobrazujeme všechny způsoby v pořadí od nejvíce doporučených po nejméně doporučenou.

ServiceManagerOptions.UseJsonObjectSerializer(ObjectSerializer objectSerializer)

Doporučeným způsobem je použít obecnou abstraktní třídu ObjectSerializer, protože podporuje různé knihovny serializace JSON, jako System.Text.Json jsou a Newtonsoft.Json platí pro všechny typy přenosu. Obvykle se nemusíte implementovat ObjectSerializer sami, protože jsou k dispozici užitečné implementace System.Text.Json JSON a Newtonsoft.Json jsou k dispozici.

• Při použití System.Text.Json jako knihovny pro zpracování JSON se předdefinovaný JsonObjectSerializer objekt používá System.Text.Json.JsonSerializer k serializaci nebo deserializaci. Tady je ukázka použití pojmenování velbloudého případu pro serializaci JSON:

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

• Při použití Newtonsoft.Json jako knihovny pro zpracování JSON nejprve nainstalujte balíček Microsoft.Azure.Core.NewtonsoftJson z NuGetu pomocí rozhraní příkazového řádku .NET:

  dotnet add package Microsoft.Azure.Core.NewtonsoftJson
  

  Tady je ukázka použití pojmenování velbloudího případu s NewtonsoftJsonObjectSerializer:

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

• Při použití jiných knihoven pro zpracování JSON

  Můžete také implementovat ObjectSerializer sami. Můžou vám pomoct následující odkazy:

  • Referenční informace k rozhraní API ObjectSerializer
  • Referenční informace k rozhraní API JsonObjectSerializer

ServiceManagerBuilder.WithNewtonsoftJson(Action<NewtonsoftServiceHubProtocolOptions> configure)

Tato metoda je určená pouze pro Newtonsoft.Json uživatele. Tady je ukázka použití pojmenování velbloudího případu:

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

ServiceManagerOptions.JsonSerializerSettings (Zastaralé)

Tato metoda se vztahuje pouze na přechodný typ přenosu. Nepoužívejte to.

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

Serializace balíčku zpráv

1. Musíte nainstalovat Microsoft.AspNetCore.SignalR.Protocols.MessagePack balíček.

2. Přidání protokolu MessagePack vedle výchozího protokolu JSON:

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

3. K úplnému řízení protokolů centra můžete použít

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

   WithHubProtocols nejprve vymaže existující protokoly a pak přidá nové protokoly. Tuto metodu můžete použít také k odebrání protokolu JSON a použití pouze MessagePacku.

V přechodném režimu ve výchozím nastavení převede datová část JSON na datovou část MessagePack a jedná se o starší způsob podpory MessagePacku. Doporučujeme ale přidat protokol centra MessagePack explicitně, protože starší verze nemusí fungovat podle očekávání.

Opakování požadavků HTTP

V přechodném režimu poskytuje tato sada SDK možnost automaticky znovu odeslat požadavky, pokud dojde k přechodným chybám, pokud jsou požadavky idempotentní. Pokud chcete tuto funkci povolit, můžete tuto ServiceManagerOptions.RetryOptions vlastnost použít.

Konkrétně se budou opakovat následující typy požadavků:

• U žádostí o zprávy, které odesílají zprávy klientům SignalR, sada SDK požadavek opakuje, pokud je stavový kód odpovědi HTTP větší než 500. Když se kód odpovědi HTTP rovná 500, může to znamenat časový limit na straně služby a opakování požadavku může vést k duplicitním zprávům.

• U jiných typů požadavků, jako je přidání připojení ke skupině, sada SDK požadavek opakuje za následujících podmínek:

  1. Stavový kód odpovědi HTTP je v rozsahu 5xx nebo vypršel časový limit požadavku se stavovým kódem 408 (vypršení časového limitu požadavku).
  2. Vypršel časový limit požadavku s delší dobou, než je délka časového limitu nakonfigurovaná v ServiceManagerOptions.HttpClientTimeout.

Sada SDK může opakovat pouze idempotentní požadavky, což jsou požadavky, které nemají žádný jiný účinek, pokud se opakují. Pokud vaše požadavky nejsou idempotentní, budete možná muset zpracovat opakované pokusy ručně.

Další kroky

V tomto článku se dozvíte, jak používat službu SignalR Service ve vašich aplikacích. Další informace o službě SignalR Najdete v následujících článcích.

Interní informace služby Azure SignalR Service

Rychlý start: Vytvoření chatovací místnosti pomocí služby SignalR