DotNet Tool

The simulator can be installed and run as a global or local .NET tool.

Installation

Global Installation

Install the tool globally to make it available from any directory:

dotnet tool install -g AzureEventGridSimulator

Run it:

azure-eventgrid-simulator

Local Installation

Install the tool locally within a project:

dotnet new tool-manifest
dotnet tool install AzureEventGridSimulator

Run it:

dotnet tool run azure-eventgrid-simulator

Updating

Global Tool

dotnet tool update -g AzureEventGridSimulator

Local Tool

dotnet tool update AzureEventGridSimulator

Uninstalling

Global Tool

dotnet tool uninstall -g AzureEventGridSimulator

Local Tool

dotnet tool uninstall AzureEventGridSimulator

Configuration

The tool reads configuration from several sources (in order of precedence):

1. Command-line arguments
2. Environment variables (with AEGS_ prefix)
3. appsettings.json in the current directory
4. Custom config file specified via --ConfigFile

Using appsettings.json

Create an appsettings.json file in the directory where you run the tool:

{
  "topics": [
    {
      "name": "MyTopic",
      "port": 60101,
      "key": "TheLocal+DevelopmentKey=",
      "subscribers": [
        {
          "name": "MySubscriber",
          "endpoint": "http://localhost:7071/api/MyFunction",
          "disableValidation": true
        }
      ]
    }
  ]
}

Using a Custom Config File

azure-eventgrid-simulator --ConfigFile=/path/to/my-config.json

Using Environment Variables

Environment variables use the AEGS_ prefix with __ as the hierarchy separator:

export AEGS_topics__0__name=MyTopic
export AEGS_topics__0__port=60101
export AEGS_topics__0__key="TheLocal+DevelopmentKey="
export AEGS_topics__0__subscribers__0__name=MySubscriber
export AEGS_topics__0__subscribers__0__endpoint=http://localhost:7071/api/events
azure-eventgrid-simulator

Runtime Requirements

The tool supports multiple .NET runtimes:

• .NET 8.0
• .NET 9.0
• .NET 10.0

The tool will use the highest installed runtime by default due to the RollForward policy.

Comparison with Other Deployment Options

Feature	.NET Tool	Docker	Aspire
Installation	dotnet tool install	docker pull	Clone repo
Configuration	appsettings.json	Environment variables	AppHost code
Azure Emulators	Manual setup	docker-compose	Automatic
Observability	Serilog	Serilog + Seq	Aspire Dashboard
Best for	Quick local testing	CI/CD pipelines	Full local dev

Troubleshooting

Tool Not Found After Installation

Ensure the .NET tools directory is in your PATH:

• Windows: %USERPROFILE%\.dotnet\tools
• macOS/Linux: ~/.dotnet/tools

Configuration Not Loading

1. Verify appsettings.json is in the current working directory
2. Check JSON syntax is valid
3. Try using --ConfigFile with an absolute path

Port Already in Use

If you see a port binding error, another process is using the configured port. Either:

• Stop the other process
• Change the topic port in configuration

Related Topics

• Configuration - Full configuration reference
• Docker - Container deployment
• Aspire - Local development with .NET Aspire