Bibliothèque de client intergiciel du service Azure Web PubSub pour .NET - version 1.2.0

  • Article

Le service Azure Web PubSub est un service qui vous permet de créer des applications web de messagerie en temps réel à l’aide de WebSockets et du modèle publication-abonnement. Toute plateforme prenant en charge les API WebSocket peut se connecter facilement au service, par exemple des pages web, des applications mobiles, des appareils de périphérie, etc. Le service gère les connexions WebSocket pour vous et autorise jusqu’à 100 000 connexions simultanées . Il fournit des API puissantes pour vous permettre de gérer ces clients et de remettre des messages en temps réel.

Tout scénario qui nécessite une messagerie de type publication/abonnement en temps réel entre un serveur et des clients ou entre des clients peut avoir recours au service Azure Web PubSub. Les fonctionnalités en temps réel traditionnelles qui demandent souvent d’interroger un serveur ou d’envoyer des requêtes HTTP peuvent aussi utiliser le service Azure Web PubSub.

Cette bibliothèque peut servir à effectuer les actions suivantes. Les détails des termes utilisés ici sont décrits dans la section Concepts clés.

  • Analyser les requêtes amont sous CloudNative CloudEvents
  • Ajouter des options de validation pour amont demande
  • API permettant d’ajouter des fonctionnalités définies par l’utilisateur pour gérer différents événements amont

| Code sourcePaquet | Documentation de référence sur les | API | Documentation produitÉchantillons |

Prise en main

Installer le package

Installer la bibliothèque cliente à partir de NuGet

dotnet add package Microsoft.Azure.WebPubSub.AspNetCore

Prérequis

Authentifier le client

Pour interagir avec le service, vous devez fournir au service Web PubSub des informations d’identification valides. Pour que cela soit possible, vous avez besoin de la chaîne de connexion ou d’une clé, à laquelle vous pouvez accéder dans le portail Azure. En outre, si vous souhaitez appeler l’API REST du service, vous pouvez appeler AddWebPubSubServiceClient<THub>() où THub est implémenté l’utilisateur WebPubSubHub à l’écoute des événements importants.

Configurer les options du service Web PubSub

public void ConfigureServices(IServiceCollection services)
{
    services.AddWebPubSub(o =>
    {
        o.ServiceEndpoint = new("<connection-string>");
    }).AddWebPubSubServiceClient<SampleHub>();
}

Mapper WebPubSubHub au routage du point de terminaison

public void Configure(IApplicationBuilder app)
{
    app.UseEndpoints(endpoint =>
    {
        endpoint.MapWebPubSubHub<SampleHub>("/eventhandler");
    });
}

Concepts clés

Pour plus d’informations sur les concepts généraux de Web PubSub dans Azure Web PubSub

WebPubSubHub

WebPubSubHub est une classe abstraite permettant aux utilisateurs d’implémenter les événements du service Web PubSub abonnés. Une fois que l’utilisateur a inscrit le gestionnaire d’événements côté service, ces événements sont transférés du service au serveur. Et WebPubSubHub fournit 4 méthodes de mappage aux événements de service pour permettre aux utilisateurs de gérer ces événements, par exemple, la gestion des clients, les validations ou l’utilisation de Azure.Messaging.WebPubSub pour diffuser les messages. Pour plus d’informations, consultez les exemples ci-dessous.

REMARQUE

Parmi les 4 méthodes, OnConnectAsync() et OnMessageReceivedAsync() sont des événements bloquants que le service respectera les retours du serveur. Outre la réponse correcte mappée, le serveur peut lever des exceptions chaque fois que la demande est contre la logique côté serveur. Et UnauthorizedAccessException seront convertis 401Unauthorized en et rest seront convertis en 500InternalServerError avec le message d’exception pour retourner le service. Ensuite, le service supprime la connexion cliente actuelle.

Exemples

Gérer amont Connect événement

private sealed class SampleHub : WebPubSubHub
{
    internal WebPubSubServiceClient<SampleHub> _serviceClient;

    // Need to ensure service client is injected by call `AddServiceHub<SampleHub>` in ConfigureServices.
    public SampleHub(WebPubSubServiceClient<SampleHub> serviceClient)
    {
        _serviceClient = serviceClient;
    }

    public override ValueTask<ConnectEventResponse> OnConnectAsync(ConnectEventRequest request, CancellationToken cancellationToken)
    {
        var response = new ConnectEventResponse
        {
            UserId = request.ConnectionContext.UserId
        };
        return new ValueTask<ConnectEventResponse>(response);
    }
}

Résolution des problèmes

Configuration de la journalisation de la console

Vous pouvez également activer la journalisation de la console facilement si vous souhaitez approfondir les requêtes que vous formulez sur le service.

Étapes suivantes

Consultez le répertoire Exemples pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque.

Contribution

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, consultez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

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