Bibliothèque de client Azure Web PubSub pour .NET

Le Kit de développement logiciel (SDK) côté client vise à accélérer le flux de travail du développeur ; plus précisément,

• simplifie la gestion des connexions clientes
• simplifie l’envoi de messages entre les clients
• réessaie automatiquement après des coupures involontaires de la connexion du client
• assure une livraison fiable des messages, en nombre et dans l’ordre, après le rétablissement d'une connexion

Comme illustré dans le diagramme, vos clients établissent des connexions WebSocket avec votre ressource Web PubSub.

Mise en route

Installer le package

Installez la bibliothèque cliente à partir de NuGet :

dotnet add package Azure.Messaging.WebPubSub.Client --prerelease

Prerequisites

• Un abonnement Azure
• Instance Web PubSub existante

Authentifier le client

Un client utilise un Client Access URL pour se connecter et s'authentifier au service. Client Access URL suit le modèle de wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Il existe plusieurs façons d’obtenir un Client Access URL. En guise de démarrage rapide, vous pouvez copier et coller à partir du portail Azure et, pour la production, vous avez généralement besoin d’un serveur de négociation pour générer Client Access URL. Consultez les détails.

Utiliser l’URL d’accès client à partir du portail Azure

En guise de démarrage rapide, vous pouvez accéder au portail Azure et copier l’URL d’accès client à partir du panneau Clés .

Comme illustré dans le diagramme, le client reçoit l’autorisation d’envoyer des messages à des groupes spécifiques et de joindre des groupes spécifiques. En savoir plus sur l’autorisation du client, consultez autorisations.

var client = new WebPubSubClient(new Uri("<client-access-uri>"));

Utiliser le serveur de négociation pour générer Client Access URL

En production, un client récupère généralement depuis un serveur de négociation le Client Access URL. Le serveur contient le connection string et génère le Client Access URL via WebPubSubServiceClient. À titre d'exemple, l'extrait de code montre comment générer simplement le Client Access URL dans un seul processus.

var client = new WebPubSubClient(new WebPubSubClientCredential(token =>
{
    // In common practice, you will have a negotiation server for generating token. Client should fetch token from it.
    return FetchClientAccessTokenFromServerAsync(token);
}));

public async ValueTask<Uri> FetchClientAccessTokenFromServerAsync(CancellationToken token)
{
    var serviceClient = new WebPubSubServiceClient("<< Connection String >>", "hub");
    return await serviceClient.GetClientAccessUriAsync();
}

Fonctionnalités permettant de différencier WebPubSubClient et WebPubSubServiceClient.

Exemples

Consommer des messages depuis le serveur et ses groupes

Un client peut ajouter des fonctions de rappel pour consommer des messages provenant du serveur et des groupes. Notez que les clients peuvent uniquement recevoir des messages de groupe auxquels ils se sont inscrits.

client.ServerMessageReceived += eventArgs =>
{
    Console.WriteLine($"Receive message: {eventArgs.Message.Data}");
    return Task.CompletedTask;
};

client.GroupMessageReceived += eventArgs =>
{
    Console.WriteLine($"Receive group message from {eventArgs.Message.Group}: {eventArgs.Message.Data}");
    return Task.CompletedTask;
};

Ajouter des rappels pour les événements connected, disconnected et stopped

Lorsqu’une connexion cliente est connectée au service, l’événement connected est déclenché une fois qu’il a reçu le message connecté du service.

client.Connected += eventArgs =>
{
    Console.WriteLine($"Connection {eventArgs.ConnectionId} is connected");
    return Task.CompletedTask;
};

Lorsqu’une connexion cliente est déconnectée et ne parvient pas à récupérer, l’événement disconnected est déclenché.

client.Disconnected += eventArgs =>
{
    Console.WriteLine($"Connection is disconnected");
    return Task.CompletedTask;
};

Lorsqu’un client est arrêté, ce qui signifie que la connexion cliente est déconnectée et que le client cesse de tenter de se reconnecter, l’événement stopped est déclenché. Cela se produit généralement après que client.StopAsync() est appelé ou que AutoReconnect est désactivé. Si vous souhaitez redémarrer le client, vous pouvez appeler client.StartAsync() dans l'événement Stopped.

client.Stopped += eventArgs =>
{
    Console.WriteLine($"Client is stopped");
    return Task.CompletedTask;
};

Réintégrer automatiquement les groupes et gérer les échecs de réintégration

Lorsqu’une connexion cliente a été supprimée et ne parvient pas à récupérer, tous les contextes de groupe sont nettoyés côté service. Cela signifie que lorsque le client se reconnecte, il doit rejoindre des groupes. Par défaut, le client a activé les options AutoRejoinGroups. Toutefois, cette fonctionnalité présente des limitations. Le client peut uniquement rejoindre des groupes auxquels il a été initialement ajouté par le client plutôt que par le serveur. Et les opérations de jonction de groupe peuvent échouer pour diverses raisons, par exemple, le client n’a pas l’autorisation de rejoindre des groupes. Dans ce cas, les utilisateurs doivent ajouter un rappel pour gérer ces défaillances.

client.RejoinGroupFailed += eventArgs =>
{
    Console.WriteLine($"Restore group failed");
    return Task.CompletedTask;
};

Opération et nouvelle tentative

Par défaut, l'opération telle que client.JoinGroupAsync(), client.LeaveGroupAsync(), client.SendToGroupAsync(), client.SendEventAsync() a trois tentatives. Vous pouvez utiliser WebPubSubClientOptions.MessageRetryOptions pour modifier. Si toutes les nouvelles tentatives ont échoué, une erreur est générée. Vous pouvez continuer à réessayer en passant le même ackId que lors des tentatives précédentes, permettant ainsi au service de dédupliquer l'opération avec le même ackId.

// Send message to group "testGroup"
try
{
    await client.JoinGroupAsync("testGroup");
}
catch (SendMessageFailedException ex)
{
    if (ex.AckId != null)
    {
        await client.JoinGroupAsync("testGroup", ackId: ex.AckId);
    }
}

Résolution des problèmes

Activer les journaux

Vous pouvez définir la variable d’environnement suivante pour afficher les journaux de débogage quand vous utilisez cette bibliothèque.

export AZURE_LOG_LEVEL=verbose

Pour obtenir des instructions plus détaillées sur l’activation des journaux, consultez les documents relatifs au package @azure/logger.

Trace dynamique

Utilisez l’outil Live Trace à partir du portail Azure pour inspecter le trafic des messages en direct via votre ressource Web PubSub.