Skip to content
Get packs

Guide · Open source

How to use eShop: run the .NET e-commerce reference app with Aspire

Updated · written with AI from the project's own documentation and checked against our catalogue data

eShop is an open-source reference application written in C# on .NET 10. It implements an e-commerce website as a set of cooperating services, and Aspire starts and manages those services on your machine. This guide shows you how to install the prerequisites, clone and run the solution, run the tests, and understand the optional Azure steps, so you can study how a multi-service store is put together.

eShopdotnet/eShop · ★ 11k · MIT

Quick start

  1. 1Install prerequisites. Install a .NET 10 SDK that matches global.json, the Aspire CLI, and Docker Desktop or Podman.
  2. 2Start the container runtime. Make sure Docker or Podman is running before you start eShop.
  3. 3Clone the repository. Run git clone https://github.com/dotnet/eShop.git and then cd into the eShop folder.
  4. 4Check the Aspire CLI. Run aspire --version to confirm the CLI is available.
  5. 5Start the app. Run aspire run from the repository root and open the dashboard URL the CLI prints.
  6. 6Stop the app. Press Ctrl+C to stop it, or use aspire stop if you started it in the background.

What you need before you start

Install a .NET 10 SDK that satisfies the repository's global.json file. Then install the Aspire CLI and check that it works.

You also need an OCI-compatible container runtime that is running. Docker Desktop is the recommended default, and Podman is also supported. Aspire has a prerequisites page for configuring Podman.

  • A .NET 10 SDK matching global.json
  • The Aspire CLI
  • Docker Desktop or Podman, started before you run eShop
  • Optional: Visual Studio with the ASP.NET and web development workload, or VS Code with C# Dev Kit and the Aspire extension
  • Optional: the .NET MAUI workload, if you want to run the client apps
aspire --version

Clone the repository and open the folder

Download the source with git, then move into the repository root. All of the following commands run from that folder.

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

Run eShop with aspire run

Make sure your container runtime is running, then start the solution from the repository root. The root aspire.config.json selects src/eShop.AppHost/eShop.AppHost.csproj, so the test AppHosts are not picked up by mistake.

When startup finishes, the CLI prints a dashboard URL that includes a login token. Open it in your browser to see the Aspire dashboard. Press Ctrl+C to stop the AppHost.

  • To run it in the background instead, use aspire start, then aspire ps to list running items.
  • When you are finished, run aspire stop.
  • In Visual Studio, open eShop.Web.slnf, set src/eShop.AppHost/eShop.AppHost.csproj as the startup project, and press Ctrl+F5.
aspire run

Run the tests

The server tests run with dotnet test against the solution filter. The browser journeys use Playwright, which starts the AppHost itself, so your container runtime must be running first.

  • Server tests: dotnet test --solution eShop.Web.slnf
  • Browser tests: install dependencies, install Chromium for Playwright, then run the e2e script
dotnet test --solution eShop.Web.slnf npm ci npx playwright install chromium npm run test:e2e

Optional: enable the AI chatbot with Microsoft Foundry

The AI chatbot is optional. It provisions a Microsoft Foundry resource during local development, so you must sign in to Azure and set your subscription and location first. Aspire then provisions the gpt-4.1-mini and text-embedding-3-small deployments and passes their connection information to the projects that use them.

The Foundry hosting integration uses a preview package at the time of the README.

  • Sign in with the Azure CLI, then store the subscription ID and location as Aspire secrets
  • Set UseFoundry to true, then run aspire run again
az login aspire secret set "Azure:SubscriptionId" "<subscription-id>" aspire secret set "Azure:Location" "eastus" $env:UseFoundry = "true" aspire run

Deploy to Azure Container Apps (evaluation only)

The AppHost is already set up with an Azure Container Apps environment, so the Aspire CLI can deploy from the application model. The README warns that this sample runs PostgreSQL, Redis and RabbitMQ as containers in Azure Container Apps, and that this setup is for evaluation and demos, not production data.

You need the prerequisites above, the Azure CLI, an active Azure subscription, and permission to create resources. aspire deploy --list-steps previews the pipeline. For non-interactive use, set the Azure settings as environment variables.

When you are done, aspire destroy deletes the entire configured resource group, including resources Aspire did not create, so check the target before you confirm.

  • Use aspire publish if you need deployment artifacts to inspect or pass to another tool. It is not required before aspire deploy.
  • Clean up with aspire destroy when the deployment is no longer needed.
az login aspire deploy --list-steps aspire deploy $env:Azure__SubscriptionId = "<subscription-id>" $env:Azure__Location = "eastus" $env:Azure__ResourceGroup = "rg-eshop-demo" aspire deploy --non-interactive

Know what the sample data is

The catalog products are defined in src/Catalog.API/Setup/catalog.json. The README says the product names, descriptions and brand names are fictional, generated with GPT-35-Turbo, and the product images were generated with DALL·E 3.

For a version of this app configured for Azure deployment, the README points to the separate eShopOnAzure repository.

What people use it for

  • Studying how a services-based .NET web app is structured and wired together
  • Learning how Aspire starts and manages multiple services and containers on a developer machine
  • Running the server and browser tests to see how the project is verified
  • Evaluating an Aspire deployment to Azure Container Apps for demos
  • Using the sample as teaching material for e-commerce application architecture

Frequently asked questions

Is eShop free to use?

eShop is released under the MIT licence, as listed in the repository. Check the LICENSE file in the repo for the full terms before reusing code.

What do I need to install to run eShop?

You need a .NET 10 SDK that satisfies global.json, the Aspire CLI, and a running OCI-compatible container runtime such as Docker Desktop or Podman. The README says no separate Aspire workload or Visual Studio component is required.

Why does aspire run fail or hang?

The README's main warning is to make sure your container runtime is running before you start eShop. Start Docker Desktop or Podman first, then run aspire run again.

Can I run eShop without Docker?

The README requires a container runtime, and it names Docker Desktop as the recommended default with Podman also supported. Without one of these running, eShop cannot start its containers.

Can I use eShop as a store for real customers?

No. The README says the Azure deployment is intended for evaluation and demonstrations, not production data. eShop is a reference application for learning and study.

Do I need to know C# to use eShop?

Running it mainly needs the .NET SDK and Aspire tools. Changing or studying the code requires familiarity with C# and .NET, so non-.NET developers will need to learn those first.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

eShop suits .NET developers, students and teachers who want a realistic, multi-service e-commerce example running under Aspire, and it is free under the MIT licence. It is a poor fit if you need a production store, if you cannot run Docker or Podman, or if you do not work with C# and .NET.

Install options & downloads