dotnet · IEvangelist · May 14, 2024 · May 13, 2024 · May 13, 2024 · May 13, 2024
diff --git a/docfx.json b/docfx.json
@@ -20,7 +20,7 @@
         "dest": ".",
         "exclude": [
           "**/obj/**",
-          "**/includes/**",
+          "**/includes/**.md",
           "_themes/**",
           "_themes.pdf/**",
           "**/docfx.json",
@@ -46,7 +46,7 @@
       ],
         "exclude": [
           "**/obj/**",
-          "**/includes/**",
+          "**/includes/**.md",
           "_themes/**",
           "_themes.pdf/**",
           "**/docfx.json",

diff --git a/docs/deployment/azure/aca-deployment-github-actions.md b/docs/deployment/azure/aca-deployment-github-actions.md
@@ -54,7 +54,9 @@ curl -fsSL https://aka.ms/install-azd.sh | bash
 
 ---
 
-[!INCLUDE [file-new-aspire](../../includes/file-new-aspire.md)]
+## Create a .NET Aspire app
+
+As a starting point, this article assumes that you've created a .NET Aspire app from the **.NET Aspire Starter Application** template. For more information, see [Quickstart: Build your first .NET Aspire app](../../get-started/build-your-first-aspire-app.md).
 
 [!INCLUDE [init workflow](includes/init-workflow.md)]
 

diff --git a/docs/deployment/azure/aca-deployment-visual-studio.md b/docs/deployment/azure/aca-deployment-visual-studio.md
@@ -18,7 +18,9 @@ ms.date: 05/03/2024
 
 [!INCLUDE [aspire-prereqs](../../includes/aspire-prereqs.md)]
 
-[!INCLUDE [file-new-aspire](../../includes/file-new-aspire.md)]
+## Create a .NET Aspire app
+
+As a starting point, this article assumes that you've created a .NET Aspire app from the **.NET Aspire Starter Application** template. For more information, see [Quickstart: Build your first .NET Aspire app](../../get-started/build-your-first-aspire-app.md).
 
 ### Deploy the app
 

diff --git a/docs/deployment/azure/aca-deployment.md b/docs/deployment/azure/aca-deployment.md
@@ -25,7 +25,9 @@ As an alternative to this tutorial and for a more in-depth guide, see [Deploy a
 
 With .NET Aspire and Azure Container Apps (ACA), you have a great hosting scenario for building out your cloud-native apps with .NET. We built some great new features into the Azure Developer CLI (`azd`) specific for making .NET Aspire development and deployment to Azure a friction-free experience. You can still use the Azure CLI and/or Bicep options when you need a granular level of control over your deployments. But for new projects, you won't find an easier path to success for getting a new microservice topology deployed into the cloud.
 
-[!INCLUDE [file-new-aspire](../../includes/file-new-aspire.md)]
+## Create a .NET Aspire app
+
+As a starting point, this article assumes that you've created a .NET Aspire app from the **.NET Aspire Starter Application** template. For more information, see [Quickstart: Build your first .NET Aspire app](../../get-started/build-your-first-aspire-app.md).
 
 ## Install the Azure Developer CLI
 

diff --git a/docs/fundamentals/media/setup-tooling/vscode-create-project.png b/docs/fundamentals/media/setup-tooling/vscode-create-project.png
diff --git a/docs/fundamentals/media/setup-tooling/vscode-debugging.png b/docs/fundamentals/media/setup-tooling/vscode-debugging.png
diff --git a/docs/fundamentals/setup-tooling.md b/docs/fundamentals/setup-tooling.md
@@ -1,17 +1,18 @@
 ---
 title: .NET Aspire tooling
 description: Learn about essential tooling concepts for .NET Aspire.
-ms.date: 04/25/2024
+ms.date: 05/13/2024
+zone_pivot_groups: dev-environment
 ---
 
 # .NET Aspire setup and tooling
 
-.NET Aspire includes tooling to help you create and configure cloud-native apps. The tooling includes useful starter project templates and other features to streamline getting started with .NET Aspire for both Visual Studio and CLI workflows. In the sections ahead, you'll learn how to work with .NET Aspire tooling and explore the following tasks:
+.NET Aspire includes tooling to help you create and configure cloud-native apps. The tooling includes useful starter project templates and other features to streamline getting started with .NET Aspire for Visual Studio, Visual Studio Code, and CLI workflows. In the sections ahead, you'll learn how to work with .NET Aspire tooling and explore the following tasks:
 
 > [!div class="checklist"]
 >
 > - Install .NET Aspire and its dependencies
-> - Create starter project templates using Visual Studio or the .NET CLI
+> - Create starter project templates using Visual Studio, Visual Studio Code, or the .NET CLI
 > - Install .NET Aspire components
 > - Work with the .NET Aspire dashboard
 
@@ -25,12 +26,13 @@ To work with .NET Aspire, you'll need the following installed locally:
 - Integrated Developer Environment (IDE) or code editor, such as:
   - [Visual Studio 2022 Preview](https://visualstudio.microsoft.com/vs/preview/) version 17.10 or higher (Optional).
   - [Visual Studio Code](https://code.visualstudio.com/) (Optional).
+    - [C# Dev Kit: Extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) (Optional).
 
 The .NET Aspire workload installs internal dependencies and makes available other tooling, such as project templates and Visual Studio features. There are two ways to install the .NET Aspire workload. If you prefer to use Visual Studio Code, follow the .NET CLI instructions:
 
-# [Visual Studio](#tab/visual-studio)
+:::zone pivot="visual-studio"
 
-Visual Studio 2022 17.10 Preview 1 or higher includes the **.NET Aspire preview 4** workload by default. To verify that you have the .NET Aspire workload installed, run the following command:
+Visual Studio 2022 17.10 Preview 1 or higher includes the latest **.NET Aspire** workload by default. To verify that you have the .NET Aspire workload installed, run the following command:
 
 ```dotnetcli
 dotnet workload list
@@ -66,7 +68,8 @@ To install the .NET Aspire workload in Visual Studio 2022 Preview, use the Visua
     dotnet workload list
     ```
 
-# [.NET CLI](#tab/dotnet-cli)
+:::zone-end
+:::zone pivot="vscode,dotnet-cli"
 
 To ensure that you install the latest version of the .NET Aspire workload, run the following [dotnet workload update](/dotnet/core/tools/dotnet-workload-update) command before you install .NET Aspire:
 
@@ -86,36 +89,32 @@ To check your version of .NET Aspire, run this command:
 dotnet workload list
 ```
 
----
+:::zone-end
 
 ## Container runtime
 
 .NET Aspire apps are designed to run in containers. You can use either Docker Desktop or Podman as your container runtime. [Docker Desktop](https://www.docker.com/products/docker-desktop/) is the most common container runtime. [Podman](https://podman.io/docs/installation) is an open-source daemonless alternative to Docker, that can build and run Open Container Initiative (OCI) containers. If your host environment has both Docker and Podman installed, .NET Aspire defaults to using Docker. You can instruct .NET Aspire to use Podman instead, by setting the `DOTNET_ASPIRE_CONTAINER_RUNTIME` environment variable to `podman`:
 
-## [Unix](#tab/unix)
+## [Linux](#tab/linux)
 
 ```bash
 export DOTNET_ASPIRE_CONTAINER_RUNTIME=podman
 ```
 
+For more information, see [Install Podman on Linux](https://podman.io/docs/installation#installing-on-linux).
+
 ## [Windows](#tab/windows)
 
 ```powershell
 $env:DOTNET_ASPIRE_CONTAINER_RUNTIME = "podman"
 ```
 
----
+For more information, see [Install Podman on Windows](https://podman.io/docs/installation#installing-on-mac--windows).
 
-For more information, see:
-
-- [Install Podman on Windows or macOS](https://podman.io/docs/installation#installing-on-mac--windows).
-- [Install Podman on Linux](https://podman.io/docs/installation#installing-on-linux).
+---
 
 ## .NET Aspire project templates
 
-> [!NOTE]
-> The .NET 9.0 SDK causes issues with the .NET Aspire workloads ability to display templates, and create projects from the templates. If you're using .NET 9.0, know that your ability to create new .NET Aspire apps is currently limited. For more information, see [.NET Aspire preview-3 cannot create app when .NET 9 is installed](https://github.com/dotnet/aspire/issues/1951) and [.NET Aspire preview-3 installed with Visual Studio 17.10 doesn't show templates](https://github.com/dotnet/aspire/issues/2186).
-
 The .NET Aspire workload makes available .NET Aspire project templates. These project templates allow you to create new apps pre-configured with the .NET Aspire project structure and default settings. These projects also provide a unified debugging experience across the different resources of your app.
 
 There are currently four project templates available:
@@ -141,15 +140,19 @@ There are currently four project templates available:
   > [!IMPORTANT]
   > The service defaults project template takes a `FrameworkReference` dependency on `Microsoft.AspNetCore.App`. This may not be ideal for some project types. For more information, see [.NET Aspire service defaults](service-defaults.md).
 
-Use Visual Studio or the .NET CLI to create new apps using these project templates. Explore additional .NET Aspire project templates in the [.NET Aspire samples](https://github.com/dotnet/aspire-samples) repository.
+Use Visual Studio, Visual Studio Code, or the .NET CLI to create new apps using these project templates. Explore additional .NET Aspire project templates in the [.NET Aspire samples](https://github.com/dotnet/aspire-samples) repository.
+
+> [!NOTE]
+> The .NET 9.0 SDK causes issues with the .NET Aspire workloads ability to display templates, and create projects from the templates. If you're using .NET 9.0, know that your ability to create new .NET Aspire apps is currently limited. For more information, see [.NET Aspire preview-3 cannot create app when .NET 9 is installed](https://github.com/dotnet/aspire/issues/1951) and [.NET Aspire preview-3 installed with Visual Studio 17.10 doesn't show templates](https://github.com/dotnet/aspire/issues/2186).
 
-# [Visual Studio](#tab/visual-studio)
+:::zone pivot="visual-studio"
 
 To create a .NET Aspire project using Visual Studio, search for *Aspire* in the Visual Studio new project window and select your desired template.
 
 :::image type="content" source="../media/aspire-templates.png" lightbox="../media/aspire-templates.png" alt-text="The .NET Aspire project templates in Visual Studio.":::
 
-# [.NET CLI](#tab/dotnet-cli)
+:::zone-end
+:::zone pivot="vscode,dotnet-cli"
 
 To see which .NET Aspire project templates are available, use the [dotnet new list](/dotnet/core/tools/dotnet-new-list) command, passing in the search term `aspire`:
 
@@ -185,7 +188,7 @@ To create a .NET Aspire project with a sample UI and API included:
 dotnet new aspire-starter
 ```
 
----
+:::zone-end
 
 ## .NET Aspire dashboard
 
@@ -199,9 +202,11 @@ The left navigation provides links to the different parts of the dashboard, each
 
 :::image type="content" source="media/setup-tooling/projects.png" lightbox="media/setup-tooling/projects.png" alt-text="A screenshot of the .NET Aspire dashboard Projects page.":::
 
+:::zone pivot="visual-studio"
+
 ## Visual Studio tooling
 
-Visual Studio provides additional features for working with .NET Aspire components and the App Host orchestrator project. These features are currently not available in Visual Studio Code or through the CLI.
+Visual Studio provides additional features for working with .NET Aspire components and the App Host orchestrator project. Not all of these features are currently available in Visual Studio Code or through the CLI.
 
 ### Add a component package
 
@@ -262,3 +267,18 @@ When you're using Visual Studio, and you select the **.NET Aspire Start Applicat
 :::image type="content" source="media/setup-tooling/create-test-projects-template.png" lightbox="media/setup-tooling/create-test-projects-template.png" alt-text="A screenshot of Visual Studio displaying the option to create a test project.":::
 
 For more information, see [Testing .NET Aspire apps](testing.md).
+
+:::zone-end
+:::zone pivot="vscode"
+
+## Visual Studio Code tooling
+
+You can use Visual Studio Code, in conjunction with the [C# Dev Kit extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit), to create and develop .NET Aspire apps. To create a new .NET Aspire app in Visual Studio Code, select the **Create .NET Project** button in the **Explorer** view, then select one of the .NET Aspire templates:
+
+:::image type="content" source="media/setup-tooling/vscode-create-project.png" lightbox="media/setup-tooling/vscode-create-project.png" alt-text="A screenshot showing how to create a new .NET Aspire project in Visual Studio Code.":::
+
+Once you've created a new .NET Aspire project, you run and debug the app, stepping through breakpoints, and inspecting variables using the Visual Studio Code debugger:
+
+:::image type="content" source="media/setup-tooling/vscode-debugging.png" lightbox="media/setup-tooling/vscode-debugging.png" alt-text="A screenshot showing how to debug a .NET Aspire project in Visual Studio Code.":::
+
+:::zone-end
diff --git a/docs/get-started/build-your-first-aspire-app.md b/docs/get-started/build-your-first-aspire-app.md
@@ -3,6 +3,7 @@ title: Build your first .NET Aspire app
 description: Learn how to build your first .NET Aspire app using the .NET Aspire Started Application template.
 ms.date: 05/13/2024
 ms.topic: quickstart
+zone_pivot_groups: dev-environment
 ---
 
 # Quickstart: Build your first .NET Aspire app
@@ -20,7 +21,25 @@ In this quickstart, you'll explore the following tasks:
 
 [!INCLUDE [aspire-prereqs](../includes/aspire-prereqs.md)]
 
-[!INCLUDE [file-new-aspire](../includes/file-new-aspire.md)]
+## Create the .NET Aspire template
+
+To create a new .NET Aspire Starter Application, you can use either Visual Studio, Visual Studio Code, or the .NET CLI.
+
+:::zone pivot="visual-studio"
+
+[!INCLUDE [visual-studio-file-new](../includes/visual-studio-file-new.md)]
+
+:::zone-end
+:::zone pivot="vscode"
+
+[!INCLUDE [vscode-file-new](../includes/vscode-file-new.md)]
+
+:::zone-end
+:::zone pivot="dotnet-cli"
+
+[!INCLUDE [dotnet-cli-file-new](../includes/dotnet-cli-file-new.md)]
+
+:::zone-end
 
 ## Test the app locally
 
@@ -29,19 +48,27 @@ The sample app is now ready for testing. You want to verify the following:
 - Weather data is retrieved from the API project using service discovery and displayed on the weather page.
 - Subsequent requests are handled via the output caching configured by the .NET Aspire Redis component.
 
-### [Visual Studio](#tab/visual-studio)
+:::zone pivot="visual-studio"
 
 In Visual Studio, set the **AspireSample.AppHost** project as the startup project by right-clicking on the project in the **Solution Explorer** and selecting **Set as Startup Project**. Then, press <kbd>F5</kbd> to run the app.
 
-### [.NET CLI](#tab/dotnet-cli)
+:::zone-end
+:::zone pivot="vscode"
+
+In Visual Studio Code, press <kbd>F5</kbd> to run the app. You'll be prompted to select which language, and C# will be suggested, select C# and then select the **AspireSample.AppHost** project with the **Default Configuration**:
+
+:::image type="content" source="media/vscode-run.png" lightbox="media/vscode-run.png" alt-text="A screenshot of the Visual Studio Code run configuration for the AspireSample.AppHost project.":::
+
+:::zone-end
+:::zone pivot="dotnet-cli"
 
 ```dotnetcli
 dotnet run --project AspireSample/AspireSample.AppHost
 ```
 
 For more information, see [dotnet run](/dotnet/core/tools/dotnet-run).
 
----
+:::zone-end
 
 1. The app displays the .NET Aspire dashboard in the browser. We'll look at the dashboard in more detail later. For now, find the **webfrontend** project in the list of resources and select the project's **localhost** endpoint.
 
@@ -54,7 +81,27 @@ For more information, see [dotnet run](/dotnet/core/tools/dotnet-run).
 
 :::image type="content" source="media/weather-page.png" lightbox="media/weather-page.png" alt-text="The Weather page of the webfrontend app showing the weather data retrieved from the API.":::
 
-🤓 Congratulations! You created and ran your first .NET Aspire application! Now let's investigate the structure and other features of your new .NET Aspire app.
+🤓 Congratulations! You created and ran your first .NET Aspire application! To stop the app, you can close the browser window.
+
+:::zone pivot="visual-studio"
+
+In Visual Studio, select the **Stop Debugging** from the **Debug** menu to stop the app.
+
+:::zone-end
+:::zone pivot="vscode"
+
+In Visual Studio Code, press <kbd>Shift</kbd> + <kbd>F5</kbd> to stop the app, or select the **Stop** button at the top center of the window:
+
+:::image type="content" source="media/vscode-stop.png" lightbox="media/vscode-stop.png" alt-text="A screenshot of the Visual Studio Code stop button.":::
+
+:::zone-end
+:::zone pivot="dotnet-cli"
+
+Press <kbd>Ctrl</kbd> + <kbd>C</kbd> in the terminal window to stop the app.
+
+:::zone-end
+
+Now let's investigate the structure and other features of your new .NET Aspire app.
 
 ## Explore the .NET Aspire dashboard
 

diff --git a/docs/get-started/media/vscode-run.png b/docs/get-started/media/vscode-run.png
diff --git a/docs/get-started/media/vscode-stop.png b/docs/get-started/media/vscode-stop.png
diff --git a/docs/includes/aspire-prereqs.md b/docs/includes/aspire-prereqs.md
@@ -12,5 +12,6 @@ To work with .NET Aspire, you need the following installed locally:
 - Integrated Developer Environment (IDE) or code editor, such as:
   - [Visual Studio 2022 Preview](https://visualstudio.microsoft.com/vs/preview/) version 17.9 or higher (Optional)
   - [Visual Studio Code](https://code.visualstudio.com/) (Optional)
+    - [C# Dev Kit: Extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) (Optional)
 
 For more information, see [.NET Aspire setup and tooling](../fundamentals/setup-tooling.md).
diff --git a/docs/includes/dotnet-cli-file-new.md b/docs/includes/dotnet-cli-file-new.md
@@ -0,0 +1,5 @@
+```dotnetcli
+dotnet new aspire-starter --use-redis-cache --output AspireSample
+```
+
+For more information, see [dotnet new](/dotnet/core/tools/dotnet-new). The .NET CLI creates a new solution that is structured to use .NET Aspire.
diff --git a/docs/includes/file-new-aspire.md b/docs/includes/file-new-aspire.md
@@ -1,32 +1,5 @@
-## Create the .NET Aspire template
-
-To create a new .NET Aspire Starter Application, you can use either Visual Studio or the .NET CLI.
-
-### [Visual Studio](#tab/visual-studio)
-
-Visual Studio provides .NET Aspire project templates that handle some initial setup configurations for you. Complete the following steps to create a project for this quickstart:
-
-1. At the top of Visual Studio, navigate to **File** > **New** > **Project**.
-1. In the dialog window, search for *Aspire* and select **.NET Aspire Starter Application**. Select **Next**.
-
-    :::image type="content" source="../media/aspire-templates.png" lightbox="../media/aspire-templates.png" alt-text="A screenshot of the .NET Aspire Starter Application template.":::
-
-1. On the **Configure your new project** screen:
-    - Enter a **Project Name** of *AspireSample*.
-    - Leave the rest of the values at their defaults and select **Next**.
-1. On the **Additional information** screen:
-    - Make sure **.NET 8.0 (Long Term Support)** is selected.
-    - Ensure that **Use Redis for caching (requires a supported container runtime)** is checked and select **Create**.
-    - Optionally, you can select **Create a tests project**. For more information, see [Testing .NET Aspire apps](../fundamentals/testing.md).
-
-Visual Studio creates a new solution that is structured to use .NET Aspire.
-
-### [.NET CLI](#tab/dotnet-cli)
-
-```dotnetcli
-dotnet new aspire-starter --use-redis-cache --output AspireSample
-```
+---
+zone_pivot_groups: dev-environment
+---
 
-For more information, see [dotnet new](/dotnet/core/tools/dotnet-new). The .NET CLI creates a new solution that is structured to use .NET Aspire.
 
----
diff --git a/docs/includes/media/vscode-new-starter-project.png b/docs/includes/media/vscode-new-starter-project.png
diff --git a/docs/includes/template-directory-structure.md b/docs/includes/template-directory-structure.md
@@ -2,7 +2,7 @@
 title: .NET Aspire Starter Application directory structure
 description: An include file that contains the directory structure of the .NET Aspire Starter Application.
 ms.topic: include
-ms.date: 11/11/2023
+ms.date: 05/13/2024
 ---
 
 ```Directory

diff --git a/docs/includes/visual-studio-file-new.md b/docs/includes/visual-studio-file-new.md
@@ -0,0 +1,16 @@
+Visual Studio provides .NET Aspire project templates that handle some initial setup configurations for you. Complete the following steps to create a project for this quickstart:
+
+1. At the top of Visual Studio, navigate to **File** > **New** > **Project**.
+1. In the dialog window, search for *Aspire* and select **.NET Aspire Starter Application**. Select **Next**.
+
+    :::image type="content" source="../media/aspire-templates.png" lightbox="../media/aspire-templates.png" alt-text="A screenshot of the .NET Aspire Starter Application template.":::
+
+1. On the **Configure your new project** screen:
+    - Enter a **Project Name** of *AspireSample*.
+    - Leave the rest of the values at their defaults and select **Next**.
+1. On the **Additional information** screen:
+    - Make sure **.NET 8.0 (Long Term Support)** is selected.
+    - Ensure that **Use Redis for caching (requires a supported container runtime)** is checked and select **Create**.
+    - Optionally, you can select **Create a tests project**. For more information, see [Testing .NET Aspire apps](../fundamentals/testing.md).
+
+Visual Studio creates a new solution that is structured to use .NET Aspire.