run-aspnetcore-microservices: a .NET 8 reference stack for e-commerce microservices
Microservices on .NET platforms used ASP.NET Web API, Docker, RabbitMQ, MassTransit, Grpc, Yarp API Gateway, PostgreSQL, Redis, SQLite, SqlServer, Marten, Entity Framework Core, CQRS, MediatR, DDD, Vertical and Clean Architecture implementation with using latest features of .NET 8 and C# 12
At a glance
- What is it?
- The repository is a teaching-grade e-commerce system split into Catalog, Basket, Discount and Ordering services, wired together with RabbitMQ, gRPC, Yarp and Docker Compose. It shows how the pieces fit, but it is not a production template you can drop in unchanged.
- Who is it for?
- Adopt it if you are learning how .NET 8 services, RabbitMQ and Yarp fit together, or if you need a working skeleton to copy patterns from. Do not adopt it as a production base: the README documents no authentication, no distributed tracing and no rollback path.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Activity is slowing. The repository last received commits 8 months ago.
- What is it written in?
- Mainly C#, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- aspnetrun/run-aspnetcore-microservices3,277 ★ · +11
| Repository | 2026-09-25 | 2026-11-15 |
|---|---|---|
| aspnetrun/run-aspnetcore-microservices | 3.3k | 3.3k |
11 Stars in the last 51 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What run-aspnetcore-microservices solves, and for whom
Most microservices examples on GitHub are either a single service with a README that talks about scale, or a diagram with no code behind it. This repository takes the opposite route: it implements a small e-commerce domain end to end, with four services that actually talk to each other over two different transports. The domain is deliberately boring (catalog items, a basket, a discount, an order) because the point is the wiring, not the business logic.
The README frames it as an "implementations on microservices with .net tools" project over a "real-world e-commerce microservices" scenario. The author also links a Udemy course and a Medium article, so the repository doubles as course material. That shapes everything about it: the code is organised to be read alongside an explanation, and the comments and folder names assume a learner, not a maintainer inheriting a system.
Who it is for: a .NET developer who has built a monolith and wants to see CQRS, DDD, gRPC and a message broker in one runnable solution. Who it is not for: a team looking for a service template to deploy next quarter. Nothing in the README describes authentication, authorisation, secrets management or a deployment pipeline, and those are the parts that decide whether a microservices system survives contact with users.
How the four services communicate: gRPC for reads, RabbitMQ for writes
The architecture splits communication by direction. Synchronous calls go over gRPC: the Basket service consumes the Discount gRPC service to calculate a product's final price, and the README describes this as "inter-service sync communication". Asynchronous calls go over RabbitMQ, with MassTransit as the abstraction layer and a topic exchange model.
The concrete flow the README describes is the checkout. The Basket service publishes a BasketCheckout event to a queue, and the Ordering service subscribes to it. A shared EventBus.Messages library holds the contract, and both services reference it. That detail matters more than it looks: the message shape lives in one place, so a change to the event breaks compilation in both producers and consumers rather than failing silently at runtime.
Each service also makes a different storage choice, which is the part of the repository worth studying closely. Catalog uses Marten as a transactional document database on PostgreSQL. Basket uses Redis as a distributed cache over basketdb and applies proxy, decorator and cache-aside patterns. Discount runs Entity Framework Core against SQLite. Ordering runs EF Core against SQL Server and auto-migrates on startup. Four services, four persistence decisions, no shared database. That is the actual lesson here, and it is more useful than the DDD vocabulary in the feature list.
Catalog and Ordering show two different architectures in one solution
The Catalog service uses Vertical Slice Architecture: feature folders, with a single .cs file holding the different classes for one feature. It exposes ASP.NET Core Minimal APIs, defines endpoints with Carter, and implements CQRS through MediatR with a validation pipeline built on FluentValidation. Cross-cutting concerns (logging, global exception handling, health checks) sit outside the slices.
The Ordering service goes the other way. It implements DDD, CQRS and Clean Architecture with MediatR, FluentValidation and Mapster, and the README lists it under "Best Practices". So the same repository contains a vertical-slice service and a layered service side by side. That is a deliberate teaching choice, and it is also the first thing a reader should question. If you copy the repository wholesale, you inherit two architectural conventions and no rule for which applies where. Pick one before you add a fifth service.
The Yarp gateway sits in front of everything, applying the gateway routing pattern with route, cluster, path, transform and destination configuration, plus rate limiting through FixedWindowLimiter. A separate WebUI project (ASP.NET Core with Bootstrap 4 and Razor) calls the gateway through Refit and HttpClientFactory rather than talking to services directly. That layering is correct, and it is the part most tutorials skip.
Running it: Docker Compose, 4 GB of memory, and port 6065
The README lists three prerequisites: Visual Studio 2022, .NET Core 8 or later, and Docker Desktop. It also gives a specific Docker Desktop setting before you start: under Settings > Advanced, allocate at least 4 GB of memory and 2 CPUs. That is not a suggestion. Four services plus PostgreSQL, Redis, SQLite, SQL Server and RabbitMQ will not start on a default Docker Desktop allocation.
Clone the repository, start Docker Desktop, then from the directory containing the compose files run:
docker-compose -f docker-compose.yml -f docker-compose.override.yml up -dThe override file is where environment variables get replaced, so the two-file form is the one to use. The README warns that some services need extra time and that a first run may appear to fail. Wait for the stack to settle before concluding anything is broken.
Once it is up, open the shopping UI:
https://localhost:6065That is the WebUI project, and it reaches the services through the Yarp gateway rather than directly. The first real use is a checkout. Add items to the basket, check out, then open the RabbitMQ dashboard and follow the queue record. Seeing the BasketCheckout message appear there is the fastest way to confirm the event-driven half of the system is actually working, because a broken subscriber looks identical to a working one from the browser.
Where this repository stops being useful
The README is silent on authentication and authorisation. There is no mention of a token issuer, an identity provider or a policy anywhere in the feature list, and the WebUI calls the gateway without describing how a user is identified. For a learning project that is a reasonable omission. For anything exposed to the internet it is disqualifying, and it is the gap you will spend the most time closing.
Rollback is the second gap. The README does not document rollback, and the Ordering service auto-migrates to SQL Server on startup. That combination means a schema change ships with the deploy and there is no described path back. In a teaching environment that is fine. In a system with real data it is the kind of default that turns a bad release into a bad week.
The storage choices also carry constraints the README does not discuss. SQLite in the Discount service is containerised and works for a demo, but it is a file-backed database with limited concurrent write behaviour. Redis in the Basket service is used as a cache, so basket contents depend on cache durability. Neither is wrong for the project's purpose. Both are decisions you would revisit before handling paying customers.
Finally, the rate limiting is a FixedWindowLimiter on the gateway. Fixed windows allow a burst at a window boundary. The README presents it as a feature without discussing that trade-off, and if you are copying the Yarp configuration for a public API, that is the line to look at first.
Alternatives, and what changes if you pick one
The most direct alternative is the official .NET microservices guidance from Microsoft, usually shipped as the eShop sample. The difference in approach is scope and intent. eShop is maintained as a reference application with a deployment story, a documented architecture book and a roadmap tied to .NET releases. This repository is tied to a course, and its README points readers to Udemy and Medium for the explanation. If you want a reference architecture you can argue about in a design review, eShop is the better fit. If you want a smaller codebase you can read in an afternoon while following along with a video, this one is easier to finish.
A second alternative is to skip the reference-application genre entirely and start from a single service with a message broker, adding services only when a boundary proves itself. That approach rejects the premise of this repository, which is that seeing four services at once teaches you something a monolith cannot. Both positions are defensible. What the repository does well is show the cost of the distributed version: four databases, two transports, a gateway and a compose file with an override, all before a single feature ships.
If your actual need is a working e-commerce backend rather than a lesson in architecture, neither this repository nor any sample is the right starting point. The domain code here exists to demonstrate patterns, and the README describes it that way.
Licence and maintenance: MIT, last push 2026-03-09
The repository is licensed under MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. That is permissive and it is the reason the code is easy to reuse in a course or an internal prototype. It is not legal advice; if you are embedding the code in a product, read the LICENSE file in the repository root and get your own review.
The MIT grant covers the code in this repository. It does not cover the course, the Medium article or any third-party service the compose file pulls in, and those carry their own terms.
On maintenance: the repository is not archived, and the last push was on 2026-03-09. That is roughly six months before the date of this writing, which puts it at the edge of current. The README targets .NET 8 and C# 12, and the repository has no published releases, so there is no published version history to check for upgrade notes. The practical upgrade cost is the usual one for a multi-service .NET solution: bump the target framework across every project, then re-verify the MassTransit and RabbitMQ configuration, the Marten document store against PostgreSQL, and the EF Core migrations for both SQLite and SQL Server. Those three are where a framework bump tends to surface.
Editorial conclusion
Adopt it if you are learning how .NET 8 services, RabbitMQ and Yarp fit together, or if you need a working skeleton to copy patterns from. Do not adopt it as a production base: the README documents no authentication, no distributed tracing and no rollback path. Before you reuse anything, run the Compose stack and check the RabbitMQ dashboard after a basket checkout to confirm the BasketCheckout event actually reaches the Ordering service.
Frequently asked questions
What are microservices in ASP.NET Core?
In this repository they are separate ASP.NET Core applications, each owning its own data store, that communicate over gRPC for synchronous calls and RabbitMQ for asynchronous events. Catalog, Basket, Discount and Ordering are the four services, and each is containerised and started through Docker Compose.
Is a microservice in run-aspnetcore-microservices just an API?
No. Each service exposes an API, but it also owns its persistence (Marten on PostgreSQL, Redis, SQLite, SQL Server), and the services exchange events through RabbitMQ with MassTransit. A plain API with a shared database would not match this structure.
How do I run run-aspnetcore-microservices locally?
Install Visual Studio 2022, .NET 8 or later, and Docker Desktop, then set Docker Desktop to at least 4 GB of memory and 2 CPUs. From the directory containing the compose files, run docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d, wait for all services to start, and open https://localhost:6065.
Which databases does run-aspnetcore-microservices use?
Four different ones. Catalog uses Marten as a document database on PostgreSQL, Basket uses Redis as a distributed cache, Discount uses Entity Framework Core with SQLite, and Ordering uses Entity Framework Core with SQL Server and auto-migrates on startup.
Does run-aspnetcore-microservices include authentication?
The README does not document authentication or authorisation anywhere in its feature list, and it does not describe how a user is identified when the WebUI calls the Yarp gateway. Treat identity as something you add yourself.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/aspnetrun-run-aspnetcore-microservices)Star history chart for your README
[](https://hysenlabs.com/projects/aspnetrun-run-aspnetcore-microservices)Was this useful?