diff --git a/docs/get-started/add-aspire-existing-app.md b/docs/get-started/add-aspire-existing-app.md index daf35c20d3..83ca11c17b 100644 --- a/docs/get-started/add-aspire-existing-app.md +++ b/docs/get-started/add-aspire-existing-app.md @@ -1,18 +1,18 @@ --- -title: Add Aspire to an existing .NET app -description: Learn how to add Aspire integrations, orchestration, and tooling to a microservices app that already exists. +title: Add Aspire to an existing app +description: Learn how to add Aspire integrations, orchestration, and tooling to a distributed app that already exists. ms.date: 10/01/2025 ms.topic: how-to -zone_pivot_groups: dev-environment +zone_pivot_groups: dev-tools --- -# Tutorial: Add Aspire to an existing .NET app +# Tutorial: Add Aspire to an existing app -If you have existing microservices and .NET web app, you can add Aspire to it and get all the included features and benefits. In this article, you add Aspire orchestration to a simple, preexisting .NET 9 project. You learn how to: +If you have existing distributed web app, you can add Aspire to it and get all the included features and benefits. In this article, you add Aspire orchestration to a simple, preexisting .NET 9 project. You learn how to: > [!div class="checklist"] > -> - Understand the structure of the existing microservices app. +> - Understand the structure of the existing distributed app. > - Enroll existing projects in Aspire orchestration. > - Understand the changes enrollment makes in the projects. > - Start the Aspire project. @@ -50,21 +50,26 @@ This layered design ensures a clear separation of concerns, making the app easie Open and start debugging the project to examine its default behavior: -:::zone pivot="visual-studio" +:::zone pivot="aspire-cli" -1. Start Visual Studio and then select **File** > **Open** > **Project/Solution**. -1. Navigate to the top level folder of the solution you cloned, select **eShopLite.sln**, and then select **Open**. -1. In the **Solution Explorer**, right-click the **eShopLite** solution, and then select **Configure Startup Projects**. -1. Select **Multiple startup projects**. -1. In the **Action** column, select **Start** for both the **Products** and **Store** projects. -1. Select **OK**. -1. To start debugging the solution, press F5 or select **Start**. -1. Two pages open in the browser: +1. Open a terminal window and change directories into the newly cloned repository. +1. To start the _Products_ app, run the following command: - - 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. + ```dotnetcli + dotnet run --project ./Products/Products.csproj + ``` -1. To stop debugging, close the browser. +1. A browser page opens, displaying the JSON for the products. If the browser doesn't open, hold down CTRL and click the **Now listening on:** link in the command's output. The page display a 404 error. Append **/api/product** to the URL and press ENTER. The JSON is displayed. +1. In a separate terminal window, again change directories to cloned repository. +1. Start the _Store_ app by running the following command: + + ```dotnetcli + dotnet run --project ./Store/Store.csproj + ``` + +1. The browser opens a page that displays the homepage of the website. If the browser doesn't open, hold down CTRL and click the **Now listening on:** link in the command's output. In the menu on the left, select **Products** to see the catalog obtained from the Web API. + +1. To stop debugging, close the browser, and press Ctrl+C in both terminals. :::zone-end :::zone pivot="vscode" @@ -76,11 +81,11 @@ Open and start debugging the project to examine its default behavior: ``` 1. Select the **Run and Debug** menu item, or press Ctrl+Shift+D. -1. Select the **create a launch.json file** link. +1. Select the **create a launch.json file** link. If you're asked to select a debugger, select **Aspire**. :::image type="content" source="media/vscode-launch.json.png" lightbox="media/vscode-launch.json.png" alt-text="Visual Studio Code: Run and Debug create launch.json file."::: -1. Copy and paste the following JSON into this file and **Save**: +1. Copy and paste the following JSON into this file, replacing it's original content, and **Save**: ## [Unix](#tab/unix) @@ -146,6 +151,7 @@ Open and start debugging the project to examine its default behavior: --- +1. At the top of the **RUN AND DEBUG** pane, in the drop-down list, select **Run all**. 1. To start debugging the solution, press F5 or select **Start**. 1. Two pages open in the browser: @@ -155,30 +161,42 @@ Open and start debugging the project to examine its default behavior: 1. To stop debugging, close the browser, and then select the **Stop** button twice (once for each running debug instance). :::zone-end -:::zone pivot="dotnet-cli" +:::zone pivot="visual-studio" -1. Open a terminal window and change directories into the newly cloned repository. -1. To start the _Products_ app, run the following command: +1. Start Visual Studio and then select **File** > **Open** > **Project/Solution**. +1. Navigate to the top level folder of the solution you cloned, select **eShopLite.sln**, and then select **Open**. +1. In the **Solution Explorer**, right-click the **eShopLite** solution, and then select **Configure Startup Projects**. +1. Select **Multiple startup projects**. +1. In the **Action** column, select **Start** for both the **Products** and **Store** projects. +1. Select **OK**. +1. To start debugging the solution, press F5 or select **Start**. +1. Two pages open in the browser: - ```dotnetcli - dotnet run --project ./Products/Products.csproj - ``` + - 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. -1. A browser page opens, displaying the JSON for the products. -1. In a separate terminal window, again change directories to cloned repository. -1. Start the _Store_ app by running the following command: +1. To stop debugging, close the browser. - ```dotnetcli - dotnet run --project ./Store/Store.csproj - ``` +:::zone-end -1. The browser opens a page that displays the homepage of the website. In the menu on the left, select **Products** to see the catalog obtained from the Web API. +No matter which tool you use, starting multiple projects manually or configuring connections between them is tedious. Additionally, the **Store** project requires explicit endpoint configuration for the **Products** API, which is both cumbersome and prone to errors. This is where Aspire simplifies and streamlines the process! -1. To stop debugging, close the browser, and press Ctrl+C in both terminals. +:::zone pivot="aspire-cli,vscode" -:::zone-end +## Install the Aspire CLI + +The Aspire CLI tool can be used to enroll your app in Aspire orchestration, both when you're using the command prompt exclusively and when you're using Visual Studio Code. -No matter which tool you use—starting multiple projects manually or configuring connections between them is tedious. Additionally, the **Store** project requires explicit endpoint configuration for the **Products** API, which is both cumbersome and prone to errors. This is where Aspire simplifies and streamlines the process! +In a terminal window, install the Aspire CLI tool: + +```dotnetcli +dotnet tool install -g Aspire.Cli --prerelease +``` + +> [!NOTE] +> For more information about installing the Aspire CLI, see [Install Aspire CLI](../cli/install.md) + +:::zone-end ## Ensure Aspire templates are installed @@ -206,11 +224,14 @@ Aspire Tes... aspire-xunit [C#] Common/Aspire/Cloud/Web/Web API In this tutorial, you'll add a AppHost project and a Service Defaults project. -If the previous command didn't find any templates you must install them. Execute this command: +If the previous command didn't find any templates: -```dotnetcli -dotnet new install Aspire.ProjectTemplates -``` +- If you're using the Aspire CLI, you don't need to take any additional actions. The Aspire CLI automatically installs the templates when it creates an Aspire project. +- If you're using Visual Studio Code or Visual Studio, you can install the latest templates with this command: + + ```dotnetcli + dotnet new install Aspire.ProjectTemplates + ``` For more information about the Aspire templates, see [Aspire templates](../fundamentals/setup-tooling.md#aspire-templates) @@ -218,64 +239,37 @@ For more information about the Aspire templates, see [Aspire templates](../funda Now, let's enroll the **Store** project, which implements the web user interface, in Aspire orchestration: -:::zone pivot="visual-studio" - -1. In Visual Studio, in the **Solution Explorer**, right-click the **Store** project, select **Add**, and then select **Aspire Orchestrator Support**. -1. In the **Add Aspire Orchestrator Support** dialog, select **OK**. - - :::image type="content" loc-scope="visual-studio" source="media/add-aspire-orchestrator-support.png" alt-text="Screenshot of the Add Aspire Orchestrator Support dialog."::: - -You should now have two new projects, both added 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 Aspire shared project to manage configurations that are reused across the projects in your solution related to [resilience](/dotnet/core/resilience/http-resilience), [service discovery](../service-discovery/overview.md), and [telemetry](../fundamentals/telemetry.md). - -In the **eShopLite.AppHost** project, open the _:::no-loc text="AppHost.cs":::_ file. Notice this line of code, which registers the **Store** project in the Aspire orchestration: - -```csharp -builder.AddProject("store"); -``` +:::zone pivot="aspire-cli,vscode" -For more information, see . - -To add the **Products** project to Aspire: - -1. In Visual Studio, in the **Solution Explorer**, right-click the **Products** project, select **Add**, and then select **Aspire Orchestrator Support**. -1. A dialog indicating that Aspire Orchestrator project already exists, select **OK**. - - :::image type="content" loc-scope="visual-studio" source="media/orchestrator-already-added.png" alt-text="Screenshot indicating that theAspire Orchestrator was already added."::: - -In the **eShopLite.AppHost** project, open the _:::no-loc text="AppHost.cs":::_ file. Notice this line of code, which registers the **Products** project in the Aspire orchestration: - -```csharp -builder.AddProject("products"); -``` +### Create an AppHost project -Also notice that the **eShopLite.AppHost** project, now depends on both the **Store** and **Products** projects. +In order to orchestrate the existing projects, you need to create a new _AppHost_ project. -:::zone-end -:::zone pivot="vscode,dotnet-cli" +1. To create a new [_AppHost_ project](../fundamentals/app-host-overview.md) from the available Aspire templates, use the following Aspire CLI command: -### Create an AppHost project + ```Aspire + aspire new + ``` -In order to orchestrate the existing projects, you need to create a new _AppHost_ project. To create a new [_AppHost_ project](../fundamentals/app-host-overview.md) from the available Aspire templates, use the following .NET CLI command: +1. In the list of templates, select **AppHost** and then press Enter. +1. For the project name, type **AppHost** and then press Enter. +1. To accept **./AppHost** as the output path, press Enter. +1. To select the default template version, press Enter. -```dotnetcli -dotnet new aspire-apphost -o eShopLite.AppHost -``` +The Aspire CLI downloads the selected template and adds a new Aspire AppHost project to the folder. Add the _AppHost_ project to existing solution: ## [Unix](#tab/unix) ```dotnetcli -dotnet sln ./eShopLite.sln add ./eShopLite.AppHost/eShopLite.AppHost.csproj +dotnet sln ./eShopLite.sln add ./AppHost/AppHost.csproj ``` ## [Windows](#tab/windows) ```dotnetcli -dotnet sln .\eShopLite.sln add .\eShopLite.AppHost\eShopLite.AppHost.csproj +dotnet sln .\eShopLite.sln add .\AppHost\AppHost.csproj ``` --- @@ -285,55 +279,62 @@ Add the **Store** project as a project reference to the _AppHost_ project using ## [Unix](#tab/unix) ```dotnetcli -dotnet add ./eShopLite.AppHost/eShopLite.AppHost.csproj reference ./Store/Store.csproj +dotnet add ./AppHost/AppHost.csproj reference ./Store/Store.csproj ``` ## [Windows](#tab/windows) ```dotnetcli -dotnet add .\eShopLite.AppHost\eShopLite.AppHost.csproj reference .\Store\Store.csproj +dotnet add .\AppHost\AppHost.csproj reference .\Store\Store.csproj ``` --- -For more information on the available templates, see [Aspire templates](../fundamentals/aspire-sdk-templates.md). - -### Create a service defaults project - -After the AppHost project is created, you need to create a new _service defaults_ project. To create a new [_service defaults_ project](../fundamentals/service-defaults.md) from the available Aspire templates, use the following .NET CLI command: - -```dotnetcli -dotnet new aspire-servicedefaults -o eShopLite.ServiceDefaults -``` - -To add the project to the solution, use the following .NET CLI command: +Update the _AppHost_ project to add a project reference to the **Products** project: ## [Unix](#tab/unix) ```dotnetcli -dotnet sln ./eShopLite.sln add ./eShopLite.ServiceDefaults/eShopLite.ServiceDefaults.csproj +dotnet add ./AppHost/AppHost.csproj reference ./Products/Products.csproj ``` ## [Windows](#tab/windows) ```dotnetcli -dotnet sln .\eShopLite.sln add .\eShopLite.ServiceDefaults\eShopLite.ServiceDefaults.csproj +dotnet add .\AppHost\AppHost.csproj reference .\Products\Products.csproj ``` --- -Update the _AppHost_ project to add a project reference to the **Products** project: +### Create a service defaults project + +After the AppHost project is created, you need to create a new _service defaults_ project. + +1. To create a new [_service defaults_ project](../fundamentals/service-defaults.md) from the available Aspire templates, use the following Aspire CLI command: + + ```Aspire + aspire new + ``` + +1. In the list of templates, select **Service defaults** and then press Enter. +1. For the project name, type **ServiceDefaults** and then press Enter. +1. To accept **./ServiceDefaults** as the output path, press Enter. +1. To select the default template version, press Enter. + +The Aspire CLI downloads the selected template and adds a new Aspire service defaults project to the folder. + +To add the project to the solution, use the following .NET CLI command: ## [Unix](#tab/unix) ```dotnetcli -dotnet add ./eShopLite.AppHost/eShopLite.AppHost.csproj reference ./Products/Products.csproj +dotnet sln ./eShopLite.sln add ./ServiceDefaults/ServiceDefaults.csproj ``` ## [Windows](#tab/windows) ```dotnetcli -dotnet add .\eShopLite.AppHost\eShopLite.AppHost.csproj reference .\Products\Products.csproj +dotnet sln .\eShopLite.sln add .\ServiceDefaults\ServiceDefaults.csproj ``` --- @@ -343,13 +344,13 @@ Both the **Store** and **Products** projects need to reference the _service defa ## [Unix](#tab/unix) ```dotnetcli -dotnet add ./Store/Store.csproj reference ./eShopLite.ServiceDefaults/eShopLite.ServiceDefaults.csproj +dotnet add ./Store/Store.csproj reference ./ServiceDefaults/ServiceDefaults.csproj ``` ## [Windows](#tab/windows) ```dotnetcli -dotnet add .\Store\Store.csproj reference .\eShopLite.ServiceDefaults\eShopLite.ServiceDefaults.csproj +dotnet add .\Store\Store.csproj reference .\ServiceDefaults\ServiceDefaults.csproj ``` --- @@ -359,13 +360,13 @@ The same command with slightly different paths should be used to add a reference ## [Unix](#tab/unix) ```dotnetcli -dotnet add ./Products/Products.csproj reference ./eShopLite.ServiceDefaults/eShopLite.ServiceDefaults.csproj +dotnet add ./Products/Products.csproj reference ./ServiceDefaults/ServiceDefaults.csproj ``` ## [Windows](#tab/windows) ```dotnetcli -dotnet add .\Products\Products.csproj reference .\eShopLite.ServiceDefaults\eShopLite.ServiceDefaults.csproj +dotnet add .\Products\Products.csproj reference .\ServiceDefaults\ServiceDefaults.csproj ``` --- @@ -383,10 +384,10 @@ Open the _:::no-loc text="AppHost.cs":::_ file of the _AppHost_ project, and rep ```csharp var builder = DistributedApplication.CreateBuilder(args); -builder.AddProject("store"); - builder.AddProject("products"); +builder.AddProject("store"); + builder.Build().Run(); ``` @@ -397,11 +398,47 @@ The preceding code: - Adds the **Products** project to the orchestrator. - Builds and runs the orchestrator. +:::zone-end +:::zone pivot="visual-studio" + +1. In Visual Studio, in the **Solution Explorer**, right-click the **Store** project, select **Add**, and then select **Aspire Orchestrator Support**. +1. In the **Add Aspire Orchestrator Support** dialog, select **OK**. + + :::image type="content" loc-scope="visual-studio" source="media/add-aspire-orchestrator-support.png" alt-text="Screenshot of the Add Aspire Orchestrator Support dialog."::: + +You should now have two new projects, both added 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**: An Aspire shared project to manage configurations that are reused across the projects in your solution related to [resilience](/dotnet/core/resilience/http-resilience), [service discovery](../service-discovery/overview.md), and [telemetry](../fundamentals/telemetry.md). + +In the **eShopLite.AppHost** project, open the _:::no-loc text="AppHost.cs":::_ file. Notice this line of code, which registers the **Store** project in the Aspire orchestration: + +```csharp +builder.AddProject("store"); +``` + +For more information, see . + +To add the **Products** project to Aspire: + +1. In Visual Studio, in the **Solution Explorer**, right-click the **Products** project, select **Add**, and then select **Aspire Orchestrator Support**. +1. A dialog indicating that Aspire Orchestrator project already exists, select **OK**. + + :::image type="content" loc-scope="visual-studio" source="media/orchestrator-already-added.png" alt-text="Screenshot indicating that theAspire Orchestrator was already added."::: + +In the **eShopLite.AppHost** project, open the _:::no-loc text="AppHost.cs":::_ file. Notice this line of code, which registers the **Products** project in the Aspire orchestration: + +```csharp +builder.AddProject("products"); +``` + +Also notice that the **eShopLite.AppHost** project, now depends on both the **Store** and **Products** projects. + :::zone-end ## Service Discovery -At this point, both projects are part of Aspire orchestration, but the **Store** project needs to rely on the **Products** backend address through [Aspire's service discovery](../service-discovery/overview.md). To enable service discovery, open the _:::no-loc text="AppHost.cs":::_ file in **eShopLite.AppHost** project and update the code so that the `builder` adds a reference to the _Products_ project: +At this point, both projects are part of Aspire orchestration, but the **Store** project needs to rely on the **Products** backend address through [Aspire's service discovery](../service-discovery/overview.md). To enable service discovery, open the _:::no-loc text="AppHost.cs":::_ file in **AppHost** project and update the code so that the `builder` adds a reference to the _Products_ project: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -441,44 +478,44 @@ The addresses for both the endpoints now uses the "products" name that was added Let's start the solution and examine the new behavior that Aspire provides. -:::zone pivot="visual-studio" +:::zone pivot="aspire-cli" -> [!NOTE] -> Notice that the **eShopLite.AppHost** project is the new startup project. +In a command prompt, change to the root of the eShopLite solution and then run this command: -1. In Visual Studio, to start debugging, press F5 Visual Studio builds the projects. -1. 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 Aspire dashboard is displayed. -1. In the dashboard, select the endpoint for the **products** project. A new browser tab appears and displays the product catalog in JSON format. -1. In the dashboard, select the endpoint for the **store** project. A new browser tab appears and displays the home page for the web app. -1. In the menu on the left, select **Products**. The product catalog is displayed. -1. To stop debugging, close the browser. +```Aspire +aspire run +``` + +Hold down CTRL and then select the **Dashboard** URL. :::zone-end :::zone pivot="vscode" Delete the _launch.json_ file that you created earlier, it no longer serves a purpose. Instead, start the _AppHost_ project, which orchestrates the other projects: -1. Start the _AppHost_ project by right-clicking the **eShopLite.AppHost** project in the **Solution Explorer** and selecting **Debug** > **Start New Instance**: - - :::image type="content" source="media/vscode-run-app-host.png" lightbox="media/vscode-run-app-host.png" alt-text="Visual Studio Code: Solution Explorer selecting Debug > Start New Instance." ::: +1. In Visual Studio Code, open the _:::no-loc text="AppHost.cs":::_ file in the _AppHost_ project. +1. To open the **RUN AND DEBUG** window, press CTRL + SHIFT + D. +1. Press F5 or select **Start Debugging**. If you are asked to select a debugger, select **C#**. +1. In you are asked to select a launch configuration, select **C#:AppHost [Default Configuration]**. > [!NOTE] > If Docker Desktop (or Podman) isn't running, you experience an error. Start the container runtime and try again. :::zone-end -:::zone pivot="dotnet-cli" - -1. Start the _AppHost_ project by running the following command: +:::zone pivot="visual-studio" - ```dotnetcli - dotnet run --project ./eShopLite.AppHost/eShopLite.AppHost.csproj - ``` +> [!NOTE] +> Notice that the **eShopLite.AppHost** project is the new startup project. - > [!NOTE] - > If Docker Desktop (or Podman) isn't running, you experience an error. Start the container runtime and try again. +1. In Visual Studio, to start debugging, press F5 Visual Studio builds the projects. +1. 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 Aspire dashboard is displayed. +1. In the dashboard, select the endpoint for the **products** project. A new browser tab appears and displays the product catalog in JSON format. +1. In the dashboard, select the endpoint for the **store** project. A new browser tab appears and displays the home page for the web app. +1. In the menu on the left, select **Products**. The product catalog is displayed. +1. To stop debugging, close the browser and then, in Visual Studio select the **Stop** button or press SHIFT + F5. :::zone-end -:::zone pivot="vscode,dotnet-cli" +:::zone pivot="aspire-cli,vscode" diff --git a/docs/zones/zone-pivot-groups.yml b/docs/zones/zone-pivot-groups.yml index 9bb6c5950c..436fd8c024 100644 --- a/docs/zones/zone-pivot-groups.yml +++ b/docs/zones/zone-pivot-groups.yml @@ -43,6 +43,16 @@ groups: title: Visual Studio - id: dotnet-cli title: .NET CLI +- id: dev-tools + title: Development tools + prompt: Choose your preferred development tools + pivots: + - id: aspire-cli + title: Aspire CLI + - id: vscode + title: Visual Studio Code + - id: visual-studio + title: Visual Studio - id: resp-host title: Hosting resource type prompt: Choose a hosting resource that supports the Redis protocol