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, highest first):

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

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__http__0__name=MySubscriber
export AEGS_topics__0__subscribers__http__0__endpoint=http://localhost:7071/api/events
export AEGS_topics__0__subscribers__http__0__disableValidation=true
azure-eventgrid-simulator

Runtime Requirements

The tool supports multiple .NET runtimes:

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

The tool multi-targets all three; it runs on whichever of these runtimes matches your installed SDK, rolling forward to the latest installed minor version (RollForward: LatestMinor).

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