# eShopOnWeb is an architecture lesson dressed as a store

> eShopOnWeb is the Microsoft sample web application that supports the Architecting Modern Web Applications ebook, and it now runs on ASP.NET Core 10.0 under NimblePros. It exists to demonstrate a domain centric, single deployment architecture rather than to be a complete shop, which is both its strength and the reason several obvious features are missing.

**NimblePros/eShopOnWeb** — Sample ASP.NET Core 10.0 reference application, powered by Microsoft, demonstrating a domain-centric application architecture with monolithic deployment model.

- Repository: https://github.com/NimblePros/eShopOnWeb
- Stars: 640 · Forks: 311
- Language: C#
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/nimblepros-eshoponweb

## Not an eCommerce product, an architecture demonstration

The readme is blunt about the scope. It is a sample ASP.NET Core reference application demonstrating a single process, monolithic application architecture and deployment model, and the goal is to show some of the principles and patterns described in the accompanying ebook. It is explicitly not meant to be an eCommerce reference application, and as such it does not implement many of the features that would be obvious or essential in a real one.

That framing decides the audience. The reader is a developer who wants to see how Microsoft would structure a web application, not a merchant who wants a store. The topics the readme lists for the book give the shape of the lesson, covering the characteristics of modern web applications, choosing between traditional web applications and SPAs, architectural principles, common web application architectures, common client side technologies, developing ASP.NET Core MVC applications, working with data, testing MVC applications, the development process for Azure hosted applications and Azure hosting recommendations.

The relationship with the other Microsoft sample is stated too. eShopOnWeb is simpler than eShopOnContainers in terms of current functionality, and it focuses on traditional web application development with a single deployment, while the containers sample focuses on a microservices and containers based architecture.

The project is now maintained by NimblePros, and the readme also points to the .NET Aspire eShop sample for anyone looking for that version, plus Microsoft's Reliable Web App guidance.

## The ebook and the repository are one deliverable

The application exists to support a free PDF ebook, Architecting Modern Web Applications with ASP.NET Core and Azure, which is also available in ePub and mobi formats and can be read online in the .NET documentation. The book has been updated to ASP.NET Core 8.0.

That coupling is the point and also the main constraint on the code. A code sample that is meant to be read alongside a book has to stay small, has to make its structure obvious, and has to avoid the incidental complexity of a real product. The application is therefore a teaching artefact whose shape is chosen for legibility.

Version handling is explicit in the readme. The main branch is currently running ASP.NET Core 10.0, and older versions are tagged, so the sample is kept in step with the current release line of the framework rather than frozen at the version the book describes. That is a small but important detail for anyone copying the code, because a pattern shown in a book and a pattern in the main branch are not guaranteed to match.

The repository also has a separate documentation site with a getting started guide for newcomers to .NET development, and the readme links an FAQ wiki page for questions about the repository itself.

## Three commands take the sample to Azure

The Azure Developer CLI route is the fastest way to see the application with a real database. The tool, azd, is a developer-centric command line interface for creating Azure applications, and it has to be installed before you can use it. On Linux and MacOS the readme gives a one line installer:

```bash
curl -fsSL https://aka.ms/install-azd.sh | bash
```

Windows users have a PowerShell installer in the readme, and package managers such as winget, choco and brew are also supported.

After logging in, the environment is initialised from the template hosted in this repository:

```bash
azd auth login
```

```bash
azd init -t NimblePros/eShopOnWeb
```

and then the resources are provisioned and the code deployed with:

```bash
azd up
```

The readme explains what to expect. You are asked for an environment name and you choose a subscription and a location, the deployment runs, and clicking the web endpoint shows the home page. The resource group created in the Azure portal is named rg-{env name}, and the database credentials are stored in Azure Key Vault when the database is created and read back from the vault at use time, which the readme contrasts with running the application locally.

That single command sequence is the quickest demonstration of the architecture, since it gives you a deployed application and a real database without touching the code.

## Locally it takes two processes and a database

Running the sample on a laptop needs more care than the azd route, and the readme explains why. Most of the site's functionality works with only the web application running, but the Admin page depends on Blazor WebAssembly running in the browser, and that page has to talk to the server through the site's PublicApi application. So two processes are needed.

The instructions are to open a terminal in the PublicApi folder and run dotnet run there, and then in the Web folder run dotnet run --launch-profile https. The application is then browsable at https://localhost:5001/, and the Blazor admin area is at https://localhost:5001/admin.

Two practical warnings are in the text. You can configure Visual Studio to start multiple projects instead of running the two terminals by hand, but if you do it manually you have to stop the applications before building the solution or you will hit file locking errors. And after cloning or downloading the sample you have to set up the database, with the readme pointing at the Entity Framework Core step for a persistent database.

The admin page is the reason for the PublicApi split, and it is the one part of the sample that is not traditional MVC. That is a deliberate teaching choice about how a modern ASP.NET Core application can host a rich client, and it is worth looking at even if you ignore the store entirely.

## Docker Compose wires the MVC app, the public API and SQL Server

A compose file in the repository brings up the whole stack, with the two application services and the database:

```yaml
  eshoppublicapi:
    image: ${DOCKER_REGISTRY-}eshoppublicapi
    build:
      context: .
      dockerfile: src/PublicApi/Dockerfile
    depends_on:
      - "sqlserver"
  sqlserver:
    image: mcr.microsoft.com/mssql/server:2022-latest
    ports:
      - "1433:1433"
    environment:
      - SA_PASSWORD=@someThingComplicated1234
      - ACCEPT_EULA=Y
```

The database image is the 2022 latest tag of Microsoft's SQL Server container, published on port 1433 with a sample administrator password and the licence acceptance flag set. Both application services are built from their own Dockerfiles under src/ and are given as depending on the sqlserver service, so the database starts first.

The compose file also accepts a DOCKER_REGISTRY variable, which is the seam for pushing the images to a registry of your own before deploying them somewhere. The sample therefore has a path that runs entirely on your machine and a path that runs on Azure, and the difference between them is mostly configuration.

One thing to notice is that the credentials are committed in the compose file. That is fine for a sample on a developer laptop and is a reminder that this file is an example, not a deployment template you would copy into a real environment.

## Dev containers, Aspire configuration and an infra folder

The repository layout shows how much tooling has been added around the sample. There is a .devcontainer/ directory, and the readme documents two dev containers, one for the eShopOnWeb app and one for the eShopOnWeb docs, with a section on learning more about dev containers.

There is also a .aspire/ directory and an aspire.config.json file at the top level, plus an azure.yaml file and an infra/ directory. Those are the pieces the azd template uses: azure.yaml describes the application to the Azure Developer CLI and infra/ holds the infrastructure definitions that azd up provisions. The compose file and the Aspire configuration sit side by side, which reflects the two ways Microsoft now expects this sample to be started.

The rest of the tree follows a modern .NET layout. There is eShopOnWeb.slnx rather than a classic solution file, a Directory.Packages.props for central package version management, a global.json that pins the SDK, CodeCoverage.runsettings for the coverage tooling, a BuildTestFormat.cs file for the build format check, and src/ and tests/ directories split by concern.

For someone learning from the sample, the dev container path is the one that gets closest to the maintainers' own environment without needing local SQL Server and .NET tooling configured by hand.

## Maintained by a consultancy, with no tagged releases

The maintenance story has shifted. The readme says this Microsoft reference application is now being maintained by NimblePros, and the repository has no GitHub releases, so the ASP.NET Core version tags and the framework version on the main branch are the version markers to look at.

The last push was on 2026-10-13 and the repository is not archived, so the sample is being kept current with the framework. The licence is MIT, with the text in the LICENSE file at the top level, so the code can be used in commercial work with attribution and no copyleft obligation. Microsoft additionally points at the Reliable Web App patterns guidance for people building real applications, which is a hint about where this sample is meant to stop.

The limitation is the one the readme states most plainly. Many features that a real shop needs are simply absent, and the application is not intended to be one. The other limitation is that this is a sample that has to keep moving with the framework, so the code on the main branch and the code in the book can differ, and the branch is the one to trust for anything you intend to run.

## Conclusion

Adopt eShopOnWeb as a teaching and reference codebase when you want a small, readable ASP.NET Core application that shows a domain centric architecture with a single deployment model, and you are willing to fill in the commerce features yourself. Skip it if you need a working shop, since the readme states it is not meant to be an eCommerce reference application, or if you want a microservices layout, where the sibling eShopOnContainers sample is the relevant one. Before you build on it, read the FAQ wiki and the architecture ebook, run dotnet run in the PublicApi folder alongside the Web project, and check that the ASP.NET Core version on the main branch matches your own target.

## FAQ

### What is eShopOnWeb and who maintains it?

It is a Microsoft sample ASP.NET Core reference application demonstrating a domain centric, single deployment architecture, now maintained by NimblePros. The main branch currently runs ASP.NET Core 10.0 and older versions are tagged.

### Is eShopOnWeb a complete eCommerce application?

No. The readme states it is meant to demonstrate the principles and patterns described in the architecture ebook and is not meant to be an eCommerce reference application, so many features that would be essential in a real shop are not implemented.

### How do I run eShopOnWeb on Azure?

Install the Azure Developer CLI, run azd auth login, then azd init -t NimblePros/eShopOnWeb to initialise the environment, and azd up to provision the resources and deploy the code. You are asked for an environment name, a subscription and a location, and the resource group is named rg-{env name}.

### How do I run eShopOnWeb locally?

The Admin page uses Blazor WebAssembly and talks to the server through the PublicApi application, so you run dotnet run in the PublicApi folder and dotnet run --launch-profile https in the Web folder, then browse to https://localhost:5001/ with the admin area at /admin. You also need to set up the database, and you must stop the running applications before building the solution to avoid file locking errors.

### What does the Docker Compose setup for eShopOnWeb include?

The compose file builds the eshopwebmvc and eshoppublicapi services from their Dockerfiles under src/ and adds a sqlserver service using mcr.microsoft.com/mssql/server:2022-latest on port 1433. Both application services depend on the database service.

## Sources

- [Issues](https://github.com/NimblePros/eShopOnWeb/issues)
- [License: MIT](https://github.com/NimblePros/eShopOnWeb/blob/main/LICENSE)
- [NimblePros/eShopOnWeb on GitHub](https://github.com/NimblePros/eShopOnWeb)
- [README](https://github.com/NimblePros/eShopOnWeb/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nimblepros-eshoponweb