Biblioteca de clientes do Chat de Comunicação do Azure para .NET – versão 1.1.2

Esse pacote contém um SDK do C# para Serviços de Comunicação do Azure para chat.

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

Introdução

Instalar o pacote

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

dotnet add package Azure.Communication.Chat 

Pré-requisitos

Você precisa de uma assinatura do Azure e de 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

Tokens de acesso do usuário

Os tokens de acesso do usuário permitem que você crie aplicativos cliente que se autenticam diretamente nos Serviços de Comunicação do Azure. Para a geração de tokens de acesso do usuário, consulte Tokens de Acesso do Usuário.

Como usar instruções

using Azure.Communication.Identity;
using Azure.Communication.Chat;

Criar um ChatClient

Isso permitirá que você crie, obtenha ou exclua threads de chat.

ChatClient chatClient = new ChatClient(
    endpoint,
    new CommunicationTokenCredential(userToken));

Criar um ChatThreadClient

O ChatThreadClient permitirá que você execute operações específicas a um thread de chat, como atualizar o tópico de thread de chat, enviar uma mensagem, adicionar participantes ao thread de chat etc.

Você pode criar uma instância de um novo ChatThreadClient usando a operação GetChatThread do ChatClient com uma ID de thread existente:

ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(chatThread.Id);

Principais conceitos

Uma conversa de chat é representada por um thread. Cada usuário no thread é chamado de participante do thread. Os participantes do thread podem conversar entre si em particular em um chat 1:1 ou se amontoar em um chat em grupo 1:N. Os usuários também recebem atualizações quase em tempo real para quando outras pessoas estão digitando e quando leem as mensagens.

Depois de inicializar uma ChatClient classe, você poderá fazer as seguintes operações de chat:

Criar um thread

CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new ChatParticipant[] { });
ChatThreadProperties chatThread = createChatThreadResult.ChatThread;

Obter um thread

ChatThread chatThread = chatClient.GetChatThread(chatThread.Id);

Obter todos os threads para o usuário

Pageable<ChatThreadItem> threads = chatClient.GetChatThreads();

Excluir um thread

chatClient.DeleteChatThread(chatThread.Id);

Depois de inicializar uma ChatThreadClient classe, você poderá fazer as seguintes operações de chat:

Atualizar um thread

chatThreadClient.UpdateTopic(topic: "Launch meeting");

Enviar uma mensagem

SendChatMessageResult sendChatMessageResult = chatThreadClient.SendMessage("Let's meet at 11am");

Atualizar uma mensagem

chatThreadClient.UpdateMessage(sendChatMessageResult.Id, content: "Instead of 11am, let's meet at 2pm");

Obter uma mensagem

ChatMessage message = chatThreadClient.GetMessage(sendChatMessageResult.Id);

Excluir uma mensagem

chatThreadClient.DeleteMessage(sendChatMessageResult.Id);

Obter mensagens

Pageable<ChatMessage> messages = chatThreadClient.GetMessages();

Obter uma lista de participantes

Pageable<ChatParticipant> chatParticipants = chatThreadClient.GetParticipants();

Adicionar participantes

chatThreadClient.AddParticipants(participants: new[] { new ChatParticipant(participantIdentifier) });

Remover um participante

chatThreadClient.RemoveParticipant(identifier: participantIdentifier);

Enviar uma notificação de digitação

chatThreadClient.SendTypingNotification();

Obter uma lista de recibos de leitura

Pageable<ChatMessageReadReceipt> readReceipts = chatThreadClient.GetReadReceipts();

Enviar uma confirmação de leitura

chatThreadClient.SendReadReceipt(sendChatMessageResult.Id);

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

Opções | do clienteAcessando a resposta | Operações de execução prolongada | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns, incluindo:

• Operações de thread
• Operações de mensagem
• Operações do participante do thread
• Operações de eventos

Operações de thread

Criar um thread

Use CreateChatThread para criar um objeto de cliente de thread de chat.

• Use topic para fornecer um tópico de thread.
• Veja a seguir os atributos com suporte para cada participante do thread:
  • communicationUser, obrigatório, é a identificação do participante do thread.
  • displayName, opcional, é o nome de exibição para o participante do thread
  • shareHistoryTime, opcional, é o horário no qual o histórico do chat é compartilhado com o participante.

ChatThreadClient é o resultado retornado da criação de um thread, você pode usá-lo para executar outras operações no thread de chat.

ChatClient chatClient = new ChatClient(
    endpoint,
    new CommunicationTokenCredential(userToken));

var chatParticipant = new ChatParticipant(identifier: kimberly)
{
    DisplayName = "Kim"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { chatParticipant });
string threadId = createChatThreadResult.ChatThread.Id;
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId);

Obter um thread

Use GetChatThread para recuperar um thread de chat do serviço. threadId é a ID exclusiva do thread.

ChatThreadProperties chatThread = await chatThreadClient.GetPropertiesAsync();

Obter threads (para um participante)

Use GetChatThreads para obter a lista de threads de chat para o participante que instanciou o chatClient.

AsyncPageable<ChatThreadItem> chatThreadItems = chatClient.GetChatThreadsAsync();
await foreach (ChatThreadItem chatThreadItem in chatThreadItems)
{
    Console.WriteLine($"{ chatThreadItem.Id}");
}

Excluir um thread

Use DeleteChatThread para excluir um thread. threadId é a ID exclusiva do thread.

await chatClient.DeleteChatThreadAsync(threadId);

Atualizar um thread

Use UpdateTopic para atualizar o tópico do thread de chat.

• topic é usado para descrever o tópico atualizado para o thread.

await chatThreadClient.UpdateTopicAsync(topic: "new topic !");

Operações de mensagem

Enviar uma mensagem

Use SendMessage para enviar uma mensagem para uma conversa.

• Use content para fornecer o conteúdo da mensagem; ele é obrigatório.
• Use type para o tipo de conteúdo da mensagem, como "Text" ou "HTML". Se não for speficied, 'Text' será definido.
• Use senderDisplayName para especificar o nome de exibição do remetente. Se não for especificado, uma cadeia de caracteres vazia será a usada.

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(content:"hello world");
var messageId = sendChatMessageResult.Id;

Obter uma mensagem

Use GetMessage para recuperar uma mensagem do serviço. messageId é a ID exclusiva da mensagem.

ChatMessage é a resposta retornada da obtenção de uma mensagem, ela contém uma ID, que é o identificador exclusivo da mensagem, entre outros campos. Confira Azure.Communication.Chat.ChatMessage

ChatMessage chatMessage = await chatThreadClient.GetMessageAsync(messageId);

Obter mensagens

Use GetMessages para recuperar todas as mensagens para o thread de chat.

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

Atualizar uma mensagem

Use UpdateMessage para atualizar uma mensagem.

• messageId é o identificador exclusivo da mensagem.
• content é o conteúdo da mensagem a ser atualizado.

await chatThreadClient.UpdateMessageAsync(messageId, "updated message content");

Excluir uma mensagem

Use DeleteMessage para excluir uma mensagem.

• messageId é o identificador exclusivo da mensagem.

await chatThreadClient.DeleteMessageAsync(messageId);

Operações do participante do thread

Obter participantes da conversa

Use GetParticipants para recuperar os participantes da conversa de chat.

AsyncPageable<ChatParticipant> allParticipants = chatThreadClient.GetParticipantsAsync();
await foreach (ChatParticipant participant in allParticipants)
{
    Console.WriteLine($"{((CommunicationUserIdentifier)participant.User).Id}:{participant.DisplayName}:{participant.ShareHistoryTime}");
}

Adicionar participantes do thread

Use AddParticipants para adicionar um ou mais participantes à conversa de chat. A seguir, estão os atributos com suporte para participantes de cada conversa:

• communicationUser, obrigatório, é a identificação do participante do thread.
• displayName, opcional, é o nome de exibição do participante do thread.
• shareHistoryTime, opcional, é o horário no qual o histórico do chat é compartilhado com o participante.

var participants = new[]
{
    new ChatParticipant(josh) { DisplayName = "Josh" },
    new ChatParticipant(gloria) { DisplayName = "Gloria" },
    new ChatParticipant(amy) { DisplayName = "Amy" }
};

await chatThreadClient.AddParticipantsAsync(participants);

Remover participante do thread

Use RemoveParticipant para remover um participante do thread. communicationUser é a identificação do participante do chat.

await chatThreadClient.RemoveParticipantAsync(gloria);

Operações de eventos

Enviar uma notificação de digitação

Use SendTypingNotification para indicar que o usuário está digitando uma resposta na conversa.

await chatThreadClient.SendTypingNotificationAsync();

Enviar confirmação de leitura

Use SendReadReceipt para notificar outros participantes de que a mensagem foi lida pelo usuário.

await chatThreadClient.SendReadReceiptAsync(messageId);

Obter confirmações de leitura

Use GetReadReceipts para verificar o status das mensagens e ver quais delas foram lidas por outros participantes de uma conversa de chat.

AsyncPageable<ChatMessageReadReceipt> allReadReceipts = chatThreadClient.GetReadReceiptsAsync();
await foreach (ChatMessageReadReceipt readReceipt in allReadReceipts)
{
    Console.WriteLine($"{readReceipt.ChatMessageId}:{((CommunicationUserIdentifier)readReceipt.Sender).Id}:{readReceipt.ReadOn}");
}

Solução de problemas

Respostas de serviço

Um RequestFailedException é gerado como uma resposta de serviço para solicitações malsucedidas. A exceção contém informações sobre qual código de resposta foi retornado do serviço.

try
{
    CreateChatThreadResult createChatThreadErrorResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { josh });
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.Message);
}

Próximas etapas

Leia mais sobre o Chat no Serviços de Comunicação do Azure

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.