run-aspnetcore-microservices: A .NET 8 E-Commerce Microservices Reference on GitHub

What This Repository Is and Who It Is For

run-aspnetcore-microservices is a companion repository for a step-by-step Udemy course on microservices architecture with .NET 8. The README describes its purpose: to show the overall picture of microservices implementations using real-world e-commerce modules. It is aimed at .NET developers who want to see how multiple patterns and technologies fit together in a single project: domain-driven design, CQRS with MediatR, Clean and Vertical Slice Architecture, gRPC inter-service communication, RabbitMQ event-driven messaging, Yarp API Gateway, and containerization with Docker Compose.

The project implements an e-commerce scenario with four domain microservices (Catalog, Basket, Discount, Ordering), an API Gateway, and a shopping web application. Each microservice owns its own database and demonstrates a different combination of .NET and data-access patterns. The repository has a companion Medium article on .NET 8 Microservices covering DDD, CQRS, Vertical/Clean Architecture, and Event-Driven Communication, and is maintained by Mehmet Ozkaya. The project is licensed under MIT and uses only the source directory (src/) alongside the standard .gitignore, LICENSE, and README files at the root level.

Five Services and How They Communicate

Each microservice in the project uses a different data store and a different communication pattern.

The Catalog microservice uses .NET 8 Minimal APIs with Vertical Slice Architecture. It stores data in PostgreSQL via the Marten library, which provides a transactional document DB layer on top of PostgreSQL. CQRS validation is handled with MediatR and FluentValidation, and HTTP endpoints are defined using the Carter library. Cross-cutting concerns including logging, global exception handling, and health checks are also implemented in the Catalog service.

The Basket microservice uses a standard ASP.NET 8 REST API with Redis as its distributed cache. It applies the Proxy, Decorator, and Cache-aside patterns. To calculate discounts, Basket calls the Discount microservice synchronously over gRPC, consuming the Protobuf messages the Discount service exposes.

The Discount microservice is an ASP.NET gRPC server with SQLite storage managed by Entity Framework Core. It provides high-performance inter-service gRPC communication to Basket.

The Ordering microservice subscribes to a BasketCheckout event from RabbitMQ using MassTransit. It uses SQL Server with Entity Framework Core and implements full DDD and Clean Architecture. MassTransit abstracts the RabbitMQ broker so the Ordering service does not depend directly on RabbitMQ client libraries.

The Yarp API Gateway reverse-proxies external requests to the correct backend service. It uses Yarp's route, cluster, path, transform, and destination configuration, and applies rate limiting with FixedWindowLimiter.

The WebUI ShoppingApp microservice is an ASP.NET Core web application with Bootstrap 4 and Razor templates. It calls the Yarp API Gateway using Refit HttpClientFactory. The ShoppingApp gives users access to the catalog and basket, and lets them trigger the checkout flow, which publishes a BasketCheckout event to RabbitMQ that the Ordering microservice then consumes.

Running the Project with Docker Compose

Running the project requires Visual Studio 2022, .NET Core 8 or later, and Docker Desktop configured with at least 4 GB of memory and 2 CPUs. After cloning the repository, start all containers from the root directory:

docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d

The override file sets environment variables for each service. After the containers are up, the Shopping Web UI is accessible at https://localhost:6065 and provides access to the catalog and basket flows. The RabbitMQ management dashboard is also available in the browser after startup, where you can observe queue activity when checking out the basket.

The README notes that some microservices need extra time to start, so if a service is not immediately reachable after running docker-compose, waiting before retrying is the recommended approach. No initialization scripts beyond the docker-compose command are documented.

Architecture Patterns: DDD, CQRS, and Clean Architecture

The repository uses three architecture patterns across the Ordering microservice that are not present in the other services. Domain-driven design organizes the Ordering domain around domain entities, aggregates, and domain events. Clean Architecture separates the domain, application, infrastructure, and presentation layers so that the domain has no dependencies on infrastructure concerns.

CQRS (Command Query Responsibility Segregation) separates read and write operations. Commands that change state and queries that return data are handled by different MediatR handlers. FluentValidation runs in a MediatR pipeline behavior, validating commands before they reach the handler.

The Catalog microservice uses Vertical Slice Architecture instead, organizing code by feature rather than by architectural layer. Each feature is a single .cs file that contains the request, response, handler, and endpoint definition. The README describes this as using feature folders with a single file per feature.

The Basket microservice uses none of these patterns explicitly; instead it applies three design patterns at the object level: Proxy, Decorator, and Cache-aside for its Redis caching layer.

Where This Project Falls Short as a Production Reference

The repository is a course companion demonstrating a set of technologies in combination, not a production-ready starter. The README covers none of the operational concerns that production microservices require: service discovery, distributed tracing, health checks beyond basic HTTP, centralized logging, secrets management, or horizontal scaling configurations.

The codebase does not include application-level tests. The README lists Visual Studio 2022 as a required tool, which limits the default development experience to Windows, although .NET 8 itself runs cross-platform.

The last push to the repository was on 2026-03-09. The project targets .NET 8 and C# 12, so teams considering adoption with newer .NET versions should check whether the dependencies listed in the project files are compatible.

All data stores are containerized for development use but the repository provides no guidance on production database configuration, backup, or migration strategy for any of the four databases (PostgreSQL, Redis, SQLite, SQL Server).

How This Compares to Microsoft's eShopOnContainers

Microsoft's eShopOnContainers is the official reference microservices implementation for .NET. It covers more services, addresses security (identity server, authentication), includes infrastructure as code, and documents cloud deployment patterns. eShopOnContainers is intended as a comprehensive reference architecture.

run-aspnetcore-microservices is simpler and more focused on demonstrating a specific set of patterns. Its value is pedagogical rather than architectural: it shows how each technology fits together without the complexity of a full production reference. The Medium article linked in the README, covering .NET 8 Microservices with DDD, CQRS, Vertical/Clean Architecture, and Event-Driven Communication, describes the intent as teaching the patterns through a concrete implementation.

For developers who have worked through eShopOnContainers and want a focused example of Marten on PostgreSQL, Carter for Minimal APIs, or Yarp with FixedWindowLimiter, this repository is a faster reference than searching through a larger codebase. For teams building production systems, eShopOnContainers provides more complete architectural coverage.

Editorial conclusion

run-aspnetcore-microservices is the right starting point for .NET developers who want to see DDD, CQRS, gRPC, RabbitMQ, Yarp, and Clean Architecture assembled in one runnable project before applying those patterns to their own work. It is a course companion, not a production template; the README does not discuss scaling, testing, security, or observability. The last push to the repository was on 2026-03-09, so dependency versions and the referenced .NET 8 tooling may need review before adoption. Before running the project, verify that Docker Desktop is configured with at least 4 GB of memory and 2 CPUs as the README specifies.

Frequently asked questions

Official sources

1. aspnetrun/run-aspnetcore-microservices on GitHub
2. Issues
3. License: MIT
4. Project website
5. README