Share via

Azure WebJobs SignalR Service bibliothèque de client pour .NET - version 1.11.2

  • Article

Cette extension fournit des fonctionnalités permettant d’accéder à Azure SignalR Service à partir d’une fonction Azure.

Prise en main

Installer le package

Installez le client SignalR Service avec NuGet :

dotnet add package Microsoft.Azure.WebJobs.Extensions.SignalRService

Prérequis

  • Abonnement Azure : Pour utiliser les services Azure, notamment Azure SignalR Service, vous avez besoin d’un abonnement. Si vous n’avez pas de compte Azure existant, vous pouvez vous inscrire à un essai gratuit ou utiliser les avantages de votre abonnement Visual Studio lorsque vous créez un compte.

  • Ressource Azure SignalR : Pour utiliser SignalR Service bibliothèque de client, vous avez également besoin d’une ressource Azure SignalR. Si vous n’êtes pas familiarisé avec la création de ressources Azure, vous pouvez suivre le guide pas à pas pour créer une ressource SignalR à l’aide du Portail Azure. Vous y trouverez également des instructions détaillées sur l’utilisation des modèles Azure CLI, Azure PowerShell ou Azure Resource Manager (ARM) pour créer une ressource SignalR.

    Pour créer rapidement la ressource SignalR nécessaire dans Azure et recevoir une chaîne de connexion, vous pouvez déployer notre exemple de modèle en cliquant sur :

    Déployer sur Azure

    Une fois l’instance déployée, ouvrez-la dans le portail, puis recherchez sa page Paramètres. Remplacez le paramètre Mode de service par Serverless.

    paramètre de mode SignalR Service

Authentifier le client

Pour que SignalR Service client accède à la ressource SignalR, il doit comprendre comment s’authentifier auprès de celle-ci. Le moyen le plus simple consiste à utiliser une chaîne de connexion qui se trouve dans le portail Azure ou à l’aide de l’extrait de code ci-dessous Azure PowerShellAzure CLI / .

Extrait de code Azure CLI :

az signalr key list -n <your-resource-name> -g <your-resource-group-name> --query primaryKey -o tsv

Azure PowerShell extrait de code :

Get-AzSignalRKey -ResourceGroupName <your-resource-name> -Name <your-resource-name>

La ConnectionStringSetting propriété des liaisons SignalR (y compris SignalRAttribute, SignalRConnectionInfoAttribute, SignalRTriggerAttribute etc.) est utilisée pour spécifier la propriété de configuration qui stocke la chaîne de connexion. Si elle n’est pas spécifiée, la propriété AzureSignalRConnectionString doit contenir la chaîne de connexion.

Pour le développement local, utilisez le local.settings.json fichier pour stocker la chaîne de connexion :

{
  "Values": {
    "<connection_name>": "<connection-string>"
  }
}

Lors du déploiement, utilisez les paramètres de l’application pour définir la chaîne de connexion.

Concepts clés

Client SignalR Service et Client SignalR

Client SignalR Service : il s’agit de cette bibliothèque. Il fournit des fonctionnalités de serveur SignalR dans un style serverless.

Client SignalR : concept opposé de serveur SignalR. Pour plus d’informations, consultez ASP.NET Core clients SignalR.

Liaison d’entrée d’informations de connexion SignalR

SignalRConnectionInfoLa liaison d’entrée facilite la génération du jeton requis pour que les clients SignalR lancent une connexion à Azure SignalR Service.

Suivez le tutoriel sur la liaison d’entrée d’informations de connexion Azure SignalR pour en savoir plus sur la liaison d’entrée d’informations de connexion SignalR.

Liaison de sortie SignalR

SignalR la liaison de sortie permet :

  • envoyer des messages à toutes les connexions, à une connexion, à un utilisateur, à un groupe.
  • ajouter/supprimer des connexions/utilisateurs dans un groupe.

Suivez la liaison de sortie Azure SignalR pour en savoir plus sur la liaison de sortie SignalR.

Déclencheur SignalR

Le déclencheur SignalR permet d’exécuter une fonction lorsqu’un message est envoyé à Azure SignalR Service.

Suivez le déclencheur Azure SignalR pour en savoir plus sur le déclencheur SignalR.

Scénarios pris en charge

  • Négocier pour un client SignalR.
  • Gérez un groupe comme ajouter/supprimer un seul utilisateur/connexion dans un groupe.
  • Envoyer des messages à un seul utilisateur/connexion, à un groupe, à tous les utilisateurs/connexions.
  • Utilisez plusieurs instances de Azure SignalR Service pour la résilience et la récupération d’urgence dans Azure Functions. Pour plus d’informations, consultez Prise en charge de plusieurs instances Azure SignalR Service dans Azure Functions.

Exemples

Négociation pour le client SignalR

Pour qu’un client se connecte à SignalR, il doit obtenir l’URL du hub client SignalR et un jeton d’accès. Nous appelons le processus de « négociation ».

[FunctionName("Negotiate")]
public static SignalRConnectionInfo Negotiate(
    [HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequest req,
    [SignalRConnectionInfo(HubName = "<hub_name>", UserId = "<user_id>")] SignalRConnectionInfo connectionInfo)
{
    return connectionInfo;
}

Diffuser des messages individuels

Pour diffuser des messages à toutes les connexions d’un hub à partir d’un appel de fonction Azure unique, vous pouvez appliquer l’attribut SignalR à la valeur de retour de la fonction. La valeur de retour doit être de type SignalRMessage.

[FunctionName("sendOneMessageWithReturnValueBinding")]
[return: SignalR(HubName = "<hub_name>")]
public static SignalRMessage SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req)
{
    return new SignalRMessage
    {
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    };
}

Vous pouvez également utiliser un out paramètre de type SignalRMessage.

[FunctionName("messages")]
public static void SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req, [SignalR(HubName = "<hub_name>")] out SignalRMessage message)
{
    message = new SignalRMessage
    {
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    };
}

Diffuser plusieurs messages

Pour diffuser plusieurs messages à toutes les connexions d’un hub à partir d’un appel de fonction Azure unique, vous pouvez appliquer l’attribut SignalR au IAsyncCollector<SignalRMessage> paramètre .

[FunctionName("messages")]
public static Task SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req,
    [SignalR(HubName = "<hub_name>")] IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
    new SignalRMessage
    {
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    });
}

Envoi de messages à une connexion, un utilisateur ou un groupe

Pour envoyer des messages à une connexion, un utilisateur ou un groupe, la fonction est similaire à la diffusion des messages ci-dessus, sauf que vous spécifiez ConnectionIdou UserIdGroupName dans les propriétés de SignalRMessage.

Voici un exemple d’envoi de messages à un utilisateur à l’aide de la liaison de valeur de retour.

[FunctionName("messages")]
[return: SignalR(HubName = "<hub_name>")]
public static SignalRMessage SendMessageToUser(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req)
{
    return new SignalRMessage
    {
        UserId = "<user_id>",
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    };
}

Déclencheur de connexion client SignalR

Pour déclencher une fonction lorsqu’un client SignalR est connecté ou déconnecté, vous pouvez appliquer l’attribut SignalRTrigger au InvocationContext paramètre .

Voici un exemple de journalisation de l’ID de connexion lorsqu’un client SignalR est connecté. Vérifiez que le deuxième paramètre du SignalRTrigger constructeur est connections, qui signifie que la catégorie du déclencheur est connexions. Le troisième

[FunctionName("SignalRTest")]
public static void Run([SignalRTrigger("<hubName>", "connections", "connected")] InvocationContext invocationContext, ILogger logger)
{
    logger.LogInformation($"{invocationContext.ConnectionId} was connected.");
}

Déclencheur de message client SignalR

Pour déclencher une fonction lorsqu’un client SignalR envoie un message, vous pouvez appliquer l’attribut SignalRTrigger au InvocationContext paramètre , appliquer l’attribut SignalRParameter à chaque paramètre dont le nom correspond au nom du paramètre dans votre message.

Voici un exemple de journalisation du contenu du message lorsqu’un client SignalR envoie un message avec la cible « SendMessage ».

[FunctionName("SignalRTest")]
public static void Run([SignalRTrigger("SignalRTest", "messages", "SendMessage")] InvocationContext invocationContext, [SignalRParameter] string message, ILogger logger)
{
    logger.LogInformation($"Receive {message} from {invocationContext.ConnectionId}.");
}

Dépannage

Étapes suivantes

Lire l’introduction à Azure Functions ou à la création d’un guide de fonction Azure

Contribution

Consultez notre CONTRIBUTING.md pour plus d’informations sur la création, le test et la contribution à cette bibliothèque.

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez cla.microsoft.com.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions