Skip to content

About

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

Topics

Resources

Contributing

Stars

643 stars

Watchers

18 watching

Forks

Latest commit

 

History

1,358 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Microsoft eShopOnWeb ASP.NET Core Reference Application

This Microsoft reference application is now being maintained by NimblePros.

If you're looking for the .NET Aspire eShop sample it's here. Microsoft also recommends the Reliable Web App patterns guidance for building web apps with enterprise app patterns.

Sample ASP.NET Core reference application, powered by Microsoft, demonstrating a single-process (monolithic) application architecture and deployment model. If you're new to .NET development, read the Getting Started for Beginners guide.

A list of Frequently Asked Questions about this repository can be found here.

Table of Contents

Overview Video

Steve "ardalis" Smith recorded a live stream providing an overview of the eShopOnWeb reference app in October 2020.

eBook

This reference application is meant to support the free .PDF download ebook: Architecting Modern Web Applications with ASP.NET Core and Azure, updated to ASP.NET Core 8.0. Also available in ePub/mobi formats.

You can also read the book in online pages at the .NET docs here: https://docs.microsoft.com/dotnet/architecture/modern-web-apps-azure/

The eShopOnWeb sample is related to the eShopOnContainers sample application which, in that case, focuses on a microservices/containers-based application architecture. However, eShopOnWeb is much simpler in regards to its current functionality and focuses on traditional Web Application Development with a single deployment.

The goal for this sample is to demonstrate some of the principles and patterns described in the eBook. It is not meant to be an eCommerce reference application, and as such it does not implement many features that would be obvious and/or essential to a real eCommerce application.

VERSIONS

The main branch is currently running ASP.NET Core 11.0.

Older versions are tagged.

Topics (eBook TOC)

  • Introduction
  • Characteristics of Modern Web Applications
  • Choosing Between Traditional Web Apps and SPAs
  • Architectural Principles
  • Common Web Application Architectures
  • Common Client Side Technologies
  • Developing ASP.NET Core MVC Apps
  • Working with Data in ASP.NET Core Apps
  • Testing ASP.NET Core MVC Apps
  • Development Process for Azure-Hosted ASP.NET Core Apps
  • Azure Hosting Recommendations for ASP.NET Core Web Apps

Running the sample using Azd template

The store's home page should look like this:

eShopOnWeb home page screenshot

The Azure Developer CLI (azd) is a developer-centric command-line interface (CLI) tool for creating Azure applications.

You need to install it before running and deploying with Azure Developer CLI.

Windows

powershell -ex AllSigned -c "Invoke-RestMethod 'https://aka.ms/install-azd.ps1' | Invoke-Expression"

Linux/MacOS

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

And you can also install with package managers, like winget, choco, and brew. For more details, you can follow the documentation: https://aka.ms/azure-dev/install.

After logging in with the following command, you will be able to use the azd cli to quickly provision and deploy the application.

azd auth login

Then, execute the azd init command to initialize the environment.

azd init -t NimblePros/eShopOnWeb

Run azd up to provision all the resources to Azure and deploy the code to those resources.

azd up

According to the prompt, enter an env name, and select subscription and location, these are the necessary parameters when you create resources. Wait a moment for the resource deployment to complete, click the web endpoint and you will see the home page.

Notes:

  1. Considering security, we store its related data (id, password) in the Azure Key Vault when we create the database, and obtain it from the Key Vault when we use it. This is different from directly deploying applications locally.
  2. The resource group name created in azure portal will be rg-{env name}.

You can also run the sample locally (see below).

Running the sample locally

The easiest way to run the sample on Windows, macOS, or Linux is with .NET Aspire. The eShopWeb.AppHost project starts everything the site needs:

  • a SQL Server container holding the Microsoft.eShopOnWeb.CatalogDb (catalog and shopping cart data) and Microsoft.eShopOnWeb.Identity (user credentials) databases
  • a Seq container for structured logs
  • the Web and PublicApi projects, with their database connection strings filled in

You need the .NET SDK listed in global.json and a container runtime such as Docker Desktop or Podman. Then, from the root folder:

dotnet run --project src/eShopWeb.AppHost

Or use the Aspire CLI with aspire run, or set eShopWeb.AppHost as the startup project in Visual Studio or Rider.

Open the Aspire dashboard link shown in the console to find the Web and PublicApi endpoints. The Web site is at https://localhost:5001/, and the admin area (Blazor WebAssembly, which calls PublicApi) is at https://localhost:5001/admin.

The first run downloads the SQL Server image, which can take a few minutes. When the apps start, they apply the Entity Framework Core migrations and seed both databases, so you should see products in the store and be able to log in with the [email protected] account. The SQL Server container and its data volume are kept between runs, so your data survives restarts. To start over with empty databases, remove the sqlserver container and its volume using your container tool.

Note: The demo accounts used to be seeded with @microsoft.com addresses. If your identity database was created before they moved to @eshop.test, it still contains the old accounts alongside the new ones, and the old [email protected] account is no longer protected from edits. Recreate the identity database to get a clean set of demo users.

The SQL Server sa password is generated on the first run and stored in the AppHost's user secrets as Parameters:sqlserver-password. The data volume keeps the password it was created with, so if you clear the AppHost's user secrets, also remove the sqlserver container and its volume (or the apps won't be able to log in to SQL Server).

Apple silicon: The SQL Server image is built for x64 only. On an Apple silicon Mac, enable Rosetta emulation for x86/amd64 images in your container runtime (for example, Docker Desktop's "Use Rosetta for x86_64/amd64 emulation on Apple Silicon" setting).

Running without Aspire

You can also run the Web and PublicApi projects directly with dotnet run, without containers, by using the EF Core in-memory database. Add the following to the appsettings.json file of each project you run, or pass --UseOnlyInMemoryDatabase=true on the command line:

{
    "UseOnlyInMemoryDatabase": true
}

The in-memory data is reseeded every time the app starts, and each app has its own copy, so changes made in the admin area (through PublicApi) don't show up in the store (Web). To use your own SQL Server instead, set the ConnectionStrings:CatalogConnection and ConnectionStrings:IdentityConnection settings, for example with user secrets.

Note that if you run the apps this way, you'll need to stop them manually in order to build the solution (otherwise you'll get file locking errors).

Working with EF Core migrations

The apps apply migrations on startup, so you don't need to run dotnet ef database update. If you change the model and need to create migrations, install the EF Core tools (dotnet tool update --global dotnet-ef) and run these commands from the Web folder (migrations add doesn't need a database; commands that connect to one, such as dotnet ef migrations list, need a --connection argument):

dotnet ef migrations add InitialModel --context catalogcontext -p ../Infrastructure/Infrastructure.csproj -s Web.csproj -o Data/Migrations

dotnet ef migrations add InitialIdentityModel --context appidentitydbcontext -p ../Infrastructure/Infrastructure.csproj -s Web.csproj -o Identity/Migrations

Dev Containers for the eShopOnWeb repo

We use dev containers to make it easier for you to run the eShopOnWeb application locally as well as our documentation.

eShopOnWeb App Dev Container

This project includes a .devcontainer folder with a dev container configuration, which lets you use a container as a full-featured dev environment.

You can use the dev container to build and run the app without needing to install any of its tools locally! You can work in GitHub Codespaces or the VS Code Dev Containers extension.

Learn more about using the dev container in eShopOnWeb's dev container readme.

eShopOnWeb Docs Dev Container

If you want to help maintain the documentation, we have a .devcontainer folder within the docs folder. This allows us to see our documentation changes in a container running Ruby and the GitHub Pages environment.

Learn More about Dev Containers

Running the sample using Docker

You can run the Web sample by running these commands from the root folder (where the .sln file is located):

docker-compose build
docker-compose up

You should be able to make requests to localhost:5106 for the Web project, and localhost:5200 for the Public API project once these commands complete. If you have any problems, especially with login, try from a new guest or incognito browser instance.

You can also run the applications by using the instructions located in their Dockerfile file in the root of each project. Again, run these commands from the root of the solution (where the .sln file is located).

Getting the GitHub Single Sign-On Working

We include GitHub as our external provider for single sign-on.

To get it running locally, you'll want to register an application in GitHub and store values in user secrets for the client ID and client secret.

We explain the code in detail in our course on ASP.NET Identity in Action: Implementing Individual Accounts.

Community Extensions

We have some great contributions from the community, and while these aren't maintained by Microsoft we still want to highlight them.

eShopOnWeb VB.NET by Mohammad Hamdy Ghanem

FShopOnWeb An F# take on eShopOnWeb by Sean G. Wright and Kyle McMaster

About

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

Topics

Resources

Contributing

Stars

643 stars

Watchers

18 watching

Forks

Releases

Packages

Used by

Contributors

Languages