Azure Web PubSub-klientbibliotek för .NET

SDK:et på klientsidan syftar till att påskynda utvecklarens arbetsflöde. mer specifikt,

• förenklar hanteringen av klientanslutningar
• förenklar sändning av meddelanden mellan klienter
• Försöker automatiskt igen efter oavsiktliga avbrott i klientuppkopplingen
• Tillförlitlig leverans av meddelanden i rätt antal och ordning efter att ha återhämtat sig från anslutningsavbrott

Som du ser i diagrammet upprättar klienterna WebSocket-anslutningar med din Web PubSub-resurs.

Komma igång

Installera paketet

Installera klientbiblioteket från NuGet:

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

Förutsättningar

• En prenumeration på Azure
• En befintlig Web PubSub-instans

Autentisera klienten

En klient använder en Client Access URL för att ansluta och autentisera med tjänsten. Client Access URL följer mönstret som wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Det finns flera sätt att hämta en Client Access URL. Som en snabbstart kan du kopiera och klistra in från Azure-portalen, och för produktion behöver du vanligtvis en förhandlingsserver för att generera Client Access URL. Se detaljer.

Använda URL för klientåtkomst från Azure-portalen

Som en snabbstart kan du gå till Azure-portalen och kopiera URL:en för klientåtkomst från bladet Nycklar .

Som du ser i diagrammet beviljas klienten behörighet att skicka meddelanden till specifika grupper och ansluta till specifika grupper. Mer information om klientbehörighet finns i behörigheter.

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

Använda förhandlingsservern för att generera Client Access URL

I produktion hämtar en klient vanligtvis Client Access URL från en förhandlingsserver. Servern innehåller connection string och genererar Client Access URL via WebPubSubServiceClient. Som ett exempel visar kodfragmentet bara hur du genererar Client Access URL inuti en enda process.

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

Funktioner för att särskilja WebPubSubClient och WebPubSubServiceClient.

Exempel

Konsumera meddelanden från servern och grupperna

En klient kan lägga till callbacks för att ta emot meddelanden från servern och grupper. Observera att klienter bara kan ta emot gruppmeddelanden som de själva har gått med i.

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

Lägga till återanrop för connected, disconnectedoch stopped händelser

När en klientanslutning är ansluten till tjänsten connected utlöses händelsen när den har tagit emot det anslutna meddelandet från tjänsten.

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

När en klientanslutning kopplas från och inte kan återställas disconnected utlöses händelsen.

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

När en klient stoppas, vilket innebär att klientanslutningen är frånkopplad och klienten slutar försöka återansluta, stopped utlöses händelsen. Detta inträffar vanligtvis efter att client.StopAsync() anropas eller inaktiverats AutoReconnect. Om du vill starta om klienten kan du anropa client.StartAsync() under Stopped-händelsen.

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

Automatiskt återanslut grupper och hantera återanslutningsfel

När en klientanslutning har avbrutits och inte kan återställas, rensas alla gruppkontexter på tjänstsidan. Det innebär att när klienten återansluter måste den återansluta till grupper. Som standard är klientalternativen aktiverade AutoRejoinGroups. Den här funktionen har dock begränsningar. Klienten kan bara återansluta till grupper som den ursprungligen är ansluten till av klienten i stället för att vara ansluten till serversidan. Återanslutning till gruppåtgärder kan misslyckas av olika skäl, till exempel om klienten inte har behörighet att ansluta till grupper. I sådana fall måste användarna lägga till ett återanrop för att hantera ett sådant fel.

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

Åtgärd och försök igen

Som standard har åtgärden client.JoinGroupAsync(), client.LeaveGroupAsync(), client.SendToGroupAsync(), client.SendEventAsync() tre omförsök. Du kan använda WebPubSubClientOptions.MessageRetryOptions för att ändra. Om alla återförsök har misslyckats utlöses ett fel. Du kan fortsätta att försöka igen genom att skicka in samma ackId som tidigare återförsök, så tjänsten kan hjälpa till att deduplicera åtgärden med samma ackId.

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

Felsökning

Aktivera loggar

Du kan ange följande miljövariabel för att hämta felsökningsloggarna när du använder det här biblioteket.

export AZURE_LOG_LEVEL=verbose

Mer detaljerade anvisningar om hur du aktiverar loggar finns i dokument för @azure/logger-paket.

Livespårning

Använd livespårningsverktyget från Azure-portalen för att inspektera livemeddelandetrafik via din Web PubSub-resurs.