Test locally by using the Azure Service Bus emulator

This article summarizes the steps to develop and test locally by using the Azure Service Bus emulator.

The emulator runs as a Docker container on your local machine, providing a local Service Bus environment for development and testing. You can set up the emulator by using either an automated script (for quick setup) or by manually configuring Docker containers (for more control).

Azure Service Bus emulator is available via the Microsoft Container Registry (MCR).

Note

The Service bus emulator is available under the Microsoft Software License Terms.

Service Bus emulator isn't compatible with the community owned open source Service Bus Explorer

Prerequisites

Minimum hardware requirements:
- 2 GB of RAM
- 5 GB of disk space
Docker Desktop needs to be installed and running in the background.

Note

Even the automated script approach uses Docker containers behind the scenes to run the Service Bus emulator.
Windows Subsystem for Linux (WSL) configuration (only for Windows):
- Install WSL
- Configure Docker to use WSL

Run the emulator

To run the Service Bus emulator, you can use an automated script or manually configure Docker containers. Both approaches result in the same containerized emulator running locally:

Automated script: Uses prebuilt scripts to automatically set up and run the emulator containers with default configuration
Docker container: Provides full control by letting you manually configure the emulator through Docker Compose files

Choose the approach that best fits your needs:

Automated script
Docker (Linux container)

Before you run the automated script, you need to clone the Azure/azure-service-bus-emulator-installer repository locally.

Windows

Use the following steps to run the Service Bus emulator locally on Windows:

Open PowerShell and navigate to the directory where you cloned the common scripts folder by using cd:
```
cd <path to your common scripts folder> # Update this path
```
Issue wsl command to open WSL at this directory.
```
wsl
```
Run the setup script ./LaunchEmulator.sh.Running the script brings up two containers: the Service Bus emulator and SQL Server Linux (a dependency for the emulator).
```
./Launchemulator.sh 
```

Linux and macOS

To run the Service Bus emulator locally on Linux or macOS:

Run the setup script LaunchEmulator.sh. Running the script brings up two containers: the Service Bus emulator and SQL Server Linux (a dependency for the emulator).

When you use Docker, the service bus emulator is fetched from the Microsoft Container Registry (MCR). Use the following steps to manually set up and run the Service Bus emulator by using Docker Compose:

To start the emulator, supply a configuration for the entities that you want to use. Save the following JSON file locally as 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"
    }
  }
}

To spin up containers for Azure Service Bus emulator, save the following .yaml file as docker-compose.yaml

Note

Azure Service Bus emulator uses the port 5672 by default. If you customized the configuration to use a different port, update the ports setting in the YAML file.

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:

Create a .env file to declare the environment variables for Service Bus emulator and ensure all of the following environment variables are set.
```
# 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
```
Important
- When you pass the value "Y" to the environment variable ACCEPT_EULA, you're acknowledging and accepting the terms and conditions of the End User License Agreement (EULA) for both Azure Service Bus emulator and SQL Server Linux.
- Make sure to place the .env file in same directory as the docker-compose.yaml file.
- Set the MSSQL_SA_PASSWORD environment variable to a strong password of at least eight characters that meets the password requirements.
- When you specify file paths in Windows, use double backslashes (\\) instead of single backslashes (\) to avoid issues with escape characters.

To run the emulator, execute following command:

docker compose -f <PathToDockerComposeFile> up -d

After the steps are successful, you can find the containers running in Docker.

Screenshot that shows the Service Bus emulator running in a container.

Verify emulator is running

Regardless of which setup method you chose, the result is the same: the Service Bus emulator running in Docker containers on your local machine. The emulator consists of two containers:

Service Bus emulator container: The main emulator service that provides Service Bus functionality
SQL Server Linux container: A dependency that provides the backend storage for the emulator

You can verify the containers are running by checking Docker Desktop or using the command docker ps in a terminal.

Interact with the emulator

You can create and manage Service Bus entities—such as queues and topics—using the Service Bus Administration Client. By default, emulator uses config.json configuration file. You can also configure entities by making declarative changes to configuration file. To know more, visit create and manage entities within Service Bus emulator

Choosing the right connection string

The Service Bus emulator uses a static connection string, but the host value varies depending on how your application is deployed relative to the emulator. Use the appropriate connection string for your setup:

When the emulator container and interacting application are running natively on local machine, use following connection string:

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

Applications (Containerized/Non-containerized) on the different machine and same local network can interact with Emulator using the IPv4 address of the machine. Use following connection string:
```
"Endpoint=sb://192.168.y.z;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"
```
Application containers on the same bridge network can interact with Emulator using its alias or IP. Following connection string assumes the name of Emulator container is "servicebus-emulator":
```
"Endpoint=sb://servicebus-emulator;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"
```
Application containers on the different bridge network can interact with Emulator using the "host.docker.internal" as host. Use following connection string:
```
"Endpoint=sb://host.docker.internal;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"
```
Important

By default, management operations using the Service Bus Administration Client require appending the port number to the emulator connection string. For example, when both the emulator and the application are running on the same machine, use the following connection string for administration operations:
```
"Endpoint=sb://localhost:5300;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;";
```
For management operations, the emulator uses port 5300 by default. You can configure the emulator to use a different port if required. Refer to know more.

For the Service Bus Emulator, creating and managing entities via the Service Bus Administration client is natively supported only in .NET.

You can use the latest client SDKs to interact with the Service Bus emulator across various programming languages. To get started, refer to the Service Bus emulator samples on GitHub.

Overview of the Azure Service Bus emulator

Last updated on 2026-01-22