From 445de72e8f512d91a7dc94c311cd90a694e45a89 Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Tue, 14 Oct 2025 17:25:01 +0100 Subject: [PATCH 1/6] Initial edits. --- docs/get-started/add-aspire-existing-app.md | 23 +++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/get-started/add-aspire-existing-app.md b/docs/get-started/add-aspire-existing-app.md index daf35c20d3..b5d219c61b 100644 --- a/docs/get-started/add-aspire-existing-app.md +++ b/docs/get-started/add-aspire-existing-app.md @@ -1,18 +1,22 @@ --- -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 --- -# Tutorial: Add Aspire to an existing .NET app +> AJMTODO: change and apply the zone-pivot-groups -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: +# Tutorial: Add Aspire to an existing app + +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: + +> AJMTODO: Check this list at the end. > [!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. @@ -146,6 +150,8 @@ Open and start debugging the project to examine its default behavior: --- +> AJMTODO: Had to select the "Run All" Launch target here. + 1. To start debugging the solution, press F5 or select **Start**. 1. Two pages open in the browser: @@ -157,6 +163,8 @@ Open and start debugging the project to examine its default behavior: :::zone-end :::zone pivot="dotnet-cli" +> AJMTODO: Want to get rid of dotnet commands and pivot. + 1. Open a terminal window and change directories into the newly cloned repository. 1. To start the _Products_ app, run the following command: @@ -178,10 +186,13 @@ Open and start debugging the project to examine its default behavior: :::zone-end -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! +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! ## Ensure Aspire templates are installed +> AJMTODO: get them to install the Aspire CLI instead. It automatically installs templates. + + If you've worked with Aspire on your current computer before, you likely have the necessary .NET project templates already installed. You can check by using the following command: ```dotnetcli From fb8a05c95c97b50b6aafebde5150e7c017d6e7a1 Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Wed, 15 Oct 2025 14:41:40 +0100 Subject: [PATCH 2/6] More edits. --- docs/get-started/add-aspire-existing-app.md | 188 +++++++++++--------- docs/zones/zone-pivot-groups.yml | 10 ++ 2 files changed, 115 insertions(+), 83 deletions(-) diff --git a/docs/get-started/add-aspire-existing-app.md b/docs/get-started/add-aspire-existing-app.md index b5d219c61b..f6d0fce486 100644 --- a/docs/get-started/add-aspire-existing-app.md +++ b/docs/get-started/add-aspire-existing-app.md @@ -3,7 +3,7 @@ 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 --- > AJMTODO: change and apply the zone-pivot-groups @@ -54,25 +54,31 @@ 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: +> AJMTODO: try this! - - 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. Open a terminal window and change directories into the newly cloned repository. +1. To start the _Products_ app, run the following command: -1. To stop debugging, close the browser. + ```dotnetcli + dotnet run --project ./Products/Products.csproj + ``` + +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: + + ```dotnetcli + dotnet run --project ./Store/Store.csproj + ``` + +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. + +1. To stop debugging, close the browser, and press Ctrl+C in both terminals. :::zone-end :::zone pivot="vscode" - 1. Start Visual Studio Code and open the folder that you cloned. From the terminal where you cloned the repo, run the following command: ```bash @@ -161,28 +167,23 @@ 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" - -> AJMTODO: Want to get rid of dotnet commands and pivot. - -1. Open a terminal window and change directories into the newly cloned repository. -1. To start the _Products_ app, run the following command: +:::zone pivot="visual-studio" - ```dotnetcli - dotnet run --project ./Products/Products.csproj - ``` +>AJMTODO: Try this -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: - - ```dotnetcli - dotnet run --project ./Store/Store.csproj - ``` +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. 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. + - 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. To stop debugging, close the browser, and press Ctrl+C in both terminals. +1. To stop debugging, close the browser. :::zone-end @@ -190,9 +191,6 @@ No matter which tool you use, starting multiple projects manually or configuring ## Ensure Aspire templates are installed -> AJMTODO: get them to install the Aspire CLI instead. It automatically installs templates. - - If you've worked with Aspire on your current computer before, you likely have the necessary .NET project templates already installed. You can check by using the following command: ```dotnetcli @@ -217,11 +215,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) @@ -229,43 +230,14 @@ 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: +:::zone pivot="aspire-cli" -```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. +> AJMTODO: Add this. :::zone-end -:::zone pivot="vscode,dotnet-cli" +:::zone pivot="vscode" + +> AJMTODO: Most of this is dotnet commands. Do it with aspire and add it to the previous pivot ("pivot="aspire-cli,vscode") ### Create an AppHost project @@ -408,6 +380,44 @@ The preceding code: - Adds the **Products** project to the orchestrator. - Builds and runs the orchestrator. +:::zone-end +:::zone pivot="visual-studio" + +> AJMRTODO: try this + +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"); +``` + +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 @@ -452,21 +462,15 @@ 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. - -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. +> AJMTODO: finish this :::zone-end :::zone pivot="vscode" +> AJMTODO: try this + 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**: @@ -476,9 +480,26 @@ Delete the _launch.json_ file that you created earlier, it no longer serves a pu > [!NOTE] > If Docker Desktop (or Podman) isn't running, you experience an error. Start the container runtime and try again. +:::zone-end +:::zone pivot="visual-studio" + +> AJMTODO: Try this + +> [!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. +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. + :::zone-end :::zone pivot="dotnet-cli" +> AJMTODO: Get rid of this + 1. Start the _AppHost_ project by running the following command: ```dotnetcli @@ -489,6 +510,7 @@ Delete the _launch.json_ file that you created earlier, it no longer serves a pu > If Docker Desktop (or Podman) isn't running, you experience an error. Start the container runtime and try again. :::zone-end +> AJMTODO: Isn't this next bit for all three pivots? :::zone pivot="vscode,dotnet-cli" 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 From e7089156d6d210e82aaf51c00593d1099b3aa42d Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Wed, 15 Oct 2025 16:46:16 +0100 Subject: [PATCH 3/6] Revised Visual Studio instructions. --- docs/get-started/add-aspire-existing-app.md | 24 ++++++--------------- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/docs/get-started/add-aspire-existing-app.md b/docs/get-started/add-aspire-existing-app.md index f6d0fce486..b2b369846c 100644 --- a/docs/get-started/add-aspire-existing-app.md +++ b/docs/get-started/add-aspire-existing-app.md @@ -56,8 +56,6 @@ Open and start debugging the project to examine its default behavior: :::zone pivot="aspire-cli" -> AJMTODO: try this! - 1. Open a terminal window and change directories into the newly cloned repository. 1. To start the _Products_ app, run the following command: @@ -65,7 +63,7 @@ Open and start debugging the project to examine its default behavior: dotnet run --project ./Products/Products.csproj ``` -1. A browser page opens, displaying the JSON for the products. +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 commands 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: @@ -73,7 +71,7 @@ Open and start debugging the project to examine its default behavior: dotnet run --project ./Store/Store.csproj ``` -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. +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 commands 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. @@ -86,11 +84,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) @@ -156,8 +154,7 @@ Open and start debugging the project to examine its default behavior: --- -> AJMTODO: Had to select the "Run All" Launch target here. - +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: @@ -169,8 +166,6 @@ Open and start debugging the project to examine its default behavior: :::zone-end :::zone pivot="visual-studio" ->AJMTODO: Try this - 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**. @@ -383,8 +378,6 @@ The preceding code: :::zone-end :::zone pivot="visual-studio" -> AJMRTODO: try this - 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**. @@ -393,7 +386,7 @@ The preceding code: 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). +- **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: @@ -483,8 +476,6 @@ Delete the _launch.json_ file that you created earlier, it no longer serves a pu :::zone-end :::zone pivot="visual-studio" -> AJMTODO: Try this - > [!NOTE] > Notice that the **eShopLite.AppHost** project is the new startup project. @@ -493,7 +484,7 @@ Delete the _launch.json_ file that you created earlier, it no longer serves a pu 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. +1. To stop debugging, close the browser and then, in Visual Studio select the **Stop** button or press SHIFT + F5. :::zone-end :::zone pivot="dotnet-cli" @@ -510,7 +501,6 @@ Delete the _launch.json_ file that you created earlier, it no longer serves a pu > If Docker Desktop (or Podman) isn't running, you experience an error. Start the container runtime and try again. :::zone-end -> AJMTODO: Isn't this next bit for all three pivots? :::zone pivot="vscode,dotnet-cli" From 527d0a3333f5a1df892d1416d2d2707e1404df34 Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Wed, 15 Oct 2025 17:32:09 +0100 Subject: [PATCH 4/6] Halfway through adding Aspire CLI instructions. --- docs/get-started/add-aspire-existing-app.md | 52 ++++++++++++++++++++- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/docs/get-started/add-aspire-existing-app.md b/docs/get-started/add-aspire-existing-app.md index b2b369846c..b7b118726d 100644 --- a/docs/get-started/add-aspire-existing-app.md +++ b/docs/get-started/add-aspire-existing-app.md @@ -63,7 +63,7 @@ Open and start debugging the project to examine its default behavior: dotnet run --project ./Products/Products.csproj ``` -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 commands output. The page display a 404 error. Append **/api/product** to the URL and press ENTER. The JSON is displayed. +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: @@ -71,7 +71,7 @@ Open and start debugging the project to examine its default behavior: 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 commands output. In the menu on the left, select **Products** to see the catalog obtained from the Web API. +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. @@ -184,6 +184,23 @@ Open and start debugging the project to examine its default behavior: 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! +:::zone pivot="aspire-cli,vscode" + +## 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. + +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 If you've worked with Aspire on your current computer before, you likely have the necessary .NET project templates already installed. You can check by using the following command: @@ -227,8 +244,39 @@ Now, let's enroll the **Store** project, which implements the web user interface :::zone pivot="aspire-cli" +### Create an AppHost project + +In order to orchestrate the existing projects, you need to create a new _AppHost_ project. + +1. To create a new [_AppHost_ project](../fundamentals/app-host-overview.md) from the available Aspire templates, use the following Aspire CLI command: + + ```Aspire + aspire new + ``` + +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. + +The Aspire CLI downloads the selected template and adds a new Aspire AppHost project to the folder. + + + > AJMTODO: Add this. +Steps: +1. add a new app host. Done. +1. Add the app host to the exitsing solution (unless aspire has already done it?) +1. Add the store project as a reference to the apphost project +1. Create a service defaults project +1. Add the service defaults project to the existing solution +1. Add the products project as a reference to the apphost project +1. Add the service default project as a reference to the store project +1. Add the service default project as a reference to the products project +1. Add the builder.AddServiceDefaults() call to both store and products. +1. Add the usual code to AppHost.cs + :::zone-end :::zone pivot="vscode" From 4339b1dc506d3e3061e6a4a2f3377ced18f70cbe Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Thu, 16 Oct 2025 12:03:23 +0100 Subject: [PATCH 5/6] Updates complete. --- docs/get-started/add-aspire-existing-app.md | 127 +++++++------------- 1 file changed, 46 insertions(+), 81 deletions(-) diff --git a/docs/get-started/add-aspire-existing-app.md b/docs/get-started/add-aspire-existing-app.md index b7b118726d..791e3ce20e 100644 --- a/docs/get-started/add-aspire-existing-app.md +++ b/docs/get-started/add-aspire-existing-app.md @@ -6,14 +6,10 @@ ms.topic: how-to zone_pivot_groups: dev-tools --- -> AJMTODO: change and apply the zone-pivot-groups - # Tutorial: Add Aspire to an existing app 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: -> AJMTODO: Check this list at the end. - > [!div class="checklist"] > > - Understand the structure of the existing distributed app. @@ -242,7 +238,7 @@ 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="aspire-cli" +:::zone pivot="aspire-cli,vscode" ### Create an AppHost project @@ -261,47 +257,18 @@ In order to orchestrate the existing projects, you need to create a new _AppHost The Aspire CLI downloads the selected template and adds a new Aspire AppHost project to the folder. - - -> AJMTODO: Add this. - -Steps: -1. add a new app host. Done. -1. Add the app host to the exitsing solution (unless aspire has already done it?) -1. Add the store project as a reference to the apphost project -1. Create a service defaults project -1. Add the service defaults project to the existing solution -1. Add the products project as a reference to the apphost project -1. Add the service default project as a reference to the store project -1. Add the service default project as a reference to the products project -1. Add the builder.AddServiceDefaults() call to both store and products. -1. Add the usual code to AppHost.cs - -:::zone-end -:::zone pivot="vscode" - -> AJMTODO: Most of this is dotnet commands. Do it with aspire and add it to the previous pivot ("pivot="aspire-cli,vscode") - -### Create an AppHost project - -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: - -```dotnetcli -dotnet new aspire-apphost -o eShopLite.AppHost -``` - 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 ``` --- @@ -311,55 +278,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 ``` --- @@ -369,13 +343,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 ``` --- @@ -385,13 +359,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 ``` --- @@ -409,10 +383,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(); ``` @@ -463,7 +437,7 @@ Also notice that the **eShopLite.AppHost** project, now depends on both the **St ## 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); @@ -505,18 +479,23 @@ Let's start the solution and examine the new behavior that Aspire provides. :::zone pivot="aspire-cli" -> AJMTODO: finish this +In a command prompt, change to the root of the eShopLite solution and then run this command: + +```Aspire +aspire run +``` + +Hold down CTRL and then select the **Dashboard** URL. :::zone-end :::zone pivot="vscode" -> AJMTODO: try this - 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. @@ -534,20 +513,6 @@ Delete the _launch.json_ file that you created earlier, it no longer serves a pu 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="dotnet-cli" - -> AJMTODO: Get rid of this - -1. Start the _AppHost_ project by running the following command: - - ```dotnetcli - dotnet run --project ./eShopLite.AppHost/eShopLite.AppHost.csproj - ``` - - > [!NOTE] - > If Docker Desktop (or Podman) isn't running, you experience an error. Start the container runtime and try again. - :::zone-end :::zone pivot="vscode,dotnet-cli" From 3463f8c288bcd2be51d11b34d84fd68ed9e3e74c Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Thu, 16 Oct 2025 13:58:23 +0100 Subject: [PATCH 6/6] Minor markdown corrections. --- docs/get-started/add-aspire-existing-app.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/get-started/add-aspire-existing-app.md b/docs/get-started/add-aspire-existing-app.md index 791e3ce20e..83ca11c17b 100644 --- a/docs/get-started/add-aspire-existing-app.md +++ b/docs/get-started/add-aspire-existing-app.md @@ -59,7 +59,7 @@ Open and start debugging the project to examine its default behavior: dotnet run --project ./Products/Products.csproj ``` -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. 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: @@ -67,12 +67,13 @@ Open and start debugging the project to examine its default behavior: 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. 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" + 1. Start Visual Studio Code and open the folder that you cloned. From the terminal where you cloned the repo, run the following command: ```bash @@ -242,7 +243,7 @@ Now, let's enroll the **Store** project, which implements the web user interface ### Create an AppHost project -In order to orchestrate the existing projects, you need to create a new _AppHost_ project. +In order to orchestrate the existing projects, you need to create a new _AppHost_ project. 1. To create a new [_AppHost_ project](../fundamentals/app-host-overview.md) from the available Aspire templates, use the following Aspire CLI command: @@ -514,7 +515,7 @@ Delete the _launch.json_ file that you created earlier, it no longer serves a pu 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"