Azure Communication Chat-Clientbibliothek für .NET – Version 1.1.2

  • Artikel

Dieses Paket enthält ein C#-SDK für Azure Communication Services für Den Chat.

Quellcode | Paket (NuGet) | Produktdokumentation

Erste Schritte

Installieren des Pakets

Installieren Sie die Azure Communication Chat-Clientbibliothek für .NET mit NuGet:

dotnet add package Azure.Communication.Chat

Voraussetzungen

Sie benötigen ein Azure-Abonnement und eine Communication Service-Ressource , um dieses Paket verwenden zu können.

Um einen neuen Communication Service zu erstellen, können Sie das Azure-Portal, die Azure PowerShell oder die .NET-Verwaltungsclientbibliothek verwenden.

Authentifizieren des Clients

Benutzer-Zugriffstoken

Mit Benutzerzugriffstoken können Sie Clientanwendungen erstellen, die gegenüber Azure Communication Services direkt authentifiziert werden. Informationen zur Generierung von Benutzerzugriffstoken finden Sie unter Benutzerzugriffstoken.

Verwenden von Anweisungen

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

Erstellen eines ChatClients

Dadurch können Sie Chatthreads erstellen, abrufen oder löschen.

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

Erstellen eines ChatThreadClient

Mit dem ChatThreadClient können Sie spezifische Vorgänge für einen Chatthread ausführen, z. B. das Aktualisieren des Chatthreadthemas, das Senden einer Nachricht, das Hinzufügen von Teilnehmern zum Chatthread usw.

Sie können einen neuen ChatThreadClient mithilfe des GetChatThread-Vorgangs des ChatClient mit einer vorhandenen Thread-ID instanziieren:

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

Wichtige Begriffe

Eine Chatunterhaltung wird durch einen Thread dargestellt. Jeder Benutzer im Thread wird als Threadteilnehmer bezeichnet. Threadteilnehmer können privat in einem 1:1-Chat miteinander chatten oder sich in einem 1:N-Gruppenchat zusammenraufen. Benutzer erhalten außerdem nahezu in Echtzeit Updates für den Zeitpunkt, an dem andere Personen eingeben und die Nachrichten gelesen haben.

Nachdem Sie eine ChatClient Klasse initialisiert haben, können Sie die folgenden Chatvorgänge ausführen:

Erstellen eines Threads

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

Thread abrufen

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

Abrufen aller Threads für den Benutzer

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

Löschen eines Threads

chatClient.DeleteChatThread(chatThread.Id);

Nachdem Sie eine ChatThreadClient Klasse initialisiert haben, können Sie die folgenden Chatvorgänge ausführen:

Aktualisieren eines Threads

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

Senden einer Nachricht

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

Aktualisieren einer Nachricht

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

Abrufen einer Nachricht

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

Löschen einer Nachricht

chatThreadClient.DeleteMessage(sendChatMessageResult.Id);

Nachrichten abrufen

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

Abrufen einer Teilnehmerliste

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

Hinzufügen von Teilnehmern

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

Entfernen eines Teilnehmers

chatThreadClient.RemoveParticipant(identifier: participantIdentifier);

Senden einer Tippbenachrichtigung

chatThreadClient.SendTypingNotification();

Abrufen einer Liste mit Lesebestätigungen

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

Senden einer Lesebestätigung

chatThreadClient.SendReadReceipt(sendChatMessageResult.Id);

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und unabhängig voneinander sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Clientoptionen | Zugreifen auf die Antwort | Vorgänge | mit langer AusführungsdauerBehandeln von Fehlern | Diagnose | Spott | Clientlebensdauer

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der gängigsten Aufgaben abdecken, einschließlich:

Threadvorgänge

Erstellen eines Threads

Verwenden Sie CreateChatThread , um ein Chatthreadclientobjekt zu erstellen.

  • Verwenden Sie topic , um ein Threadthema zu geben.
  • Die folgenden Attribute werden für jeden Threadteilnehmer unterstützt:
    • communicationUser, erforderlich, ist dies die Identifikation für den Threadteilnehmer.
    • displayName, optional, ist der Anzeigename für den Threadteilnehmer
    • shareHistoryTime (optional) ist der Zeitpunkt, ab dem der Chatverlauf für den Teilnehmer freigegeben wird.

ChatThreadClient ist das Ergebnis, das vom Erstellen eines Threads zurückgegeben wird. Sie können es verwenden, um andere Vorgänge für den Chatthread auszuführen.

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

Thread abrufen

Verwenden Sie GetChatThread , um einen Chatthread aus dem Dienst abzurufen. threadId ist die eindeutige ID des Threads.

ChatThreadProperties chatThread = await chatThreadClient.GetPropertiesAsync();

Threads abrufen (für einen Teilnehmer)

Verwenden Sie GetChatThreads , um die Liste der Chatthreads für den Teilnehmer abzurufen, der den chatClient instanziiert hat.

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

Löschen eines Threads

Verwenden Sie DeleteChatThread zum Löschen eines Threads. threadId ist die eindeutige ID des Threads.

await chatClient.DeleteChatThreadAsync(threadId);

Aktualisieren eines Threads

Verwenden Sie UpdateTopic , um das Chatthreadthema zu aktualisieren.

  • topic wird verwendet, um das aktualisierte Thema für den Thread zu beschreiben.
await chatThreadClient.UpdateTopicAsync(topic: "new topic !");

Nachrichtenvorgänge

Senden einer Nachricht

Verwenden Sie SendMessage, um eine Nachricht an einen Thread zu senden.

  • Verwenden Sie content, um den Inhalt für die Chatnachricht anzugeben. Dies ist erforderlich.
  • Verwenden Sie type, um den Inhaltstyp der Nachricht anzugeben (beispielsweise „Text“ oder „Html“). Wenn nicht speficiert, wird "Text" festgelegt.
  • Verwenden Sie senderDisplayName, um den Anzeigenamen des Absenders anzugeben. Ohne Angabe wird eine leere Zeichenfolge festgelegt.
SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(content:"hello world");
var messageId = sendChatMessageResult.Id;

Abrufen einer Nachricht

Verwenden Sie GetMessage, um eine Nachricht vom Dienst abzurufen. messageId ist die eindeutige ID der Nachricht.

ChatMessage ist die Antwort, die vom Abrufen einer Nachricht zurückgegeben wird. Sie enthält eine ID, die neben anderen Feldern der eindeutige Bezeichner der Nachricht ist. Weitere Informationen finden Sie unter „Azure.Communication.Chat.ChatMessage“.

ChatMessage chatMessage = await chatThreadClient.GetMessageAsync(messageId);

Nachrichten abrufen

Verwenden Sie GetMessages , um alle Nachrichten für den Chatthread abzurufen.

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

Aktualisieren einer Nachricht

Verwenden Sie UpdateMessage zum Aktualisieren einer Nachricht.

  • messageId ist der eindeutige Bezeichner der Nachricht.
  • content ist der zu aktualisierende Nachrichteninhalt.
await chatThreadClient.UpdateMessageAsync(messageId, "updated message content");

Löschen einer Nachricht

Verwenden Sie DeleteMessage zum Löschen einer Nachricht.

  • messageId ist der eindeutige Bezeichner der Nachricht.
await chatThreadClient.DeleteMessageAsync(messageId);

Threadteilnehmervorgänge

Abrufen der Threadteilnehmer

Verwenden Sie GetParticipants, um die Teilnehmer des Chatthreads abzurufen.

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

Hinzufügen von Threadteilnehmern

Verwenden Sie AddParticipants, um dem Chatthread einen oder mehrere Teilnehmer hinzuzufügen. Für die einzelnen Threadteilnehmer werden jeweils folgende Attribute unterstützt:

  • communicationUser, erforderlich, ist dies die Identifizierung für den Threadteilnehmer.
  • displayName (optional) ist der Anzeigename für den Threadteilnehmer.
  • shareHistoryTime (optional) ist der Zeitpunkt, ab dem der Chatverlauf für den Teilnehmer freigegeben wird.
var participants = new[]
{
    new ChatParticipant(josh) { DisplayName = "Josh" },
    new ChatParticipant(gloria) { DisplayName = "Gloria" },
    new ChatParticipant(amy) { DisplayName = "Amy" }
};

await chatThreadClient.AddParticipantsAsync(participants);

Threadteilnehmer entfernen

Verwenden Sie RemoveParticipant , um einen Threadteilnehmer aus dem Thread zu entfernen. communicationUser ist die Identifikation des Chatteilnehmers.

await chatThreadClient.RemoveParticipantAsync(gloria);

Ereignisvorgänge

Senden einer Eingabebenachrichtigung

Verwenden Sie SendTypingNotification, um anzugeben, dass der Benutzer eine Antwort für den Thread eingibt.

await chatThreadClient.SendTypingNotificationAsync();

Senden einer Lesebestätigung

Verwenden Sie SendReadReceipt, um andere Teilnehmer darüber zu informieren, dass die Nachricht vom Benutzer gelesen wurde.

await chatThreadClient.SendReadReceiptAsync(messageId);

Abrufen von Lesebestätigungen

Verwenden Sie GetReadReceipts, um den Status von Nachrichten zu überprüfen und zu ermitteln, welche Nachrichten von anderen Teilnehmern eines Chatthreads gelesen wurden.

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

Problembehandlung

Dienstantworten

Ein RequestFailedException wird als Dienstantwort für nicht erfolgreiche Anforderungen ausgelöst. Die Ausnahme enthält Informationen darüber, welcher Antwortcode vom Dienst zurückgegeben wurde.

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

Nächste Schritte

Weitere Informationen zum Chat in Azure Communication Services

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.