Skip to content

Configuration

Jump to bottom
Paul Mcilreavy edited this page Sep 19, 2026 · 5 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 extra port to serve the dashboard on, in addition to each enabled topic's port.
eventValidationLimits.maximumOverallMessageSizeInBytes Maximum size of a whole request body, in bytes. Larger requests are rejected with 413. Default: 1536000 (~1.5 MB).
eventValidationLimits.maximumEventSizeInBytes Maximum size of each individual event, in bytes. A request with a larger event is rejected with 413. Default: 1049600 (~1 MB).

The defaults match Azure Event Grid's limits (see Size Validation). eventValidationLimits sits at the root of the configuration, next to topics. Raise the limits if you need to publish larger test payloads:

{
  "eventValidationLimits": {
    "maximumOverallMessageSizeInBytes": 3072000,
    "maximumEventSizeInBytes": 2099200
  }
}

Or with environment variables:

AEGS_eventValidationLimits__maximumOverallMessageSizeInBytes=3072000
AEGS_eventValidationLimits__maximumEventSizeInBytes=2099200

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. Note that the legacy format only supports HTTP subscribers — Service Bus, Storage Queue, and Event Hub subscribers require the grouped format above.

{
  "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, or the AEGS_ConfigFile environment variable:

# .NET tool
azure-eventgrid-simulator --ConfigFile=/path/to/config.json

# Release binary (AzureEventGridSimulator.exe on Windows)
./AzureEventGridSimulator --ConfigFile=/path/to/config.json

# Environment variable (e.g. in Docker)
AEGS_ConfigFile=/path/to/config.json azure-eventgrid-simulator

A relative path is resolved against the current directory. The file is loaded on top of appsettings.json and appsettings.{Environment}.json, and environment variables and command-line arguments still override it. See DotNet Tool for the tool, and docker/README.md for mounting a config file into the container.

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 name controls which appsettings.{Environment}.json file is loaded. The simulator only reads environment variables with the ASPNETCORE_ or AEGS_ prefix, so set one of:

ASPNETCORE_ENVIRONMENT=Development  # Loads appsettings.Development.json
# or equivalently
AEGS_ENVIRONMENT=Development

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 within their topic (case-insensitive); the same name may be reused on different topics, matching Azure Event Grid

Related Topics

Home

Getting Started

Subscribers

Features

Deployment

Reference

Clone this wiki locally