Partilhar via

Usar o SDK de Gerenciamento do Azure SignalR

  • Artigo

O SDK de Gerenciamento do Azure SignalR ajuda você a gerenciar clientes SignalR por meio do Serviço SignalR do Azure diretamente, como mensagens de transmissão. Portanto, esse SDK pode ser, mas não limitado a ser usado em ambientes sem servidor. Você pode usar esse SDK para gerenciar clientes SignalR conectados ao seu Serviço Azure SignalR em qualquer ambiente, como em um aplicativo de console, em uma função do Azure ou em um servidor Web.

Nota

Para ver os guias do SDK versão 1.9.x e anteriores, vá para SDK de Gerenciamento de Serviços do Azure SignalR (Legado). Você também pode querer ler Diretrizes de migração.

Importante

As cadeias de conexão brutas aparecem neste artigo apenas para fins de demonstração.

Uma cadeia de conexão inclui as informações de autorização necessárias para seu aplicativo acessar o serviço Azure Web PubSub. A chave de acesso dentro da cadeia de conexão é semelhante a uma senha de root para o seu serviço. Em ambientes de produção, proteja sempre as suas chaves de acesso. Use o Azure Key Vault para gerenciar e girar suas chaves com segurança e proteger sua cadeia de conexão usando a ID do Microsoft Entra e autorizar o acesso com a ID do Microsoft Entra.

Evite distribuir chaves de acesso para outros usuários, codificá-las ou salvá-las em qualquer lugar em texto simples acessível a outras pessoas. Rode as chaves se acreditar que podem ter sido comprometidas.

Funcionalidades

Caraterística Transitório Persistente
Difusão ✔️ ✔️
Transmissão, exceto alguns clientes ✔️ ✔️
Enviar a um cliente ✔️ ✔️
Enviar aos clientes ✔️ ✔️
Enviar a um utilizador ✔️ ✔️
Enviar aos utilizadores ✔️ ✔️
Enviar para um grupo ✔️ ✔️
Enviar para grupos ✔️ ✔️
Enviar para um grupo, exceto alguns clientes ✔️ ✔️
Adicionar um utilizador a um grupo ✔️ ✔️
Remover um utilizador de um grupo ✔️ ✔️
Verificar se um utilizador num grupo ✔️ ✔️
Suporte a várias instâncias de serviço SignalR ❌ ✔️
Suporte a clientes MessagePack desde v1.21.0 desde v1.20.0
Repetir erro transitório desde v1.22.0 ❌

Os recursos vêm apenas com a nova API

Caraterística Transitório Persistente
Verificar se existe uma ligação ✔️ Desde v1.11
Verificar se existe um grupo ✔️ Desde v1.11
Verificar se existe um utilizador ✔️ Desde v1.11
Fechar uma conexão de cliente ✔️ Desde v1.11

  • Mais detalhes sobre os diferentes modos podem ser encontrados aqui.

  • Um exemplo completo sobre o SDK de gerenciamento pode ser encontrado aqui.

Utilização

Esta seção mostra como usar o SDK de Gerenciamento.

Criar Service Manager

Crie sua instância de ServiceManager um ServiceManagerBuilderarquivo .

As cadeias de conexão brutas aparecem neste artigo apenas para fins de demonstração. Em ambientes de produção, proteja sempre as suas chaves de acesso. Use o Azure Key Vault para gerenciar e girar suas chaves com segurança e proteger sua cadeia de conexão usando a ID do Microsoft Entra e autorizar o acesso com a ID do Microsoft Entra.


var serviceManager = new ServiceManagerBuilder()
                    .WithOptions(option =>
                    {
                        option.ConnectionString = "<Your Azure SignalR Service Connection String>";
                    })
                    .WithLoggerFactory(loggerFactory)
                    .BuildServiceManager();

Você pode usar ServiceManager para verificar a integridade do ponto de extremidade do Azure SignalR e criar contexto de hub de serviço. A seção a seguir fornece detalhes sobre a criação do contexto do hub de serviço.

Para verificar a integridade do ponto de extremidade do Azure SignalR, você pode usar ServiceManager.IsServiceHealthy o método. Se você tiver vários pontos de extremidade do Azure SignalR, somente o primeiro ponto de extremidade será verificado.

var health = await serviceManager.IsServiceHealthy(cancellationToken);

Criar contexto do Service Hub

Crie sua instância de a partir de ServiceHubContext um ServiceManager:

var serviceHubContext = await serviceManager.CreateHubContextAsync("<Your Hub Name>",cancellationToken);

Negociação

No modo padrão, um ponto de extremidade /<Your Hub Name>/negotiate é exposto para negociação pelo SDK do Serviço Azure SignalR. Os clientes SignalR atingem esse ponto de extremidade e redirecionam para o Serviço Azure SignalR mais tarde.

No modo sem servidor, recomendamos que você hospede um ponto de extremidade de negociação para atender à solicitação de negociação dos clientes SignalR e redirecionar os clientes para o Serviço SignalR do Azure.

Gorjeta

Leia mais detalhes sobre o redirecionamento no Protocolo de Negociação do SignalR.

Tanto o token de ponto de extremidade quanto o de acesso são úteis quando você deseja redirecionar clientes SignalR para seu Serviço Azure SignalR.

Você pode usar a instância de para gerar a URL do ponto de extremidade e o token de ServiceHubContext acesso correspondente para que os clientes SignalR se conectem ao seu Serviço SignalR do Azure.

var negotiationResponse = await serviceHubContext.NegotiateAsync(new (){UserId = "<Your User Id>"});

Suponha que seu ponto de extremidade de hub é http://<Your Host Name>/<Your Hub Name>, então seu ponto de extremidade de negociação é http://<Your Host Name>/<Your Hub Name>/negotiate. Depois de hospedar o ponto de extremidade de negociação, você pode usar os clientes SignalR para se conectar ao seu hub da seguinte forma:

var connection = new HubConnectionBuilder().WithUrl("http://<Your Host Name>/<Your Hub Name>").Build();
await connection.StartAsync();

O exemplo sobre como usar o SDK de Gerenciamento para redirecionar clientes SignalR para o Serviço Azure SignalR pode ser encontrado aqui.

Enviar mensagens e gerenciar grupos

A ServiceHubContext partir da ServiceHubContextBuilder qual construímos é uma classe que implementa e estende.IServiceHubContext Você pode usá-lo para enviar mensagens para seus clientes e gerenciar seus grupos.

try
{
    // Broadcast
    await hubContext.Clients.All.SendAsync(callbackName, obj1, obj2, ...);

    // Send to user
    await hubContext.Clients.User(userId).SendAsync(callbackName, obj1, obj2, ...);

    // Send to group
    await hubContext.Clients.Group(groupId).SendAsync(callbackName, obj1, obj2, ...);

    // add user to group
    await hubContext.UserGroups.AddToGroupAsync(userId, groupName);

    // remove user from group
    await hubContext.UserGroups.RemoveFromGroupAsync(userId, groupName);
}
finally
{
    await hubContext.DisposeAsync();
}

Hub fortemente tipado

Um hub fortemente tipado é um modelo de programação que você pode extrair seus métodos de cliente em uma interface, para evitar erros como escrever incorretamente o nome do método ou passar os tipos de parâmetros errados.

Digamos que temos um método cliente chamado ReceivedMessage com dois parâmetros de cadeia de caracteres. Sem hubs fortemente tipados, você transmite para clientes através do hubContext.Clients.All.SendAsync("ReceivedMessage", user, message). Com hubs fortemente tipados, você primeiro define uma interface como esta:

public interface IChatClient
{
    Task ReceiveMessage(string user, string message);
}

E então você cria um contexto de hub fortemente tipado, que implementa , T é a interface do IHubContext<Hub<T>, T>método do cliente:

ServiceHubContext<IChatClient> serviceHubContext = await serviceManager.CreateHubContextAsync<IChatClient>(hubName, cancellationToken);

Finalmente, você pode invocar diretamente o método:

await Clients.All.ReceiveMessage(user, message);

Exceto pela diferença de enviar mensagens, você pode negociar ou gerenciar grupos com o mesmo ServiceHubContext.ServiceHubContext<T>

Leia mais sobre hubs fortemente tipados nos documentos do ASP.NET Core aqui.

Tipo de transporte

Esse SDK pode se comunicar com o Serviço SignalR do Azure com dois tipos de transporte:

  • Transitório: crie uma solicitação Http do Serviço Azure SignalR para cada mensagem enviada. O SDK simplesmente encapsula a API REST do Serviço Azure SignalR no modo Transitório. É útil quando você não consegue estabelecer uma conexão WebSockets.
  • Persistente: crie uma conexão WebSockets primeiro e, em seguida, envie todas as mensagens nessa conexão. É útil quando você envia um grande número de mensagens.

Resumo dos comportamentos de serialização dos argumentos em mensagens

Serialização Transitório Persistente
Biblioteca JSON padrão Newtonsoft.Json O mesmo que ASP.NET Core SignalR:
Newtonsoft.Json para .NET Standard 2.0;
System.Text.Json para .NET Core App 3.1 e superior
Suporte a clientes MessagePack desde v1.21.0 desde v1.20.0

Serialização JSON

No Management SDK, os argumentos de método enviados aos clientes são serializados em JSON. Temos várias maneiras de personalizar a serialização JSON. Mostramos todos os caminhos na ordem do mais recomendado ao menos recomendado.

ServiceManagerOptions.UseJsonObjectSerializer(ObjectSerializer objectSerializer)

A maneira mais recomendada é usar uma classe ObjectSerializerabstrata geral, porque ela suporta diferentes bibliotecas de serialização JSON, como System.Text.Json e Newtonsoft.Json e se aplica a todos os tipos de transporte. Normalmente, você não precisa implementar ObjectSerializer sozinho, pois implementações JSON úteis para System.Text.Json e Newtonsoft.Json já são fornecidas.

  • Ao usar System.Text.Json como biblioteca de processamento JSON O builtin JsonObjectSerializer usa System.Text.Json.JsonSerializer para serialização/desserialização. Aqui está um exemplo para usar a nomenclatura de caso camel para serialização JSON:

    var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.ConnectionString = "***";
        o.UseJsonObjectSerializer(new JsonObjectSerializer(new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase
        }));
    })
    .BuildServiceManager();

  • Ao usar Newtonsoft.Json como biblioteca de processamento JSON Primeiro, instale o pacote Microsoft.Azure.Core.NewtonsoftJson do NuGet usando a CLI .NET:

    dotnet add package Microsoft.Azure.Core.NewtonsoftJson

    Aqui está um exemplo para usar a nomenclatura de maiúsculas e minúsculas de camelo com NewtonsoftJsonObjectSerializer:

    var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.ConnectionString = "***";
        o.UseJsonObjectSerializer(new NewtonsoftJsonObjectSerializer(new JsonSerializerSettings()
        {
            ContractResolver = new CamelCasePropertyNamesContractResolver()
        }));
    })
    .BuildServiceManager();

  • Ao usar outras bibliotecas de processamento JSON

    Você também pode implementar ObjectSerializer por conta própria. Os links a seguir podem ajudar:

ServiceManagerBuilder.WithNewtonsoftJson(Action<NewtonsoftServiceHubProtocolOptions> configure)

Este método é apenas para Newtonsoft.Json usuários. Aqui está um exemplo para usar a nomeação de maiúsculas e minúsculas:

var serviceManager = new ServiceManagerBuilder()
    .WithNewtonsoftJson(o =>
    {
        o.PayloadSerializerSettings = new JsonSerializerSettings
        {
            ContractResolver = new CamelCasePropertyNamesContractResolver()
        };
    })
    .BuildServiceManager();
ServiceManagerOptions.JsonSerializerSettings (Preterido)

Este método aplica-se apenas ao tipo de transporte transitório. Não utilize.

var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.JsonSerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
    })
    .BuildServiceManager();

Serialização do pacote de mensagens

  1. Você precisa instalar Microsoft.AspNetCore.SignalR.Protocols.MessagePack o pacote.

  2. Para adicionar um protocolo MessagePack lado a lado com o protocolo JSON padrão:

    var serviceManagerBuilder = new ServiceManagerBuilder()
    .AddHubProtocol(new MessagePackHubProtocol());

  3. Para controlar totalmente os protocolos de hub, você pode usar

        var serviceManagerBuilder = new ServiceManagerBuilder()
        .WithHubProtocols(new MessagePackHubProtocol(), new JsonHubProtocol());

    WithHubProtocols primeiro limpa os protocolos existentes e, em seguida, adiciona os novos protocolos. Você também pode usar esse método para remover o protocolo JSON e usar somente MessagePack.

Para o modo transitório, por padrão, o lado do serviço converte a carga JSON em carga útil do MessagePack e é a maneira herdada de oferecer suporte ao MessagePack. No entanto, recomendamos que você adicione um protocolo de hub MessagePack explicitamente, pois a maneira herdada pode não funcionar como esperado.

Repetição de solicitações HTTP

Para o modo transitório , este SDK fornece a capacidade de reenviar automaticamente solicitações quando ocorrem erros transitórios, desde que as solicitações sejam idempotentes. Para habilitar esse recurso, você pode usar a ServiceManagerOptions.RetryOptions propriedade.

Em particular, os seguintes tipos de pedidos são repetidos:

  • Para solicitações de mensagem que enviam mensagens para clientes SignalR, o SDK tenta novamente a solicitação se o código de status da resposta HTTP for maior que 500. Quando o código de resposta HTTP é igual a 500, ele pode indicar um tempo limite no lado do serviço, e tentar novamente a solicitação pode resultar em mensagens duplicadas.

  • Para outros tipos de solicitações, como adicionar uma conexão a um grupo, o SDK tenta novamente a solicitação nas seguintes condições:

    1. O código de status da resposta HTTP está no intervalo 5xx ou a solicitação atingiu o tempo limite com um código de status de 408 (Tempo limite da solicitação).
    2. A solicitação atingiu o tempo limite com uma duração maior do que a duração do tempo limite configurado em ServiceManagerOptions.HttpClientTimeout.

O SDK só pode repetir solicitações idempotentes, que são solicitações que não têm outro efeito se forem repetidas. Se suas solicitações não forem idempotentes, talvez seja necessário lidar com novas tentativas manualmente.

Próximos passos

Neste artigo, você aprenderá a usar o Serviço SignalR em seus aplicativos. Consulte os seguintes artigos para saber mais sobre o Serviço SignalR.

Elementos internos do Azure SignalR Service

Guia de início rápido: criar uma sala de chat usando o Serviço SignalR