Libreria client PubSub di Azure per .NET

L'SDK lato client mira a velocizzare il flusso di lavoro dello sviluppatore; più in particolare,

• semplifica la gestione delle connessioni client
• semplifica l'invio di messaggi tra i client
• Riprova automaticamente dopo cadute impreviste della connessione del client.
• recapita in modo affidabile i messaggi in numero e in ordine dopo il ripristino dalla caduta della connessione

Come illustrato nel diagramma, i client stabiliscono connessioni WebSocket con la risorsa Web PubSub.

Come iniziare

Installare il pacchetto

Installare la libreria client da NuGet:

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

Prerequisiti

• Una sottoscrizione di Azure
• Un'istanza Web PubSub esistente

Autenticare il client

Un client usa un Client Access URL oggetto per connettersi ed eseguire l'autenticazione con il servizio. Client Access URL segue il modello come wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Esistono diversi modi per ottenere un oggetto Client Access URL. Come inizio rapido, è possibile copiare e incollare dal portale di Azure, e per la produzione di solito è necessario un server di negoziazione per generare Client Access URL. Vedere i dettagli.

Usare l'URL Accesso Client dal portale di Azure

Come avvio rapido, puoi accedere al portale di Azure e copiare l'URL di accesso client dal pannello Chiavi.

Come illustrato nel diagramma, al client viene concessa l'autorizzazione per l'invio di messaggi a gruppi specifici e l'aggiunta a gruppi specifici. Ulteriori informazioni sui permessi client, vedere autorizzazioni.

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

Usare il server di negoziazione per generare Client Access URL

Nell'ambiente di produzione, un client recupera in genere l'oggetto Client Access URL da un server di negoziazione. Il server contiene connection string e genera l'oggetto Client Access URL tramite WebPubSubServiceClient. Come esempio, il frammento di codice illustra semplicemente come generare l'oggetto Client Access URL all'interno di un singolo processo.

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

Funzionalità per distinguere WebPubSubClient e WebPubSubServiceClient.

Esempi

Consumare messaggi dal server e dai gruppi

Un client può aggiungere callback per consumare messaggi dal server e dai gruppi. Si noti che i client possono ricevere solo messaggi di gruppo a cui hanno aderito.

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

Aggiungere callback per gli eventi connected, disconnected e stopped

Quando una connessione client è connessa al servizio, l'evento connected viene attivato dopo aver ricevuto il messaggio connesso dal servizio.

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

Quando una connessione client viene disconnessa e non riesce a eseguire il ripristino, l'evento disconnected viene attivato.

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

Quando un client viene arrestato, il che significa che la connessione client viene disconnessa e il client smette di tentare di riconnettersi, l'evento stopped viene attivato. Ciò si verifica in genere dopo che viene chiamato il client.StopAsync() o disabilitato il AutoReconnect. Se si vuole riavviare il client, è possibile chiamare client.StartAsync() nell'evento Stopped .

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

Riconnetti automaticamente i gruppi e gestire l'errore di riconnessione

Quando una connessione client si è interrotta e non riesce a recuperare, tutti i contesti di gruppo vengono puliti sul lato del servizio. Ciò significa che quando il client si riconnette, deve riconnettersi ai gruppi. Per impostazione predefinita, il client ha abilitato le opzioni AutoRejoinGroups. Tuttavia, questa funzionalità presenta limitazioni. Il client può solo riunirsi ai gruppi a cui si è originariamente unito dal client piuttosto che a quelli uniti dal server. Inoltre, le operazioni di rientro nel gruppo potrebbero non riuscire a causa di vari motivi, ad esempio il client non dispone dell'autorizzazione per unirsi ai gruppi. In questi casi, gli utenti devono aggiungere un callback per gestire tale errore.

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

Operazione e ripetizione dei tentativi

Per impostazione predefinita, operazioni come client.JoinGroupAsync(), client.LeaveGroupAsync(), client.SendToGroupAsync() e client.SendEventAsync() hanno tre tentativi. È possibile usare WebPubSubClientOptions.MessageRetryOptions per modificare. Se tutti i tentativi non sono riusciti, viene generato un errore. È possibile continuare a ripetere i tentativi passando lo stesso ackId dei tentativi precedenti, così il servizio può aiutare a deduplicare l'operazione con lo stesso 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);
    }
}

Risoluzione dei problemi

Abilitare i log

È possibile impostare la variabile di ambiente seguente per ottenere i log di debug quando si usa questa libreria.

export AZURE_LOG_LEVEL=verbose

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.

Tracciamento in tempo reale

Usare lo strumento Live Trace dal portale di Azure per esaminare il traffico dei messaggi live tramite la risorsa Web PubSub.