dotnet/eShop: a .NET reference storefront you run with the Aspire CLI

What dotnet/eShop is for, and who should open it

This is a reference application, not a product. The README calls it "A reference .NET application implementing an e-commerce website using a services-based architecture", and that framing decides everything else about it. The audience is developers who already know ASP.NET Core and want to see how a multi-service .NET system is wired together, how the pieces are hosted, and how a single command brings the whole graph up on a workstation.

The subject is deliberately an online store because a storefront needs a catalog, a basket, an ordering path, an identity, and a web front end. Each of those becomes a separate service, and the composition is the lesson. If you are looking for a shopping cart to deploy, you are in the wrong repository. If you want to understand how .NET projects declare their dependencies on databases, caches and message brokers so that an orchestrator can start them, this is the sample Microsoft maintains for exactly that.

The README also notes that this version is based on .NET 10, with the .NET 8 line preserved on the release/8.0 branch. That branch split matters: code you read on main may not match tutorials written against the older release.

How the Aspire AppHost composes the services

The architecture is services-based, and Aspire is the mechanism that assembles it. The repository carries an aspire.config.json at the root, and the README explains its purpose plainly: it selects src/eShop.AppHost/eShop.AppHost.csproj, "avoiding ambiguity with the test AppHosts in the repository". That one file is why a bare command from the repository root knows what to start.

The AppHost project is the application model. Services are declared there along with the resources they need, and the Aspire CLI reads that model and runs it. The README states that no separate Aspire workload or Visual Studio component is required, because the AppHost SDK and the hosting integrations are referenced by the projects in the repository. That is a real convenience: the model travels with the source rather than depending on a machine-wide installation.

One consequence of the layout is easy to miss. The repository contains more than one AppHost, and the tests bring up their own. The root configuration file exists to disambiguate, which means that if you move or rename that file, the plain command stops being unambiguous. The README does not describe what the CLI does in that case.

The optional AI chatbot shows how far the model reaches. Setting UseFoundry to true makes Aspire provision Microsoft Foundry deployments of gpt-4.1-mini and text-embedding-3-small and inject their connection information into the consuming projects. The README flags that the Foundry hosting integration currently uses a preview package, so that particular path is not the stable part of the sample.

Installing dotnet/eShop and running it for the first time

Four prerequisites come before anything else. A .NET 10 SDK that satisfies global.json, the Aspire CLI, an OCI-compatible container runtime (Docker Desktop is the recommended default, Podman is also supported), and a clone of the repository. The README warns in a callout that the container runtime must be running before you start eShop, which is the failure most people hit first.

After installing the Aspire CLI, verify it is on the path:

aspire --version

You should see a version string. If the command is not found, the CLI install step did not complete and nothing later will work.

Clone the repository and change into it:

 git clone https://github.com/dotnet/eShop.git
 cd eShop

From the repository root, start the application:

aspire run

The README states that when startup completes, the CLI prints a dashboard URL shaped like https://localhost:<port>/login?t=<token>. Open that URL to reach the Aspire dashboard, where the running services and their resources are listed. Ctrl+C stops the AppHost.

If you would rather not hold the terminal, the README gives a background variant: aspire start, then aspire ps to list what is running, and aspire stop when you are finished. From Visual Studio the equivalent is opening eShop.Web.slnf, setting src/eShop.AppHost/eShop.AppHost.csproj as the startup project, and pressing Ctrl+F5.

The first real use is not to shop. It is to open the dashboard and watch the services and their dependencies come up, then trace one request through the model. That is what the sample is built to show.

Tests, browser journeys and the Node toolchain

Server tests run through the solution filter rather than a project path:

dotnet test --solution eShop.Web.slnf

The end-to-end journeys use Playwright, and the repository's package.json defines the scripts that drive it. Playwright starts the AppHost itself, so the README repeats the container runtime requirement for this path too. Setup is three commands:

npm ci
npx playwright install chromium
npm run test:e2e

The package.json shows two more scripts worth knowing: test:e2e:headed runs the same suite with a visible browser, and test:e2e:report opens the Playwright report. The devDependencies pin @playwright/test, @types/node and dotenv.

There is a mismatch in that file that nobody has cleaned up: package.json declares "license": "ISC" while the repository LICENSE is MIT. It is a small thing, and it is also the kind of detail that tells you how much attention the non-.NET corners of this repository receive.

Deploying to Azure Container Apps, and the warning attached to it

The AppHost is already configured with an Azure Container Apps environment, so the Aspire CLI can deploy straight from the application model. The README states that running aspire publish first is not required, because aspire deploy invokes the deployment pipeline and its dependencies directly rather than consuming an earlier publish output. Publish exists for when you want artifacts to inspect or to hand to another tool.

The deployment steps are short:

az login
aspire deploy --list-steps
aspire deploy

For non-interactive runs, the README shows environment variables with double underscores: Azure__SubscriptionId, Azure__Location and Azure__ResourceGroup. A preview of the pipeline is available through --list-steps before anything is created.

This is where the sample draws its sharpest boundary. A warning in the README says the deployment runs PostgreSQL, Redis and RabbitMQ as containers in Azure Container Apps and that this configuration "is intended for evaluation and demonstrations, not production data". That is not a hedge about tuning. It is a statement that the data layer as shipped is not something to point at real customers.

Cleanup deserves the same attention. The README notes that aspire destroy deletes the entire configured resource group, including resources Aspire did not create, and advises reviewing the target before confirming. If you deploy into a resource group that holds anything else, destroy will take it with the sample.

Where dotnet/eShop stops being the right tool

The production-data warning is the first limitation, and it is explicit. The second is subtler: a reference application optimizes for showing mechanisms, not for the operational concerns a real storefront accumulates. Rate limiting, payment provider integration, tax and shipping rules, returns, inventory reconciliation, and the migration story for a live catalog are outside what the README describes. The sample catalog data is generated, with product text from GPT-35-Turbo and images from DALL·E 3, which tells you the data path is illustrative rather than realistic in shape or volume.

The third limitation is version churn. This line is based on .NET 10 with an Aspire-based startup, while the previous release is .NET 8 on a separate branch. Guidance written against the older branch will not map cleanly onto the current one, and the Foundry integration is on a preview package. Anyone treating the repository as a stable base inherits that movement.

The README is also silent on rollback. There is no documented procedure for undoing a deploy short of aspire destroy, and no description of how to keep the previous revision serving during an update. If your release process depends on staged rollback, this sample does not model it.

eShopOnAzure and what the alternative does differently

The README points to a sibling project for a version of the app configured for deployment on Azure: the Azure-Samples/eShopOnAzure repository. The difference is in what each one optimizes for. This repository is organized around the Aspire application model, where services and their resources are declared in an AppHost and the CLI materializes that model locally and in the cloud, with the containerized PostgreSQL, Redis and RabbitMQ topology described above. The Azure-focused sibling is oriented toward running the storefront on Azure services rather than toward the composition model itself.

That distinction is not cosmetic. If your interest is learning how a .NET distributed application declares dependencies and gets orchestrated, the AppHost is the point and this repository is the right one. If your interest is what the storefront looks like when its backing services are managed Azure offerings rather than containers started for a demo, the sibling repository answers a different question. Neither is a drop-in replacement for the other, and the README does not claim they are.

Licence, maintenance and the cost of tracking main

The repository is MIT licensed, which is permissive and imposes few conditions on reuse. The package.json declares ISC for the Node tooling, which conflicts with the repository LICENSE. If the licence of the test tooling matters to your review, that discrepancy is worth resolving with your own counsel rather than assuming either value. Nothing here is legal advice.

Maintenance signals are straightforward. The repository is not archived, and the last push was on 2026-09-21. The most recent release listed is dotnet8, tagged 2024-10-25, which means the release tags lag well behind the branch. If you pin to a release you are pinning to the .NET 8 line; if you track main you are on .NET 10 with the Aspire startup and a preview Foundry package in the optional path.

Upgrade cost follows from that. The startup surface is the Aspire CLI, the root aspire.config.json and global.json, and all three move as the platform moves. A team using this as a learning reference pays almost nothing to stay current. A team that copied services into a product pays the cost of every one of those shifts, plus the cost of replacing the containerized data tier the README explicitly disclaims for production.

Editorial conclusion

Adopt dotnet/eShop if you are learning how a .NET distributed application is composed and orchestrated, or if you want a working model to read before designing your own service boundaries. Do not adopt it as a production storefront: the README states the Azure deployment runs PostgreSQL, Redis and RabbitMQ as containers and is intended for evaluation and demonstrations, not production data. Before you build on it, verify the .NET 10 SDK against global.json, confirm the container runtime is running, and read aspire.config.json to see which AppHost the CLI will start.

Frequently asked questions

Official sources

1. dotnet/eShop on GitHub
2. Issues
3. License: MIT
4. README
5. Releases