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

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

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

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

Предварительные условия

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

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

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

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

Создать пространство имен:

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

2. Выберите всплывающее меню в левом верхнем углу и перейдите на страницу "Все службы".

3. На панели навигации слева выберите "Интеграция".

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

   

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

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

   2. Для группы ресурсов выберите существующую группу ресурсов или создайте новую.

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

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

   4. Для расположения выберите регион для размещения пространства имен.

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

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

      Внимание

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

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

   6. Нажмите Review + create внизу страницы.

      

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

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

   

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

   

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

1. На странице пространства имен Service Bus разверните сущности в меню навигации слева и выберите топики в левом меню.

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

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

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

   

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

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

   

2. На странице Тема очереди Service Bus выберите + Подписка на панели инструментов.

   

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

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

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

      

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

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

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

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

Запуск Visual Studio

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

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

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

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

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

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

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

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

      

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

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

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

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

   • Без пароля
   • Строка подключения

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

   Внимание

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

   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. Перейдите к пространству имен вашего Service Bus.

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

      

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

      

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

      

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

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

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

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

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

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

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

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.

   • Без пароля
   • Строка подключения

   • Создает объект ServiceBusClient с помощью DefaultAzureCredential объекта. DefaultAzureCredential автоматически обнаруживает и использует учетные данные вашей учетной записи входа в Visual Studio для аутентификации в Azure Service Bus.
   • Вызывает метод CreateProcessor на объекте ServiceBusClient, чтобы создать объект ServiceBusProcessor для указанного топика Service Bus.
   • Указание обработчиков для событий ProcessMessageAsync и ProcessErrorAsync объекта ServiceBusProcessor.
   • Запуск обработки сообщений путем вызова StartProcessingAsync для объекта ServiceBusProcessor.
   • Вызов StopProcessingAsync для объекта ServiceBusProcessor при нажатии пользователем кнопки для завершения обработки.

   Внимание

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

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

   // 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. Снова просмотрите сведения на портале.

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

     

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

     

Связанный контент

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

• Библиотека клиента Служебной шины Azure для .NET - файл Readme
• Примеры .NET для Служебной шины Azure на сайте GitHub
• Справочник по API .NET