使用 Azure 服务总线模拟器在本地进行测试

本文总结了使用 Azure 服务总线模拟器进行本地开发和测试的步骤。

模拟器在本地计算机上作为 Docker 容器运行，提供用于开发和测试的本地服务总线环境。可以使用自动化脚本（用于快速设置）或手动配置 Docker 容器（以便进行更多控制）来设置模拟器。

Azure 服务总线模拟器通过 Microsoft容器注册表（MCR）提供。

注意

服务总线模拟器根据 Microsoft 软件许可条款提供。

服务总线模拟器与社区拥有的开源服务总线资源管理器不兼容

先决条件

最低硬件要求：
- 2 GB 的 RAM
- 5 GB 的磁盘空间
需要在后台安装并运行 Docker Desktop。

注意

即使是自动化脚本方法也使用后台的 Docker 容器来运行服务总线模拟器。
适用于 Linux 的 Windows 子系统 (WSL) 配置（仅限 Windows）：
- 安装 WSL
- 配置 Docker 以使用 WSL

运行仿真器

若要运行服务总线模拟器，可以使用自动化脚本或手动配置 Docker 容器。这两种方法都会导致同一容器化模拟器在本地运行：

自动脚本：使用预生成的脚本自动设置和运行具有默认配置的模拟器容器
Docker 容器：通过 Docker Compose 文件手动配置模拟器，从而提供完全控制

选择最符合需求的方法：

自动化脚本
Docker（Linux 容器）

在运行自动化脚本之前，需要在本地克隆 Azure/azure-service-bus-emulator-installer 存储库。

Windows

使用以下步骤在 Windows 上本地运行服务总线模拟器：

打开 PowerShell 并导航到克隆了脚本文件夹的目录，使用cd命令：
```
cd <path to your common scripts folder> # Update this path
```
发出 wsl 命令以在此目录中打开 WSL。
```
wsl
```
运行安装脚本。/LaunchEmulator.sh。运行脚本会启动两个容器：服务总线模拟器和 SQL Server Linux（模拟器的依赖项）。
```
./Launchemulator.sh 
```

Linux 和 macOS

若要在 Linux 或 macOS 上本地运行服务总线模拟器，请执行以下操作：

LaunchEmulator.sh 运行安装脚本。运行脚本会启动两个容器：服务总线模拟器和 SQL Server Linux（模拟器的依赖项）。

使用 Docker 时，服务总线模拟器将从 Microsoft容器注册表（MCR）提取。使用以下步骤通过 Docker Compose 手动设置和运行服务总线模拟器：

若要启动模拟器，请为要使用的实体提供配置。在本地将以下 JSON 文件保存为 config.json：

{
   "UserConfig": {
    "Namespaces": [
      {
        "Name": "sbemulatorns",
        "Queues": [
          {
            "Name": "queue.1",
            "Properties": {
              "DeadLetteringOnMessageExpiration": false,
              "DefaultMessageTimeToLive": "PT1H",
              "DuplicateDetectionHistoryTimeWindow": "PT20S",
              "ForwardDeadLetteredMessagesTo": "",
              "ForwardTo": "",
              "LockDuration": "PT1M",
              "MaxDeliveryCount": 3,
              "RequiresDuplicateDetection": false,
              "RequiresSession": false
            }
          }
        ],

        "Topics": [
          {
            "Name": "topic.1",
            "Properties": {
              "DefaultMessageTimeToLive": "PT1H",
              "DuplicateDetectionHistoryTimeWindow": "PT20S",
              "RequiresDuplicateDetection": false
            },
            "Subscriptions": [
              {
                "Name": "subscription.1",
                "Properties": {
                  "DeadLetteringOnMessageExpiration": false,
                  "DefaultMessageTimeToLive": "PT1H",
                  "LockDuration": "PT1M",
                  "MaxDeliveryCount": 3,
                  "ForwardDeadLetteredMessagesTo": "",
                  "ForwardTo": "",
                  "RequiresSession": false
                },
                "Rules": [
                  {
                    "Name": "app-prop-filter-1",
                    "Properties": {
                      "FilterType": "Correlation",
                      "CorrelationFilter": {
                        "ContentType": "application/text",
                        "CorrelationId": "id1",
                        "Label": "subject1",
                        "MessageId": "msgid1",
                        "ReplyTo": "someQueue",
                        "ReplyToSessionId": "sessionId",
                        "SessionId": "session1",
                        "To": "xyz"
                      }
                    }
                  }
                ]
              },
              {
                "Name": "subscription.2",
                "Properties": {
                  "DeadLetteringOnMessageExpiration": false,
                  "DefaultMessageTimeToLive": "PT1H",
                  "LockDuration": "PT1M",
                  "MaxDeliveryCount": 3,
                  "ForwardDeadLetteredMessagesTo": "",
                  "ForwardTo": "",
                  "RequiresSession": false
                },
                "Rules": [
                  {
                    "Name": "user-prop-filter-1",
                    "Properties": {
                      "FilterType": "Correlation",
                      "CorrelationFilter": {
                        "Properties": {
                          "prop1": "value1"
                        }
                      }
                    }
                  }
                ]
              },
              {
                "Name": "subscription.3",
                "Properties": {
                  "DeadLetteringOnMessageExpiration": false,
                  "DefaultMessageTimeToLive": "PT1H",
                  "LockDuration": "PT1M",
                  "MaxDeliveryCount": 3,
                  "ForwardDeadLetteredMessagesTo": "",
                  "ForwardTo": "",
                  "RequiresSession": false
                }
              },
              {
                "Name": "subscription.4",
                "Properties": {
                  "DeadLetteringOnMessageExpiration": false,
                  "DefaultMessageTimeToLive": "PT1H",
                  "LockDuration": "PT1M",
                  "MaxDeliveryCount": 3,
                  "ForwardDeadLetteredMessagesTo": "",
                  "ForwardTo": "",
                  "RequiresSession": false
                },
                "Rules": [
                  {
                    "Name": "sql-filter-1",
                    "Properties": {
                      "FilterType": "Sql",
                      "SqlFilter": {
                        "SqlExpression": "sys.MessageId = '123456' AND userProp1 = 'value1'"
                      },
                      "Action" : {
                        "SqlExpression": "SET sys.To = 'Entity'"
                      }
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "Logging": {
      "Type": "File"
    }
  }
}

若要为 Azure 服务总线模拟器启动容器，请将以下 .yaml 文件另存为 docker-compose.yaml

注意

Azure 服务总线模拟器默认使用端口 5672。如果将配置自定义为使用不同的端口，请更新 YAML 文件中的设置 ports 。

name: microsoft-azure-servicebus-emulator
services:
  emulator:
    container_name: "servicebus-emulator"
    image: mcr.microsoft.com/azure-messaging/servicebus-emulator:latest
    pull_policy: always
    volumes:
      - "${CONFIG_PATH}:/ServiceBus_Emulator/ConfigFiles/Config.json"
    ports:
      - "5672:5672"
      - "5300:${EMULATOR_HTTP_PORT:-5300}"
    environment:
      SQL_SERVER: mssql
      MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD}"  # Password should be same as what is set for SQL Server Linux 
      ACCEPT_EULA: ${ACCEPT_EULA}
      EMULATOR_HTTP_PORT: ${EMULATOR_HTTP_PORT:-5300}
      SQL_WAIT_INTERVAL: ${SQL_WAIT_INTERVAL} # Optional: Time in seconds to wait for SQL to be ready (default is 15 seconds)
    depends_on:
      - mssql
    networks:
      sb-emulator:
        aliases:
          - "sb-emulator"
  mssql:
        container_name: "mssql"
        image: "mcr.microsoft.com/mssql/server:2022-latest"
        networks:
          sb-emulator:
            aliases:
              - "mssql"
        environment:
          ACCEPT_EULA: ${ACCEPT_EULA}
          MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD}" # To be filled by user as per policy : https://learn.microsoft.com/sql/relational-databases/security/strong-passwords?view=sql-server-linux-ver16 

networks:
  sb-emulator:

创建一个 .env 文件来声明服务总线模拟器的环境变量，并确保设置了以下所有环境变量。

# Environment file for user-defined variables in docker-compose.yml

# 1. CONFIG_PATH: Path to Config.json file
# Ex: CONFIG_PATH="C:\\Config\\Config.json"
CONFIG_PATH="<Replace with path to Config.json file>"

# 2. ACCEPT_EULA: Pass 'Y' to accept license terms for SQL Server Linux and Service Bus emulator.
# Service Bus emulator EULA : https://github.com/Azure/azure-service-bus-emulator-installer/blob/main/EMULATOR_EULA.txt
# SQL Server Linux EULA : https://go.microsoft.com/fwlink/?LinkId=746388
ACCEPT_EULA="N"

# 3. MSSQL_SA_PASSWORD to be filled by user as per policy
MSSQL_SA_PASSWORD=""

# 4. Port on which emulator will expose Management & Health-check APIs
EMULATOR_HTTP_PORT=5300

重要

将值“Y”传递给环境变量 ACCEPT_EULA时，你将同时确认并接受 Azure 服务总线模拟器和 SQL Server Linux 最终用户许可协议（EULA）的条款和条件。
请确保将 .env 文件放置在文件 docker-compose.yaml 所在的同一目录中。
将 MSSQL_SA_PASSWORD 环境变量设置为至少包含八个字符的强密码，以满足密码要求。
在 Windows 中指定文件路径时，请使用双反斜杠（\\）而不是单个反斜杠（\）以避免转义字符出现问题。

若要运行模拟器，请执行以下命令：

docker compose -f <PathToDockerComposeFile> up -d

步骤成功后，可以找到在 Docker 中运行的容器。

显示容器中运行的服务总线模拟器的屏幕截图。

验证模拟器是否正在运行

无论选择哪种安装方法，结果都是相同的：在本地计算机上的 Docker 容器中运行的服务总线模拟器。模拟器由两个容器组成：

服务总线模拟器容器：提供服务总线功能的主要模拟器服务
SQL Server Linux 容器：为模拟器提供后端存储的依赖项

可以通过检查 Docker Desktop 或使用终端中的命令 docker ps 来验证容器是否正在运行。

与模拟器交互

可以使用服务总线管理客户端创建和管理服务总线实体，例如队列和主题。默认情况下，模拟器使用 config.json 配置文件。还可以通过对配置文件进行声明性更改来配置实体。若要了解详细信息，请访问在服务总线模拟器中创建和管理实体

选择正确的连接字符串

服务总线模拟器使用静态连接字符串，但主机值因应用程序相对于模拟器的部署方式而异。请为您的设置使用适当的连接字符串：

当模拟器容器和交互应用程序在本地计算机上进行本地运行时，请使用以下连接字符串：

"Endpoint=sb://localhost;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"

不同计算机上的应用程序（容器化/非容器化）和同一本地网络可以使用计算机的 IPv4 地址与模拟器交互。使用以下连接字符串：
```
"Endpoint=sb://192.168.y.z;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"
```
同一网桥网络上的应用程序容器可以使用其别名或 IP 与模拟器交互。以下连接字符串假定模拟器容器的名称为“servicebus-emulator”：
```
"Endpoint=sb://servicebus-emulator;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"
```
不同网桥网络上的应用程序容器可以使用“host.docker.internal”作为主机与模拟器进行交互。使用以下连接字符串：
```
"Endpoint=sb://host.docker.internal;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"
```
重要

默认情况下，使用服务总线管理客户端的管理作需要将 端口号 追加到模拟器连接字符串。例如，当模拟器和应用程序在同一台计算机上运行时，请使用以下连接字符串执行管理作：
```
"Endpoint=sb://localhost:5300;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;";
```
对于管理作，模拟器默认使用端口 5300。如果需要，可以将模拟器配置为使用其他端口。请参阅详细信息。

在服务总线模拟器中，仅在 .NET 中才原生支持通过服务总线管理客户端创建和管理实体。

可以使用最新的客户端 SDK 跨各种编程语言与服务总线模拟器进行交互。若要开始，请参阅 GitHub 上的服务总线模拟器示例。

Azure 服务总线模拟器概述

Last updated on 2026-01-22

共用方式為