Utilisez Azure SignalR Service

Article
12/13/2024

Cet article vous montre comment utiliser le Kit de développement logiciel (SDK) côté serveur d’applications pour vous connecter à SignalR Service lorsque vous utilisez SignalR dans votre serveur d’applications.

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.

Créer une instance de service SignalR Azure

Suivez Démarrage rapide : utiliser un modèle ARM pour déployer Azure SignalR pour créer une instance de service SignalR.

Pour ASP.NET Core SignalR

Installer le SDK

Exécutez la commande pour installer le Kit de développement logiciel (SDK) SignalR Service sur votre projet ASP.NET Core.

dotnet add package Microsoft.Azure.SignalR

Dans votre classe Startup, utilisez le Kit de développement logiciel (SDK) SignalR Service comme extrait de code suivant.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR()
            .AddAzureSignalR();
}

public void Configure(IApplicationBuilder app)
{
    app.UseEndpoints(routes =>
    {
        routes.MapHub<YourHubClass>("/path_for_your_hub");
    });
}

Configurer la chaîne de connexion

Des chaînes de connexion brutes sont utilisées dans cet article à des fins de démonstration uniquement. 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.

Il existe deux approches pour configurer la chaîne de connexion de SignalR Service dans votre application.

Définissez une variable d’environnement nommée Azure:SignalR:ConnectionString ou Azure__SignalR__ConnectionString.
- Dans Azure App Service, placez-le dans les paramètres de l’application.

Transmettez la chaîne de connexion comme paramètre de AddAzureSignalR().

services.AddSignalR()
        .AddAzureSignalR("<replace with your connection string>");

services.AddSignalR()
        .AddAzureSignalR(options => options.ConnectionString = "<replace with your connection string>");

Configurer des options

Il existe quelques options que vous pouvez personnaliser lors de l’utilisation du Kit de développement logiciel (SDK) Azure SignalR Service.

`ConnectionString`

La valeur par défaut est la valeur le Azure:SignalR:ConnectionString connectionString ou appSetting dans le fichier web.config.
Il peut être reconfiguré, mais assurez-vous que la valeur n’est PAS codée en dur.

`InitialHubServerConnectionCount`

La valeur par défaut est 5.
Cette option contrôle le nombre initial de connexions par hub entre le serveur d’applications et Azure SignalR Service. Conservez-la généralement comme valeur par défaut est suffisante. Pendant l’exécution, le Kit de développement logiciel (SDK) peut démarrer de nouvelles connexions de serveur pour l’optimisation des performances ou l’équilibrage de charge. Lorsque vous avez un grand nombre de clients, vous pouvez lui donner un plus grand nombre pour un meilleur débit. Par exemple, si vous avez 100 000 clients au total, le nombre de connexions peut être augmenté à 10 ou 15.

`MaxHubServerConnectionCount`

La valeur par défaut est null.
Cette option contrôle le nombre maximal de connexions autorisées par hub entre le serveur d’applications et Azure SignalR Service. Pendant l’exécution, le Kit de développement logiciel (SDK) peut démarrer de nouvelles connexions de serveur pour l’optimisation des performances ou l’équilibrage de charge. Par défaut, une nouvelle connexion de serveur démarre chaque fois que nécessaire. Lorsque le nombre maximal de connexions de serveur autorisé est configuré, le Kit de développement logiciel (SDK) ne démarre pas de nouvelles connexions lorsque le nombre de connexions serveur atteint la limite.

`ApplicationName`

La valeur par défaut est null.
Cette option peut être utile lorsque vous souhaitez partager la même instance Azure SignalR pour différents serveurs d’applications contenant les mêmes noms de hub. Si ce n’est pas le cas, tous les serveurs d’applications connectés sont considérés comme des instances de la même application.

`ClaimsProvider`

La valeur par défaut est null.
Cette option contrôle les revendications que vous souhaitez associer à la connexion cliente. Elle est utilisée lorsque le Kit de développement logiciel (SDK) service génère un jeton d’accès pour le client dans la requête de négociation du client. Par défaut, toutes les revendications depuis HttpContext.User de la requête négociée sont réservées. Elles sont accessibles à l’adresse Hub.Context.User.
Normalement, vous devez laisser cette option comme c’est le cas. Veillez à comprendre ce qui se passe avant de le personnaliser.

`AccessTokenLifetime`

La valeur par défaut est 1 hour.
Cette option contrôle la durée de vie valide du jeton d’accès, que le Kit de développement logiciel (SDK) service génère pour chaque client. Le jeton d’accès est retourné dans la réponse à la requête de négociation du client.
Quand ServerSentEvent ou LongPolling est utilisé comme transport, la connexion cliente est fermée en raison d’un échec d’authentification après l’expiration du délai d’expiration. Vous pouvez augmenter cette valeur pour éviter la déconnexion du client.

`AccessTokenAlgorithm`

La valeur par défaut est HS256
Cette option offre le choix de SecurityAlgorithms au moment où vous générez un jeton d’accès. Désormais, les valeurs facultatives prises en charge sont HS256 et HS512. Notez que HS512 est plus sécurisé, mais que le jeton généré est comparativement plus long que celui utilisant HS256.

`ServerStickyMode`

La valeur par défaut est Disabled.
Cette option spécifie le mode de collage du serveur. Lorsque le client est routé vers le serveur avec lequel il négocie d’abord, nous l’appelons collage du serveur.
Dans les scénarios distribués, plusieurs serveurs d’applications peuvent être connectés à une instance Azure SignalR. Comme l’expliquent les connexions clientes, le client négocie d’abord avec le serveur d’applications, puis redirige vers Azure SignalR pour établir la connexion persistante. Azure SignalR trouve ensuite un serveur d’applications pour servir le client, comme l’expliquent les données de transport entre le client et le serveur.
- Quand Disabled, le client est acheminé vers un serveur d’applications aléatoire. En général, les serveurs d’applications ont des connexions client équilibrées avec ce mode. Si vos scénarios sont diffusés ou envoyés par groupe, utilisez cette option par défaut.
- Quand Preferred, Azure SignalR tente de trouver le serveur d’applications avec lequel le client négocie d’abord de manière qu’aucun autre coût ou routage global n’est nécessaire. Celui-ci peut être utile lorsque votre scénario est envoyé à la connexion*. L’envoi à la connexion peut avoir de meilleures performances et une latence inférieure lorsque l’expéditeur et le récepteur sont acheminés vers le même serveur d’applications.
- Quand Required, Azure SignalR tente toujours de trouver le serveur d’applications avec lequel le client négocie d’abord. Cette option peut être utile quand un contexte client est récupéré à partir de l’étape negotiate et stocké en mémoire, puis à utiliser à l’intérieur des Hub. Toutefois, cette option peut présenter des inconvénients en matière de performances, car elle exige qu’Azure SignalR prenne d’autres efforts pour trouver ce serveur d’applications particulier globalement et pour maintenir le routage global des trafics entre le client et le serveur.

`GracefulShutdown`

`GracefulShutdown.Mode`

La valeur par défaut est Off
Cette option spécifie le comportement une fois que le serveur d’applications reçoit un SIGINT (CTRL + C).
Lorsqu’il est défini sur WaitForClientsClose, au lieu d’arrêter immédiatement le serveur, nous l’supprimons du service Azure SignalR pour empêcher les nouvelles connexions clientes d’être affectées à ce serveur.
Lorsque la valeur est définie sur MigrateClients, en outre, nous essayons de migrer des connexions clientes vers un autre serveur valide. La migration est déclenchée uniquement après la remise d’un message.
- OnConnected et OnDisconnected sont déclenchés lorsque les connexions doivent être migrées dedans ou dehors.
- IConnectionMigrationFeature peut vous aider à identifier si la connexion est migrée dedans ou dehors.
- Consultez nos exemples de codes d’utilisation des détails.

`GracefulShutdown.Timeout`

La valeur par défaut est 30 seconds
Cette option spécifie la durée la plus longue d’attente pour que les clients soient fermés/migrés.

`ServiceScaleTimeout`

La valeur par défaut est 5 minutes
Cette option spécifie le temps le plus long en attente des points de terminaison de service de mise à l’échelle dynamique, qui affectent au minimum les clients en ligne. Normalement, la mise à l’échelle dynamique entre un serveur d’applications unique et un point de terminaison de service peut être terminée en secondes, tout en considérant si vous avez plusieurs serveurs d’applications et plusieurs points de terminaison de service avec gigue réseau et souhaitez garantir la stabilité du client, vous pouvez configurer cette valeur en conséquence.

`MaxPollIntervalInSeconds`

La valeur par défaut est 5
Cette option définit l’intervalle maximal d’interrogation autorisé pour les connexions LongPolling dans Azure SignalR Service. Si la requête de sondage suivante ne se trouve pas dans MaxPollIntervalInSeconds, Azure SignalR Service nettoie la connexion cliente.
La valeur est limitée à [1, 300].

`TransportTypeDetector`

Valeur par défaut : tous les transports sont activés.
Cette option définit une fonction pour personnaliser les transports que les clients peuvent utiliser pour envoyer des requêtes HTTP.
Utilisez ces options au lieu de HttpConnectionDispatcherOptions.Transports pour configurer les transports.

`AllowStatefulReconnects`

La valeur par défaut est null
Cette option active ou désactive les reconnexions avec état pour tous les hubs.
En cas de valeur null, le Kit de développement logiciel (SDK) lit les paramètres de hub.
En cas de valeur true, Azure SignalR Service active les reconnexions avec état dans tous les hubs déclarés. Et les clients doivent activer les reconnexions avec état du côté client.
En cas de valeur false, Azure SignalR Service désactive les reconnexions avec état dans tous les hubs déclarés.

Exemple

Vous pouvez configurer les options ci-dessus comme l’exemple de code suivant.

services.AddSignalR()
        .AddAzureSignalR(options =>
            {
                options.InitialHubServerConnectionCount = 10;
                options.AccessTokenLifetime = TimeSpan.FromDays(1);
                options.ClaimsProvider = context => context.User.Claims;

                options.GracefulShutdown.Mode = GracefulShutdownMode.WaitForClientsClose;
                options.GracefulShutdown.Timeout = TimeSpan.FromSeconds(10);
                options.TransportTypeDetector = httpContext => AspNetCore.Http.Connections.HttpTransportType.WebSockets | AspNetCore.Http.Connections.HttpTransportType.LongPolling;
            });

Pour l’ASP.NET SignalR hérité

Remarque

S’il s’agit de votre première tentative de SignalR, nous vous recommandons d’utiliser le ASP.NET Core SignalR, il est plus simple, plus fiable et plus facile à utiliser.

Installer le SDK

Installez le Kit de développement logiciel (SDK) SignalR Service sur votre projet ASP.NET avec la Console Gestionnaire de package :

Install-Package Microsoft.Azure.SignalR.AspNet

Dans votre classe Startup, utilisez le Kit de développement logiciel (SDK) SignalR Service comme extrait de code suivant, remplacez MapSignalR() par MapAzureSignalR({your_applicationName}). Remplacez {YourApplicationName} par le nom de votre application, il s’agit du nom unique pour distinguer cette application par vos autres applications. Vous pouvez utiliser la valeur this.GetType().FullName.

public void Configuration(IAppBuilder app)
{
    app.MapAzureSignalR(this.GetType().FullName);
}

Configurer la chaîne de connexion

Définissez la chaîne de connexion dans le fichier web.config, à la section connectionStrings :

<configuration>
    <connectionStrings>
        <add name="Azure:SignalR:ConnectionString" connectionString="Endpoint=...;AccessKey=..."/>
    </connectionStrings>
    ...
</configuration>

Configurer des options

Il existe quelques options que vous pouvez personnaliser lors de l’utilisation du Kit de développement logiciel (SDK) Azure SignalR Service.

`ConnectionString`

La valeur par défaut est la valeur le Azure:SignalR:ConnectionString connectionString ou appSetting dans le fichier web.config.
Il peut être reconfiguré, mais assurez-vous que la valeur n’est PAS codée en dur.

`InitialHubServerConnectionCount`

La valeur par défaut est 5.
Cette option contrôle le nombre initial de connexions par hub entre le serveur d’applications et Azure SignalR Service. Conservez-la généralement comme valeur par défaut est suffisante. Pendant l’exécution, le Kit de développement logiciel (SDK) peut démarrer de nouvelles connexions de serveur pour l’optimisation des performances ou l’équilibrage de charge. Lorsque vous avez un grand nombre de clients, vous pouvez lui donner un plus grand nombre pour un meilleur débit. Par exemple, si vous avez 100 000 clients au total, le nombre de connexions peut être augmenté à 10 ou 15.

`MaxHubServerConnectionCount`

La valeur par défaut est null.
Cette option contrôle le nombre maximal de connexions autorisées par hub entre le serveur d’applications et Azure SignalR Service. Pendant l’exécution, le Kit de développement logiciel (SDK) peut démarrer de nouvelles connexions de serveur pour l’optimisation des performances ou l’équilibrage de charge. Par défaut, une nouvelle connexion de serveur démarre chaque fois que nécessaire. Lorsque le nombre maximal de connexions de serveur autorisé est configuré, le Kit de développement logiciel (SDK) ne démarre pas de nouvelles connexions lorsque le nombre de connexions serveur atteint la limite.

`ApplicationName`

La valeur par défaut est null.
Cette option peut être utile lorsque vous souhaitez partager la même instance Azure SignalR pour différents serveurs d’applications contenant les mêmes noms de hub. Si ce n’est pas le cas, tous les serveurs d’applications connectés sont considérés comme des instances de la même application.

`ClaimProvider`

La valeur par défaut est null.
Cette option contrôle les revendications que vous souhaitez associer à la connexion cliente. Elle est utilisée lorsque le Kit de développement logiciel (SDK) service génère un jeton d’accès pour le client dans la requête de négociation du client. Par défaut, toutes les revendications depuis IOwinContext.Authentication.User de la requête négociée sont réservées.
Normalement, vous devez laisser cette option comme c’est le cas. Veillez à comprendre ce qui se passe avant de le personnaliser.

`AccessTokenLifetime`

La valeur par défaut est 1 hour.
Cette option contrôle la durée de vie valide du jeton d’accès, que le Kit de développement logiciel (SDK) de service génère pour chaque client. Le jeton d’accès est retourné dans la réponse à la requête de négociation du client.
Quand ServerSentEvent ou LongPolling est utilisé comme transport, la connexion cliente est fermée en raison d’un échec d’authentification après l’expiration du délai d’expiration. Vous pouvez augmenter cette valeur pour éviter la déconnexion du client.

`AccessTokenAlgorithm`

La valeur par défaut est HS256
Cette option offre le choix de SecurityAlgorithms au moment où vous générez un jeton d’accès. Désormais, les valeurs facultatives prises en charge sont HS256 et HS512. Notez que HS512 est plus sécurisé, mais que le jeton généré est comparativement plus long que celui utilisant HS256.

`ServerStickyMode`

La valeur par défaut est Disabled.
Cette option spécifie le mode de collage du serveur. Lorsque le client est routé vers le serveur avec lequel il négocie d’abord, nous l’appelons collage du serveur.
Dans les scénarios distribués, plusieurs serveurs d’applications peuvent être connectés à une instance Azure SignalR. Comme l’expliquent les connexions clientes, le client négocie d’abord avec le serveur d’applications, puis redirige vers Azure SignalR pour établir la connexion persistante. Azure SignalR trouve ensuite un serveur d’applications pour servir le client, comme l’expliquent les données de transport entre le client et le serveur.
- Quand Disabled, le client est acheminé vers un serveur d’applications aléatoire. En général, les serveurs d’applications ont des connexions client équilibrées avec ce mode. Si vos scénarios sont diffusés ou envoyés par groupe, utilisez cette option par défaut.
- Quand Preferred, Azure SignalR tente de trouver le serveur d’applications avec lequel le client négocie d’abord de manière qu’aucun autre coût ou routage global n’est nécessaire. Celui-ci peut être utile lorsque votre scénario est envoyé à la connexion*. L’envoi à la connexion peut avoir de meilleures performances et une latence inférieure lorsque l’expéditeur et le récepteur sont acheminés vers le même serveur d’applications.
- Quand Required, Azure SignalR tente toujours de trouver le serveur d’applications avec lequel le client négocie d’abord. Cette option peut être utile quand un contexte client est récupéré à partir de l’étape negotiate et stocké en mémoire, puis à utiliser à l’intérieur des Hub. Toutefois, cette option peut présenter des inconvénients en matière de performances, car elle exige qu’Azure SignalR prenne d’autres efforts pour trouver ce serveur d’applications particulier globalement et pour maintenir le routage global des trafics entre le client et le serveur.

`MaxPollIntervalInSeconds`

La valeur par défaut est 5
Cette option définit le temps d’inactivité maximal autorisé pour les connexions inactives dans Azure SignalR Service. Dans ASP.NET SignalR, il s’applique au type de transport d’interrogation long ou à la reconnexion. Si la requête /reconnect ou /poll suivante ne se trouve pas dans MaxPollIntervalInSeconds, Azure SignalR Service nettoie la connexion cliente.
La valeur est limitée à [1, 300].

Exemple

Vous pouvez configurer les options ci-dessus comme l’exemple de code suivant.

app.Map("/signalr",subApp => subApp.RunAzureSignalR(this.GetType().FullName, new HubConfiguration(), options =>
{
    options.InitialHubServerConnectionCount = 1;
    options.AccessTokenLifetime = TimeSpan.FromDays(1);
    options.ClaimProvider = context => context.Authentication?.User.Claims;
}));

Effectuer un scale-out du serveur d’applications

Avec Azure SignalR Service, les connexions persistantes sont déchargées à partir du serveur d’applications pour vous concentrer sur l’implémentation de votre logique métier dans les classes hub. Toutefois, vous devez toujours effectuer un scale-out des serveurs d’applications pour obtenir de meilleures performances lors de la gestion des connexions clientes massives. Voici quelques conseils pour effectuer une mise à l’échelle des serveurs d’applications.

Plusieurs serveurs d’applications peuvent se connecter à la même instance Azure SignalR Service.
Si vous souhaitez partager la même instance Azure SignalR pour différentes applications contenant les mêmes noms de hub, définissez-les avec une autre option ApplicationName. Si ce n’est pas le cas, tous les serveurs d’applications connectés sont considérés comme des instances de la même application.
Tant que l’option ApplicationName et le nom de la classe hub sont identiques, les connexions provenant de différents serveurs d’applications sont regroupées dans le même hub.
Chaque connexion cliente est créée uniquement dans un des serveurs d’applications, et les messages de ce client ne sont envoyés qu’à ce même serveur d’applications. Si vous souhaitez accéder aux informations du client globalement (à partir de tous les serveurs d’applications), vous devez utiliser un stockage centralisé pour enregistrer les informations du client à partir de tous les serveurs d’applications.

É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

Partager via

Utilisez Azure SignalR Service

Créer une instance de service SignalR Azure

Pour ASP.NET Core SignalR

Installer le SDK

Configurer la chaîne de connexion

Configurer des options

ConnectionString

InitialHubServerConnectionCount

MaxHubServerConnectionCount

ApplicationName

ClaimsProvider

AccessTokenLifetime

AccessTokenAlgorithm

ServerStickyMode

GracefulShutdown

GracefulShutdown.Mode

GracefulShutdown.Timeout

ServiceScaleTimeout

MaxPollIntervalInSeconds

TransportTypeDetector

AllowStatefulReconnects

Exemple

Pour l’ASP.NET SignalR hérité

Installer le SDK

Configurer la chaîne de connexion

Configurer des options

ConnectionString

InitialHubServerConnectionCount

MaxHubServerConnectionCount

ApplicationName

ClaimProvider

AccessTokenLifetime

AccessTokenAlgorithm

ServerStickyMode

MaxPollIntervalInSeconds

Exemple

Effectuer un scale-out du serveur d’applications

Étapes suivantes

Commentaires

Ressources supplémentaires

`ConnectionString`

`InitialHubServerConnectionCount`

`MaxHubServerConnectionCount`

`ApplicationName`

`ClaimsProvider`

`AccessTokenLifetime`

`AccessTokenAlgorithm`

`ServerStickyMode`

`GracefulShutdown`

`GracefulShutdown.Mode`

`GracefulShutdown.Timeout`

`ServiceScaleTimeout`

`MaxPollIntervalInSeconds`

`TransportTypeDetector`

`AllowStatefulReconnects`

`ConnectionString`

`InitialHubServerConnectionCount`

`MaxHubServerConnectionCount`

`ApplicationName`

`ClaimProvider`

`AccessTokenLifetime`

`AccessTokenAlgorithm`

`ServerStickyMode`

`MaxPollIntervalInSeconds`