Skip to content

Contributing

Jump to bottom
Paul Mcilreavy edited this page Jun 10, 2026 · 5 revisions

Thank you for your interest in contributing to the Azure Event Grid Simulator! This guide will help you get started with development.

Development Environment

Prerequisites

  • .NET 10.0 SDK or later
  • A code editor (Visual Studio, VS Code, Rider, etc.)
  • Git

Getting Started

  1. Clone the repository:

    git clone https://github.com/pm7y/AzureEventGridSimulator.git
cd AzureEventGridSimulator

  2. Restore dependencies:

    dotnet restore src/AzureEventGridSimulator.sln

  3. Build the project:

    dotnet build src/AzureEventGridSimulator.sln

  4. Run the simulator:

    cd src/AzureEventGridSimulator
dotnet run

Project Structure

AzureEventGridSimulator/
├── src/
│   ├── AzureEventGridSimulator/           # Main application
│   │   ├── Controllers/                   # HTTP endpoints
│   │   ├── Domain/
│   │   │   ├── Commands/                  # Command handlers
│   │   │   ├── Entities/                  # Domain models
│   │   │   └── Services/                  # Delivery, retry, dashboard, validation
│   │   ├── Infrastructure/
│   │   │   ├── Extensions/                # Filtering logic
│   │   │   ├── Mediator/                  # Custom mediator
│   │   │   ├── Middleware/                # Request processing
│   │   │   └── Settings/                  # Configuration models
│   │   └── Program.cs
│   ├── AzureEventGridSimulator.Tests/     # Tests
│   │   ├── UnitTests/
│   │   ├── IntegrationTests/
│   │   └── ActualSimulatorTests/
│   ├── AzureEventGridSimulator.AppHost/   # .NET Aspire orchestration
│   └── AzureEventGridSimulator.ServiceDefaults/ # Aspire service defaults
└── wiki/                                  # Documentation

See the Architecture page for a detailed explanation of the codebase.

Build Flavours

Building the solution produces two flavours of the simulator. The AppHost builds the simulator with ASPIRE_ENABLED=true (which compiles in the ServiceDefaults OpenTelemetry wiring) into separate bin/aspire/ and obj/aspire/ directories, while the regular build goes to the usual bin/ and obj/. Don't be surprised by the extra aspire output folders — the split keeps the two flavours from overwriting each other's outputs.

Code Formatting

This project uses CSharpier for consistent code formatting. CSharpier runs automatically on every build.

Manual Formatting

dotnet tool restore
dotnet csharpier format src

Editor Integration

For the best experience, install the CSharpier extension for your editor:

Running Tests

Unit Tests

dotnet test src/AzureEventGridSimulator.sln --filter "Category=unit"

Integration Tests

Integration tests require Docker for running dependent services:

dotnet test src/AzureEventGridSimulator.sln --filter "Category=integration"

All Tests

dotnet test src/AzureEventGridSimulator.sln

CI/CD and Releases

GitHub Workflows

The project uses several GitHub Actions workflows:

Workflow Trigger Purpose
CI (ci.yml) Pull requests Build and test on Windows, Ubuntu, macOS
Release Please (release-please.yml) Push to master Creates release PRs from conventional commits
Release (release.yml) Release published Builds and uploads platform binaries
NuGet Release (nuget-release.yml) Release published Publishes to NuGet.org
Docker Release (docker-release.yml) Release published Publishes to Docker Hub
CodeQL (codeql.yml) Push/PR Security analysis

Release Please

This project uses Release Please to automate releases. It works by:

  1. Analyzing commits - Scans conventional commit messages since the last release
  2. Creating a release PR - Automatically opens a PR with version bump and changelog updates
  3. Publishing on merge - When the release PR is merged, it creates a GitHub release and triggers deployment workflows

Conventional Commits

Commit messages must follow Conventional Commits format. This is enforced by git hooks installed on first build.

Prefix Purpose Appears in Changelog
feat: New feature Yes
fix: Bug fix Yes
perf: Performance improvement Yes
deps: Dependency updates Yes
docs: Documentation No
chore: Maintenance No
refactor: Code changes No
test: Tests No
build: Build system No
ci: CI configuration No

Examples:

feat: add Azure Storage Queue subscriber support
fix: correct retry delay calculation
docs: update configuration examples
chore: update dependencies

Version Bumping

Release Please determines version bumps based on commit types:

  • feat: commits trigger a minor version bump (1.0.0 → 1.1.0)
  • fix: commits trigger a patch version bump (1.0.0 → 1.0.1)
  • Breaking changes trigger a major version bump (1.0.0 → 2.0.0)

Indicating breaking changes:

Use ! after the type (recommended):

feat!: remove deprecated API endpoint
feat(api)!: change authentication method

Or use BREAKING CHANGE: in the commit footer:

feat: change authentication method

BREAKING CHANGE: API now requires OAuth tokens instead of API keys

Making Changes

Branch Naming

Use descriptive branch names:

  • feature/add-new-subscriber-type
  • fix/retry-calculation-bug
  • docs/update-configuration-guide

Code Style

  • Follow existing patterns in the codebase
  • Use meaningful variable and method names
  • Add XML documentation for public APIs
  • Keep methods focused and small

Pull Requests

Before Submitting

  1. Ensure tests pass:

    dotnet test src/AzureEventGridSimulator.sln

  2. Format your code:

    dotnet csharpier format src

  3. Build without warnings:

    dotnet build src/AzureEventGridSimulator.sln --warnaserror

PR Guidelines

  • Provide a clear description of what the PR does
  • Reference any related issues
  • Include tests for new functionality
  • Update documentation if needed
  • Keep PRs focused - one feature or fix per PR

Review Process

  1. Submit your PR against the master branch
  2. Wait for CI checks to pass
  3. Address any review feedback
  4. Once approved, the maintainer will merge

Adding New Features

New Subscriber Type

To add a new subscriber type:

  1. Create settings class in Infrastructure/Settings/
  2. Implement delivery service in Domain/Services/Delivery/
  3. Register in dependency injection
  4. Add configuration documentation
  5. Add tests

New Configuration Option

  1. Add property to appropriate settings class
  2. Update validation if needed
  3. Document in wiki Configuration page
  4. Add tests

Reporting Issues

When reporting bugs, please include:

  1. Environment details:

    • OS and version
    • .NET version (dotnet --version)
    • Simulator version

  2. Configuration:

    • Relevant appsettings.json (redact sensitive values)

  3. Steps to reproduce:

    • Clear, numbered steps
    • Expected vs actual behavior

  4. Logs:

    • Any error messages or stack traces

Feature Requests

Before submitting a feature request:

  1. Check existing issues for duplicates
  2. Consider if the feature aligns with the project's goals
  3. Provide a clear use case

Questions?

Related Topics

Home

Getting Started

Subscribers

Features

Deployment

Reference

Clone this wiki locally