Biblioteca de clientes do serviço Azure Web PubSub para .NET – versão 1.3.0

  • Artigo

O Azure Web PubSub é um serviço gerenciado do Azure que ajuda os desenvolvedores a criar aplicativos Web facilmente com recursos em tempo real e padrão de publicação/assinatura. Qualquer cenário que exija mensagens de publicação/assinatura em tempo real entre o servidor e os clientes ou entre clientes pode usar o serviço Azure Web PubSub. Os recursos tradicionais em tempo real que geralmente exigem a sondagem do servidor ou o envio de solicitações HTTP também podem usar o serviço Azure Web PubSub.

Você pode usar essa biblioteca no lado do servidor de aplicativos para gerenciar as conexões de cliente WebSocket, conforme mostrado no diagrama abaixo:

Estouro

Use essa biblioteca para:

  • Enviar mensagens para hubs e grupos.
  • Enviar mensagens para usuários e conexões específicos.
  • Organizar usuários e conexões em grupos.
  • Fechar conexões
  • Conceder, revogar e verificar permissões para uma conexão existente

Os detalhes sobre os termos usados aqui são descritos na seção Principais conceitos.

Código-fonte | Pacote | Documentação de referência da API | Documentação do produto | Exemplos

Introdução

Instalar o pacote

Instale a biblioteca de clientes do NuGet:

dotnet add package Azure.Messaging.WebPubSub

Pré-requisitos

Criar e autenticar um WebPubSubServiceClient

Para interagir com o serviço, você precisará criar uma instância da classe WebPubSubServiceClient. Para tornar isso possível, você precisará da cadeia de conexão ou de uma chave, que pode ser acessada no portal do Azure.

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

Principais conceitos

Conexão

Uma conexão, também conhecida como cliente ou conexão cliente, representa uma conexão do WebSocket individual ao serviço Web PubSub. Quando conectado com sucesso, uma ID de conexão exclusiva é atribuída a essa conexão pelo serviço Web PubSub.

Hub

Um hub é um conceito lógico para um conjunto de conexões de cliente. Normalmente, você usa um hub para cada finalidade específica, por exemplo, o hub de chat ou o hub de notificações. Quando uma conexão de cliente é criada, ela se conecta a um hub e, durante seu tempo de vida, pertence a esse hub. Aplicativos diferentes podem compartilhar o mesmo serviço Azure Web PubSub usando nomes de hub diferentes.

Grupo

Um grupo é um subconjunto de conexões com o hub. Você pode adicionar uma conexão de cliente a um grupo ou removê-la do grupo sempre que desejar. Por exemplo, quando um cliente entra em uma sala de chat ou quando um cliente sai da sala de chat, essa sala de chat pode ser considerada um grupo. Um cliente pode ingressar em vários grupos e um grupo pode conter vários clientes.

Usuário

As conexões com o Web PubSub podem pertencer a um usuário. Um usuário pode ter várias conexões, por exemplo, quando apenas um usuário está conectado a vários dispositivos ou a várias guias do navegador.

Mensagem

Quando um cliente está conectado, ele pode enviar mensagens ao aplicativo upstream ou receber mensagens do aplicativo upstream por meio da conexão do WebSocket.

Exemplos

Gerar o URI completo que contém o token de acesso para a conexão a ser usada ao conectar o 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" });

Enviar mensagens para as conexões

Transmitir uma mensagem de texto para todos os clientes

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

serviceClient.SendToAll("Hello World!");

Transmitir uma mensagem JSON para todos os clientes

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

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

Transmitir uma mensagem binária para todos os clientes

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

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

Transmitir mensagens para clientes usando filtro

O Azure Web PubSub dá suporte à sintaxe de filtro OData para filtrar as conexões para as quais enviar mensagens.

Detalhes sobre filter a sintaxe, confira Sintaxe de filtro OData para o 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)"));

Gerenciamento de Conexão

Adicione conexões para algum usuário a algum 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");

Remover a conexão de todos os grupos

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

Solução de problemas

Configuração do registro em log do console

Também é possível habilitar registro em log do console facilmente se quiser se aprofundar nas solicitações que está fazendo ao serviço.

Próximas etapas

Dê uma olhada no diretório de exemplos para obter exemplos detalhados sobre como usar essa biblioteca.

Você também pode encontrar mais exemplos aqui.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, acesse https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões