Edit

Tutorial: Add .NET Aspire to an existing .NET 8 microservices app

  • Article

If you have already created a microservices .NET web app, you can use Visual Studio to add .NET Aspire to it and get all the features and benefits available to those who enabled .NET Aspire when they selected File > New > Project and chose Enlist in Aspire orchestration. In this article, you'll add .NET Aspire orchestration to a simple, pre-existing .NET 8 project. You'll learn how to:

  • Understand the structure of the existing microservices app.
  • Enroll existing projects in .NET Aspire orchestration.
  • Understand the changes enrollment makes in the projects.
  • Start the .NET Aspire app.

Prerequisites

To work with .NET Aspire, you need the following installed locally:

For more information, see .NET Aspire setup and tooling.

Get started

Let's start by obtaining the code for the solution:

  1. Open a command prompt and change to a directory where you want to store the code.

  2. To clone to .NET 8 example solution, use this command:

    git clone https://github.com/MicrosoftDocs/mslearn-dotnet-cloudnative-devops.git eShopLite

Explore the sample app

This article uses a .NET 8 solution with three projects:

  • Data Entities. This project is an example class library. It defines the Product class used in the Web App and Web API.
  • Products. This example Web API returns a list of products in the catalog and their properties.
  • Store. This example Blazor Web App displays the product catalog to website visitors.

Open and start debugging the project to examine its default behavior:

  1. Start Visual Studio and then select File > Open > Project/Solution.

  2. Navigate to the top level folder of the solution you cloned, select eShopLite.sln, and then select Open.

  3. In the Solution Explorer, right-click the eShopLite solution, and then select Configure Startup Projects.

  4. Select Multiple startup projects and then select the Create new launch profile button.

  5. In the Action column, select Start for both the Products and Store projects.

  6. Select OK.

  7. To start debugging the solution, press F5 or select Start.

  8. Two pages open in the browser:

    • A page displays products in JSON format from a call to the Products Web API.
    • A page displays the homepage of the website. In the menu on the left, select Products to see the catalog obtained from the Web API.

  9. To stop debugging, close the browser.

Add .NET Aspire to the Store web app

Now, let's enroll the Store project, which implements the web user interface, in .NET Aspire orchestration:

  1. In Visual Studio, in the Solution Explorer, right-click the Store project, select Add, and then select .NET Aspire Orchestrator Support.

  2. In the Add .NET Aspire Orchestrator Support dialog, select OK.

    Screenshot of the Add .NET Aspire Orchestrator Support dialog.

Visual Studio adds two new projects to the solution:

  • eShopLite.AppHost: An orchestrator project designed to connect and configure the different projects and services of your app. The orchestrator is set as the Startup project, and it depends on the eShopLite.Store project.
  • eShopLite.ServiceDefaults: A .NET Aspire shared project to manage configurations that are reused across the projects in your solution related to resilience, service discovery, and telemetry.

In the eShopLite.AppHost project, open the Program.cs file. Notice this line of code, which registers the Store project in the .NET Aspire orchestration:

builder.AddProject<Projects.Store>("store");

For more information, see AddProject.

To add the Products project to .NET Aspire:

  1. In Visual Studio, in the Solution Explorer, right-click the Products project, select Add, and then select .NET Aspire Orchestrator Support.
  2. In the Microsoft Visual Studio dialog, select OK.
  3. In the Add .NET Aspire Orchestrator Support dialog, select OK.

In the eShopLite.AppHost project, open the Program.cs file. Notice this line of code, which registers the Products project in the .NET Aspire orchestration:

builder.AddProject<Projects.Products>("products");

Also notice that the eShopLite.AppHost project, now depends on both the Store and Products projects.

Service Discovery

At this point, both projects are part of .NET Aspire orchestration, but the Store needs to be able to discover the Products backend address through .NET Aspire's service discovery. To enable service discovery, open the Program.cs file in eShopLite.AppHost and update the code that the Store adds a reference to the Products project:

var products = builder.AddProject<Projects.Products>("products");

builder.AddProject<Projects.Store>("store").WithReference(products);

Next, update the appsettings.json in the Store project to of the ProductEndpoint and ProductEndpointHttps:

"ProductEndpoint": "http://products",
"ProductEndpointHttps": "https://products",

The address uses the name of the Products project that was added to the orchestrator in the AppHost.

Explore the enrolled app

Let's start the solution and examine the new behavior that .NET Aspire has added.

Note

Notice that the eShopLite.AppHost project is the new startup project.

  1. In Visual Studio, to start debugging, press F5 Visual Studio builds the projects.
  2. If the Start Docker Desktop dialog appears, select Yes. Visual Studio starts the Docker engine and creates the necessary containers. When the deployment is complete, the .NET Aspire dashboard is displayed.
  3. In the dashboard, select the endpoint for the products project. A new browser tab appears and displays the product catalog in JSON format.
  4. In the dashboard, select the endpoint for the store project. A new browser tab appears and displays the home page for the web app.
  5. In the menu on the left, select Products. The product catalog is displayed.
  6. Close the browser to stop debugging.

Congratulations! You have added .NET Aspire orchestration to your pre-existing web app. You can now add .NET Aspire components and use the .NET Aspire tooling to streamline your cloud-native web app development.