ECommerce Tutorial Overview

Verified by tests

OrderServiceIntegrationTests, CreateProductWorkflowTests — library CI run #31657041675 (2026-08-13)

Build a complete e-commerce system using Whizbang to learn all framework features through a realistic, production-ready example.

What You'll Build

A distributed e-commerce platform with 7 microservices:

flowchart TD
    subgraph EPA["ECommerce Platform Architecture"]
        OrderSvc["Order Service<br/>(Commands)"]
        InventorySvc["Inventory Service<br/>(Commands)"]
        PaymentSvc["Payment Service<br/>(Commands)"]
        Bus["Azure Service Bus<br/>(Topics)"]
        NotificationSvc["Notification Service<br/>(Events)"]
        ShippingSvc["Shipping Service<br/>(Events)"]
        AnalyticsSvc["Analytics Service<br/>(Perspectives)"]

        OrderSvc --> Bus
        InventorySvc --> Bus
        PaymentSvc --> Bus
        Bus --> NotificationSvc
        Bus --> ShippingSvc
        Bus --> AnalyticsSvc
    end

    class OrderSvc,InventorySvc,PaymentSvc layer-command
    class Bus layer-event
    class NotificationSvc,ShippingSvc layer-core
    class AnalyticsSvc layer-read

Services

Service	Type	Purpose
Order Service	Command API	Order management, CRUD operations
Inventory Service	Command Worker	Stock tracking, reservations
Payment Service	Command Worker	Payment processing, transactions
Notification Service	Event Worker	Email/SMS notifications
Shipping Service	Event Worker	Shipment creation, tracking
Customer Service	Query API	Customer read models (BFF)
Analytics Service	Event Worker	Real-time analytics, reporting

What You'll Learn

Core Features

• ✅ Commands & Events - Request/response + pub/sub patterns
• ✅ Receptors - Message handlers with business logic
• ✅ Perspectives - Event-driven read models (CQRS)
• ✅ Dispatcher - Zero-reflection message routing
• ✅ Message Context - Correlation, causation, tracing

Messaging Patterns

• ✅ Outbox Pattern - Reliable cross-service events
• ✅ Inbox Pattern - Exactly-once message processing
• ✅ Work Coordination - Lease-based distributed processing
• ✅ Event Envelopes - Hop-based observability

Data Access

• ✅ Dapper + PostgreSQL - High-performance queries
• ✅ EF Core 10 - Full-featured ORM
• ✅ Event Store - Event sourcing with time-travel
• ✅ Perspectives Storage - Read model schemas

Infrastructure

• ✅ .NET Aspire - Local orchestration with emulators
• ✅ Azure Service Bus - Production messaging
• ✅ Health Checks - Kubernetes readiness/liveness
• ✅ Policy-Based Routing - Multi-tenant, environment-aware

Advanced Topics

• ✅ Source Generators - Zero-reflection discovery
• ✅ AOT Compatibility - Native AOT deployment
• ✅ Testing - Unit, integration, e2e tests
• ✅ Deployment - Docker, Kubernetes, Azure

Prerequisites

• .NET 10.0 RC2+ SDK
• Docker Desktop (for PostgreSQL, Azurite, Service Bus emulator)
• Visual Studio 2024 or VS Code with C# DevKit
• Azure CLI (for production deployment)
• Basic C# knowledge (records, async/await, dependency injection)

Tutorial Structure

Part 1: Foundation (Order & Inventory)

1. Tutorial Overview ← You are here
2. Order Management - Create orders, command handling
3. Inventory Service - Stock reservations, event publishing

Part 2: Distributed Processing (Payment & Notifications)

1. Payment Processing - Payment gateway integration
2. Notification Service - Email/SMS via events

Part 3: Logistics & Analytics (Shipping & Reporting)

1. Shipping Service - Shipment creation, tracking
2. Analytics Service - Real-time dashboards

Part 4: Customer Experience (Read Models)

1. Customer Service - BFF pattern, perspectives

Part 5: Production Readiness

1. Testing Strategy - Unit, integration, e2e tests
2. Deployment - Docker, Kubernetes, Azure

Project Setup

1. Create Solution

Create Solution

mkdir ECommerce
cd ECommerce

dotnet new sln -n ECommerce

2. Add Projects

Add Projects

# Order Service (HTTP API)
dotnet new webapi -n ECommerce.OrderService.API
dotnet sln add ECommerce.OrderService.API

# Inventory Service (Background Worker)
dotnet new worker -n ECommerce.InventoryWorker
dotnet sln add ECommerce.InventoryWorker

# Payment Service (Background Worker)
dotnet new worker -n ECommerce.PaymentWorker
dotnet sln add ECommerce.PaymentWorker

# Notification Service (Background Worker)
dotnet new worker -n ECommerce.NotificationWorker
dotnet sln add ECommerce.NotificationWorker

# Shipping Service (Background Worker)
dotnet new worker -n ECommerce.ShippingWorker
dotnet sln add ECommerce.ShippingWorker

# Customer Service (HTTP API - BFF)
dotnet new webapi -n ECommerce.CustomerService.API
dotnet sln add ECommerce.CustomerService.API

# Analytics Service (Background Worker)
dotnet new worker -n ECommerce.AnalyticsWorker
dotnet sln add ECommerce.AnalyticsWorker

# Shared Contracts
dotnet new classlib -n ECommerce.Contracts
dotnet sln add ECommerce.Contracts

# Aspire App Host (Orchestration)
dotnet new aspire-apphost -n ECommerce.AppHost
dotnet sln add ECommerce.AppHost

3. Add Whizbang Packages

Add Whizbang Packages

# All projects
dotnet add ECommerce.OrderService.API package Whizbang.Core
dotnet add ECommerce.InventoryWorker package Whizbang.Core
dotnet add ECommerce.PaymentWorker package Whizbang.Core
dotnet add ECommerce.NotificationWorker package Whizbang.Core
dotnet add ECommerce.ShippingWorker package Whizbang.Core
dotnet add ECommerce.CustomerService.API package Whizbang.Core
dotnet add ECommerce.AnalyticsWorker package Whizbang.Core

# Projects with Azure Service Bus
dotnet add ECommerce.OrderService.API package Whizbang.Transports.AzureServiceBus
dotnet add ECommerce.InventoryWorker package Whizbang.Transports.AzureServiceBus
dotnet add ECommerce.PaymentWorker package Whizbang.Transports.AzureServiceBus
dotnet add ECommerce.NotificationWorker package Whizbang.Transports.AzureServiceBus
dotnet add ECommerce.ShippingWorker package Whizbang.Transports.AzureServiceBus
dotnet add ECommerce.AnalyticsWorker package Whizbang.Transports.AzureServiceBus

# Projects with PostgreSQL (EF Core driver)
dotnet add ECommerce.OrderService.API package Whizbang.Data.EFCore.Postgres
dotnet add ECommerce.InventoryWorker package Whizbang.Data.EFCore.Postgres
dotnet add ECommerce.CustomerService.API package Whizbang.Data.EFCore.Postgres
dotnet add ECommerce.AnalyticsWorker package Whizbang.Data.EFCore.Postgres

# Aspire integration (AppHost only)
dotnet add ECommerce.AppHost package Aspire.Hosting.Azure.ServiceBus
dotnet add ECommerce.AppHost package Whizbang.Hosting.Azure.ServiceBus

4. Project Structure

ECommerce/
├── ECommerce.sln
├── ECommerce.AppHost/             # .NET Aspire orchestration
├── ECommerce.Contracts/           # Shared messages
│   ├── Ids.cs                     # [WhizbangId] strongly-typed IDs
│   ├── Commands/
│   │   ├── CreateOrderCommand.cs
│   │   ├── ReserveInventoryCommand.cs
│   │   └── ProcessPaymentCommand.cs
│   └── Events/
│       ├── OrderCreatedEvent.cs
│       ├── InventoryReservedEvent.cs
│       └── PaymentProcessedEvent.cs
├── ECommerce.OrderService.API/    # Order management
│   ├── Receptors/
│   │   └── CreateOrderReceptor.cs
│   └── Endpoints/
│       └── Orders/CreateOrderEndpoint.cs
├── ECommerce.InventoryWorker/     # Inventory management
│   ├── Receptors/
│   │   └── ReserveInventoryReceptor.cs
│   └── Perspectives/
│       └── InventorySummaryPerspective.cs
├── ECommerce.PaymentWorker/       # Payment processing
│   └── Receptors/
│       └── ProcessPaymentReceptor.cs
├── ECommerce.NotificationWorker/  # Notifications
│   └── Receptors/
│       └── SendNotificationReceptor.cs
├── ECommerce.ShippingWorker/      # Shipping
│   └── Receptors/
│       └── CreateShipmentReceptor.cs
├── ECommerce.CustomerService.API/ # Customer BFF
│   ├── Perspectives/
│   │   ├── OrderSummaryPerspective.cs
│   │   └── CustomerActivityPerspective.cs
│   └── Controllers/
│       └── CustomersController.cs
└── ECommerce.AnalyticsWorker/     # Analytics
    └── Perspectives/
        └── DailySalesAnalyticsPerspective.cs

:::note The shipped sample at samples/ECommerce/ in the library repository uses ECommerce.BFF.API (Backend-for-Frontend with GraphQL, SignalR, and lens-backed endpoints) as its read-side service — the tutorial's CustomerService.API/AnalyticsWorker correspond to that role. :::

Key Concepts Demonstrated

Event-Driven Architecture

Event-Driven Architecture

// Command: Create Order (synchronous)
CreateOrderCommand → CreateOrderReceptor → OrderCreatedEvent

// Event: Order Created (asynchronous pub/sub)
OrderCreatedEvent → Published to Azure Service Bus
  ├─ InventoryWorker → ReserveInventoryCommand
  ├─ NotificationWorker → SendNotificationCommand
  └─ AnalyticsWorker → UpdateDailySales (perspective)

CQRS (Command Query Responsibility Segregation)

Write Side: - Order Service receives CreateOrderCommand - CreateOrderReceptor handles command - Publishes OrderCreatedEvent to event bus

Read Side: - Customer Service subscribes to OrderCreatedEvent - Order summary perspective updates the read model (pure Apply functions) - Lens queries serve the read model (fast!)

Saga Pattern (Distributed Transactions)

flowchart TD
    subgraph Saga["Saga: Order Processing"]
        S1["CreateOrder"] --> S2["OrderCreated"]
        S2 --> S3["ReserveInventory"] --> S4["InventoryReserved"]
        S4 --> S5["ProcessPayment"] --> S6["PaymentProcessed"]
        S6 --> S7["CreateShipment"] --> S8["ShipmentCreated"]
        S8 --> S9["SendShippingNotification"] --> S10["NotificationSent"]
    end

    subgraph Comp["Compensation (if payment fails)"]
        direction LR
        C1["PaymentFailed"] --> C2["ReleaseInventory"] --> C3["InventoryReleased"]
    end

    class S1,S3,S5,S7,S9,C2 layer-command
    class S2,S4,S6,S8,S10,C1,C3 layer-event

Development Workflow

1. Run Locally (Aspire)

Run Locally (Aspire)

cd ECommerce.AppHost
dotnet run

Open the Aspire Dashboard from the URL printed in the console.

2. Create Order via API

Create Order via API

curl -X POST http://localhost:5000/api/orders \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "0195b3f0-1234-7abc-8def-0123456789ab",
    "lineItems": [
      { "productId": "0195b3f0-5678-7abc-8def-0123456789ab", "productName": "Widget", "quantity": 2, "unitPrice": 19.99 }
    ]
  }'

3. Observe Event Flow

Check Aspire Dashboard: - Order Service: HTTP request logged - Service Bus: OrderCreated event published - Inventory Worker: InventoryReserved event published - Payment Worker: PaymentProcessed event published - Notification Worker: Email sent

4. Query Read Model

Query Read Model

curl http://localhost:5001/customers/cust-123/orders

Returns denormalized order summary from read model (fast!).

Next Steps

Continue to Order Management to start building the Order Service.

---

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