Biblioteca cliente del servicio Azure Web PubSub para .NET: versión 1.3.0

  • Artículo

Azure Web PubSub es un servicio administrado de Azure que ayuda a los desarrolladores a compilar fácilmente aplicaciones web con características en tiempo real y patrón de publicación-suscripción. Cualquier escenario que requiera mensajería de publicación y suscripción en tiempo real entre el servidor y los clientes o entre clientes, puede usar el servicio Azure Web PubSub. Las características tradicionales en tiempo real que a menudo requieren tener que sondear desde el servidor o enviar solicitudes HTTP, también pueden usar el servicio Azure Web PubSub.

Puede usar esta biblioteca en el lado del servidor de aplicaciones para administrar las conexiones de cliente de WebSocket, como se muestra en el diagrama siguiente:

desbordamiento

Use esta biblioteca para:

  • Enviar mensajes a centros y grupos.
  • Enviar mensajes a determinados usuarios y conexiones.
  • Organizar usuarios y conexiones en grupos.
  • Cerrar conexiones.
  • Conceder, revocar y comprobar permisos para una conexión existente.

(Los detalles sobre los términos usados aquí se describen en la sección Conceptos clave):

Código fuente | Paquete | Documentación de referencia de API | Documentación del producto | Ejemplos

Introducción

Instalar el paquete

Instale la biblioteca cliente desde NuGet:

dotnet add package Azure.Messaging.WebPubSub

Requisitos previos

Crear y autenticar una WebPubSubServiceClient

Para interactuar con el servicio, tiene que crear una instancia de la clase WebPubSubServiceClient. Para que esto sea posible, necesitará la cadena de conexión o una clave, a las que puede acceder en Azure Portal.

// Create a WebPubSubServiceClient that will authenticate using a key credential.
var serviceClient = new WebPubSubServiceClient(new Uri(endpoint), "some_hub", new AzureKeyCredential(key));

Conceptos clave

Conexión

Una conexión, también conocida como "cliente" o "conexión de cliente", representa una conexión WebSocket individual conectada al servicio Web PubSub. Cuando se conecta correctamente, el servicio Web PubSub asigna un identificador de conexión único a esta conexión.

Hub

El centro de conectividad es un concepto lógico para un conjunto de conexiones de clientes. Normalmente se usa un centro de conectividad para una finalidad, por ejemplo, un centro de conectividad de chats o uno de notificaciones. Cuando se establece una conexión de cliente, esta se realiza con un centro de conectividad y, durante su vigencia, pertenece a dicho centro. Diferentes aplicaciones pueden compartir un servicio de Azure Web PubSub mediante el uso de nombres de centros de conectividad diferentes.

Grupo

El grupo es un subconjunto de conexiones al centro de conectividad. Puede agregar una conexión de cliente a un grupo o quitarla de este cuando quiera. Por ejemplo, cuando un cliente se une a una sala de chat o sale de ella, dicha sala puede considerarse un grupo. Un cliente puede unirse a varios grupos, y un grupo puede contener varios clientes.

Usuario

Las conexiones a Web PubSub pueden pertenecer a un usuario. Un usuario puede tener varias conexiones, por ejemplo, cuando está conectado a través de varios dispositivos o distintas pestañas del explorador.

Message

Cuando un cliente está conectado, puede enviar mensajes a la aplicación de nivel superior o recibir mensajes de esta, mediante la conexión WebSocket.

Ejemplos

Generación del URI completo que contiene el token de acceso para la conexión que se va a usar al conectar Azure Web PubSub

// Generate client access URI for userA
serviceClient.GetClientAccessUri(userId: "userA");
// Generate client access URI with initial permissions
serviceClient.GetClientAccessUri(roles: new string[] { "webpubsub.joinLeaveGroup.group1", "webpubsub.sendToGroup.group1" });
// Generate client access URI with initial groups to join when the connection connects
serviceClient.GetClientAccessUri(groups: new string[] { "group1", "group2" });

Envío de mensajes a las conexiones

Difusión de un mensaje de texto a todos los clientes

var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");

serviceClient.SendToAll("Hello World!");

Difusión de un mensaje JSON a todos los clientes

var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");

serviceClient.SendToAll(RequestContent.Create(
        new
        {
            Foo = "Hello World!",
            Bar = 42
        }),
        ContentType.ApplicationJson);

Difusión de un mensaje binario a todos los clientes

var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");

Stream stream = BinaryData.FromString("Hello World!").ToStream();
serviceClient.SendToAll(RequestContent.Create(stream), ContentType.ApplicationOctetStream);

Difusión de mensajes a clientes mediante filtro

Azure Web PubSub admite la sintaxis de filtro de OData para filtrar las conexiones a las que enviar mensajes.

Para más información sobre la filter sintaxis, consulte Sintaxis de filtro de OData para Azure Web PubSub.

var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");

// Use filter to send text message to anonymous connections
serviceClient.SendToAll(
        RequestContent.Create("Hello World!"),
        ContentType.TextPlain,
        filter: ClientConnectionFilter.Create($"userId eq {null}"));

// Use filter to send JSON message to connections in groupA but not in groupB
var group1 = "GroupA";
var group2 = "GroupB";
serviceClient.SendToAll(RequestContent.Create(
        new
        {
            Foo = "Hello World!",
            Bar = 42
        }),
        ContentType.ApplicationJson,
        filter: ClientConnectionFilter.Create($"{group1} in groups and not({group2} in groups)"));

Administración de conexiones

Agregue conexiones para algún usuario a algún grupo:

client.AddUserToGroup("some_group", "some_user");

// Avoid sending messages to users who do not exist.
if (client.UserExists("some_user").Value)
{
    client.SendToUser("some_user", "Hi, I am glad you exist!");
}

client.RemoveUserFromGroup("some_group", "some_user");

Eliminación de la conexión de todos los grupos

var client = new WebPubSubServiceClient(connectionString, "some_hub");
client.RemoveConnectionFromAllGroups("some_connection");

Solución de problemas

Configuración del registro de la consola

También puede habilitar el registro de la consola fácilmente si desea profundizar más en las solicitudes que realiza en el servicio.

Pasos siguientes

Eche un vistazo al directorio de ejemplos para obtener ejemplos detallados sobre cómo usar esta biblioteca.

También puede encontrar más ejemplos aquí.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más información, visite https://cla.microsoft.com..

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones