Test locally by using the Azure Event Hubs emulator

This article summarizes the steps to develop and test locally by using the Azure Event Hubs emulator.

Prerequisites

• Docker desktop
• Minimum hardware requirements:
  • 2 GB of RAM
  • 5 GB of disk space
• Windows Subsystem for Linux (WSL) configuration (only for Windows):
  • Install WSL
  • Configure Docker to use WSL

Note

Before you continue with the steps in this article, make sure Docker Desktop is operational in the background.

Run the emulator

To run the Event Hubs emulator, you can use an automated script or a Linux container:

Automated script

Before you run an automated script, clone the emulator's GitHub installer repository locally.

Windows

Use the following steps to run the Event Hubs emulator locally on Windows:

1. Allow the execution of unsigned scripts by running this command in the PowerShell window:

   $>Start-Process powershell -Verb RunAs -ArgumentList 'Set-ExecutionPolicy Bypass –Scope CurrentUser'

2. Run the setup script LaunchEmulator.ps1. Running the script brings up two containers: the Event Hubs emulator and Azurite (a dependency for the emulator).

Linux and macOS

To run the Event Hubs emulator locally on Linux or macOS:

• Run the setup script LaunchEmulator.sh. Running the script brings up two containers: the Event Hubs emulator and Azurite (a dependency for the emulator).

Docker (Linux container)

1. 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": {
           "NamespaceConfig": [
           {
               "Type": "EventHub",
               "Name": "emulatorNs1",
               "Entities": [
               {
                   "Name": "eh1",
                   "PartitionCount": "2",
                   "ConsumerGroups": [
                   {
                       "Name": "cg1"
                   }
                   ]
               }
               ]
           }
           ], 
           "LoggingConfig": {
               "Type": "File"
           }
       }
   }
   
   

2. Save the following .yaml file as docker-compose.yaml to spin up containers for the Event Hubs emulator:

   name: microsoft-azure-eventhubs
   services:
     emulator:
       container_name: "eventhubs-emulator"
       image: "mcr.microsoft.com/azure-messaging/eventhubs-emulator:latest"
       volumes:
         - "${CONFIG_PATH}:/Eventhubs_Emulator/ConfigFiles/Config.json"
       ports:
         - "5672:5672"
       environment:
         BLOB_SERVER: azurite
         METADATA_SERVER: azurite
         ACCEPT_EULA: ${ACCEPT_EULA}
       depends_on:
         - azurite
       networks:
         eh-emulator:
           aliases:
             - "eventhubs-emulator"
     azurite:
       container_name: "azurite"
       image: "mcr.microsoft.com/azure-storage/azurite:latest"
       ports:
         - "10000:10000"
         - "10001:10001"
         - "10002:10002"
       networks:
         eh-emulator:
           aliases:
             - "azurite"
   networks:
     eh-emulator:
   

3. Create an .env file to declare the environment variables for the Event Hubs emulator:

   # Centralized environment variables store for docker-compose
   
   # 1. CONFIG_PATH: Path to config.json file
   CONFIG_PATH="<Replace with path to config.json file>" 
   
   # 2. ACCEPT_EULA: Pass 'Y' to accept license terms. 
   ACCEPT_EULA="N"
   
   

   The argument ACCEPT_EULA confirms the Microsoft Software License Terms. Be sure to place the .env file in the same directory as the docker-compose.yaml file.

   Important

   When you're specifying file paths in Windows, use double backslashes (\\) instead of single backslashes (\) to avoid confusion with escape characters.

4. Run the following command to run the emulator:

    docker compose -f <PathToDockerComposeFile> up -d
   

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

Interact with the emulator

You can use the following connection string to connect to the Event Hubs emulator:

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

With the latest client SDK releases, you can interact with the emulator in various programming languages. For details, see Client SDKs.

To get started, refer to the Event Hubs emulator samples on GitHub.

Related content

Overview of the Azure Event Hubs emulator