Skip to content

Configuration

Jump to bottom
Paul Mcilreavy edited this page Dec 22, 2025 · 2 revisions

Topics and their subscribers are configured in the appsettings.json file.

You can add multiple topics. Each topic must have a unique port. Each topic can have multiple subscribers.

Basic Example

An example of one topic with one subscriber:

{
  "topics": [
    {
      "name": "MyAwesomeTopic",
      "port": 60101,
      "key": "TheLocal+DevelopmentKey=",
      "subscribers": [
        {
          "name": "LocalAzureFunctionSubscription",
          "endpoint": "http://localhost:7071/runtime/webhooks/EventGrid?functionName=PersistEventToDb",
          "disableValidation": true
        }
      ]
    }
  ]
}

Topic Settings

Setting Description
name The name of the topic. It can only contain letters, numbers, and dashes.
port The port to use for the topic endpoint. The topic will listen on https://0.0.0.0:{port}/.
key The key that will be used to validate the aeg-sas-key or aeg-sas-token header in each request. If this is not supplied then no key validation will take place.
disabled (Optional) Set to true to disable this topic. The topic will not be started and events cannot be published to it.
subscribers The subscriptions for this topic.
inputSchema (Optional) The expected input event schema. Values: EventGridSchema or CloudEventV1_0. If not specified, the schema is auto-detected from the request.
outputSchema (Optional) The output event schema for delivery to subscribers. If not specified, events are delivered in the same schema they were received in.
serviceBusConnectionString (Optional) Default Service Bus connection string for all Service Bus subscribers in this topic. Subscribers can override with their own.
serviceBusNamespace (Optional) Default Service Bus namespace (without .servicebus.windows.net). Use with serviceBusSharedAccessKeyName and serviceBusSharedAccessKey.
serviceBusSharedAccessKeyName (Optional) Default shared access key name for Service Bus.
serviceBusSharedAccessKey (Optional) Default shared access key for Service Bus.
storageQueueConnectionString (Optional) Default Storage Queue connection string for all Storage Queue subscribers in this topic. Subscribers can override with their own.
eventHubConnectionString (Optional) Default Event Hub connection string for all Event Hub subscribers in this topic. Subscribers can override with their own.
eventHubNamespace (Optional) Default Event Hub namespace (without .servicebus.windows.net). Use with eventHubSharedAccessKeyName and eventHubSharedAccessKey.
eventHubSharedAccessKeyName (Optional) Default shared access key name for Event Hub.
eventHubSharedAccessKey (Optional) Default shared access key for Event Hub.

App Settings

Setting Description
dangerousAcceptAnyServerCertificateValidator Set to true to accept any server certificate. Useful when testing with self-signed certificates.
dashboardEnabled Enable the web-based dashboard UI for viewing event history and diagnostics. Default: true.
dashboardPort Optional dedicated port for the dashboard. If not set, dashboard is served on each topic's port.

Subscriber Types

The simulator supports four subscriber types:

Grouped Format (Recommended)

{
  "subscribers": {
    "http": [
      {
        "name": "WebhookSubscription",
        "endpoint": "https://example.com/webhook"
      }
    ],
    "serviceBus": [
      {
        "name": "ServiceBusSubscription",
        "connectionString": "Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=...;SharedAccessKey=...",
        "queue": "my-queue"
      }
    ],
    "storageQueue": [
      {
        "name": "StorageQueueSubscription",
        "connectionString": "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net",
        "queueName": "my-queue"
      }
    ],
    "eventHub": [
      {
        "name": "EventHubSubscription",
        "connectionString": "Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=...;SharedAccessKey=...",
        "eventHubName": "my-event-hub"
      }
    ]
  }
}

Legacy Format (Still Supported)

For backwards compatibility, a flat array of HTTP subscribers is still supported:

{
  "subscribers": [
    {
      "name": "WebhookSubscription",
      "endpoint": "https://example.com/webhook"
    }
  ]
}

Complete Example

{
  "topics": [
    {
      "name": "OrdersTopic",
      "port": 60101,
      "key": "TheLocal+DevelopmentKey=",
      "serviceBusConnectionString": "Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=...",
      "storageQueueConnectionString": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=...;EndpointSuffix=core.windows.net",
      "eventHubConnectionString": "Endpoint=sb://my-eventhub-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=...",
      "subscribers": {
        "http": [
          {
            "name": "WebhookSubscription",
            "endpoint": "https://myapp.com/webhooks/orders",
            "disableValidation": true,
            "filter": {
              "includedEventTypes": ["Order.Created", "Order.Updated"]
            }
          }
        ],
        "serviceBus": [
          {
            "name": "OrdersQueueSubscription",
            "queue": "orders-queue",
            "properties": {
              "OrderId": { "type": "dynamic", "value": "data.orderId" },
              "EventType": { "type": "dynamic", "value": "EventType" },
              "Source": { "type": "static", "value": "EventGridSimulator" }
            }
          }
        ],
        "storageQueue": [
          {
            "name": "OrdersStorageQueueSubscription",
            "queueName": "orders-archive"
          }
        ],
        "eventHub": [
          {
            "name": "OrdersEventHubSubscription",
            "eventHubName": "orders-events",
            "deliverySchema": "CloudEventV1_0",
            "properties": {
              "OrderId": { "type": "dynamic", "value": "data.orderId" },
              "Region": { "type": "static", "value": "west-us" }
            }
          }
        ]
      }
    }
  ]
}

Note: The serviceBus, storageQueue, and eventHub subscribers above inherit their connection strings from the topic-level settings. Subscribers can override these by specifying their own connectionString.

Command Line Configuration

You can specify the configuration file to use by setting the ConfigFile command line argument:

AzureEventGridSimulator.exe --ConfigFile=/path/to/config.json

Environment Variable Configuration

The simulator supports configuration via environment variables using the AEGS_ prefix. This is useful for Docker and containerized deployments.

Format

Environment variables use double underscores (__) to represent nested JSON paths:

# Topic configuration
AEGS_topics__0__name=MyTopic
AEGS_topics__0__port=60101
AEGS_topics__0__key=TheLocal+DevelopmentKey=

# Subscriber configuration
AEGS_topics__0__subscribers__http__0__name=MySubscriber
AEGS_topics__0__subscribers__http__0__endpoint=http://localhost:7071/api/MyFunction
AEGS_topics__0__subscribers__http__0__disableValidation=true

# App settings
AEGS_dashboardEnabled=true
AEGS_dashboardPort=9000

Docker Example

docker run -p 60101:60101 \
  -e AEGS_topics__0__name=MyTopic \
  -e AEGS_topics__0__port=60101 \
  -e AEGS_topics__0__key=TheLocal+DevelopmentKey= \
  -e AEGS_topics__0__subscribers__http__0__name=MySubscriber \
  -e AEGS_topics__0__subscribers__http__0__endpoint=http://host.docker.internal:7071/api/MyFunction \
  pmcilreavy/azureeventgridsimulator

Environment Name

The ENVIRONMENT variable controls which appsettings.{Environment}.json file is loaded:

ENVIRONMENT=Development  # Loads appsettings.Development.json

Naming Rules

Topic and subscriber names must follow these rules:

  • Can only contain letters, numbers, and dashes (a-z, A-Z, 0-9, -)
  • Cannot be empty
  • Topic names must be unique across all topics
  • Subscriber names must be unique across all topics (globally unique)

Related Topics

Getting Started

Subscribers

Features

Deployment

Reference

Clone this wiki locally