Azure Service Bus Emulator Installer

This repository contains the scripts required to install and run the Azure Service Bus Emulator.

• Azure Service Bus Emulator Installer
  • About Azure Service Bus
  • About Azure Service Bus emulator
  • Run Azure Service Bus Emulator
  • Prerequisites
  • Running the Emulator
    • Using Automated Script
    • Windows
    • Linux & macOS
      • Using Docker Compose (Linux Container)
  • Interacting with the emulator
  • Code Samples
  • Support
  • License

About Azure Service Bus

Azure Service Bus is a fully managed enterprise message broker offering queues and publish-subscribe topics. It decouples applications and services, providing benefits like load-balancing across workers, safe data and control routing, and reliable transactional coordination. Read more here.

About Azure Service Bus emulator

The Azure Service Bus emulator offers a local development experience for the Service bus service. You can use the emulator to develop and test code against the service in isolation, free from cloud interference.

Caution

Emulator is intended solely for development and testing scenarios.Any kind of Production use is strictly discouraged. There is no official support provided for Emulator. Any issues/suggestions should be reported via GitHub issues on GitHub project.

Run Azure Service Bus Emulator

This section summarizes the steps to develop and test locally with Service Bus Emulator. To read more about Service Bus, read here.

Prerequisites

• Docker
  • Docker Desktop
• Minimum hardware Requirements:
  • 2 GB RAM
  • 5 GB of Disk space
• WSL Enablement (Only for Windows):
  • Install Windows Subsystem for Linux (WSL) | Microsoft Learn
  • Configure Docker to use WSL

Note

Before you continue with the subsequent steps, make sure Docker Engine is operational in the background.

Running the Emulator

This section highlights different steps to run Service Bus Emulator. Details are as follows:

Using Automated Script

Before running automated script, clone the installation repository locally.

Windows

After completing the prerequisites, you can proceed with the following steps to run the Service Bus Emulator locally on Windows:

1. Open PowerShell and navigate to the directory where the common scripts folder is cloned using cd:

   cd <path to your common scripts folder> # Update this path
      

2. Issue wsl command to open WSL at this directory.

   wsl
   

3. Run the setup script ./LaunchEmulator.sh Running the script brings up two containers: Service Bus emulator and SQLedge (a dependency for the emulator).

   ./Launchemulator.sh
   
   
   

Linux & macOS

After completing the prerequisites, you can proceed with the following steps to run the Service Bus Emulator locally.

1. Execute the setup script LaunchEmulator.sh . Running the script would bring up two containers – Service Bus Emulator & Azure SQL Edge (dependency for Emulator)

2. Execute the same script LaunchEmulator.sh with the option --compose-down=Y to issue a docker compose down to terminate the containers.

LaunchEmulator.sh --compose-down=Y

Using Docker Compose (Linux Container)

You can also spin up Emulator using Docker Compose file directly. Refer here for details:

Once the steps are successful, Emulator compose set can be found running in Docker.

Interacting 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

Note

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

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 & health-check, the emulator uses port 5300 by default.
You can configure the emulator to use a different port if required using the EMULATOR_HTTP_PORT environment variable.

Code Samples

• .Net - SDK Version "Azure.Messaging.ServiceBus v7.20.1" supports emulator management APIs natively.
  • .Net Code sample
• SDKs in other languages do not honor non‑TLS connections or custom ports in the connection string. As a result, they do not natively support the Emulator’s management APIs. Limited workarounds are available to configure these SDKs to communicate with the Emulator over non‑TLS and custom ports. Refer to the code samples for details.
  • Go Code sample
  • Java Code sample
  • JavaScript Code sample
  • Python Code sample

Support

There is no official support provided for Emulator.Any issues/suggestions should be reported via GitHub issues on installation repo.

License

The scripts and documentation in this project are released under the MIT License.

The software (Azure Service Bus Emulator and Sql Edge) that the scripts in this repository install are licensed under separate terms. Refer to the terms governing each software below:

• Azure Service Bus emulator : EULA
• Azure SQL Edge Developer Edition: EULA
  • SQL Edge provides Developer and Premium editions, Service Bus Emulator relies on the Developer edition which is licensed for use as a development and test system and cannot be used in a production environment.