Начало работы с разделами и подписками Служебной шины Azure (.NET)

  • Статья

В этом кратком руководстве показано, как отправлять сообщения в раздел Служебной шины и получать сообщения о подписке на этот раздел с помощью библиотеки .NET для Azure.Messaging.ServiceBus.

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

  1. Создание пространства имен служебной шины с помощью портала Azure.
  2. Создание раздела служебной шины с помощью портала Azure.
  3. Создание подписки на этот раздел служебной шины с помощью портала Azure.
  4. Напишите консольное приложение .NET для отправки набора сообщений в раздел.
  5. Напишите консольное приложение .NET для получения этих сообщений из подписки.

Примечание.

Это краткое руководство содержит пошаговые инструкции для реализации простого сценария отправки пакета сообщений в раздел Служебной шины и получения этих сообщений из подписки раздела. Дополнительные примеры других и более сложных сценариев см. на странице примеров Служебной шины Azure для .NET на GitHub.

  • В этом кратком руководстве показано два способа подключения к Служебная шина Azure: строка подключения и без пароля. Первый вариант показывает, как использовать строка подключения для подключения к пространству имен служебная шина. Второй вариант показывает, как использовать субъект безопасности в идентификаторе Microsoft Entra ID и управлении доступом на основе ролей (RBAC) для подключения к пространству имен служебная шина. Вам не нужно беспокоиться о наличии жестко закодированных строка подключения в коде или в файле конфигурации или в безопасном хранилище, например Azure Key Vault. Если вы не знакомы с Azure, вы можете найти вариант строка подключения проще следовать. Мы рекомендуем использовать параметр без пароля в реальных приложениях и рабочих средах. Дополнительные сведения см. в разделе "Проверка подлинности и авторизация".

Необходимые компоненты

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

  • Подписка Azure. Чтобы использовать службы Azure, включая Служебную шину Azure, вам потребуется подписка. Если у вас нет существующей учетной записи Azure, вы можете зарегистрироваться и получить бесплатную пробную версию.
  • Visual Studio 2022. Пример приложения использует новые функции, представленные в C# 10. Вы по-прежнему можете использовать клиентская библиотека служебная шина с предыдущими версиями языка C#, но синтаксис может отличаться. Чтобы использовать последний синтаксис, рекомендуется установить .NET 6.0 или более позднюю версию latestязыка. Если вы используете Visual Studio, версии до Visual Studio 2022 несовместимы с инструментами, необходимыми для сборки проектов C# 10.

Создание пространства имен на портале Azure

Чтобы приступить к использованию сущностей обмена сообщениями в служебной шине в Azure, сначала необходимо создать пространство имен с уникальным для Azure именем. Пространство имен предоставляет контейнер области для служебная шина ресурсов (очередей, тем и т. д.) в приложении.

Создание пространства имен службы:

  1. Войдите на портал Azure.

  2. Перейдите на страницу "Все службы".

  3. На панели навигации слева выберите "Интеграция" из списка категорий, наведите указатель мыши на служебная шина, а затем нажмите + кнопку на плитке служебная шина.

    Image showing selection of Create a resource, Integration, and then Service Bus in the menu.

  4. В теге Основные сведения на странице Создание пространства имен выполните следующие действия:

    1. Выберите подписку Azure, в которой будет создано пространство имен.

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

    3. Введите имя для пространства имен. В имени пространства имен должны соблюдаться следующие соглашения об именовании:

      • Это имя должно быть уникальным в пределах Azure. Система немедленно проверяет, доступно ли оно.
      • Длина имени составляет не менее 6 и не более 50 символов.
      • Имя может содержать только буквы, цифры и дефисы (-).
      • Имя должно начинаться с буквы или цифры и заканчиваться буквой или цифрой.
      • Имя не должно оканчиваться на -sb или -mgmt.

    4. Укажите расположение — регион для размещения пространства имен.

    5. Для параметра Ценовая категория выберите ценовую категорию ("Базовый", "Стандартный" или "Премиум") для пространства имен. Для работы с этим кратким руководством выберите вариант Стандартный.

      Внимание

      Чтобы использовать разделы и подписки, выберите категорию "Стандартный" или "Премиум". Разделы и подписки не поддерживаются в ценовой категории "Базовый".

      Если выбрана ценовая категория Премиум, укажите число единиц обмена сообщениями. В категории "Премиум" обеспечивается изоляция ресурсов на уровне ЦП и памяти, так что рабочая нагрузка выполняется изолированно от других. Контейнер ресурса называется единицей обмена сообщениями. Пространству имен ценовой категории "Премиум" выделяется по крайней мере одна единица обмена сообщениями. Для каждого пространства имен служебной шины Premium можно выбрать 1, 2, 4, 8 или 16 единиц обмена сообщениями. Дополнительные сведения см. в статье Уровни обмена сообщениями через служебную шину Premium и Standard.

    6. В нижней части страницы выберите Review + create (Проверить и создать).

      Image showing the Create a namespace page

    7. На странице Проверить и создать проверьте параметры и нажмите кнопку Создать.

  5. После успешного развертывания ресурса выберите "Перейти к ресурсу " на странице развертывания.

    Image showing the deployment succeeded page with the Go to resource link.

  6. Вы увидите домашнюю страницу пространства имен служебной шины.

    Image showing the home page of the Service Bus namespace created.

Создание раздела с помощью портала Azure

  1. На странице Пространство имен служебной шины выберите пункт Разделы в левом меню.

  2. На панели инструментов выберите + Раздел.

  3. Введите имя раздела. Для других параметров оставьте значения по умолчанию.

  4. Нажмите кнопку создания.

    Image showing the Create topic page.

Создание подписки на раздел

  1. Выберите раздел, который был создан в предыдущем разделе.

    Image showing the selection of topic from the list of topics.

  2. На странице Раздел Служебной шины выберите + Подписка на панели инструментов.

    Image showing the Add subscription button.

  3. На странице Создать подписку выполните следующие действия:

    1. Введите S1 в качестве имени подписки.

    2. Задайте для параметра Максимальное число доставок значение 3.

    3. Выберите Создать, чтобы создать подписку.

      Image showing the Create subscription page.

Проверка подлинности приложения в Azure

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

Первый вариант показывает, как использовать субъект безопасности в идентификаторе Microsoft Entra ID и управлении доступом на основе ролей (RBAC) для подключения к пространству имен служебная шина. Вам не нужно беспокоиться о наличии жестко закодированных строка подключения в коде или в файле конфигурации или в безопасном хранилище, например Azure Key Vault.

Второй вариант показывает, как использовать строка подключения для подключения к пространству имен служебная шина. Если вы не знакомы с Azure, вы можете найти вариант строка подключения проще следовать. Мы рекомендуем использовать параметр без пароля в реальных приложениях и рабочих средах. Дополнительные сведения см. в разделе "Проверка подлинности и авторизация". Дополнительные сведения о проверке подлинности без пароля см. на странице обзора.

Назначение ролей пользователю Microsoft Entra

При локальной разработке убедитесь, что учетная запись пользователя, которая подключается к Служебная шина Azure имеет правильные разрешения. Для отправки и получения сообщений вам потребуется роль владельца данных Служебная шина Azure. Чтобы назначить себе эту роль, вам потребуется роль Администратор istrator пользователя или другую роль, которая включает Microsoft.Authorization/roleAssignments/write действие. Роли Azure RBAC можно назначить пользователю с помощью портала Azure, Azure CLI или Azure PowerShell. Узнайте больше о доступных область для назначений ролей на странице обзора область.

В следующем примере роль назначается Azure Service Bus Data Owner учетной записи пользователя, которая предоставляет полный доступ к ресурсам Служебная шина Azure. В реальном сценарии следуйте принципу наименьших привилегий , чтобы предоставить пользователям только минимальные разрешения, необходимые для более безопасной рабочей среды.

Встроенные роли Azure для служебной шины Azure

Для служебной шины Azure управление пространствами имен и всеми связанными ресурсами через портал Azure и API управления ресурсами Azure уже защищено с помощью модели Azure RBAC. Azure предоставляет следующие встроенные роли Azure для авторизации доступа к пространству имен служебной шины:

  • Служебная шина Azure Владелец данных: включает доступ к пространству имен служебная шина и его сущностям (очереди, разделы, подписки и фильтры). Участник этой роли может отправлять и получать сообщения из очередей или разделов или подписок.
  • Служебная шина Azure Отправителю данных: используйте эту роль, чтобы предоставить доступ к пространству имен служебная шина и его сущностям.
  • Служебная шина Azure приемник данных: используйте эту роль, чтобы предоставить доступ к пространству имен служебная шина и его сущностям.

Если вы хотите создать пользовательскую роль, см. раздел "Права", необходимые для операций служебная шина.

Добавление пользователя Microsoft Entra в роль владельца Служебная шина Azure

Добавьте имя пользователя Microsoft Entra в роль владельца данных Служебная шина Azure на уровне пространства имен служебная шина. Это позволит приложению, работающему в контексте учетной записи пользователя, отправлять сообщения в очередь или раздел, а также получать сообщения из очереди или подписки раздела.

Внимание

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

  1. Если в портал Azure нет страницы пространства имен служебная шина, найдите пространство имен служебная шина с помощью главной панели поиска или навигации слева.

  2. На странице обзора выберите элемент управления доступом (IAM) в меню слева.

  3. На странице Контроль доступа (IAM) откройте вкладку Назначения ролей.

  4. Выберите + Добавить в верхнем меню, а затем выберите Добавить назначение роли в появившемся раскрывающемся меню.

    A screenshot showing how to assign a role.

  5. Используйте поле поиска, чтобы отфильтровать результаты для отображения нужной роли. В этом примере найдите Azure Service Bus Data Owner и выберите соответствующий результат. Теперь щелкните Далее.

  6. В разделе Назначение доступа для выберите Пользователь, группа или субъект-служба и + Выбрать членов.

  7. В диалоговом окне найдите имя пользователя Microsoft Entra (обычно ваш user@domain адрес электронной почты), а затем выберите в нижней части диалогового окна.

  8. Нажмите кнопку Проверить и назначить, чтобы перейти на последнюю страницу, а затем еще раз Проверить и назначить, чтобы завершить процесс.

Запуск Visual Studio и вход в Azure

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

  1. Запустите Visual Studio. Если появится окно "Начало работы ", выберите " Продолжить без ссылки на код " в правой области.

  2. Нажмите кнопку Войти в правом верхнем углу Visual Studio.

    Screenshot showing the button to sign in to Azure using Visual Studio.

  3. Войдите с помощью учетной записи Microsoft Entra, назначенной ранее роли.

    Screenshot showing the account selection.

Отправка сообщений в раздел

В этом разделе показано, как создать консольное приложение .NET для отправки сообщений в раздел служебная шина.

Примечание.

Это краткое руководство содержит пошаговые инструкции для реализации простого сценария отправки пакета сообщений в раздел Служебной шины и получения этих сообщений из подписки раздела. Дополнительные примеры других и более сложных сценариев см. на странице примеров Служебной шины Azure для .NET на GitHub.

Создание консольного приложение

  1. В Visual Studio выберите "Файл ->Создать -> Проект ".
  2. В диалоговом окне Создать проект выполните следующие действия: (если это диалоговое окно не отображается, щелкните в меню пункт Файл, затем последовательно выберите Создать и Проект).

    1. Выберите язык программирования C#.

    2. Для типа приложения выберите значение Консоль.

    3. Выберите консольное приложение из списка результатов.

    4. Затем выберите Далее.

      Image showing the Create a new project dialog box with C# and Console selected

  3. Введите QueueSender в качестве имени проекта, ServiceBusQueueQuickStart в качестве имени решения, а затем нажмите Далее.
  4. На странице Дополнительная информация выберите Создать для создания решения и проекта.

Добавление пакетов NuGet в проект

  1. Выберите в меню элементы Инструменты>Диспетчер пакетов NuGet>Консоль диспетчера пакетов.

  2. Выполните следующую команду, чтобы установить пакет NuGet Azure.Messaging.ServiceBus .

    Install-Package Azure.Messaging.ServiceBus

  3. Выполните следующую команду, чтобы установить пакет NuGet Azure.Identity .

    Install-Package Azure.Identity

Добавление кода для отправки сообщений в раздел

  1. Замените содержимое Program.cs приведенным ниже кодом. Важные шаги описаны в этом разделе с дополнительными сведениями в комментариях кода.

    1. Создает объект ServiceBusClient с помощью DefaultAzureCredential объекта. DefaultAzureCredentialавтоматически обнаруживает и использует учетные данные входа Visual Studio для проверки подлинности в Служебная шина Azure.
    2. Вызов метода CreateSender для объекта ServiceBusClient. Это позволяет создать объект ServiceBusSender для указанного раздела Служебной шины.
    3. Создание ServiceBusMessageBatch с использованием ServiceBusSender.CreateMessageBatchAsync.
    4. Добавление сообщений в пакет с помощью ServiceBusMessageBatch.TryAddMessage.
    5. Отправка пакета сообщений в раздел Служебной шины с помощью метода ServiceBusSender.SendMessagesAsync.

    Внимание

    Обновите значения заполнителей (<NAMESPACE-NAME>и<TOPIC-NAME>) в фрагменте кода с именами пространства имен и раздела служебная шина.

    using System.Threading.Tasks;
using Azure.Messaging.ServiceBus;
using Azure.Identity;

// the client that owns the connection and can be used to create senders and receivers
ServiceBusClient client;

// the sender used to publish messages to the topic
ServiceBusSender sender;

// number of messages to be sent to the topic
const int numOfMessages = 3;

// The Service Bus client types are safe to cache and use as a singleton for the lifetime
// of the application, which is best practice when messages are being published or read
// regularly.

//TODO: Replace the "<NAMESPACE-NAME>" and "<TOPIC-NAME>" placeholders.
client = new ServiceBusClient(
    "<NAMESPACE-NAME>.servicebus.windows.net",
    new DefaultAzureCredential());
sender = client.CreateSender("<TOPIC-NAME>");

// create a batch 
using ServiceBusMessageBatch messageBatch = await sender.CreateMessageBatchAsync();

for (int i = 1; i <= numOfMessages; i++)
{
    // try adding a message to the batch
    if (!messageBatch.TryAddMessage(new ServiceBusMessage($"Message {i}")))
    {
        // if it is too large for the batch
        throw new Exception($"The message {i} is too large to fit in the batch.");
    }
}

try
{
    // Use the producer client to send the batch of messages to the Service Bus topic
    await sender.SendMessagesAsync(messageBatch);
    Console.WriteLine($"A batch of {numOfMessages} messages has been published to the topic.");
}
finally
{
    // Calling DisposeAsync on client types is required to ensure that network
    // resources and other unmanaged objects are properly cleaned up.
    await sender.DisposeAsync();
    await client.DisposeAsync();
}

Console.WriteLine("Press any key to end the application");
Console.ReadKey();

  2. Выполните сборку проекта и убедитесь, что она прошла без ошибок.

  3. Выполните программу и дождитесь подтверждающего сообщения.

    A batch of 3 messages has been published to the topic

    Внимание

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

  4. На портале Azure выполните следующие действия:

    1. Перейдите к пространству имен Служебной шины.

    2. В центральной области в нижней части страницы Обзор перейдите на вкладку Разделы и выберите раздел Служебной шины. В приведенном ниже примере это mytopic.

      Select topic

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

      Messages sent to the topic

    4. Выберите подписку в области снизу. В приведенном ниже примере это S1. На странице подписки на Служебную шину для параметра Количество активных сообщений отображается значение 3. В подписку поступили три сообщения, которые вы отправили в раздел, но получатель их еще не открыл.

      Messages received at the subscription

Получение сообщений из подписки

В этом разделе описано, как создать консольное приложение .NET, которое получает сообщения из подписки в раздел служебная шина.

Примечание.

Это краткое руководство содержит пошаговые инструкции для реализации простого сценария отправки пакета сообщений в раздел Служебной шины и получения этих сообщений из подписки раздела. Дополнительные примеры других и более сложных сценариев см. на странице примеров Служебной шины Azure для .NET на GitHub.

Создание проекта для получателя

  1. В окне Обозревателя решений щелкните правой кнопкой мыши решение ServiceBusTopicQuickStart, выберите Добавить и выберите Новый проект.
  2. Выберите Консольное приложение и нажмите Далее.
  3. Введите SubscriptionReceiver в поле Имя проекта и нажмите кнопку Далее.
  4. На странице Дополнительные сведения выберите Создать.
  5. В окне Обозреватель решений щелкните правой кнопкой мыши SubscriptionReceiver и выберите Установить как запускаемый проект.

Добавление пакетов NuGet в проект

  1. Выберите в меню элементы Инструменты>Диспетчер пакетов NuGet>Консоль диспетчера пакетов.

  2. Выберите SubscriptionReceiver для раскрывающегося списка проектов по умолчанию.

  3. Выполните следующую команду, чтобы установить пакет NuGet Azure.Messaging.ServiceBus .

    Install-Package Azure.Messaging.ServiceBus

  4. Выполните следующую команду, чтобы установить пакет NuGet Azure.Identity .

    Install-Package Azure.Identity

Добавьте код для получения сообщений из подписки.

В этом разделе вы добавите код для получения сообщений из подписки.

  1. Замените существующее содержимое Program.cs следующими свойствами и методами:

    using System.Threading.Tasks;
using Azure.Messaging.ServiceBus;
using Azure.Identity;

// the client that owns the connection and can be used to create senders and receivers
ServiceBusClient client;

// the processor that reads and processes messages from the subscription
ServiceBusProcessor processor;    

// handle received messages
async Task MessageHandler(ProcessMessageEventArgs args)
{
    string body = args.Message.Body.ToString();
    Console.WriteLine($"Received: {body} from subscription.");

    // complete the message. messages is deleted from the subscription. 
    await args.CompleteMessageAsync(args.Message);
}

// handle any errors when receiving messages
Task ErrorHandler(ProcessErrorEventArgs args)
{
    Console.WriteLine(args.Exception.ToString());
    return Task.CompletedTask;
}

  2. Добавьте следующий код в конец Program.cs.

    Внимание

    Обновите значения заполнителей (<NAMESPACE-NAME>, <TOPIC-NAME>,<SUBSCRIPTION-NAME>) в фрагменте кода с именами пространства имен, раздела и подписки служебная шина.

    Дополнительные сведения см. в комментариях, содержащихся в коде.

    // The Service Bus client types are safe to cache and use as a singleton for the lifetime
// of the application, which is best practice when messages are being published or read
// regularly.
//
// Create the clients that we'll use for sending and processing messages.
// TODO: Replace the <NAMESPACE-NAME> placeholder
client = new ServiceBusClient(
    "<NAMESPACE-NAME>.servicebus.windows.net",
    new DefaultAzureCredential());

// create a processor that we can use to process the messages
// TODO: Replace the <TOPIC-NAME> and <SUBSCRIPTION-NAME> placeholders
processor = client.CreateProcessor("<TOPIC-NAME>", "<SUBSCRIPTION-NAME>", new ServiceBusProcessorOptions());

try
{
    // add handler to process messages
    processor.ProcessMessageAsync += MessageHandler;

    // add handler to process any errors
    processor.ProcessErrorAsync += ErrorHandler;

    // start processing 
    await processor.StartProcessingAsync();

    Console.WriteLine("Wait for a minute and then press any key to end the processing");
    Console.ReadKey();

    // stop processing 
    Console.WriteLine("\nStopping the receiver...");
    await processor.StopProcessingAsync();
    Console.WriteLine("Stopped receiving messages");
}
finally
{
    // Calling DisposeAsync on client types is required to ensure that network
    // resources and other unmanaged objects are properly cleaned up.
    await processor.DisposeAsync();
    await client.DisposeAsync();
}

  3. Вот как будет выглядеть файл Program.cs:

    using System;
using System.Threading.Tasks;
using Azure.Messaging.ServiceBus;
using Azure.Identity;

// the client that owns the connection and can be used to create senders and receivers
ServiceBusClient client;

// the processor that reads and processes messages from the subscription
ServiceBusProcessor processor;

// handle received messages
async Task MessageHandler(ProcessMessageEventArgs args)
{
    string body = args.Message.Body.ToString();
    Console.WriteLine($"Received: {body} from subscription.");

    // complete the message. messages is deleted from the subscription. 
    await args.CompleteMessageAsync(args.Message);
}

// handle any errors when receiving messages
Task ErrorHandler(ProcessErrorEventArgs args)
{
    Console.WriteLine(args.Exception.ToString());
    return Task.CompletedTask;
}

// The Service Bus client types are safe to cache and use as a singleton for the lifetime
// of the application, which is best practice when messages are being published or read
// regularly.
//
// Create the clients that we'll use for sending and processing messages.
// TODO: Replace the <NAMESPACE-NAME> placeholder
client = new ServiceBusClient(
    "<NAMESPACE-NAME>.servicebus.windows.net",
    new DefaultAzureCredential());

// create a processor that we can use to process the messages
// TODO: Replace the <TOPIC-NAME> and <SUBSCRIPTION-NAME> placeholders
processor = client.CreateProcessor("<TOPIC-NAME>", "<SUBSCRIPTION-NAME>", new ServiceBusProcessorOptions());

try
{
    // add handler to process messages
    processor.ProcessMessageAsync += MessageHandler;

    // add handler to process any errors
    processor.ProcessErrorAsync += ErrorHandler;

    // start processing 
    await processor.StartProcessingAsync();

    Console.WriteLine("Wait for a minute and then press any key to end the processing");
    Console.ReadKey();

    // stop processing 
    Console.WriteLine("\nStopping the receiver...");
    await processor.StopProcessingAsync();
    Console.WriteLine("Stopped receiving messages");
}
finally
{
    // Calling DisposeAsync on client types is required to ensure that network
    // resources and other unmanaged objects are properly cleaned up.
    await processor.DisposeAsync();
    await client.DisposeAsync();
}

  4. Выполните сборку проекта и убедитесь, что она прошла без ошибок.

  5. Запустите приложение получателя. Вы должны увидеть полученные сообщения. Нажмите любую клавишу, чтобы остановить работу приемника и приложения.

    Wait for a minute and then press any key to end the processing
Received: Message 1 from subscription: S1
Received: Message 2 from subscription: S1
Received: Message 3 from subscription: S1

Stopping the receiver...
Stopped receiving messages

  6. Снова просмотрите сведения на портале.

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

      Messages sent and received

    • На странице подписки на Служебную шину для параметра Количество активных сообщений отображается нулевое значение. Это означает, что получатель получил сообщения из этой подписки и обработал их.

      Active message count at the subscription at the end

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

Ознакомьтесь со следующими примерами и документацией: