Usare Azure SignalR Management SDK

Azure SignalR Management SDK consente di gestire i client SignalR tramite Servizio Azure SignalR direttamente, ad esempio i messaggi di trasmissione. Pertanto, questo SDK potrebbe essere usato solo in ambienti serverless . È possibile usare questo SDK per gestire i client SignalR connessi al Servizio Azure SignalR in qualsiasi ambiente, ad esempio in un'app console, in una funzione di Azure o in un server Web.

Nota

Per visualizzare le guide per SDK versione 1.9.x e precedenti, passare a Servizio Azure SignalR Management SDK (legacy). È anche possibile leggere il materiale sussidiario sulla migrazione.

Importante

Le stringa di connessione non elaborate vengono visualizzate in questo articolo solo a scopo dimostrativo.

Un stringa di connessione include le informazioni di autorizzazione necessarie per consentire all'applicazione di accedere alle Servizio Azure SignalR. La chiave di accesso all'interno della stringa di connessione è simile a una password radice per il servizio. Negli ambienti di produzione proteggere sempre le chiavi di accesso. Usare Azure Key Vault per gestire e ruotare le chiavi in modo sicuro e proteggere i stringa di connessione usando Microsoft Entra ID e autorizzare l'accesso con Microsoft Entra ID.

Evitare di distribuire le chiavi di accesso ad altri utenti, impostarle come hardcoded o salvarle in un file di testo normale accessibile ad altri. Ruotare le chiavi se si ritiene che siano state compromesse.

Funzionalità

Funzionalità	Temporaneo	Persistente
Broadcast	✔️	✔️
Trasmissione ad eccezione di alcuni client	✔️	✔️
Inviare a un client	✔️	✔️
Inviare ai client	✔️	✔️
Inviare a un utente	✔️	✔️
Inviare agli utenti	✔️	✔️
Invia a un gruppo	✔️	✔️
Inviare ai gruppi	✔️	✔️
Inviare a un gruppo ad eccezione di alcuni client	✔️	✔️
Aggiungere un utente a un gruppo	✔️	✔️
Rimuovere un utente da un gruppo	✔️	✔️
Controllare se un utente in un gruppo	✔️	✔️
Supporto di più istanze del servizio SignalR	❌	✔️
Supporto dei client MessagePack	dalla versione 1.21.0	dalla versione 1.20.0
Errore temporaneo di ripetizione dei tentativi	dalla versione 1.22.0	❌

Le funzionalità sono disponibili solo con una nuova API

Funzionalità	Temporaneo	Persistente
Controllare se esiste una connessione	✔️	Dalla versione 1.11
Controllare se esiste un gruppo	✔️	Dalla versione 1.11
Controllare se un utente esiste	✔️	Dalla versione 1.11
Chiudere una connessione client	✔️	Dalla versione 1.11

• Altre informazioni sulle diverse modalità sono disponibili qui.

• Un esempio completo sull'SDK di gestione è disponibile qui.

Utilizzo

Questa sezione illustra come usare Management SDK.

Creare Service Manager

Compilare l'istanza di ServiceManager da un oggetto ServiceManagerBuilder.

Le stringa di connessione non elaborate vengono visualizzate in questo articolo solo a scopo dimostrativo. Negli ambienti di produzione proteggere sempre le chiavi di accesso. Usare Azure Key Vault per gestire e ruotare le chiavi in modo sicuro e proteggere i stringa di connessione usando Microsoft Entra ID e autorizzare l'accesso con Microsoft Entra ID.

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

È possibile usare ServiceManager per controllare l'integrità dell'endpoint di Azure SignalR e creare il contesto dell'hub di servizio. La sezione seguente fornisce informazioni dettagliate sulla creazione del contesto dell'hub dei servizi.

Per controllare l'integrità dell'endpoint di Azure SignalR, è possibile usare il ServiceManager.IsServiceHealthy metodo . Se sono presenti più endpoint di Azure SignalR, viene controllato solo il primo endpoint.

var health = await serviceManager.IsServiceHealthy(cancellationToken);

Creare il contesto dell'hub di servizio

Creare l'istanza di ServiceHubContext da :ServiceManager

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

Trattativa

In modalità predefinita, un endpoint /<Your Hub Name>/negotiate viene esposto per la negoziazione da Servizio Azure SignalR SDK. I client SignalR raggiungono questo endpoint e quindi reindirizzano a Servizio Azure SignalR in un secondo momento.

In modalità serverless, è consigliabile ospitare un endpoint di negoziazione per gestire la richiesta negoziata dei client SignalR e reindirizzare i client a Servizio Azure SignalR.

Suggerimento

Per altre informazioni sul reindirizzamento, vedere Il protocollo di negoziazione di SignalR.

Sia l'endpoint che il token di accesso sono utili quando si vogliono reindirizzare i client SignalR ai Servizio Azure SignalR.

È possibile usare l'istanza di per generare l'URL dell'endpoint e il token di ServiceHubContext accesso corrispondente per i client SignalR per connettersi al Servizio Azure SignalR.

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

Si supponga che l'endpoint dell'hub sia http://<Your Host Name>/<Your Hub Name>, quindi l'endpoint di negoziazione è http://<Your Host Name>/<Your Hub Name>/negotiate. Dopo aver ospitato l'endpoint di negoziazione, è possibile usare i client SignalR per connettersi all'hub come segue:

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

L'esempio su come usare Management SDK per reindirizzare i client SignalR a Servizio Azure SignalR è disponibile qui.

Inviare messaggi e gestire i gruppi

L'oggetto ServiceHubContext creato da ServiceHubContextBuilder è una classe che implementa ed estende IServiceHubContext. È possibile usarlo per inviare messaggi ai client e gestire i gruppi.

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

Hub tipizzati in modo sicuro

Un hub fortemente tipizzato è un modello di programmazione che è possibile estrarre i metodi client in un'interfaccia, in modo da evitare errori come l'ortografia del nome del metodo o il passaggio dei tipi di parametro errati.

Si supponga di avere un metodo client denominato ReceivedMessage con due parametri stringa. Senza hub fortemente tipizzato, si trasmette ai client tramite hubContext.Clients.All.SendAsync("ReceivedMessage", user, message). Con hub fortemente tipizzato, è prima necessario definire un'interfaccia simile alla seguente:

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

Si crea quindi un contesto hub fortemente tipizzato, che implementa IHubContext<Hub<T>, T>, T è l'interfaccia del metodo client:

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

Infine, è possibile richiamare direttamente il metodo :

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

Ad eccezione della differenza dell'invio di messaggi, è possibile negoziare o gestire i gruppi con ServiceHubContext<T> proprio come ServiceHubContext.

Altre informazioni sugli hub fortemente tipizzato sono disponibili nella documentazione di ASP.NET Core qui.

Tipo di trasporto

Questo SDK può comunicare con Servizio Azure SignalR con due tipi di trasporto:

• Temporaneo: creare una richiesta HTTP Servizio Azure SignalR per ogni messaggio inviato. L'SDK esegue semplicemente il wrapping Servizio Azure SignalR'API REST in modalità temporanea. È utile quando non è possibile stabilire una connessione WebSocket.
• Persistente: creare prima una connessione WebSocket e quindi inviare tutti i messaggi in questa connessione. È utile quando si inviano un numero elevato di messaggi.

Riepilogo dei comportamenti di serializzazione degli argomenti nei messaggi

Serializzazione	Temporaneo	Persistente
Libreria JSON predefinita	Newtonsoft.Json	Uguale a ASP.NET Core SignalR: Newtonsoft.Json per .NET Standard 2.0; System.Text.Json per .NET Core App 3.1 e versioni successive
Supporto dei client MessagePack	dalla versione 1.21.0	dalla versione 1.20.0

Serializzazione JSON

In Management SDK gli argomenti del metodo inviati ai client vengono serializzati in JSON. Sono disponibili diversi modi per personalizzare la serializzazione JSON. Vengono mostrati tutti i modi nell'ordine dal più consigliato al meno consigliato.

ServiceManagerOptions.UseJsonObjectSerializer(ObjectSerializer objectSerializer)

Il modo più consigliato consiste nell'usare una classe ObjectSerializerastratta generale , perché supporta librerie di serializzazione JSON diverse, System.Text.Json ad esempio e Newtonsoft.Json e si applica a tutti i tipi di trasporto. In genere non è necessario implementare ObjectSerializer se stessi, perché sono già disponibili implementazioni JSON utili per System.Text.Json e Newtonsoft.Json .

• Quando si usa System.Text.Json come libreria di elaborazione JSON L'oggetto builtin JsonObjectSerializer usa System.Text.Json.JsonSerializer per la serializzazione/deserializzazione. Ecco un esempio per usare la denominazione di maiuscole e minuscole camel per la serializzazione JSON:

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

• Quando si usa Newtonsoft.Json come libreria di elaborazione JSON Installare prima di tutto il pacchetto Microsoft.Azure.Core.NewtonsoftJson da NuGet usando l'interfaccia della riga di comando di .NET:

  dotnet add package Microsoft.Azure.Core.NewtonsoftJson
  

  Ecco un esempio per usare la denominazione di maiuscole e minuscole camel con NewtonsoftJsonObjectSerializer:

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

• Quando si usano altre librerie di elaborazione JSON

  È anche possibile implementare ObjectSerializer autonomamente. I collegamenti seguenti possono essere utili:

  • Informazioni di riferimento sulle API di ObjectSerializer
  • Informazioni di riferimento sulle API di JsonObjectSerializer

ServiceManagerBuilder.WithNewtonsoftJson(Action<NewtonsoftServiceHubProtocolOptions> configure)

Questo metodo è solo per Newtonsoft.Json gli utenti. Ecco un esempio per usare la denominazione di maiuscole e minuscole camel:

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

ServiceManagerOptions.JsonSerializerSettings (Deprecato)

Questo metodo si applica solo al tipo di trasporto temporaneo. Non utilizzare

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

Serializzazione di Message Pack

1. È necessario installare il Microsoft.AspNetCore.SignalR.Protocols.MessagePack pacchetto.

2. Per aggiungere un protocollo MessagePack side-by-side con il protocollo JSON predefinito:

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

3. Per controllare completamente i protocolli hub, è possibile usare

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

   WithHubProtocols cancella prima i protocolli esistenti e quindi aggiunge i nuovi protocolli. È anche possibile usare questo metodo per rimuovere il protocollo JSON e usare solo MessagePack.

Per la modalità temporanea, per impostazione predefinita il lato servizio converte il payload JSON nel payload MessagePack ed è il modo legacy per supportare MessagePack. È tuttavia consigliabile aggiungere un protocollo hub MessagePack in modo esplicito perché il modo legacy potrebbe non funzionare come previsto.

Tentativi di ripetizione delle richieste HTTP

Per la modalità temporanea , questo SDK offre la possibilità di inviare automaticamente le richieste quando si verificano errori temporanei, purché le richieste siano idempotenti. Per abilitare questa funzionalità, è possibile usare la ServiceManagerOptions.RetryOptions proprietà .

In particolare, vengono ritentati i tipi di richieste seguenti:

• Per le richieste di messaggio che inviano messaggi ai client SignalR, l'SDK ritenta la richiesta se il codice di stato della risposta HTTP è maggiore di 500. Quando il codice di risposta HTTP è uguale a 500, potrebbe indicare un timeout sul lato servizio e ritentare la richiesta potrebbe comportare messaggi duplicati.

• Per altri tipi di richieste, ad esempio l'aggiunta di una connessione a un gruppo, l'SDK ritenta la richiesta nelle condizioni seguenti:

  1. Il codice di stato della risposta HTTP è compreso nell'intervallo 5xx o si verifica il timeout della richiesta con un codice di stato 408 (timeout richiesta).
  2. Timeout della richiesta con una durata superiore alla lunghezza del timeout configurata in ServiceManagerOptions.HttpClientTimeout.

L'SDK può ritentare solo le richieste idempotenti, che sono richieste che non hanno altro effetto se vengono ripetute. Se le richieste non sono idempotenti, potrebbe essere necessario gestire manualmente i tentativi.

Passaggi successivi

Questo articolo illustra come usare Servizio SignalR nelle applicazioni. Per altre informazioni sulle Servizio SignalR, vedere gli articoli seguenti.

Elementi interni del Servizio Azure SignalR

Guida introduttiva: Creare una chat room usando Servizio SignalR