Azure Web PubSub-clientbibliotheek voor .NET

De SDK aan de clientzijde wil de werkstroom van ontwikkelaars versnellen; meer specifiek,

• vereenvoudigt het beheren van clientverbindingen
• vereenvoudigt het verzenden van berichten tussen clients
• automatisch opnieuw proberen na onbedoelde uitval van clientverbinding
• betrouwbaar levert berichten qua aantal en volgorde na herstel van verbinding onderbrekingen

Zoals in het diagram wordt weergegeven, maken uw clients WebSocket-verbindingen met uw Web PubSub-resource.

Aan de slag

Installeer het pakket

Installeer de clientbibliotheek vanuit NuGet:

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

Vereiste voorwaarden

• Een Azure-abonnement
• Een bestaand Web PubSub-exemplaar

De client verifiëren

Een client gebruikt een Client Access URL om verbinding te maken en zich bij de service te authentiseren. Client Access URL volgt het patroon als wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Er zijn meerdere manieren om een Client Access URL. Als snelle start kunt u kopiëren en plakken vanuit de Azure-portal, en voor productie hebt u meestal een onderhandelingsserver nodig om Client Access URL te genereren. Bekijk details.

URL voor clienttoegang gebruiken vanuit De Azure-portal

Als u snel aan de slag wilt gaan, kunt u naar de Azure portal gaan en de URL voor clienttoegang kopiëren vanaf de blade 'Sleutels'.

Zoals in het diagram wordt weergegeven, krijgt de client toestemming om berichten naar specifieke groepen te verzenden en lid te worden van specifieke groepen. Meer informatie over clientmachtigingen vindt u onder machtigingen.

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

Onderhandelingsserver gebruiken om te genereren Client Access URL

In productie haalt een client meestal de Client Access URL van een onderhandelingsserver op. De server bevat de connection string en genereert de Client Access URL via WebPubSubServiceClient. Als voorbeeld laat het codefragment zien hoe u het Client Access URL binnen één proces genereert.

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

Functies om onderscheid te maken WebPubSubClient en WebPubSubServiceClient.

Voorbeelden

Berichten van de server en groepen gebruiken

Een client kan callbacks toevoegen om berichten van de server en groepen te gebruiken. Houd er rekening mee dat clients alleen groepsberichten kunnen ontvangen die eraan zijn toegevoegd.

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

Callbacks voor connected, disconnecteden stopped gebeurtenissen toevoegen

Wanneer een clientverbinding is verbonden met de service, wordt de connected gebeurtenis geactiveerd zodra deze het verbonden bericht van de service heeft ontvangen.

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

Wanneer een clientverbinding is verbroken en niet kan worden hersteld, wordt de disconnected gebeurtenis geactiveerd.

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

Wanneer een client is gestopt, wat betekent dat de clientverbinding is verbroken en de client stopt met opnieuw verbinding maken, wordt de stopped gebeurtenis geactiveerd. Dit gebeurt meestal nadat de client.StopAsync() is aangeroepen of de AutoReconnect is uitgeschakeld. Als u de client opnieuw wilt starten, kunt u client.StartAsync() aanroepen in de Stopped gebeurtenis.

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

Automatisch opnieuw deelnemen aan groepen en fout bij opnieuw deelnemen afhandelen

Wanneer een clientverbinding is verbroken en niet kan worden hersteld, worden alle groepscontexten aan de servicezijde opgeschoond. Dat betekent dat wanneer de client opnieuw verbinding maakt, de client opnieuw moet deelnemen aan groepen. Standaard zijn de clientopties ingeschakeld AutoRejoinGroups. Deze functie heeft echter beperkingen. De client kan alleen opnieuw deelnemen aan groepen die oorspronkelijk zijn gekoppeld door de client in plaats van lid te worden van de server. En het opnieuw deelnemen aan groepsbewerkingen kan om verschillende redenen mislukken, bijvoorbeeld omdat de client niet gemachtigd is om lid te worden van groepen. In dergelijke gevallen moeten gebruikers een callback toevoegen om dergelijke fouten af te handelen.

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

Bewerking en nieuwe poging

Standaard heeft de bewerking, zoals client.JoinGroupAsync(), client.LeaveGroupAsync(), client.SendToGroupAsync(), client.SendEventAsync(), drie herhalingen. U kunt dit gebruiken WebPubSubClientOptions.MessageRetryOptions om te wijzigen. Als alle herhaalde pogingen zijn mislukt, wordt een fout geworpen. U kunt het opnieuw proberen door hetzelfde ackId door te geven als bij eerdere pogingen, zodat de service kan helpen om de bewerking met dezelfde ackId te ontdubbelen.

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

Probleemoplossingsproces

Logboeken inschakelen

U kunt de volgende omgevingsvariabele instellen om de logboeken voor foutopsporing op te halen bij het gebruik van deze bibliotheek.

export AZURE_LOG_LEVEL=verbose

Voor meer gedetailleerde instructies over het inschakelen van logboeken, kunt u de @azure/logger pakketdocumentenbekijken.

Live Trace

Gebruik het hulpprogramma Live Trace vanuit de Azure-portal om live berichtenverkeer te inspecteren via uw Web PubSub-resource.