Installation Guide¶

Verified by tests

ServiceRegistrationGeneratorTests, EFCoreServiceRegistrationGeneratorTests — library CI run #31657041675 (2026-08-13)

This guide walks you through installing Whizbang and setting up your first project.

Prerequisites¶

Before installing Whizbang, ensure you have:

Required¶

.NET 10.0 SDK (10.0.100 or later — the repository pins 10.0.100 in global.json)
```
dotnet --version
# Should show 10.0.100 or later
```
Latest C# language version (the repository builds with <LangVersion>latest</LangVersion>, included with the .NET 10 SDK)

Recommended¶

Visual Studio (with .NET 10 SDK support) or Visual Studio Code with C# Dev Kit
Docker Desktop (for PostgreSQL and Azure Service Bus Emulator)
.NET Aspire Workload (for orchestration):
```
dotnet workload install aspire
```

Installation Options¶

Option 1: NuGet Packages (Recommended)¶

Install Whizbang packages for your specific needs:

Core Package¶

Core Package

dotnet add package Whizbang.Core

Includes: - Core interfaces (IDispatcher, IReceptor, IPerspectiveFor, ILensQuery) - Message envelope and observability - Background workers (outbox publish, inbox dispatch, perspectives) - Object pooling for performance - Policy engine foundation

Data Access Packages¶

Dapper + PostgreSQL (lightweight, fast): Data Access Packages

dotnet add package Whizbang.Data.Dapper.Postgres

EF Core + PostgreSQL (full-featured): Data Access Packages (2)

dotnet add package Whizbang.Data.EFCore.Postgres
dotnet add package Whizbang.Data.EFCore.Postgres.Generators

SQLite (development/testing): Data Access Packages (3)

dotnet add package Whizbang.Data.Dapper.Sqlite

Transport Packages¶

Azure Service Bus: Transport Packages

dotnet add package Whizbang.Transports.AzureServiceBus
dotnet add package Whizbang.Hosting.Azure.ServiceBus

RabbitMQ: Transport Packages - RabbitMQ

dotnet add package Whizbang.Transports.RabbitMQ
dotnet add package Whizbang.Hosting.RabbitMQ

Source Generators¶

Automatic Discovery: Source Generators

dotnet add package Whizbang.Generators

Includes: - Receptor discovery and registration (generated AddReceptors() / AddWhizbangDispatcher()) - Perspective discovery (generated AddPerspectiveRunners()) - Message registry generation (VSCode extension) - Strongly-typed ID generation ([WhizbangId]) - AOT-compatible JSON contexts

Option 2: Package Bundle¶

For complete functionality, add all packages:

Option 2: Package Bundle

<!-- YourProject.csproj -->
<ItemGroup>
  <PackageReference Include="Whizbang.Core" Version="x.x.x" />
  <PackageReference Include="Whizbang.Generators" Version="x.x.x" />
  <PackageReference Include="Whizbang.Data.Dapper.Postgres" Version="x.x.x" />
  <PackageReference Include="Whizbang.Transports.AzureServiceBus" Version="x.x.x" />
  <PackageReference Include="Whizbang.Hosting.Azure.ServiceBus" Version="x.x.x" />
</ItemGroup>

Option 3: Central Package Management (Recommended for Solutions)¶

Use Directory.Packages.props for version management:

Option 3: Central Package Management (Recommended for

<!-- Directory.Packages.props -->
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <!-- Whizbang Packages -->
    <PackageVersion Include="Whizbang.Core" Version="x.x.x" />
    <PackageVersion Include="Whizbang.Generators" Version="x.x.x" />
    <PackageVersion Include="Whizbang.Data.Dapper.Postgres" Version="x.x.x" />
    <PackageVersion Include="Whizbang.Data.EFCore.Postgres" Version="x.x.x" />
    <PackageVersion Include="Whizbang.Data.EFCore.Postgres.Generators" Version="x.x.x" />
    <PackageVersion Include="Whizbang.Transports.AzureServiceBus" Version="x.x.x" />
    <PackageVersion Include="Whizbang.Hosting.Azure.ServiceBus" Version="x.x.x" />
  </ItemGroup>
</Project>

Then in project files:

Option 3: Central Package Management (Recommended for

<!-- YourProject.csproj -->
<ItemGroup>
  <PackageReference Include="Whizbang.Core" />
  <PackageReference Include="Whizbang.Generators" />
  <!-- Versions come from Directory.Packages.props -->
</ItemGroup>

Project Setup¶

1. Create New Project¶

Create New Project

# Create solution
dotnet new sln -n MyWhizbangApp

# Create ASP.NET Core Web API project
dotnet new webapi -n MyWhizbangApp.API
dotnet sln add MyWhizbangApp.API

# Add Whizbang packages
cd MyWhizbangApp.API
dotnet add package Whizbang.Core
dotnet add package Whizbang.Generators
dotnet add package Whizbang.Data.Dapper.Postgres

2. Configure Target Framework¶

Ensure your project targets .NET 10:

Configure Target Framework

<!-- MyWhizbangApp.API.csproj -->
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <LangVersion>latest</LangVersion>
  </PropertyGroup>
</Project>

3. Add Directory.Build.props (Optional but Recommended)¶

Create solution-level build configuration:

Add Directory.Build.props (Optional but Recommended)

<!-- Directory.Build.props -->
<Project>
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <LangVersion>latest</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>

  <PropertyGroup>
    <!-- Source Generator Settings -->
    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
    <CompilerGeneratedFilesOutputPath>$(MSBuildProjectDirectory)/.whizbang/cache</CompilerGeneratedFilesOutputPath>
  </PropertyGroup>
</Project>

4. Configure .editorconfig (K&R/Egyptian Braces)¶

Whizbang follows K&R/Egyptian braces style:

# .editorconfig
root = true

[*.cs]
# Brace style - K&R/Egyptian (opening brace on same line)
csharp_new_line_before_open_brace = none
csharp_new_line_before_else = false
csharp_new_line_before_catch = false
csharp_new_line_before_finally = false

# Indentation
indent_style = space
indent_size = 4

# Naming conventions
dotnet_naming_rule.async_methods_end_in_async.severity = warning
dotnet_naming_rule.async_methods_end_in_async.symbols = async_methods
dotnet_naming_rule.async_methods_end_in_async.style = end_in_async

dotnet_naming_symbols.async_methods.applicable_kinds = method
dotnet_naming_symbols.async_methods.required_modifiers = async

dotnet_naming_style.end_in_async.required_suffix = Async
dotnet_naming_style.end_in_async.capitalization = pascal_case

Database Setup¶

PostgreSQL (Recommended for Production)¶

Option A: Docker (Easiest)¶

Option A: Docker (Easiest)

docker run -d \
  --name whizbang-postgres \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_USER=whizbang \
  -e POSTGRES_DB=whizbang \
  -p 5432:5432 \
  postgres:16

Option B: .NET Aspire (Automatic)¶

With Aspire, PostgreSQL starts automatically:

Option B: .NET Aspire (Automatic)

// AppHost/Program.cs
var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
    .WithPgAdmin()
    .AddDatabase("whizbangdb");

var api = builder.AddProject<Projects.MyWhizbangApp_API>("api")
    .WithReference(postgres);

builder.Build().Run();

Connection String Configuration¶

appsettings.Development.json: Connection String Configuration

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=whizbang;Username=whizbang;Password=your_password"
  }
}

IDE Configuration¶

Visual Studio¶

Install .NET 10 SDK (bundled with recent Visual Studio releases)
Enable Source Generators:
Tools → Options → Text Editor → C# → Advanced
Check "Enable source generators"
View Generated Files:
Solution Explorer → Show All Files
Expand .whizbang/cache/ folder

Visual Studio Code¶

Install Extensions:

code --install-extension ms-dotnettools.csdevkit
code --install-extension ms-dotnettools.csharp

Configure settings.json:

{
  "dotnet.testWindow.useTestingPlatformProtocol": true,
  "omnisharp.enableRoslynAnalyzers": true,
  "omnisharp.enableEditorConfigSupport": true
}

Install Whizbang VSCode Extension (Optional):
Provides CodeLens annotations
Message flow visualization
Jump-to-definition for handlers

JetBrains Rider¶

Enable Source Generators:
Settings → Build, Execution, Deployment → Toolset and Build
Check "Enable source generators"
Configure NuGet Sources:
Settings → NuGet → Sources
Add nuget.org if not present

Verify Installation¶

1. Build Project¶

Build Project

dotnet build

Expected output:

Build succeeded.
    0 Warning(s)
    0 Error(s)

2. Check Source Generators¶

Check Source Generators

ls .whizbang/cache/

Expected files (after adding receptors — generated sources are grouped per generator):

.whizbang/cache/
└── Whizbang.Generators/
    ├── Whizbang.Generators.ReceptorDiscoveryGenerator/
    │   ├── ReceptorRegistry.g.cs
    │   ├── DispatcherRegistrations.g.cs
    │   └── Dispatcher.g.cs
    ├── Whizbang.Generators.PerspectiveDiscoveryGenerator/
    │   └── PerspectiveRegistrations.g.cs
    └── Whizbang.Generators.MessageRegistryGenerator/
        └── MessageRegistry.g.cs

3. Run Tests (if added)¶

Run Tests (if added)

dotnet test

Troubleshooting¶

Issue: Source Generators Not Running¶

Symptoms: No files in .whizbang/cache/

Solutions: 1. Rebuild solution: dotnet clean && dotnet build 2. Check generator package is referenced:

dotnet list package | grep Whizbang.Generators

3. Enable verbose MSBuild output:

dotnet build -v:detailed | grep Whizbang

Issue: "Type 'IReceptor' Not Found"¶

Symptoms: Cannot resolve Whizbang types

Solutions: 1. Verify package installation:

dotnet restore
dotnet list package

2. Check target framework is net10.0 3. Add using directive:

using Whizbang.Core;

Issue: PostgreSQL Connection Fails¶

Symptoms: "Connection refused" or timeout errors

Solutions: 1. Check PostgreSQL is running:

docker ps | grep postgres

2. Test connection:

psql -h localhost -U whizbang -d whizbang

3. Verify connection string in appsettings.json

Issue: Native AOT Warnings¶

Symptoms: Trimming warnings during publish

Solutions: 1. Whizbang is trimming-safe by design 2. Ensure all JSON contexts are generated:

[JsonSerializable(typeof(YourMessage))]
partial class YourJsonContext : JsonSerializerContext { }

3. Use Whizbang.Generators to auto-generate contexts

Next Steps¶

✅ Installation Complete!

What's Next?

Quick Start Tutorial - Build your first Whizbang app
Project Structure Guide - Organize your application
Core Concepts: Receptors - Understand message handling

Additional Resources¶

Sample Projects: /samples/ECommerce in the Whizbang repository
Package Documentation: https://nuget.org/packages/Whizbang.Core
GitHub Issues: https://github.com/whizbang-lib/whizbang/issues

Version 1.0.0 - Foundation Release | Last Updated: 2024-12-12