Azure.Communication.Chat 1.3.0

Azure Communication Chat 客户端库，适用于 .NET

此包包含 Azure Communication 服务聊天功能的 C# SDK。

源代码 | 软件包（NuGet） | 产品文档

入门

安装包

使用 NuGet 安装 Azure Communication Chat 客户端库 for .NET

dotnet add package Azure.Communication.Chat

先决条件

您需要一个 Azure 订阅 和一个 通信服务资源 来使用此包。

要创建新的通讯服务，您可以使用 Azure Portal、Azure PowerShell 或 .NET 管理客户端库。

客户端认证

用户访问令牌

用户访问令牌使您能够构建直接对 Azure 通讯服务进行认证的客户端应用程序。有关生成用户访问令牌的说明，请参阅 用户访问令牌。

使用语句

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

创建一个 ChatClient

这将允许您创建、获取或删除聊天线程。

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

创建一个 ChatThreadClient

ChatThreadClient 允许您执行针对特定聊天线程的操作，如更新聊天主题、发送消息、将参与者添加到聊天线程等。

您可以使用 ChatClient 的 GetChatThread 操作和现有的线程 ID 来实例化一个新的 ChatThreadClient

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

关键概念

聊天会话由一个线程表示。线程中的每个用户称为线程参与者。线程参与者可以私下进行 1:1 聊天或者在 1:N 群组聊天中进行群聊。用户还会收到其他人在键入以及他们已经阅读消息的实时更新。

一旦初始化了 ChatClient 类，您可以进行以下聊天操作

创建一个线程

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

获取一个线程

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

获取用户的全部线程

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

删除一个线程

chatClient.DeleteChatThread(chatThread.Id);

一旦初始化了 ChatThreadClient 类，您可以进行以下聊天操作

更新一个线程

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

发送一条消息

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

更新一条消息

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

获取一条消息

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

删除一条消息

chatThreadClient.DeleteMessage(sendChatMessageResult.Id);

获取消息

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

获取参与者列表

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

添加参与者

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

删除参与者

chatThreadClient.RemoveParticipant(identifier: participantIdentifier);

发送打字通知

chatThreadClient.SendTypingNotification();

获取阅读回执列表

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

发送阅读回执

chatThreadClient.SendReadReceipt(sendChatMessageResult.Id);

线程安全性

我们保证所有客户端实例方法都是线程安全的，且互不干扰（《指南》）。这确保了重新使用客户端实例的建议总是安全的，即使在跨线程的情况下也是。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 调试 | 模拟 | 客户端生命周期

示例

以下部分提供了几个代码片段，涵盖了最常见的一些任务，包括

• 线程操作
• 消息操作
• 线程参与者操作
• 事件操作

线程操作

创建一个线程

使用 CreateChatThread 创建聊天线程客户端对象。

• 使用 topic 为线程指定主题。
• 以下是每个线程参与者的支持属性
  • communicationUser，必需，它是线程参与者的标识。
  • displayName，可选，是线程参与者的显示名称。
  • shareHistoryTime，可选，是从此时开始与参与者共享聊天历史的时间。

ChatThreadClient 是创建线程后返回的结果，您可以使用它对聊天线程执行其他操作。

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);

获取一个线程

使用 GetChatThread 从服务中检索聊天线程。 threadId 是线程的唯一标识符。

ChatThreadProperties chatThread = await chatThreadClient.GetPropertiesAsync();

获取线程（参与者）

使用 GetChatThreads 获取调用聊天Client的参与者的聊天线程列表。

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

删除一个线程

使用 DeleteChatThread 删除线程。 threadId 是线程的唯一标识符。

await chatClient.DeleteChatThreadAsync(threadId);

更新一个线程

使用 UpdateTopic 更新聊天线程主题。

• topic 用于描述为线程更新的主题。

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

消息操作

发送一条消息

使用 SendMessage 向线程发送消息。

• 使用 content 提供消息的内容，这是必需的。
• 使用 type 指定消息的内容类型，例如 'Text' 或 'Html'。如果没有指定，将设置 'Text'。
• 使用 senderDisplayName 指定发送者的显示名称。如果没有指定，将设置空字符串。

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

获取一条消息

使用 GetMessage 从服务中检索消息。 messageId 是消息的唯一标识符。

ChatMessage 是获取消息时返回的响应，它包含一个id，这是消息的唯一标识符，以及其他字段。请参阅 Azure.Communication.Chat.ChatMessage

ChatMessage chatMessage = await chatThreadClient.GetMessageAsync(messageId);

获取消息

使用 GetMessages 获取聊天线程的所有消息。

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

更新一条消息

使用 UpdateMessage 更新消息。

• messageId 是消息的唯一标识符。
• content 是要更新的消息内容。

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

删除一条消息

使用 DeleteMessage 删除消息。

• messageId 是消息的唯一标识符。

await chatThreadClient.DeleteMessageAsync(messageId);

线程参与者操作

获取线程参与者

使用 GetParticipants 检索聊天线程的参与者。

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

添加线程参与者

使用 向聊天线程添加一个或多个参与者。以下是为每个线程参与者支持的属性

• communicationUser，必需，它是线程参与者的标识。
• displayName，可选，是线程参与者的显示名称。
• shareHistoryTime，可选，是从此时开始与参与者共享聊天历史的时间。

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

await chatThreadClient.AddParticipantsAsync(participants);

移除线程参与者

使用 RemoveParticipant 从线程中移除线程参与者。 communicationUser 是聊天参与者的标识。

await chatThreadClient.RemoveParticipantAsync(gloria);

事件操作

发送打字通知

使用 SendTypingNotification 表明用户正在线程中键入响应。

await chatThreadClient.SendTypingNotificationAsync();

发送已读回执

使用 SendReadReceipt 通知其他参与者消息已被用户阅读。

await chatThreadClient.SendReadReceiptAsync(messageId);

获取已读回执

使用 GetReadReceipts 检查消息的状态，以查看哪些被聊天线程的其他参与者阅读。

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

故障排除

服务响应

对于任何不成功的请求，都会抛出 RequestFailedException 作为服务响应。异常包含有关从服务返回的响应代码的信息。

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

后续步骤

在 Azure Communication Services 中了解有关 Chat 的更多信息

贡献力量

此项目欢迎贡献和建议。大多数贡献需要您同意一项贡献者许可协议（CLA），声明您有权并实际授权我们使用您的贡献。有关详细信息，请访问 cla.microsoft.com。

此项目采用了 Microsoft Open Source Code of Conduct。有关更多信息，请参阅Code of Conduct FAQ，或通过[email protected]与任何额外的疑问或评论联系。