通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure 通信聊天客户端库 - 版本 1.1.2

  • 项目

此包包含用于聊天Azure 通信服务的 C# SDK。

源代码 | 包 (NuGet) | 产品文档

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 通信聊天客户端库：

dotnet add package Azure.Communication.Chat

先决条件

需要 Azure 订阅 和 通信服务资源 才能使用此包。

若要创建新的通信服务，可以使用 Azure 门户、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 是线程的唯一 ID。

ChatThreadProperties chatThread = await chatThreadClient.GetPropertiesAsync();

获取参与者) 的线程 (

使用 GetChatThreads 获取实例化 chatClient 的参与者的聊天线程列表。

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

删除线程

使用 DeleteChatThread 删除线程。 threadId 是线程的唯一 ID。

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 是消息的唯一 ID。

ChatMessage 是从获取消息返回的响应，它包含 ID，该 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}");
}

添加线程参与者

使用 AddParticipants 将一个或多个参与者添加到聊天会话。 下面是对每个会话参与者支持的属性：

  • 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 通信服务 中的聊天

贡献

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 cla.microsoft.com。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。