Biblioteca cliente Azure Web PubSub para .NET

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

• Simplifica a gestão das ligações com clientes
• simplifica o envio de mensagens entre clientes
• tenta novamente automaticamente após quedas não intencionais da ligação ao cliente
• entrega mensagens de forma fiável em quantidade e em ordem após recuperação de quebras de ligação

Como mostrado no diagrama, os seus clientes estabelecem ligações WebSocket com o seu recurso Web PubSub.

Como Começar

Instale o pacote

Instale a biblioteca cliente 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 ligar 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>. Existem várias formas de obter um Client Access URL. Como início rápido, podes copiar e colar do portal Azure e, para produção, normalmente precisas de um servidor de negociação para gerar Client Access URL. Ver detalhes.

Usar URL de Acesso ao Cliente a partir do portal Azure

Como início rápido, podes ir ao portal Azure e copiar o URL de Acesso ao Cliente da blâmina Keys .

Como mostrado no diagrama, o cliente recebe permissão para enviar mensagens para grupos específicos e juntar-se a grupos específicos. Saiba mais sobre permissões do cliente, consulte permissões.

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

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

Em produção, um cliente normalmente recupera 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 excerto de código demonstra apenas 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();
}

Características para diferenciar WebPubSubClient e WebPubSubServiceClient.

Exemplos

Consumir mensagens do servidor e dos grupos

Um cliente pode adicionar callbacks para consumir mensagens do servidor e dos grupos. Note que os clientes só podem receber mensagens de grupo dos quais eles aderiram.

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 eventos connected, disconnected e stopped

Quando uma ligação do cliente está conectada ao serviço, o evento connected é acionado assim que recebe a mensagem de conexão do serviço.

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

Quando uma ligação cliente é desligada e não recupera, o disconnected evento é desencadeado.

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

Quando um cliente é parado, o que significa que a ligação ao cliente é desligada e o cliente deixa de tentar reconectar-se, o stopped evento é desencadeado. Isto normalmente acontece depois de o client.StopAsync() ser chamado ou de o AutoReconnect ser desativado. Se quiser reiniciar o cliente, pode chamar client.StartAsync() no evento Stopped.

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

Entrar automaticamente nos grupos e lidar com falhas de reentrada

Quando uma ligação ao cliente cai e falha em recuperar, todos os contextos de grupo são limpos do lado do serviço. Isto significa que, quando o cliente se reconecta, precisa de voltar a juntar-se aos grupos. Por defeito, o cliente ativava AutoRejoinGroups opções. No entanto, esta funcionalidade tem limitações. O cliente só pode voltar a juntar-se a grupos a que o cliente aderiu originalmente, em vez de ser associado pelo lado do servidor. E as operações de reintegração de grupos podem falhar por várias razões, por exemplo, o cliente não tem permissão para entrar em grupos. Nesses casos, os utilizadores precisam de adicionar um callback para lidar com tal falha.

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

Operação e tentativa de nova execução

Por defeito, a operação como client.JoinGroupAsync(), client.LeaveGroupAsync(), client.SendToGroupAsync(), client.SendEventAsync() tem três tentativas. Podes usar WebPubSubClientOptions.MessageRetryOptions para mudar. Se todas as tentativas falharem, é lançado um erro. Pode continuar a tentar novamente passando o mesmo ackId das tentativas anteriores, de modo que o serviço possa ajudar a desduplicar a 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);
    }
}

Solução de problemas

Ativar registos

Pode definir a seguinte variável de ambiente para obter os registos de depuração ao usar esta 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.

Live Trace

Use a ferramenta Live Trace do portal Azure para inspecionar o tráfego de mensagens em tempo real através do seu recurso Web PubSub.