Azure 服务总线主题和订阅入门 (.NET)

本快速入门介绍如何使用 Azure.Messaging.ServiceBus .NET 库向服务总线主题发送消息和接收有关该主题订阅的消息。

在本快速入门中，你将执行以下步骤：

1. 使用 Azure 门户创建服务总线命名空间。
2. 使用 Azure 门户创建服务总线主题。
3. 使用 Azure 门户创建该主题的服务总线订阅。
4. 编写 .NET 控制台应用程序，向主题发送一组消息。
5. 编写 .NET 控制台应用程序，从订阅接收这些消息。

先决条件

如果你是首次使用该服务，请在使用本快速入门之前先参阅服务总线概述。

• 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. 在左侧的导航栏中，从类别列表中选择“集成”，将鼠标悬停在“服务总线”上，然后选择“服务总线”磁贴上的 按钮。+。

   

4. 在“创建命名空间”页的“基本信息”标记中，执行以下步骤 ：

   1. 对于“订阅”，请选择要在其中创建命名空间的 Azure 订阅。

   2. 对于“资源组”，请选择该命名空间驻留到的现有资源组，或创建一个新资源组。

   3. 输入命名空间的名称。 命名空间名称应遵循以下命名约定：

      • 该名称在 Azure 中必须唯一。 系统会立即检查该名称是否可用。
      • 名称长度最少为 6 个字符，最多为 50 个字符。
      • 名称只能包含字母、数字和连字符“-”。
      • 名称必须以字母开头，并且必须以字母或数字结尾。
      • 名称不以“-sb”或“-mgmt”结尾。

   4. 对于“位置”，请选择托管该命名空间的区域。

   5. 对于“定价层”，请选择命名空间的定价层（“基本”、“标准”或“高级”）。 对于本快速入门，请选择“标准”。

      重要

      若要使用主题和订阅，请选择“标准”或“高级”。 基本定价层不支持主题/订阅。

      如果选择了“高级”定价层，请指定“消息传送单元”数 。 高级层在 CPU 和内存级别提供资源隔离，使每个工作负荷在隔离的环境中运行。 此资源容器称为消息传送单元。 高级命名空间至少具有一个消息传送单元。 可为每个服务总线高级命名空间选择 1、2、4、8 或 16 个消息传送单元。 有关详细信息，请参阅服务总线高级消息传送。

   6. 在页面底部选择“查看 + 创建”。

      

   7. 在“查看 + 创建”页上，查看设置，然后选择“创建” 。

5. 资源部署成功后，在部署页上选择“转到资源”。

   

6. 将会看到服务总线命名空间的主页。

   

使用 Azure 门户创建主题

1. 在“服务总线命名空间”页面上，选择左侧菜单中的“主题”。

2. 在工具栏中选择“+ 主题”。

3. 输入主题名称。 将其他选项保留默认值。

4. 选择“创建”。

   

创建主题的订阅

1. 选择在上一部分创建的主题。

   

2. 在“服务总线主题”页面上，选择工具栏上的“+ 订阅” 。

   

3. 在“创建订阅”页上执行以下步骤：

   1. 对于订阅名称，输入“S1” 。

   2. 对于“最大交付数”，输入“3” 。

   3. 然后，选择“创建”以创建订阅。

      

向 Azure 验证应用

本快速入门介绍了连接到 Azure 服务总线的两种方法：无密码和连接字符串方法。 第一个选项展示如何使用 Azure Active Directory 中的安全主体和基于角色的访问控制 (RBAC) 连接到服务总线命名空间。 无需担心代码、配置文件或安全存储（如 Azure Key Vault）中存在硬编码的连接字符串。 第二个选项展示如何使用连接字符串连接到服务总线命名空间。 如果不熟悉 Azure，你可能会感觉连接字符串选项更易于使用。 建议在实际应用程序和生产环境中使用无密码选项。 有关详细信息，请参阅身份验证和授权。 还可以在概述页上阅读有关无密码身份验证的详细信息。

启动 Visual Studio 并登录到 Azure

可以使用以下步骤授权对服务总线命名空间的访问：

1. 启动 Visual Studio。 如果看到“入门”窗口，请在右窗格中选择“在不使用代码的情况下继续”链接。

2. 选择 Visual Studio 右上角的“登录”按钮。

   

3. 使用你之前为其分配角色的 Microsoft Entra 帐户登录。

   

将消息发送到主题

本部分介绍如何创建一个向服务总线主题发送消息的 .NET 控制台应用程序。

创建控制台应用程序

1. 在 Visual Studio 中，选择“文件”->“新建”->“项目”菜单。
2. 在“创建新项目”对话框中执行以下步骤：如果看不到此对话框，请在菜单中选择“文件”，然后依次选择“新建”、“项目”。

   1. 选择“C#”作为编程语言。

   2. 选择“控制台”作为应用程序类型。

   3. 从结果列表中选择“控制台应用”。

   4. 然后，选择“下一步” 。

      

3. 输入 TopicSender 作为项目名称，输入 ServiceBusTopicQuickStart 作为解决方案名称，然后选择“下一步”。
4. 在“其他信息”页面，选择“创建”来创建解决方案和项目。

向项目添加 NuGet 包

添加将消息发送到主题的代码

1. 将 Program.cs 的内容替换为以下代码。 本部分概述了重要步骤，并在代码注释中提供了其他信息。

   • 无密码
   • 连接字符串

   1. 使用 对象创建 ServiceBusClientDefaultAzureCredential 对象。 DefaultAzureCredential 将自动发现并使用你的 Visual Studio 登录凭据向 Azure 服务总线进行身份验证。
   2. 对 对象调用 CreateSenderServiceBusClient 方法，从而为特定的“服务总线”主题创建 ServiceBusSender 对象。
   3. 使用 ServiceBusSender.CreateMessageBatchAsync 创建 ServiceBusMessageBatch 对象。
   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.chinacloudapi.cn",
       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 中传播需要一两分钟。 在极少数情况下，最多可能需要 8 分钟才能完成。 如果在首次运行代码时收到身份验证错误，请稍等片刻再试。

4. 在 Azure 门户中按照以下步骤操作：

   1. 导航到服务总线命名空间。

   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 的末尾。

   • 无密码
   • 连接字符串

   • 使用 对象创建 ServiceBusClientDefaultAzureCredential 对象。 DefaultAzureCredential 将自动发现并使用你的 Visual Studio 登录凭据向 Azure 服务总线进行身份验证。
   • 对 对象调用 CreateProcessorServiceBusClient 方法，从而为指定的服务总线主题创建 ServiceBusProcessor 对象。
   • 为 对象的 ProcessMessageAsync 和 ProcessErrorAsyncServiceBusProcessor 事件指定处理程序。
   • 通过对 对象调用 StartProcessingAsyncServiceBusProcessor 以开始处理消息。
   • 当用户按下某个键结束处理时，将对 对象调用 StopProcessingAsyncServiceBusProcessor。

   重要

   使用服务总线命名空间、主题和订阅的名称更新代码片段中的占位符值（<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.chinacloudapi.cn",
       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.chinacloudapi.cn",
       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. 再次检查门户。

   • 在“服务总线主题”页上的“消息”图表中，你会看到三条传入消息和三条传出消息。 如果未看到这些值，请等待几分钟，然后刷新页面以查看更新后的图表。

     

   • 在“服务总线订阅”页面上，你会看到“活动消息计数”为零 。 这是因为接收方已接收并已完成来自此订阅的消息。

     

后续步骤

请参阅以下文档和示例：

• 适用于 .NET 的 Azure 服务总线客户端库 - 自述文件
• GitHub 上的 Azure 服务总线的 .NET 示例
• .NET API 参考