Biblioteca de clientes Comum de Comunicação do Azure para .NET – versão 1.2.1

Artigo
04/18/2023

Esse pacote contém código comum para bibliotecas do Serviço de Comunicação do Azure.

Código-fonte | Pacote (NuGet) | Documentação do produto

Introdução

Instalar o pacote

Instale a biblioteca de clientes Comuns de Comunicação do Azure para .NET com o NuGet.

dotnet add package Azure.Communication.Common

Pré-requisitos

Você precisa de uma assinatura do Azure e um Recurso do Serviço de Comunicação para usar esse pacote.

Para criar um novo Serviço de Comunicação, você pode usar o Portal do Azure, o Azure PowerShell ou a biblioteca de clientes de gerenciamento do .NET.

Autenticar o cliente

Este módulo não contém um cliente e, em vez disso, bibliotecas que ajudam outros clientes de Comunicação do Azure a se autenticarem.

Principais conceitos

CommunicationTokenCredential

O CommunicationTokenCredential objeto é usado para autenticar um usuário com os Serviços de Comunicação, como Chat ou Chamada. Opcionalmente, ele fornece um mecanismo de atualização automática para garantir um estado de autenticação continuamente estável durante as comunicações.

Dependendo do seu cenário, talvez você queira inicializar o CommunicationTokenCredential com:

um token estático (adequado para clientes de curta duração usados para, por exemplo, enviar mensagens de Chat pontuais) ou
uma função de retorno de chamada que garante um estado de autenticação contínua (ideal, por exemplo, para sessões de chamada longas).

Os tokens fornecidos para o CommunicationTokenCredential por meio do construtor ou por meio do retorno de chamada do atualizador de token podem ser obtidos usando a biblioteca de Identidade de Comunicação do Azure.

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Exemplos

Criar uma credencial com um token estático

Para clientes de curta duração, a atualização do token após a expiração não é necessária e CommunicationTokenCredential pode ser instanciada com um token estático.

string token = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_USER_TOKEN");
using var tokenCredential = new CommunicationTokenCredential(token);

Criar uma credencial com um retorno de chamada

Como alternativa, para clientes de longa duração, você pode criar um com um CommunicationTokenCredential retorno de chamada para renovar tokens se tiver expirado. Aqui, passamos duas funções imaginadas que fazem solicitações de rede para recuperar cadeias de caracteres de token para o usuário Bob. Se os retornos de chamada forem passados, mediante solicitações (enviando uma mensagem de chat), CommunicationTokenCredential garantirá que um token válido seja adquirido antes da execução da solicitação. É necessário que o FetchTokenForUserFromMyServer método retorne um token válido (com uma data de validade definida no futuro) o tempo todo.

Opcionalmente, você pode habilitar a atualização proativa de tokens em que um novo token será adquirido assim que o token anterior se aproximar da expiração. Usando esse método, suas solicitações são menos propensas a serem bloqueadas para adquirir um novo token:

using var tokenCredential = new CommunicationTokenCredential(
    new CommunicationTokenRefreshOptions(
        refreshProactively: true, // Indicates if the token should be proactively refreshed in the background or only on-demand
        tokenRefresher: cancellationToken => FetchTokenForUserFromMyServer("bob@contoso.com", cancellationToken))
    {
        AsyncTokenRefresher = cancellationToken => FetchTokenForUserFromMyServerAsync("bob@contoso.com", cancellationToken)
    });

Se você já tiver um token, poderá otimizar ainda mais a atualização do token passando esse token inicial:

string initialToken = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_USER_TOKEN");
using var tokenCredential = new CommunicationTokenCredential(
    new CommunicationTokenRefreshOptions(
       refreshProactively: true, // Indicates if the token should be proactively refreshed in the background or only on-demand
       tokenRefresher: cancellationToken => FetchTokenForUserFromMyServer("bob@contoso.com", cancellationToken))
    {
        AsyncTokenRefresher = cancellationToken => FetchTokenForUserFromMyServerAsync("bob@contoso.com", cancellationToken),
        InitialToken = initialToken
    });

Solução de problemas

As falhas proativas de atualização ocorrem em um thread em segundo plano e, para evitar falhas no aplicativo, as exceções serão tratadas silenciosamente. Todas as outras falhas ocorrerão durante sua solicitação usando outros clientes, como chat, em que você pode capturar a exceção usando RequestFailedException.

Próximas etapas

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, visite cla.microsoft.com.

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.