Клиентская библиотека Azure Web PubSub для .NET

Замечание

Сведения об терминах, используемых здесь, описаны в статье основных понятий .

Клиентский пакет SDK направлен на ускорение рабочего процесса разработчика; в частности,

• упрощение управления клиентскими подключениями
• упрощает отправку сообщений между клиентами
• автоматически переподключается после случайного разрыва подключения клиента
• надежно доставляет сообщения в нужном количестве и порядке после восстановления после обрывов соединений

Как показано на схеме, ваши клиенты устанавливают подключения WebSocket к вашему ресурсу Web PubSub.

Начало работы

Установите пакет

Установите клиентную библиотеку из NuGet:

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

Предпосылки

• подписка Azure
• Существующий экземпляр Web PubSub

аутентификация клиента;

Клиент использует Client Access URL для подключения и проверки подлинности в службе. Client Access URL следует шаблону, как и wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Существует несколько способов получения Client Access URL. В качестве быстрого начала можно скопировать и вставить на портале Azure, а для рабочей среды обычно требуется сервер переговоров для создания Client Access URL. См. подробные сведения.

Использование URL-адреса клиентского доступа на портале Azure

Чтобы быстро начать, перейдите на портал Azure и скопируйте URL-адрес клиентского доступа из вкладки Ключи.

Как показано на схеме, клиент получает разрешение на отправку сообщений определенным группам и присоединение к определенным группам. Дополнительные сведения о разрешении клиента см. в разделе "Разрешения".

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

Использовать сервер переговоров для генерации Client Access URL

В производственной среде клиент обычно извлекает Client Access URL с сервера согласования. Сервер содержит connection string и создает Client Access URL через WebPubSubServiceClient. В качестве примера фрагмент кода просто демонстрирует, как создать Client Access URL внутри одного процесса.

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

Функции для различения WebPubSubClient и WebPubSubServiceClient.

Имя класса	WebPubSubClient	WebPubSubServiceClient
Имя пакета NuGet	Azure.Messaging.WebPubSub.Client	Azure.Messaging.WebPubSub
Функции	Используется на стороне клиента. Публикация сообщений и подписка на сообщения.	Используется на стороне сервера. Создание URI клиентского доступа и управление клиентами

Примеры

Использование сообщений с сервера и групп

Клиент может добавлять обратные вызовы для обработки сообщений с сервера и групп. Обратите внимание, что клиенты могут получать только групповые сообщения, к которым они присоединились.

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

Добавьте обратные вызовы для событий connected, disconnected и stopped

При подключении клиента к службе событие connected активируется после получения сообщения о подключении от службы.

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

При разрыве подключения клиента и невозможности его восстановления срабатывает событие disconnected.

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

Когда клиент остановлен, это означает, что подключение клиента отключено, и клиент перестает пытаться повторно подключиться, stopped событие активируется. Обычно это происходит после вызова client.StopAsync() или отключения AutoReconnect. Если вы хотите перезапустить клиент, вызовите client.StartAsync() в событии Stopped.

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

Автоматическое повторное присоединение групп и обработка сбоя повторного подключения

Если подключение клиента пропало и не удается восстановить, все контексты групп очищаются на стороне службы. Это означает, что при повторном подключении клиента необходимо повторно присоединиться к группам. По умолчанию клиент включил параметры AutoRejoinGroups. Однако эта функция имеет ограничения. Клиент может повторно присоединиться только к группам, которые изначально присоединяются клиентом, а не присоединяются к серверу. Повторное подключение к операциям группы может не удаваться по различным причинам, например, у клиента нет разрешения на присоединение к группам. В таких случаях пользователям необходимо добавить обратный вызов для обработки такого сбоя.

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

Операция и повторная попытка

По умолчанию операция, например client.JoinGroupAsync()client.LeaveGroupAsync(), client.SendToGroupAsync()client.SendEventAsync() имеет три повтора. Вы можете использовать WebPubSubClientOptions.MessageRetryOptions для изменения. Если произошел сбой всех повторных попыток, возникает ошибка. Вы можете продолжать пытаться, передав ту же ackId что и в предыдущих попытках, таким образом, служба может помочь в дедупликации операции, используя тот же 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);
    }
}

Устранение неполадок

Включение журналов

Чтобы получить журналы отладки при использовании этой библиотеки, можно задать следующую переменную среды.

export AZURE_LOG_LEVEL=verbose

Дополнительные инструкции по включению журналов см. в документации по пакету @azure/loger.

Интерактивная трассировка

Используйте средство динамической трассировки с портала Azure, чтобы проверить динамический трафик сообщений через ресурс Web PubSub.