Использование пакета SDK для управления Azure SignalR

Статья
12/12/2024

Пакет SDK для управления Azure SignalR помогает управлять клиентами SignalR через Служба Azure SignalR напрямую, например широковещательные сообщения. Поэтому этот пакет SDK может быть, но не ограничен использованием в бессерверных средах. Этот пакет SDK можно использовать для управления клиентами SignalR, подключенными к Служба Azure SignalR в любой среде, например в консольном приложении, в функции Azure или на веб-сервере.

Примечание.

Чтобы просмотреть руководства по пакету SDK версии 1.9.x и раньше, перейдите к пакету SDK для управления Служба Azure SignalR (устаревшая версия). Вам также может потребоваться ознакомиться с руководством по миграции.

Внимание

Необработанные строка подключения отображаются в этой статье только для демонстрационных целей.

Строка подключения включает сведения о авторизации, необходимые для доступа к Служба Azure SignalR приложения. Ключ доступа в строке подключения аналогичен паролю привилегированного пользователя для службы. В рабочих средах всегда защищать ключи доступа. Используйте Azure Key Vault для безопасного управления ключами и защиты строка подключения с помощью идентификатора Microsoft Entra и авторизации доступа с помощью идентификатора Microsoft Entra.

Старайтесь не распространять ключи доступа среди других пользователей, жестко программировать их или где-то сохранять в виде обычного текста в открытом доступе для других пользователей. Меняйте свои ключи постоянно, если предполагаете, что они могут быть подобраны.

Функции

Функция	Временный	Постоянный
Broadcast	✔️	✔️
Широковещательная передача, кроме некоторых клиентов	✔️	✔️
Отправка клиенту	✔️	✔️
Отправка клиентам	✔️	✔️
Отправка пользователю	✔️	✔️
Отправка пользователям	✔️	✔️
Оправка группе	✔️	✔️
Отправка в группы	✔️	✔️
Отправка в группу, кроме некоторых клиентов	✔️	✔️
Добавление пользователя в группу	✔️	✔️
Удаление пользователя из группы	✔️	✔️
Проверка того, входит ли пользователь в группу	✔️	✔️

Поддержка нескольких экземпляров службы SignalR	❌	✔️
Поддержка клиентов MessagePack	с версии 1.21.0	с версии 1.20.0
Повторная временная ошибка	с версии 1.22.0	❌

Функции доступны только с новым API

Функция	Временный	Постоянный
Проверка наличия подключения	✔️	С версии 1.11
Проверьте, существует ли группа	✔️	С версии 1.11
Проверьте, существует ли пользователь	✔️	С версии 1.11
Закрытие подключения клиента	✔️	С версии 1.11

Дополнительные сведения о различных режимах см . здесь.
Полный пример пакета SDK для управления можно найти здесь.

Использование

В этом разделе показано, как использовать пакет SDK для управления.

Создание Service Manager

Создание экземпляра ServiceManager из .ServiceManagerBuilder

Необработанные строка подключения отображаются в этой статье только для демонстрационных целей. В рабочих средах всегда защищать ключи доступа. Используйте Azure Key Vault для безопасного управления ключами и защиты строка подключения с помощью идентификатора Microsoft Entra и авторизации доступа с помощью идентификатора Microsoft Entra.


var serviceManager = new ServiceManagerBuilder()
                    .WithOptions(option =>
                    {
                        option.ConnectionString = "<Your Azure SignalR Service Connection String>";
                    })
                    .WithLoggerFactory(loggerFactory)
                    .BuildServiceManager();

Вы можете использовать ServiceManager для проверки работоспособности конечной точки Azure SignalR и создания контекста концентратора служб. В следующем разделе содержатся сведения о создании контекста концентратора служб.

Чтобы проверить работоспособность конечной точки Azure SignalR, можно использовать ServiceManager.IsServiceHealthy метод. Если у вас несколько конечных точек Azure SignalR, проверяется только первая конечная точка.

var health = await serviceManager.IsServiceHealthy(cancellationToken);

Создание контекста Центра служб

Создайте экземпляр ServiceHubContext из :ServiceManager

var serviceHubContext = await serviceManager.CreateHubContextAsync("<Your Hub Name>",cancellationToken);

Переговоры

В режиме по умолчанию конечная точка /<Your Hub Name>/negotiate предоставляется для согласования с помощью пакета SDK Служба Azure SignalR. Клиенты SignalR достигают этой конечной точки, а затем перенаправляются на Служба Azure SignalR позже.

В бессерверном режиме рекомендуется разместить конечную точку переговоров для обслуживания запроса на согласование клиентов SignalR и перенаправления клиентов на Служба Azure SignalR.

Совет

Дополнительные сведения о перенаправлении см. в протоколе переговоров SignalR.

Как конечные точки, так и маркер доступа полезны, если вы хотите перенаправить клиенты SignalR в Служба Azure SignalR.

Экземпляр можно использовать для создания URL-адреса конечной точки и соответствующего ServiceHubContext маркера доступа для клиентов SignalR для подключения к Служба Azure SignalR.

var negotiationResponse = await serviceHubContext.NegotiateAsync(new (){UserId = "<Your User Id>"});

Предположим, что конечная точка концентратора — http://<Your Host Name>/<Your Hub Name>это конечная точка http://<Your Host Name>/<Your Hub Name>/negotiateпереговоров. После размещения конечной точки согласования можно использовать клиенты SignalR для подключения к концентратору следующим образом:

var connection = new HubConnectionBuilder().WithUrl("http://<Your Host Name>/<Your Hub Name>").Build();
await connection.StartAsync();

Пример использования пакета SDK для управления для перенаправления клиентов SignalR в Служба Azure SignalR можно найти здесь.

Отправка сообщений и управление группами

ServiceHubContextBuilder Сборка ServiceHubContext из этого класса, реализующего и IServiceHubContextрасширяющегося. Его можно использовать для отправки сообщений клиентам и управления группами.

try
{
    // Broadcast
    await hubContext.Clients.All.SendAsync(callbackName, obj1, obj2, ...);

    // Send to user
    await hubContext.Clients.User(userId).SendAsync(callbackName, obj1, obj2, ...);

    // Send to group
    await hubContext.Clients.Group(groupId).SendAsync(callbackName, obj1, obj2, ...);

    // add user to group
    await hubContext.UserGroups.AddToGroupAsync(userId, groupName);

    // remove user from group
    await hubContext.UserGroups.RemoveFromGroupAsync(userId, groupName);
}
finally
{
    await hubContext.DisposeAsync();
}

Строго типизированный концентратор

Строго типизированный концентратор — это модель программирования, которую можно извлечь клиентские методы в интерфейс, чтобы избежать ошибок, таких как ошибка имени метода или передача неправильных типов параметров.

Предположим, что у нас есть метод ReceivedMessage клиента с двумя строковыми параметрами. Без строго типизированных центров вы передаете клиентам через hubContext.Clients.All.SendAsync("ReceivedMessage", user, message). При использовании строго типизированных концентраторов сначала необходимо определить интерфейс следующим образом:

public interface IChatClient
{
    Task ReceiveMessage(string user, string message);
}

Затем создается строго типизированный контекст концентратора, реализующий IHubContext<Hub<T>, T>T интерфейс клиентского метода:

ServiceHubContext<IChatClient> serviceHubContext = await serviceManager.CreateHubContextAsync<IChatClient>(hubName, cancellationToken);

Наконец, можно напрямую вызвать метод:

await Clients.All.ReceiveMessage(user, message);

За исключением разницы в отправке сообщений, вы можете вести переговоры или управлять группами так ServiceHubContext<T> же, как ServiceHubContext.

Дополнительные сведения о строго типизированных центрах см. в документации по ASP.NET Core.

Тип транспорта

Этот пакет SDK может взаимодействовать с Служба Azure SignalR двумя типами транспорта:

Временный: создайте HTTP-запрос Служба Azure SignalR для каждого отправленного сообщения. Пакет SDK просто упаковывает Служба Azure SignalR REST API в временный режим. Это полезно, если не удается установить подключение WebSockets.
Постоянное: сначала создайте подключение WebSockets, а затем отправьте все сообщения в этом соединении. Это полезно при отправке большого количества сообщений.

Сводка по поведению сериализации аргументов в сообщениях

Сериализация	Временный	Постоянный
Библиотека JSON по умолчанию	`Newtonsoft.Json`	То же, что и ASP.NET Core SignalR: `Newtonsoft.Json` для .NET Standard 2.0; `System.Text.Json` для .NET Core App 3.1 и более поздних версий
Поддержка клиентов MessagePack	с версии 1.21.0	с версии 1.20.0

Сериализация JSON

В пакете SDK для управления аргументы метода, отправленные клиентам, сериализуются в JSON. У нас есть несколько способов настройки сериализации JSON. Мы показываем все способы в порядке от наиболее рекомендуемого до наименьшего рекомендуемого.

`ServiceManagerOptions.UseJsonObjectSerializer(ObjectSerializer objectSerializer)`

Наиболее рекомендуемым способом является использование общего абстрактного класса ObjectSerializer, так как он поддерживает различные библиотеки сериализации JSON, такие как System.Text.Json и Newtonsoft.Json применяется ко всем типам транспорта. Обычно вам не нужно реализовывать ObjectSerializer себя, так как удобные реализации System.Text.Json JSON и Newtonsoft.Json уже предоставляются.

При использовании System.Text.Json в качестве библиотеки обработки JSON встроенная JsonObjectSerializer используется System.Text.Json.JsonSerializer для сериализации или десериализации. Ниже приведен пример для использования именования верблюдьего регистра для сериализации JSON:
```
var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.ConnectionString = "***";
        o.UseJsonObjectSerializer(new JsonObjectSerializer(new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase
        }));
    })
    .BuildServiceManager();
```

При использовании Newtonsoft.Json в качестве библиотеки обработки JSON сначала установите пакет Microsoft.Azure.Core.NewtonsoftJson из NuGet с помощью .NET CLI:

dotnet add package Microsoft.Azure.Core.NewtonsoftJson

Ниже приведен пример для использования именования верблюдьего регистра с NewtonsoftJsonObjectSerializer:

var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.ConnectionString = "***";
        o.UseJsonObjectSerializer(new NewtonsoftJsonObjectSerializer(new JsonSerializerSettings()
        {
            ContractResolver = new CamelCasePropertyNamesContractResolver()
        }));
    })
    .BuildServiceManager();

При использовании других библиотек обработки JSON

Вы также можете реализовать ObjectSerializer самостоятельно. Следующие ссылки могут помочь:
- Справочник по API ObjectSerializer
- Справочник по API JsonObjectSerializer

`ServiceManagerBuilder.WithNewtonsoftJson(Action<NewtonsoftServiceHubProtocolOptions> configure)`

Этот метод предназначен только для Newtonsoft.Json пользователей. Ниже приведен пример для использования именования верблюдьих вариантов:

var serviceManager = new ServiceManagerBuilder()
    .WithNewtonsoftJson(o =>
    {
        o.PayloadSerializerSettings = new JsonSerializerSettings
        {
            ContractResolver = new CamelCasePropertyNamesContractResolver()
        };
    })
    .BuildServiceManager();

`ServiceManagerOptions.JsonSerializerSettings` (не рекомендуется)

Этот метод применяется только к временному типу транспорта. Не использовать это.

var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.JsonSerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
    })
    .BuildServiceManager();

Сериализация пакета сообщений

Необходимо установить Microsoft.AspNetCore.SignalR.Protocols.MessagePack пакет.
Чтобы добавить протокол MessagePack параллельно с протоколом JSON по умолчанию:
```
var serviceManagerBuilder = new ServiceManagerBuilder()
    .AddHubProtocol(new MessagePackHubProtocol());
```
Для полного управления протоколами концентратора можно использовать
```
    var serviceManagerBuilder = new ServiceManagerBuilder()
        .WithHubProtocols(new MessagePackHubProtocol(), new JsonHubProtocol());
```
WithHubProtocols сначала очищает существующие протоколы, а затем добавляет новые протоколы. Этот метод также можно использовать для удаления протокола JSON и использования MessagePack только.

Для временного режима по умолчанию сторона службы преобразует полезные данные JSON в полезные данные MessagePack, и это устаревший способ поддержки MessagePack. Однако рекомендуется явно добавить протокол Концентратора MessagePack, так как устаревший способ может не работать должным образом.

Повторные попытки HTTP-запросов

В временном режиме этот пакет SDK предоставляет возможность автоматического повторного отправки запросов при возникновении временных ошибок, если запросы идемпотентны. Чтобы включить эту возможность, можно использовать ServiceManagerOptions.RetryOptions свойство.

В частности, извлекаются следующие типы запросов:

Для запросов сообщений, отправляющих сообщения клиентам SignalR, пакет SDK повторяет запрос, если код состояния HTTP-ответа превышает 500. Если код ответа HTTP равен 500, он может указывать время ожидания на стороне службы, а повторная попытка запроса может привести к повторяющимся сообщениям.
Для других типов запросов, таких как добавление подключения к группе, пакет SDK повторяет запрос в следующих условиях:
1. Код состояния ответа HTTP находится в диапазоне 5xx или время ожидания запроса с кодом состояния 408 (время ожидания запроса).
2. Время ожидания запроса истекло с длительностью дольше, чем длина времени ожидания, настроенная в ServiceManagerOptions.HttpClientTimeout.

Пакет SDK может выполнять только повторные идемпотентные запросы, которые не имеют другого эффекта, если они повторяются. Если ваши запросы не идемпотентны, может потребоваться вручную обрабатывать повторные попытки.

Следующие шаги

Из этой статьи вы узнаете, как использовать Служба SignalR в приложениях. Дополнительные сведения о Служба SignalR см. в следующих статьях.

Azure SignalR Service internals (Внутренние компоненты Службы Azure SignalR)

Краткое руководство. Создание комнаты чата с помощью Служба SignalR

Поделиться через

Использование пакета SDK для управления Azure SignalR

Функции

Использование

Создание Service Manager

Создание контекста Центра служб

Переговоры

Отправка сообщений и управление группами

Строго типизированный концентратор

Тип транспорта

Сводка по поведению сериализации аргументов в сообщениях

Сериализация JSON

`ServiceManagerOptions.UseJsonObjectSerializer(ObjectSerializer objectSerializer)`

`ServiceManagerBuilder.WithNewtonsoftJson(Action<NewtonsoftServiceHubProtocolOptions> configure)`

`ServiceManagerOptions.JsonSerializerSettings` (не рекомендуется)

Сериализация пакета сообщений

Повторные попытки HTTP-запросов

Следующие шаги

Обратная связь

Дополнительные ресурсы

Поделиться через

Использование пакета SDK для управления Azure SignalR

Функции

Использование

Создание Service Manager

Создание контекста Центра служб

Переговоры

Отправка сообщений и управление группами

Строго типизированный концентратор

Тип транспорта

Сводка по поведению сериализации аргументов в сообщениях

Сериализация JSON

ServiceManagerOptions.UseJsonObjectSerializer(ObjectSerializer objectSerializer)

ServiceManagerBuilder.WithNewtonsoftJson(Action<NewtonsoftServiceHubProtocolOptions> configure)

ServiceManagerOptions.JsonSerializerSettings (не рекомендуется)

Сериализация пакета сообщений

Повторные попытки HTTP-запросов

Следующие шаги

Обратная связь

Дополнительные ресурсы

`ServiceManagerOptions.UseJsonObjectSerializer(ObjectSerializer objectSerializer)`

`ServiceManagerBuilder.WithNewtonsoftJson(Action<NewtonsoftServiceHubProtocolOptions> configure)`

`ServiceManagerOptions.JsonSerializerSettings` (не рекомендуется)