eShop Reference Application

repository·main·Indexed 27 days ago

A reference implementation of an e-commerce website built with .NET 9 and .NET Aspire, demonstrating a services-based architecture. The project includes guides for local setup using Visual Studio or the .NET CLI, Azure deployment via the Azure Developer CLI (azd), Azure OpenAI configuration, and Playwright E2E testing. It also details Ordering API commands for managing order lifecycles, including CreateOrderCommand, order status transitions, and shipping.

Tokens: 2.1K
Snippets: 4
Records: 13
Agent score: 95%

What's inside eShop

Deploy eShop to Azure using Azure Developer CLI (azd)
main
You can deploy the .NET Aspire project to Azure using the azd CLI.
1. Install/Update azd: Azure Developer CLI.
2. Login:
  azd auth login
3. Initialize: Run azd init from the root of the repository.
  Select Use code in the current directory.
  Confirm .NET (Aspire) detection.
  Select services to expose to the Internet (e.g., webapp).
  Provide an environment name.
4. Deploy:
  azd up
azd up will create Azure resources and deploy the sample. Once finished, it will provide the url for the webapp. You can re-run azd up after making changes to re-deploy.
```
azd auth login
azd init
azd up
```
https://github.com/dotnet/eshop/blob/main/README.md
Run the eShop solution locally
main
Ensure Docker is started before running the application.
Using Visual Studio (Windows)
1. Open the eShop.Web.slnf file.
2. Set eShop.AppHost.csproj as the startup project.
3. Press Ctrl-F5 to launch via .NET Aspire.
Using the Terminal
Run the AppHost project directly using the .NET CLI:
```
dotnet run --project src/eShop.AppHost/eShop.AppHost.csproj
```
After running, look for the Aspire dashboard login URL in the console output: Login to the dashboard at: http://localhost:XXXXX/login?t=uniquelogincodeforyou
Note: If you encounter HTTPS issues, you may need to install ASP.NET Core HTTPS development certificates: https://aka.ms/aspnet/https-trust-dev-cert
```
dotnet run --project src/eShop.AppHost/eShop.AppHost.csproj
```
https://github.com/dotnet/eshop/blob/main/README.md
Install and configure the eShop development environment
main
To run eShop locally, you must clone the repository and ensure Docker Desktop is installed and running. The setup process varies by operating system and preferred IDE.
Windows with Visual Studio
Install Visual Studio 2022 (version 17.10 or newer) with the following workloads:
- ASP.NET and web development
- .NET Aspire SDK (found in Individual components)
- (Optional) .NET Multi-platform App UI development for client apps.
Alternatively, you can automate the configuration using PowerShell as an Administrator:
```
install-Module -Name Microsoft.WinGet.Configuration -AllowPrerelease -AcceptLicense -Force
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
get-WinGetConfiguration -file .\ .\configurations\vside.dsc.yaml | Invoke-WinGetConfiguration -AcceptConfigurationAgreements
```
Note: A restart is required after running this script.
Mac, Linux, or Windows without Visual Studio
Install the latest .NET 9 SDK.
To automate environment configuration for VS Code via PowerShell (Administrator):
```
install-Module -Name Microsoft.WinGet.Configuration -AllowPrerelease -AcceptLicense  -Force
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
get-WinGetConfiguration -file .\ .\configurations\vscode.dsc.yaml | Invoke-WinGetConfiguration -AcceptConfigurationAgreements
```
Note: These commands may require sudo on non-Windows systems. A restart is required after running.
https://github.com/dotnet/eshop/blob/main/README.md
Configure Azure OpenAI in eShop
main
To use Azure OpenAI features, update the configuration in eShop.AppHost/appsettings.json and enable the feature in eShop.AppHost/Program.cs.
1. Add the OpenAi connection string to appsettings.json:
```
"ConnectionStrings": {
  "OpenAi": "Endpoint=xxx;Key=xxx;"
}
```
1. In eShop.AppHost/Program.cs, set the useOpenAI flag to true:
```
bool useOpenAI = true;
```
https://github.com/dotnet/eshop/blob/main/README.md
Configure Playwright E2E testing environment
main
The eShop project uses Playwright for end-to-end (E2E) testing. The configuration is located in playwright.config.ts and defines how tests are executed, which browsers are used, and how the application server is managed.
Key Configuration Details:
- Test Directory: Tests are located in ./e2e.
- Base URL: The default base URL for actions like page.goto('/') is http://localhost:5045.
- Authentication: The project uses a shared storage state for authenticated tests, located at playwright/.auth/user.json.
- CI Behavior: On Continuous Integration (CI), the configuration automatically enables forbidOnly, sets retries to 2, and limits workers to 1 to ensure stability.
Test Projects:
- setup: Runs setup scripts matching **/*.setup.ts.
- e2e tests logged in: Runs specific tests (AddItemTest.spec.ts, RemoveItemTest.spec.ts) that depend on the setup project and use the stored authentication state.
- e2e tests without logged in: Runs unauthenticated tests (e.g., BrowseItemTest.spec.ts).
https://github.com/dotnet/eshop/blob/main/playwright.config.ts
Configure the Playwright webServer for eShop
main
Playwright is configured to automatically manage the eShop application lifecycle via the webServer option. This ensures the application is running before tests start.
- Startup Command: dotnet run --project src/eShop.AppHost/eShop.AppHost.csproj
- Target URL: http://localhost:5045
- Server Reuse: On local development, the existing server is reused (reuseExistingServer: !process.env.CI) to speed up test cycles.
- Timeout: The startup timeout is 60 seconds locally, or 5 minutes on CI.
```
webServer: {
  command: 'dotnet run --project src/eShop.AppHost/eShop.AppHost.csproj',
  url: 'http://localhost:5045',
  reuseExistingServer: !process.env.CI,
  stderr: 'pipe',
  stdout: 'pipe',
  timeout: process.env.CI ? (5 * 60_000) : 60_000,
}
```
https://github.com/dotnet/eshop/blob/main/playwright.config.ts
Set order status to stock confirmed using SetStockConfirmedOrderStatusCommand
main
The SetStockConfirmedOrderStatusCommand is used to transition an order's status to 'Stock Confirmed'. It requires the unique OrderNumber of the order you wish to update. This command returns a bool indicating whether the operation was successful.
https://github.com/dotnet/eshop/blob/main/src/Ordering.API/Application/Commands/SetStockConfirmedOrderStatusCommand.cs
Create an order draft with CreateOrderDraftCommand
main
Use the CreateOrderDraftCommand to initiate the creation of a new order draft. This command requires a BuyerId and a collection of BasketItem objects. It returns an OrderDraftDTO representing the created draft.
https://github.com/dotnet/eshop/blob/main/src/Ordering.API/Application/Commands/CreateOrderDraftCommand.cs
Use SetStockRejectedOrderStatusCommand to reject order status
main
The SetStockRejectedOrderStatusCommand is used to update an order's status to 'Stock Rejected'. It requires the specific order number and a list of the stock item IDs that were rejected. This command returns a bool indicating whether the operation was successful.
https://github.com/dotnet/eshop/blob/main/src/Ordering.API/Application/Commands/SetStockRejectedOrderStatusCommand.cs

Create a new order using CreateOrderCommand

main

The CreateOrderCommand is used to initiate the creation of a new order within the Ordering API. It follows the CQRS pattern and is designed to be immutable. To create a command, you must provide user identity details, shipping address information, payment card details, and a list of order items derived from a basket.

Data Contract Fields:

Field	Type	Description
`UserId`	`string`	The unique identifier of the user
`UserName`	`string`	The name of the user
`City`	`string`	Shipping city
`Street`	`string`	Shipping street address
`State`	`string`	Shipping state/province
`Country`	`string`	Shipping country
`ZipCode`	`string`	Shipping postal/zip code
`CardNumber`	`string`	Payment card number
`CardHolderName`	`string`	Name of the cardholder
`CardExpiration`	`DateTime`	Expiration date of the card
`CardSecurityNumber`	`string`	Card security number (CVV)
`CardTypeId`	`int`	Identifier for the type of card
`OrderItems`	`IEnumerable<OrderItemDTO>`	The list of items included in the order

Ship an order using ShipOrderCommand
main
The ShipOrderCommand is used to initiate the shipping process for a specific order. It requires the unique OrderNumber of the order you wish to ship. The command returns a bool indicating whether the shipping operation was successful.
https://github.com/dotnet/eshop/blob/main/src/Ordering.API/Application/Commands/ShipOrderCommand.cs
Set order status to awaiting validation using SetAwaitingValidationOrderStatusCommand
main
Use the SetAwaitingValidationOrderStatusCommand to transition an order's status to the 'Awaiting Validation' state. This command requires the unique OrderNumber of the order you wish to update. It returns a bool indicating whether the operation was successful.
https://github.com/dotnet/eshop/blob/main/src/Ordering.API/Application/Commands/SetAwaitingValidationOrderStatusCommand.cs

eShop Reference Application

What's inside eShop

Using Visual Studio (Windows)

Using the Terminal

Windows with Visual Studio

Mac, Linux, or Windows without Visual Studio

Key Configuration Details:

Test Projects: