Biblioteca de clientes do Azure Web PubSub para .NET

Observação

Os detalhes sobre os termos usados aqui são descritos no artigo de conceitos-chave .

O SDK do lado do cliente visa acelerar o fluxo de trabalho do desenvolvedor; mais especificamente,

• simplifica o gerenciamento de conexões de cliente
• simplifica o envio de mensagens entre clientes
• tenta novamente automaticamente após quedas não intencionais da conexão do cliente
• entrega mensagens de forma confiável em quantidade e na ordem correta após se recuperar de quedas de conexão

Conforme mostrado no diagrama, seus clientes estabelecem conexões WebSocket com o recurso Web PubSub.

Como começar

Instalar o pacote

Instale a biblioteca de clientes do NuGet:

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

Pré-requisitos

• Uma assinatura do Azure
• Uma instância existente do Web PubSub

Autenticar o cliente

Um cliente usa um Client Access URL para se conectar e autenticar com o serviço. Client Access URL segue o padrão como wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Há várias maneiras de obter um Client Access URL. Como um início rápido, você pode copiar e colar no portal do Azure e, para produção, geralmente é necessário um servidor de negociação para gerar a Client Access URL. Confira os detalhes.

Usar a URL de Acesso ao Cliente no portal do Azure

Como um início rápido, você pode acessar o portal do Azure e copiar a URL de Acesso ao Cliente da folha Chaves .

Conforme mostrado no diagrama, o cliente recebe a permissão de enviar mensagens para grupos específicos e ingressar grupos específicos. Saiba mais sobre a permissão do cliente, confira as permissões.

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

Usar o servidor de negociação para gerar Client Access URL

Em produção, um cliente geralmente obtém o Client Access URL de um servidor de negociação. O servidor mantém o connection string e gera o Client Access URL através de WebPubSubServiceClient. Como exemplo, o snippet de código apenas demonstra como gerar o Client Access URL dentro de um único processo.

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

Recursos para diferenciar WebPubSubClient e WebPubSubServiceClient.

Nome da Classe	WebPubSubClient	WebPubSubServiceClient
Nome do Pacote NuGet	Azure.Messaging.WebPubSub.Client	Azure.Messaging.WebPubSub
Features	Usado no lado do cliente. Publique mensagens e assine mensagens.	Usado no lado do servidor. Gerar o URI de Acesso do Cliente e gerenciar clientes

Exemplos

Consumir mensagens do servidor e dos grupos

Um cliente pode adicionar retornos de chamada para consumir mensagens do servidor e dos grupos. Observe que os clientes podem receber apenas mensagens de grupos dos quais participaram.

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

Adicionar callbacks para os eventos connected, disconnected, e stopped

Quando uma conexão de cliente é estabelecida com o serviço, o evento connected é disparado quando recebe a mensagem de confirmação de conexão do serviço.

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

Quando uma conexão de cliente é desconectada e falha ao recuperar, o disconnected evento é disparado.

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

Quando um cliente é interrompido, o que significa que a conexão do cliente é desconectada e o cliente para de tentar se reconectar, o stopped evento é disparado. Isso geralmente acontece depois que o client.StopAsync() é chamado ou o AutoReconnect é desabilitado. Se você quiser reiniciar o cliente, poderá chamar client.StartAsync() no evento Stopped.

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

Reingressar em grupos automaticamente e lidar com falha de reingresso

Quando uma conexão de cliente é interrompida e não consegue se recuperar, todos os contextos de grupo são limpos no lado do serviço. Isso significa que, quando o cliente se reconecta, ele precisa se juntar novamente aos grupos. Por padrão, o cliente habilitou as opções AutoRejoinGroups. No entanto, esse recurso tem limitações. O cliente só pode reingressar em grupos aos quais tenha ingressado originalmente pelo próprio cliente e não pelo lado do servidor. E as operações de reingresso no grupo podem falhar devido a vários motivos, por exemplo, o cliente não tem permissão para ingressar em grupos. Nesses casos, os usuários precisam adicionar um retorno de chamada para lidar com essa falha.

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

Operação e nova tentativa

Por padrão, a operação, como client.JoinGroupAsync(), client.LeaveGroupAsync(), client.SendToGroupAsync()client.SendEventAsync()tem três reties. Você pode usar WebPubSubClientOptions.MessageRetryOptions para alterar. Se todas as novas tentativas falharem, um erro será gerado. Você pode continuar tentando novamente passando o mesmo ackId das repetições anteriores, assim, o serviço pode ajudar a eliminar a duplicação da operação com o mesmo 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);
    }
}

Resolução de problemas

Habilitar logs

Você pode definir a variável de ambiente a seguir para obter os logs de depuração ao usar essa biblioteca.

export AZURE_LOG_LEVEL=verbose

Para obter instruções mais detalhadas sobre como habilitar logs, você pode consultar os documentos do pacote @azure/logger.

Rastreamento ao vivo

Use a ferramenta Live Trace do portal do Azure para inspecionar o tráfego de mensagens ao vivo por meio do recurso Do Web PubSub.