Azure Web PubSub-Clientbibliothek für .NET

Das clientseitige SDK zielt darauf ab, den Workflow des Entwicklers zu beschleunigen; genauer gesagt:

• vereinfacht die Verwaltung von Clientverbindungen
• vereinfacht das Senden von Nachrichten zwischen Clients
• automatisches Wiederholen nach unbeabsichtigten Abbrüchen der Clientverbindung
• stellt Nachrichten zuverlässig in der richtigen Anzahl und Reihenfolge nach Wiederherstellung einer unterbrochenen Verbindung bereit

Wie im Diagramm dargestellt, richten Ihre Clients WebSocket-Verbindungen mit Ihrer Web PubSub-Ressource ein.

Erste Schritte

Installiere das Paket

Installieren Sie die Clientbibliothek von NuGet:

dotnet add package Azure.Messaging.WebPubSub.Client --prerelease

Voraussetzungen

• Ein Azure-Abonnement
• Eine vorhandene Web PubSub-Instanz

Authentifizieren des Clients

Ein Client verwendet ein Client Access URL, um sich mit dem Dienst zu verbinden und zu authentifizieren. Client Access URL folgt dem Muster als wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Es gibt mehrere Möglichkeiten, einen Client Access URL zu erhalten. Als Schnellstart können Sie Inhalte aus dem Azure-Portal kopieren und einfügen. Für die Produktion benötigen Sie in der Regel einen Aushandlungsserver zur Generierung von Client Access URL. Details anzeigen.

Verwenden der Clientzugriffs-URL über das Azure-Portal

Als Schnellstart können Sie zum Azure-Portal wechseln und die Clientzugriffs-URL vom Blatt "Schlüssel" kopieren.

Wie im Diagramm dargestellt, erhält der Client die Berechtigung zum Senden von Nachrichten an bestimmte Gruppen und das Beitreten zu bestimmten Gruppen. Weitere Informationen zu Clientberechtigungen finden Sie unter "Berechtigungen".

var client = new WebPubSubClient(new Uri("<client-access-uri>"));

Verwenden Sie den Aushandlungsserver zum Generieren Client Access URL

In der Produktion ruft ein Client in der Regel das Client Access URL von einem Aushandlungsserver ab. Der Server speichert die connection string und generiert die Client Access URL durch WebPubSubServiceClient. Als Beispiel veranschaulicht der Codeausschnitt lediglich, wie die Client Access URL innerhalb eines einzelnen Prozesses generiert wird.

var client = new WebPubSubClient(new WebPubSubClientCredential(token =>
{
    // In common practice, you will have a negotiation server for generating token. Client should fetch token from it.
    return FetchClientAccessTokenFromServerAsync(token);
}));

public async ValueTask<Uri> FetchClientAccessTokenFromServerAsync(CancellationToken token)
{
    var serviceClient = new WebPubSubServiceClient("<< Connection String >>", "hub");
    return await serviceClient.GetClientAccessUriAsync();
}

Funktionen zur Unterscheidung WebPubSubClient und WebPubSubServiceClient.

Beispiele

Nutzen von Nachrichten vom Server und von Gruppen

Ein Client kann Rückrufe hinzufügen, um Nachrichten vom Server und von Gruppen zu nutzen. Beachten Sie, dass Clients nur Gruppennachrichten empfangen können, denen sie beigetreten sind.

client.ServerMessageReceived += eventArgs =>
{
    Console.WriteLine($"Receive message: {eventArgs.Message.Data}");
    return Task.CompletedTask;
};

client.GroupMessageReceived += eventArgs =>
{
    Console.WriteLine($"Receive group message from {eventArgs.Message.Group}: {eventArgs.Message.Data}");
    return Task.CompletedTask;
};

Hinzufügen von Rückrufen für connected, disconnectedund stopped Ereignisse

Wenn eine Clientverbindung mit dem Dienst verbunden ist, wird das connected Ereignis ausgelöst, nachdem die verbundene Nachricht vom Dienst empfangen wurde.

client.Connected += eventArgs =>
{
    Console.WriteLine($"Connection {eventArgs.ConnectionId} is connected");
    return Task.CompletedTask;
};

Wenn eine Clientverbindung getrennt wird und die Wiederherstellung fehlschlägt, wird das disconnected Ereignis ausgelöst.

client.Disconnected += eventArgs =>
{
    Console.WriteLine($"Connection is disconnected");
    return Task.CompletedTask;
};

Wenn ein Client gestoppt wird, was bedeutet, dass die Clientverbindung getrennt wird und der Client aufhört, sich erneut zu verbinden, wird das stopped Ereignis ausgelöst. Dies geschieht in der Regel, nachdem client.StopAsync() aufgerufen wird oder AutoReconnect deaktiviert wird. Wenn Sie den Client neu starten möchten, können Sie client.StartAsync() im Stopped-Ereignis aufrufen.

client.Stopped += eventArgs =>
{
    Console.WriteLine($"Client is stopped");
    return Task.CompletedTask;
};

Automatischer erneuter Beitritt von Gruppen und Umgang mit fehlgeschlagenen erneuten Beitritten

Wenn eine Clientverbindung gelöscht wurde und nicht wiederhergestellt werden kann, werden alle Gruppenkontexte auf der Dienstseite bereinigt. Das bedeutet, wenn der Client erneut eine Verbindung herstellen kann, muss er erneut an Gruppen teilnehmen. Standardmäßig hat der Client die Optionen AutoRejoinGroups aktiviert. Dieses Feature hat jedoch Einschränkungen. Der Client kann nur Gruppen erneut beitreten, denen er ursprünglich selbst beigetreten ist, anstatt vom Server hinzugefügt worden zu sein. Und das Wiederherstellen von Gruppenoperationen kann aus verschiedenen Gründen fehlschlagen, zum Beispiel, wenn der Client keine Berechtigung hat, Gruppen beizutreten. In solchen Fällen müssen Benutzer einen Rückruf hinzufügen, um einen solchen Fehler zu behandeln.

client.RejoinGroupFailed += eventArgs =>
{
    Console.WriteLine($"Restore group failed");
    return Task.CompletedTask;
};

Vorgang und Wiederholen

Standardmäßig weist der Vorgang wie client.JoinGroupAsync(), client.LeaveGroupAsync(), client.SendToGroupAsync(), client.SendEventAsync() drei Wiederholungen auf. Sie können WebPubSubClientOptions.MessageRetryOptions verwenden, um etwas zu ändern. Wenn alle Wiederholungen fehlgeschlagen sind, wird ein Fehler ausgelöst. Sie können den Vorgang weiterhin wiederholen, indem Sie dieselben ackId wie bei vorherigen Wiederholungen übergeben, damit der Dienst dazu beitragen kann, den Vorgang mit demselben ackIdzu deduplizieren.

// Send message to group "testGroup"
try
{
    await client.JoinGroupAsync("testGroup");
}
catch (SendMessageFailedException ex)
{
    if (ex.AckId != null)
    {
        await client.JoinGroupAsync("testGroup", ackId: ex.AckId);
    }
}

Problembehandlung

Aktivieren von Protokollen

Sie können die folgende Umgebungsvariable festlegen, um die Debugprotokolle abzurufen, wenn Sie diese Bibliothek verwenden.

export AZURE_LOG_LEVEL=verbose

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Live-Ablaufverfolgung

Verwenden Sie das Live Trace-Tool aus dem Azure-Portal, um den Livenachrichtendatenverkehr über Ihre Web PubSub-Ressource zu überprüfen.