Korzystanie z zestawu AZURE SignalR Management SDK

Zestaw SDK zarządzania usługą Azure SignalR ułatwia zarządzanie klientami usługi SignalR za pośrednictwem usługi Azure SignalR Service bezpośrednio, takich jak komunikaty emisji. W związku z tym ten zestaw SDK może nie być ograniczony do użycia w środowiskach bezserwerowych . Za pomocą tego zestawu SDK można zarządzać klientami usługi SignalR połączonymi z usługą Azure SignalR Service w dowolnym środowisku, takim jak w aplikacji konsolowej, w funkcji platformy Azure lub na serwerze internetowym.

Uwaga

Aby wyświetlić przewodniki dotyczące zestawu SDK w wersji 1.9.x i wcześniejszej, przejdź do zestawu AZURE SignalR Service Management SDK (starsza wersja) . Warto również przeczytać wskazówki dotyczące migracji.

Ważne

Nieprzetworzone parametry połączenia są wyświetlane tylko w tym artykule w celach demonstracyjnych.

Parametry połączenia zawiera informacje o autoryzacji wymagane przez aplikację w celu uzyskania dostępu do usługi Azure Web PubSub. Klucz dostępu wewnątrz parametry połączenia jest podobny do hasła głównego usługi. W środowiskach produkcyjnych zawsze chroń klucze dostępu. Usługa Azure Key Vault umożliwia bezpieczne zarządzanie kluczami i obracanie ich oraz zabezpieczanie parametry połączenia przy użyciu identyfikatora Entra firmy Microsoft.

Unikaj dystrybuowania kluczy dostępu do innych użytkowników, kodowania ich lub zapisywania ich w dowolnym miejscu w postaci zwykłego tekstu, który jest dostępny dla innych użytkowników. Obracanie kluczy, jeśli uważasz, że mogły one zostać naruszone.

Funkcje

Funkcja	Przejściowy	Stale
Emisja	✔️	✔️
Emisja z wyjątkiem niektórych klientów	✔️	✔️
Wysyłanie do klienta	✔️	✔️
Wysyłanie do klientów	✔️	✔️
Wyślij do użytkownika	✔️	✔️
Wysyłanie do użytkowników	✔️	✔️
Wysyłanie do grupy	✔️	✔️
Wysyłanie do grup	✔️	✔️
Wysyłanie do grupy z wyjątkiem niektórych klientów	✔️	✔️
Dodawanie użytkownika do grupy	✔️	✔️
Usuwanie użytkownika z grupy	✔️	✔️
Sprawdzanie, czy użytkownik w grupie	✔️	✔️
Obsługa wielu wystąpień usługi SignalR	❌	✔️
Obsługa klientów messagePack	od wersji 1.21.0	od wersji 1.20.0
Ponów próbę błędu przejściowego	od wersji 1.22.0	❌

Funkcje są dostarczane tylko z nowym interfejsem API

Funkcja	Przejściowy	Stale
Sprawdzanie, czy istnieje połączenie	✔️	Od wersji 1.11
Sprawdzanie, czy grupa istnieje	✔️	Od wersji 1.11
Sprawdzanie, czy użytkownik istnieje	✔️	Od wersji 1.11
Zamykanie połączenia klienta	✔️	Od wersji 1.11

• Więcej szczegółów na temat różnych trybów można znaleźć tutaj.

• Pełny przykład zestawu SDK zarządzania można znaleźć tutaj.

Użycie

W tej sekcji pokazano, jak używać zestawu SDK zarządzania.

Tworzenie programu Service Manager

Skompiluj wystąpienie klasy ServiceManager z klasy ServiceManagerBuilder.

Nieprzetworzone parametry połączenia są wyświetlane tylko w tym artykule w celach demonstracyjnych. W środowiskach produkcyjnych zawsze chroń klucze dostępu. Usługa Azure Key Vault umożliwia bezpieczne zarządzanie kluczami i obracanie ich oraz zabezpieczanie parametry połączenia przy użyciu identyfikatora Entra firmy Microsoft.

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

Możesz użyć ServiceManager polecenia , aby sprawdzić kondycję punktu końcowego usługi Azure SignalR i utworzyć kontekst centrum usług. Poniższa sekcja zawiera szczegółowe informacje na temat tworzenia kontekstu centrum usług.

Aby sprawdzić kondycję punktu końcowego usługi Azure SignalR, możesz użyć ServiceManager.IsServiceHealthy metody . Jeśli masz wiele punktów końcowych usługi Azure SignalR, sprawdzany jest tylko pierwszy punkt końcowy.

var health = await serviceManager.IsServiceHealthy(cancellationToken);

Tworzenie kontekstu centrum usług

Utwórz wystąpienie klasy ServiceHubContext na podstawie elementu ServiceManager:

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

Negocjacja

W trybie domyślnym punkt końcowy /<Your Hub Name>/negotiate jest udostępniany na potrzeby negocjacji przez zestaw SDK usługi Azure SignalR Service. Klienci usługi SignalR docierają do tego punktu końcowego, a następnie przekieruj do usługi Azure SignalR Service później.

W trybie bezserwerowym zalecamy hostowanie punktu końcowego negocjacji w celu obsłużenia żądania negocjowania klientów usługi SignalR i przekierowania klientów do usługi Azure SignalR Service.

Napiwek

Przeczytaj więcej szczegółów na temat przekierowania w protokole negocjacji usługi SignalR.

Zarówno punkt końcowy, jak i token dostępu są przydatne, gdy chcesz przekierować klientów usługi SignalR do usługi Azure SignalR Service.

Możesz użyć wystąpienia ServiceHubContext , aby wygenerować adres URL punktu końcowego i odpowiedni token dostępu dla klientów usługi SignalR w celu nawiązania połączenia z usługą Azure SignalR Service.

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

Załóżmy, że punkt końcowy centrum to http://<Your Host Name>/<Your Hub Name>, a punkt końcowy negocjacji to http://<Your Host Name>/<Your Hub Name>/negotiate. Po hostowanie punktu końcowego negocjacji możesz użyć klientów signalR, aby nawiązać połączenie z centrum w następujący sposób:

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

Przykład użycia zestawu SDK zarządzania do przekierowywania klientów usługi SignalR do usługi Azure SignalR Service można znaleźć tutaj.

Wysyłanie komunikatów i zarządzanie grupami

ServiceHubContext Kompilowanie z ServiceHubContextBuilder klasy to klasa, która implementuje i rozszerza klasę IServiceHubContext. Można go użyć do wysyłania komunikatów do klientów i zarządzania grupami.

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

Silnie typizowane centrum

Silnie typizowane centrum to model programowania, który można wyodrębnić metody klienta do interfejsu, aby uniknąć błędów, takich jak błędy pisowni nazwy metody lub przekazywanie nieprawidłowych typów parametrów.

Załóżmy, że mamy metodę klienta o nazwie ReceivedMessage z dwoma parametrami ciągu. Bez silnie typiowanych centrów emisja jest emitowana do klientów za pośrednictwem programu hubContext.Clients.All.SendAsync("ReceivedMessage", user, message). W przypadku silnie typiowanych koncentratorów należy najpierw zdefiniować interfejs podobny do następującego:

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

Następnie utworzysz silnie typizowane kontekst centrum, który implementuje IHubContext<Hub<T>, T>element , T jest interfejsem metody klienta:

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

Na koniec można bezpośrednio wywołać metodę :

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

Z wyjątkiem różnicy w wysyłaniu wiadomości, można negocjować grupy lub zarządzać nimi tak ServiceHubContext<T> samo jak ServiceHubContext.

Więcej informacji na temat silnie typiowanych centrów można znaleźć w dokumentacji ASP.NET Core tutaj.

Typ transportu

Ten zestaw SDK może komunikować się z usługą Azure SignalR Service z dwoma typami transportu:

• Przejściowy: utwórz żądanie HTTP usługi Azure SignalR Service dla każdego wysłanego komunikatu. Zestaw SDK po prostu opakowuje interfejs API REST usługi Azure SignalR Service w trybie przejściowym. Jest to przydatne, gdy nie możesz ustanowić połączenia protokołu WebSocket.
• Trwałe: najpierw utwórz połączenie protokołu WebSockets, a następnie wyślij wszystkie komunikaty w tym połączeniu. Jest to przydatne podczas wysyłania dużej liczby komunikatów.

Podsumowanie zachowań serializacji argumentów w komunikatach

Serializacja	Przejściowy	Stale
Domyślna biblioteka JSON	Newtonsoft.Json	Tak samo jak ASP.NET Core SignalR: Newtonsoft.Json dla platformy .NET Standard 2.0; System.Text.Json dla aplikacji .NET Core App 3.1 lub nowszej
Obsługa klientów messagePack	od wersji 1.21.0	od wersji 1.20.0

Serializacja JSON

W zestawie SDK zarządzania argumenty metody wysyłane do klientów są serializowane w formacie JSON. Mamy kilka sposobów dostosowywania serializacji JSON. Pokazujemy wszystkie sposoby w kolejności od najbardziej zalecanych do najmniej zalecanych.

ServiceManagerOptions.UseJsonObjectSerializer(ObjectSerializer objectSerializer)

Najbardziej zalecanym sposobem jest użycie ogólnej klasy ObjectSerializerabstrakcyjnej , ponieważ obsługuje różne biblioteki serializacji JSON, takie jak System.Text.Json i, i Newtonsoft.Json dotyczy wszystkich typów transportu. Zwykle nie trzeba implementować ObjectSerializer siebie, ponieważ przydatne implementacje JSON dla System.Text.Json i Newtonsoft.Json są już udostępniane.

• W przypadku używania System.Text.Json jako biblioteki przetwarzania JSON builtin JsonObjectSerializer używa System.Text.Json.JsonSerializer metody do serializacji/deserializacji. Oto przykład użycia nazewnictwa przypadków camel na potrzeby serializacji JSON:

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

• W przypadku używania Newtonsoft.Json jako biblioteki przetwarzania JSON najpierw zainstaluj pakiet Microsoft.Azure.Core.NewtonsoftJson z narzędzia NuGet przy użyciu interfejsu wiersza polecenia platformy .NET:

  dotnet add package Microsoft.Azure.Core.NewtonsoftJson
  

  Oto przykład użycia nazewnictwa przypadków wielbłąda z NewtonsoftJsonObjectSerializer:

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

• W przypadku korzystania z innych bibliotek przetwarzania JSON

  Możesz również zaimplementować ObjectSerializer samodzielnie. Poniższe linki mogą pomóc:

  • Dokumentacja interfejsu API ObjectSerializer
  • Dokumentacja interfejsu API JsonObjectSerializer

ServiceManagerBuilder.WithNewtonsoftJson(Action<NewtonsoftServiceHubProtocolOptions> configure)

Ta metoda dotyczy tylko Newtonsoft.Json użytkowników. Oto przykład użycia nazewnictwa przypadków wielbłąda:

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

ServiceManagerOptions.JsonSerializerSettings (Przestarzałe)

Ta metoda dotyczy tylko przejściowego typu transportu. Nie używaj tego.

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

Serializacja pakietu komunikatów

1. Należy zainstalować Microsoft.AspNetCore.SignalR.Protocols.MessagePack pakiet.

2. Aby dodać protokół MessagePack obok siebie z domyślnym protokołem JSON:

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

3. Aby w pełni kontrolować protokoły koncentratora, możesz użyć polecenia

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

   WithHubProtocols najpierw czyści istniejące protokoły, a następnie dodaje nowe protokoły. Możesz również użyć tej metody, aby usunąć protokół JSON i użyć tylko pakietu MessagePack.

W przypadku trybu przejściowego strona usługi domyślnie konwertuje ładunek JSON na ładunek MessagePack i jest to starszy sposób obsługi pakietu MessagePack. Zalecamy jednak jawne dodanie protokołu centrum MessagePack, ponieważ starszy sposób może nie działać zgodnie z oczekiwaniami.

Ponów próbę żądań HTTP

W przypadku trybu przejściowego ten zestaw SDK umożliwia automatyczne ponowne wysyłanie żądań w przypadku wystąpienia błędów przejściowych, o ile żądania są idempotentne. Aby włączyć tę funkcję, możesz użyć ServiceManagerOptions.RetryOptions właściwości .

W szczególności ponawiane są następujące typy żądań:

• W przypadku żądań komunikatów wysyłających komunikaty do klientów usługi SignalR zestaw SDK ponawia próbę żądania, jeśli kod stanu odpowiedzi HTTP jest większy niż 500. Gdy kod odpowiedzi HTTP jest równy 500, może wskazywać limit czasu po stronie usługi, a ponowienie próby żądania może spowodować zduplikowanie komunikatów.

• W przypadku innych typów żądań, takich jak dodanie połączenia do grupy, zestaw SDK ponawia próbę żądania w następujących warunkach:

  1. Kod stanu odpowiedzi HTTP znajduje się w zakresie 5xx lub przekroczono limit czasu żądania z kodem stanu 408 (limit czasu żądania).
  2. Upłynął limit czasu żądania z czasem dłuższym niż długość limitu czasu skonfigurowanego w programie ServiceManagerOptions.HttpClientTimeout.

Zestaw SDK może ponawiać próby tylko żądań idempotentnych, które nie mają innego wpływu, jeśli są powtarzane. Jeśli żądania nie są idempotentne, może być konieczne ręczne obsłużenie ponownych prób.

Następne kroki

Z tego artykułu dowiesz się, jak używać usługi SignalR Service w aplikacjach. Zapoznaj się z następującymi artykułami, aby dowiedzieć się więcej o usłudze SignalR Service.

Wewnętrzne elementy usługi Azure SignalR Service

Szybki start: tworzenie pokoju rozmów przy użyciu usługi SignalR Service