Azure Service Bus emulator

As a developer working with Azure, one challenge I often face is setting up a realistic local environment, disconnected from Azure. Azure recently released the Azure Service Bus emulator, which is a sorely needed tool when developing locally. It offers many benefits, although it comes with a few limitations. One huge benefit is the possibility to interact with a Service Bus locally. If you’re using Service Bus in your project, this will enhance your development experience. You don’t need to create fake topics or queues in Azure for testing purposes only. You don’t need to agree with your teammate that you will test a specific integration in the Test environment, and that no-one else can interact with the Service Bus for this integration. In this post I will guide you through how to set up the emulator locally using Docker. To achieve this yourself, you need to have Docker installed on your computer. Since I’m working on a windows OS, I’m using Docker Desktop.

Config.json

First of all, we need to create a config.json file. This is where we will supply the configuration for the entities we want. In the configuration below, we are defining one Service Bus queue, one Service Bus topic and one Service Bus subscription.

{
    "UserConfig": {
      "Namespaces": [
        {
          "Name": "emulatorDemonstration",
          "Queues": [
            {
              "Name": "myServiceBusQueue",
              "Properties": {
                "DeadLetteringOnMessageExpiration": false,
                "DefaultMessageTimeToLive": "PT1H",
                "DuplicateDetectionHistoryTimeWindow": "PT20S",
                "ForwardDeadLetteredMessagesTo": "",
                "ForwardTo": "",
                "LockDuration": "PT1M",
                "MaxDeliveryCount": 10,
                "RequiresDuplicateDetection": false,
                "RequiresSession": false
              }
            }
          ],
          "Topics": [
            {
              "Name": "myServiceBusTopic",
              "Properties": {
                "DefaultMessageTimeToLive": "PT1H",
                "DuplicateDetectionHistoryTimeWindow": "PT20S",
                "RequiresDuplicateDetection": false
              },
              "Subscriptions": [
                {
                  "Name": "myServiceBusSubscription",
                  "Properties": {
                    "DeadLetteringOnMessageExpiration": false,
                    "DefaultMessageTimeToLive": "PT1H",
                    "LockDuration": "PT1M",
                    "MaxDeliveryCount": 10,
                    "ForwardDeadLetteredMessagesTo": "",
                    "ForwardTo": "",
                    "RequiresSession": false
                  }
                }
              ]
            }
          ]
        }
      ],
      "Logging": {
        "Type": "File"
      }
    }
  }

.env file

The next step will be to define a .env file for the Service Bus emulator. These are the environment variables we will use in our docker-compose.yml file. Here you will need to set the path for out config.json file and a password for the SQL database. This is needed because the emulator has a dependency towards SQL edge.

CONFIG_PATH="./config.json"
ACCEPT_EULA="Y"
MSSQL_SA_PASSWORD: "Re@llyStr0ngP@assw0rd"

docker-compose.yml

Finally, we will create a docker-compose.yml file. This file uses the configuration from the .env file that we defined above.

name: microsoft-azure-servicebus-emulator
services:
  emulator:
    container_name: "servicebus-emulator"
    image: mcr.microsoft.com/azure-messaging/servicebus-emulator:latest
    volumes:
      - "${CONFIG_PATH}:/ServiceBus_Emulator/ConfigFiles/Config.json"
    ports:
      - "5672:5672"
    environment:
      SQL_SERVER: sqledge  
      MSSQL_SA_PASSWORD: ${MSSQL_SA_PASSWORD}
      ACCEPT_EULA: ${ACCEPT_EULA}
    depends_on:
      - sqledge
    networks:
      sb-emulator:
        aliases:
          - "sb-emulator"
  sqledge:
        container_name: "sqledge"
        image: "mcr.microsoft.com/azure-sql-edge:latest"
        networks:
          sb-emulator:
            aliases:
              - "sqledge"
        environment:
          ACCEPT_EULA: ${ACCEPT_EULA}
          MSSQL_SA_PASSWORD: ${MSSQL_SA_PASSWORD}
networks:
  sb-emulator:

Starting the emulator

The folder I’m working from currently looks like this

To start the emulator, we can run the command docker compose -f docker-compose.yml up -d from our terminal, from the folder where the docker-compose.yml file is located.

The first time you run the command, it will download all images needed to run the containers, before it starts the containers.

You should now be able to see the containers running

Interact with the emulator

To interact with the emulator, you can use the following connection string:
Endpoint=sb://localhost;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;

Sources

https://hub.docker.com/r/microsoft/azure-messaging-servicebus-emulator
https://learn.microsoft.com/en-us/azure/service-bus-messaging/overview-emulator#known-limitations

Azure Service Bus emulator was originally published in Compendium on Medium, where people are continuing the conversation by highlighting and responding to this story.