Klientská knihovna Azure Web PubSub pro .NET

Poznámka:

Podrobnosti o zde použitých termínech jsou popsány v klíčovém článku o konceptech .

Cílem sady SDK na straně klienta je urychlit pracovní postup vývojáře; konkrétněji,

• zjednodušuje správu klientských připojení.
• zjednodušuje odesílání zpráv mezi klienty.
• automaticky znovu připojí po nezamýšlených výpadcích připojení klienta
• spolehlivě doručuje zprávy v počtu a v pořadí po obnovení spojení po výpadcích

Jak znázorňuje diagram, vaši klienti navazují připojení WebSocket s vaší službou Web PubSub.

Začínáme

Nainstalujte balíček

Nainstalujte klientskou knihovnu z NuGetu:

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

Předpoklady

• Předplatné Azure
• Existující instance Web PubSub

Ověření klienta

Klient se pomocí Client Access URL připojuje ke službě a ověřuje se. Client Access URL se řídí vzorem jako wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Existuje několik způsobů, jak získat Client Access URL. Jako rychlý start můžete kopírovat a vkládat z portálu Azure, a pro produkční prostředí obvykle potřebujete vyjednávací server k vygenerování Client Access URL. Prohlédněte podrobnosti.

Použití adresy URL klientského přístupu z webu Azure Portal

Jako rychlý start můžete přejít na Web Azure Portal a zkopírovat adresu URL klientského přístupu z okna Klíče .

Jak je znázorněno v diagramu, klientovi je uděleno oprávnění k odesílání zpráv konkrétním skupinám a připojování ke konkrétním skupinám. Další informace o oprávněních klienta najdete v tématu Oprávnění.

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

Použijte vyjednávací server k vytvoření Client Access URL

V produkčním prostředí klient obvykle načte Client Access URL z vyjednávacího serveru. Server uchovává connection string a generuje Client Access URL prostřednictvím WebPubSubServiceClient. Jako příklad fragment kódu ukazuje, jak vygenerovat Client Access URL uvnitř jednoho procesu.

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

Funkce pro rozlišení WebPubSubClient a WebPubSubServiceClient.

Název třídy	WebPubSubClient	WebPubSubServiceClient
Název balíčku NuGet	Azure.Messaging.WebPubSub.Client	Azure.Messaging.WebPubSub
Features	Používá se na straně klienta. Publikování zpráv a přihlášení k odběru zpráv	Používá se na straně serveru. Generování identifikátoru URI klientského přístupu a správa klientů

Příklady

Využívání zpráv ze serveru a skupin

Klient může přidat zpětná volání pro využívání zpráv ze serveru a skupin. Upozorňujeme, že klienti můžou přijímat jenom zprávy skupiny, ke kterým se připojil.

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

Přidejte zpětná volání pro connected, disconnected a stopped události

Když je klientské připojení ke službě připojeno, connected událost se aktivuje, jakmile obdrží zprávu o připojení ze služby.

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

Když se spojení klienta odpojí a nepodaří se ho obnovit, dojde k aktivaci události disconnected.

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

Když je klient zastavený, což znamená, že je připojení klienta odpojené a klient se přestane pokoušet znovu připojit, stopped aktivuje se událost. K tomu obvykle dochází poté, co je client.StopAsync() zavolán, nebo když je zakázán AutoReconnect. Pokud chcete klienta restartovat, můžete zavolat client.StartAsync() v Stopped události.

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

Automatické opětovné připojení skupin a řešení selhání při opětovném připojení

Když se připojení klienta přeruší a nepodaří se obnovit, všechny kontexty skupiny se vyčistí na straně služby. To znamená, že když se klient znovu připojí, musí se znovu připojit ke skupinám. Ve výchozím nastavení klient povolil AutoRejoinGroups možnosti. Tato funkce má ale omezení. Klient se může znovu připojit pouze ke skupinám, ke kterým byl původně připojen klientem , a ne ke straně serveru. Operace opětovného připojení ke skupinám můžou selhat z různých důvodů, například klient nemá oprávnění ke spojení skupin. V takových případech musí uživatelé přidat zpětné volání, aby takové selhání zvládli.

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

Operace a opakování

Ve výchozím nastavení má operace, například client.JoinGroupAsync(), client.LeaveGroupAsync()client.SendToGroupAsync()client.SendEventAsync() , tři reties. Můžete použít WebPubSubClientOptions.MessageRetryOptions ke změně. Pokud došlo k selhání všech opakovaných pokusů, vyvolá se chyba. Můžete zkusit opakování tím, že zadáte stejný ackId jako při předchozích pokusech, takže služba může pomoci deduplikovat operaci se stejným 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);
    }
}

Řešení problémů

Povolení protokolů

Následující proměnnou prostředí můžete nastavit, abyste při používání této knihovny získali protokoly ladění.

export AZURE_LOG_LEVEL=verbose

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Živé trasování

Pomocí nástroje Živé trasování z portálu Azure můžete sledovat provoz příchozích zpráv prostřednictvím prostředku Web PubSub.