Biblioteca cliente de Azure Web PubSub para .NET

El SDK del lado cliente tiene como objetivo acelerar el flujo de trabajo del desarrollador; más concretamente,

• simplifica la administración de conexiones de cliente
• simplifica el envío de mensajes entre clientes
• Reintenta automáticamente después de caídas no deseadas de la conexión del cliente.
• entrega los mensajes de forma confiable en cantidad y orden después de recuperarse de caídas de conexión

Como se muestra en el diagrama, los clientes establecen conexiones de WebSocket con el recurso de Web PubSub.

Cómo empezar

Instalar el paquete

Instale la biblioteca cliente desde NuGet:

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

Prerrequisitos

• Una suscripción de Azure
• Una instancia existente de Web PubSub

Autenticar el cliente

Un cliente usa Client Access URL para conectarse y autenticarse con el servicio. Client Access URL sigue el patrón como wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Hay varias maneras de obtener Client Access URL. Como inicio rápido, puede copiar y pegar desde Azure Portal y, para la producción, normalmente necesitará un servidor de negociación para generar Client Access URL. Consulte los detalles.

Utilizar la URL de acceso de cliente desde el portal de Azure

Como inicio rápido, vaya al portal de Azure y copie la URL de acceso de cliente desde el panel Claves.

Como se muestra en el diagrama, al cliente se le concede permiso para enviar mensajes a grupos específicos y unirse a grupos específicos. Más información sobre el permiso de cliente, consulte Permisos.

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

Uso del servidor de negociación para generar Client Access URL

En producción, un cliente suele obtener el Client Access URL de un servidor de negociación. El servidor mantiene connection string y genera el Client Access URL a través de WebPubSubServiceClient. Como ejemplo, el fragmento de código simplemente muestra cómo generar el Client Access URL dentro de un único proceso.

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();
}

Características para diferenciar WebPubSubClient y WebPubSubServiceClient.

Examples

Consumir mensajes del servidor y los grupos

Un cliente puede agregar funciones de devolución de llamada para consumir mensajes del servidor y los grupos. Tenga en cuenta que los clientes solo pueden recibir mensajes de los grupos a los que se han unido.

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;
};

Agregue devoluciones de llamada para los eventos connected, disconnected y stopped.

Cuando una conexión de cliente está conectada al servicio, el connected evento se desencadena una vez que recibe el mensaje conectado del servicio.

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

Cuando se desconecta una conexión de cliente y no se puede recuperar, se desencadena el disconnected evento.

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

Cuando se detiene un cliente, lo que significa que la conexión de cliente está desconectada y el cliente deja de intentar volver a conectarse, se desencadena el stopped evento. Esto suele ocurrir después de que se llame a client.StopAsync() o se deshabilite AutoReconnect. Si desea reiniciar el cliente, puede llamar a client.StartAsync() en el evento Stopped.

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

Volver a unirse automáticamente a grupos y gestionar los errores que se producen al volver a unirse

Cuando se ha quitado una conexión de cliente y no se puede recuperar, todos los contextos de grupo se limpian en el lado del servicio. Esto significa que cuando el cliente se vuelve a conectar, debe volver a unirse a grupos. De forma predeterminada, el cliente habilitó las opciones de AutoRejoinGroups. Sin embargo, esta característica tiene limitaciones. El cliente solo puede volver a unirse a los grupos a los que se unió originalmente, no a los que se unieron en el lado del servidor. Las operaciones de reincorporación a grupos pueden fallar por varias razones, por ejemplo, si el cliente no tiene permiso para unirse a grupos. En tales casos, los usuarios deben agregar un callback para gestionar este error.

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

Operación y reintento

De forma predeterminada, la operación como client.JoinGroupAsync(), client.LeaveGroupAsync(), client.SendToGroupAsync(), client.SendEventAsync() tiene tres reties. Puede usar WebPubSubClientOptions.MessageRetryOptions para cambiar. Si se han producido errores en todos los reintentos, se produce un error. Puede seguir intentando transferir el mismo ackId que en los reintentos anteriores, de modo que el servicio pueda ayudar a desduplicar la operación con el mismo 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);
    }
}

Solución de problemas

Habilitación de registros

Puede establecer la siguiente variable de entorno para obtener los registros de depuración cuando se usa esta biblioteca.

export AZURE_LOG_LEVEL=verbose

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.

Seguimiento en vivo

Use la herramienta Live Trace de Azure Portal para inspeccionar el tráfico de mensajes en directo a través del recurso de Web PubSub.