Partager via

Utiliser le kit de développement logiciel (SDK) Azure SignalR Management

  • Article

Le kit de développement logiciel (SDK) Azure SignalR Management vous aide à gérer les clients SignalR via Azure SignalR Service directement, comme les messages de diffusion. Par conséquent, ce kit de développement logiciel (SDK) peut être utilisé, mais pas limité à eux, dans les environnements serverless. Vous pouvez utiliser ce kit de développement logiciel (SDK) pour gérer les clients SignalR connectés à votre service Azure SignalR dans n’importe quel environnement, comme dans une application console, une fonction Azure ou un serveur web.

Remarque

Pour afficher des guides pour le kit de développement logiciel (SDK) version 1.9.x et antérieure, accédez à Kit de développement logiciel (SDK) Azure SignalR Service Management (hérité). Vous pouvez également lire les Instructions relatives à la migration.

Important

Des chaînes de connexion brutes sont utilisées dans cet article uniquement à des fins de démonstration.

Une chaîne de connexion contient les informations d’autorisation requises pour que votre application accède au service Azure Web PubSub. La clé d’accès à l’intérieur dans la chaîne de connexion est semblable à un mot de passe racine pour votre service. Dans les environnements de production, protégez toujours vos clés d’accès. Utilisez Azure Key Vault pour gérer et permuter vos clés de façon sécurisée, sécuriser votre chaîne de connexion en utilisant Microsoft Entra ID et autoriser l’accès avec Microsoft Entra ID.

Évitez de distribuer des clés d’accès à d’autres utilisateurs, de les coder en dur ou de les enregistrer en texte brut dans un emplacement accessible à d’autres personnes. Effectuez une rotation de vos clés si vous pensez qu’elles ont pu être compromises.

Fonctionnalités

Fonctionnalité Temporaire Persistent
Diffusion ✔️ ✔️
Diffuser à l’exception de certains clients ✔️ ✔️
Envoyer à un client ✔️ ✔️
Envoyer à des clients ✔️ ✔️
Envoyer à un utilisateur ✔️ ✔️
Envoyer à des utilisateurs ✔️ ✔️
Envoyer à un groupe ✔️ ✔️
Envoyer à des groupes ✔️ ✔️
Envoyer à un groupe à l’exception de certains clients ✔️ ✔️
Ajouter un utilisateur à un groupe ✔️ ✔️
Supprimer un utilisateur d’un groupe ✔️ ✔️
Vérifier si un utilisateur est dans un groupe ✔️ ✔️
Configurer plusieurs instances de service SignalR ❌ ✔️
Prise en charge des clients MessagePack depuis v1.21.0 depuis v1.20.0
Nouvelle tentative d’erreur temporaire depuis v1.22.0 ❌

Les fonctionnalités sont fournies uniquement avec une nouvelle API

Fonctionnalité Temporaire Persistent
Vérifier si une connexion existe ✔️ Depuis v1.11
Vérifier si un groupe existe ✔️ Depuis v1.11
Vérifier si un utilisateur existe ✔️ Depuis v1.11
Fermer une connexion cliente ✔️ Depuis v1.11

  • Vous trouverez plus d’informations sur les différents modes ici.

  • Vous trouverez iciun exemple complet du kit de développement logiciel (SDK) de gestion.

Utilisation

Cette section montre comment utiliser le kit de développement logiciel (SDK) de gestion.

Créer Service Manager

Créer votre instance de ServiceManager depuis un ServiceManagerBuilder.

Des chaînes de connexion brutes sont utilisées dans cet article uniquement à des fins de démonstration. Dans les environnements de production, protégez toujours vos clés d’accès. Utilisez Azure Key Vault pour gérer et permuter vos clés de façon sécurisée, sécuriser votre chaîne de connexion en utilisant Microsoft Entra ID et autoriser l’accès avec Microsoft Entra ID.


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

Vous pouvez utiliser ServiceManager pour vérifier l’intégrité du point de terminaison Azure SignalR et créer un contexte de hub de service. La section suivante fournit des détails sur la création d’un contexte de hub de service.

Pour vérifier l’intégrité du point de terminaison Azure SignalR, vous pouvez utiliser la méthode ServiceManager.IsServiceHealthy. Si vous avez plusieurs points de terminaison Azure SignalR, seul le premier est vérifié.

var health = await serviceManager.IsServiceHealthy(cancellationToken);

Créer un contexte Service Hub

Créez votre instance de ServiceHubContext depuis un ServiceManager :

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

Négociation

En mode par défaut, un point de terminaison /<Your Hub Name>/negotiate est exposé pour la négociation par le kit de développement logiciel (SDK) Azure SignalR Service. Les clients SignalR atteignent ce point de terminaison, puis redirigent vers Azure SignalR Service ultérieurement.

En mode serverless, nous vous recommandons d’héberger un point de terminaison de négociation pour traiter la requête de négociation des clients SignalR et de rediriger les clients vers Azure SignalR Service.

Conseil

Pour plus d’informations sur la redirection, consultez le protocole de négociation de SignalR.

Le point de terminaison et le jeton d’accès sont utiles lorsque vous souhaitez rediriger des clients SignalR vers votre Azure SignalR Service.

Vous pouvez utiliser l’instance de ServiceHubContext pour générer l’URL du point de terminaison et le jeton d’accès correspondant, pour que les clients SignalR se connectent à votre Azure SignalR Service.

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

Si on suppose que le point de terminaison de votre hub est http://<Your Host Name>/<Your Hub Name>, alors votre point de terminaison de négociation est http://<Your Host Name>/<Your Hub Name>/negotiate. Une fois que vous hébergez le point de terminaison de négociation, vous pouvez utiliser les clients SignalR pour vous connecter à votre hub comme suit :

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

L’exemple de l’utilisation du kit de développement logiciel (SDK) de gestion pour rediriger les clients SignalR vers Azure SignalR Service est disponible ici.

Envoyer des messages et gérer des groupes

Le ServiceHubContext que nous générons depuis ServiceHubContextBuilder est une classe qui implémente et étend IServiceHubContext. Vous pouvez l’utiliser pour envoyer des messages à vos clients et gérer vos groupes.

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 fortement typé

Un hub fortement typé est un modèle de programmation avec lequel vous pouvez extraire vos méthodes client dans une interface, afin d’éviter les erreurs telles qu’une orthographe incorrecte du nom de la méthode ou la transmission de types de paramètres incorrects.

Supposons que nous avons une méthode client appelée ReceivedMessage avec deux paramètres de chaîne. Sans hubs fortement typés, vous diffusez vers les clients via hubContext.Clients.All.SendAsync("ReceivedMessage", user, message). Avec des hubs fortement typés, vous définissez d’abord une interface comme celle-ci :

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

Vous créez ensuite un contexte de hub fortement typé, qui implémente IHubContext<Hub<T>, T>, T est votre interface de méthode client :

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

Enfin, vous pouvez appeler directement la méthode :

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

À l’exception de la différence d’envoi de messages, vous pouvez négocier ou gérer des groupes avec ServiceHubContext<T> comme avec ServiceHubContext.

Pour plus d’informations sur les hubs fortement typés, consultez la documentation ASP.NET Core ici.

Type de transport

Ce kit de développement logiciel (SDK) peut communiquer avec Azure SignalR Service avec deux types de transport :

  • Temporaire : créez un Azure SignalR Service de requête Http pour chaque message envoyé. Le kit de développement logiciel (SDK) enveloppe simplement l’API REST Azure SignalR Service en mode temporaire. Ceci est utile lorsque vous ne parvenez pas à établir une connexion WebSockets.
  • Persistant : créez d’abord une connexion WebSockets, puis envoyez tous les messages dans cette connexion. Ceci est utile lorsque vous envoyez de grands nombres de messages.

Résumé des comportements de sérialisation des arguments dans les messages

Sérialisation Temporaire Persistent
Bibliothèque JSON par défaut Newtonsoft.Json Identique à ASP.NET Core SignalR :
Newtonsoft.Json pour .NET Standard 2.0 ;
System.Text.Json pour .NET Core App 3.1 et versions ultérieures
Prise en charge des clients MessagePack depuis v1.21.0 depuis v1.20.0

Sérialisation JSON

Dans le kit de développement logiciel (SDK) de gestion, les arguments de méthode envoyés aux clients sont sérialisés en JSON. Nous avons plusieurs méthodes pour personnaliser la sérialisation JSON. Nous vous présentons toutes ces méthodes de la plus recommandée à celle qui l’est le moins.

ServiceManagerOptions.UseJsonObjectSerializer(ObjectSerializer objectSerializer)

La méthode la plus recommandée consiste à utiliser une classe abstraite générale ObjectSerializer, car elle prend en charge différentes bibliothèques de sérialisation JSON comme System.Text.Json et Newtonsoft.Json, et s’applique à tous les types de transport. En règle générale, vous n’avez pas besoin d’implémenter ObjectSerializer vous-même, car de pratiques implémentations JSON pour System.Text.Json et Newtonsoft.Json sont déjà fournies.

  • Lors de l’utilisation de System.Text.Json en tant que bibliothèque de traitement JSON, la base de données intégrée JsonObjectSerializer est utilisée System.Text.Json.JsonSerializer pour la sérialisation/désérialisation. Voici un exemple d’utilisation du nommage CamelCase pour la sérialisation JSON :

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

  • Lors de l’utilisation de Newtonsoft.Json en tant que bibliothèque de traitement JSON, installez d’abord le package Microsoft.Azure.Core.NewtonsoftJson depuis NuGet à l’aide de l’interface CLI .NET :

    dotnet add package Microsoft.Azure.Core.NewtonsoftJson

    Voici un exemple d’utilisation du nommage CamelCase avec NewtonsoftJsonObjectSerializer :

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

  • Lors de l’utilisation d’autres bibliothèques de traitement JSON

    Vous pouvez également implémenter ObjectSerializer vous-même. Les liens suivants peuvent vous aider :

ServiceManagerBuilder.WithNewtonsoftJson(Action<NewtonsoftServiceHubProtocolOptions> configure)

Cette méthode est uniquement destinée aux utilisateurs Newtonsoft.Json. Voici un exemple d’utilisation du nommage CamelCase :

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

Cette méthode s’applique uniquement au type de transport temporaire. Ne pas utiliser.

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

Sérialisation de packs de messages

  1. Vous devez installer le package Microsoft.AspNetCore.SignalR.Protocols.MessagePack.

  2. Pour ajouter un protocole MessagePack en parallèle du protocole JSON par défaut :

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

  3. Pour contrôler entièrement les protocoles hub, vous pouvez utiliser

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

    WithHubProtocols efface d’abord les protocoles existants, puis ajoute les nouveaux. Vous pouvez également utiliser cette méthode pour supprimer le protocole JSON et utiliser MessagePack uniquement.

Pour le mode temporaire, le côté service convertit par défaut la charge utile JSON en charge utile MessagePack. Il s’agit de la méthode héritée pour prendre en charge MessagePack. Toutefois, nous vous recommandons d’ajouter explicitement un protocole hub MessagePack, car la méthode héritée peut ne pas fonctionner comme vous l’attendez.

Nouvelle tentative de requêtes HTTP

Pour le mode temporaire, ce kit de développement logiciel (SDK) offre la possibilité de renvoyer automatiquement les requêtes lorsque des erreurs temporaires se produisent, tant que les requêtes sont idempotentes. Pour activer cette fonctionnalité, vous pouvez utiliser la propriété ServiceManagerOptions.RetryOptions.

En particulier, les types de requêtes suivants sont retentés :

  • Pour les requêtes de message qui envoient des messages aux clients SignalR, le kit de développement logiciel (SDK) retente la requête si le code d’état de la réponse HTTP est supérieur à 500. Lorsque le code de réponse HTTP est égal à 500, cela peut indiquer un délai d’expiration côté service et retenter la requête pourrait entraîner des messages en double.

  • Pour d’autres types de requêtes, comme l’ajout d’une connexion à un groupe, le kit de développement logiciel (SDK) retente la requête sous les conditions suivantes :

    1. Le code d’état de la réponse HTTP se trouve dans la plage 5xx ou la requête a expiré avec un code d’état 408 (Délai d’expiration de la requête).
    2. La requête a expiré avec une durée supérieure à la durée configurée dans ServiceManagerOptions.HttpClientTimeout.

Le kit de développement logiciel (SDK) ne peut faire de nouvelles tentatives que pour les requêtes idempotentes, qui sont des requêtes qui n’ont aucun autre effet si elles sont répétées. Si vos requêtes ne sont pas idempotentes, vous devrez peut-être gérer manuellement les nouvelles tentatives.

Étapes suivantes

Dans cet article, vous apprenez à utiliser SignalR Service dans vos applications. Consultez les articles suivants pour en savoir plus sur SignalR Service.

Éléments internes Azure SignalR Service

Démarrage rapide : créer une salle de conversation en utilisant SignalR Service