Краткое руководство. Отправка и получение сообщений из очереди Служебная шина Azure (.NET)

  • Статья

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

  1. Создание пространства имен служебной шины с помощью портала Azure.

  2. Создание очереди служебной шины с помощью портала Azure.

  3. Напишите консольное приложение .NET для отправки набора сообщений в очередь.

  4. Напишите консольное приложение .NET для получения этих сообщений из очереди.

    Примечание.

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

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

Если вы новичок в этой службе, прежде чем приступить к этому руководству, ознакомьтесь с обзором служебной шины 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 creation of a queue in the portal

Внимание

Если вы не знакомы с Azure, вы можете найти параметр Подключение ion String проще следовать. Перейдите на вкладку Подключение ion String, чтобы просмотреть инструкции по использованию строка подключения в этом кратком руководстве. Рекомендуется использовать параметр без пароля в реальных приложениях и рабочих средах.

Проверка подлинности приложения в 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 a 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 в качестве имени решения, после чего нажмите Далее.

    Image showing the solution and project names in the Configure your new project dialog box

  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 следующим кодом: Важные шаги описаны в следующем разделе с дополнительными сведениями в комментариях кода.

    Внимание

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

    using Azure.Messaging.ServiceBus;
using Azure.Identity;

// name of your Service Bus queue
// 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 queue
ServiceBusSender sender;

// number of messages to be sent to the queue
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.
//
// Set the transport type to AmqpWebSockets so that the ServiceBusClient uses the port 443. 
// If you use the default AmqpTcp, ensure that ports 5671 and 5672 are open.
var clientOptions = new ServiceBusClientOptions
{ 
    TransportType = ServiceBusTransportType.AmqpWebSockets
};
//TODO: Replace the "<NAMESPACE-NAME>" and "<QUEUE-NAME>" placeholders.
client = new ServiceBusClient(
    "<NAMESPACE-NAME>.servicebus.windows.net",
    new DefaultAzureCredential(),
    clientOptions);
sender = client.CreateSender("<QUEUE-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 queue
    await sender.SendMessagesAsync(messageBatch);
    Console.WriteLine($"A batch of {numOfMessages} messages has been published to the queue.");
}
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 queue

    Внимание

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

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

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

    2. На странице Обзор выберите очередь в центральной области снизу.

      Image showing the Service Bus Namespace page in the Azure portal with the queue selected.

    3. Обратите внимание на значения в разделе Основное.

      Image showing the number of messages received and the size of the queue.

    Обратите внимание на следующие значения:

    • Значение счетчика Активных сообщений для очереди теперь равно 3. Всякий раз, когда вы запускаете это приложение-отправитель без получения сообщений, это значение увеличивается на 3.
    • Текущий размер очереди увеличивается каждый раз, когда приложение добавляет сообщения в очередь.
    • На диаграмме Сообщения в нижнем разделе Показатели вы можете увидеть, что в очереди есть три входящих сообщения.

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

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

Примечание.

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

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

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

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

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

  2. Выберите QueueReceiver для проекта по умолчанию.

    Screenshot showing QueueReceiver project selected in the Package Manager Console.

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

    Install-Package Azure.Messaging.ServiceBus

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

    Install-Package Azure.Identity

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

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

  1. Program В классе добавьте следующий код:

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

// 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 queue
ServiceBusProcessor processor;

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

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

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

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

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

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

    Внимание

    Обновите значения заполнителей (<NAMESPACE-NAME>и<QUEUE-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.
//
// Set the transport type to AmqpWebSockets so that the ServiceBusClient uses port 443. 
// If you use the default AmqpTcp, make sure that ports 5671 and 5672 are open.

// TODO: Replace the <NAMESPACE-NAME> placeholder
var clientOptions = new ServiceBusClientOptions()
{
    TransportType = ServiceBusTransportType.AmqpWebSockets
};
client = new ServiceBusClient(
    "<NAMESPACE-NAME>.servicebus.windows.net",
    new DefaultAzureCredential(),
    clientOptions);

// create a processor that we can use to process the messages
// TODO: Replace the <QUEUE-NAME> placeholder
processor = client.CreateProcessor("<QUEUE-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. Завершенный Program класс должен соответствовать следующему коду:

    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 queue
ServiceBusProcessor processor;

// 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.
//
// Set the transport type to AmqpWebSockets so that the ServiceBusClient uses port 443.
// If you use the default AmqpTcp, make sure that ports 5671 and 5672 are open.

// TODO: Replace the <NAMESPACE-NAME> and <QUEUE-NAME> placeholders
var clientOptions = new ServiceBusClientOptions() 
{
    TransportType = ServiceBusTransportType.AmqpWebSockets
};
client = new ServiceBusClient("<NAMESPACE-NAME>.servicebus.windows.net", 
    new DefaultAzureCredential(), clientOptions);

// create a processor that we can use to process the messages
// TODO: Replace the <QUEUE-NAME> placeholder
processor = client.CreateProcessor("<QUEUE-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();
}

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

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

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

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

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

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

Stopping the receiver...
Stopped receiving messages

  7. Снова просмотрите сведения на портале. Подождите несколько минут и обновите страницу, если вы не видите 0 для Активных сообщений.

    • Значения Активных сообщений и Текущий размер теперь равны 0.

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

      Screenshot showing active messages and size after receive.

Очистка ресурсов

Перейдите к пространству имен служебная шина в портал Azure и выберите "Удалить" в портал Azure, чтобы удалить пространство имен и очередь в ней.

См. также

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

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

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