Skip to content

Commit 2412c22

Browse files
Copilotalistairmatthewsadamint
authored
Add documentation for Aspire Visual Studio Code extension (#5314)
* Initial plan * Add Aspire VS Code extension documentation Co-authored-by: alistairmatthews <[email protected]> * Add link to VS Code extension from setup-tooling.md Co-authored-by: alistairmatthews <[email protected]> * Update docs/fundamentals/aspire-vscode-extension.md * Update docs/fundamentals/aspire-vscode-extension.md * Update docs/fundamentals/aspire-vscode-extension.md * Update docs/fundamentals/aspire-vscode-extension.md * Update docs/fundamentals/aspire-vscode-extension.md * Address all PR review feedback for VS Code extension docs * Adding a screenshot of the extension installation. * Fixing an image path. * Adding a second screenshot. * Small corrections. * Fixing a markdown lint problem. * Removed the extra period from @copilot's feedback. * small fixes * fix trailing space --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: alistairmatthews <[email protected]> Co-authored-by: Alistair Matthews <[email protected]> Co-authored-by: Adam Ratzman <[email protected]>
1 parent 6b10c7f commit 2412c22

File tree

5 files changed

+198
-0
lines changed

5 files changed

+198
-0
lines changed

‎docs/fundamentals/aspire-vscode-extension.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: Aspire Visual Studio Code extension
3+
description: Learn how to use the Aspire Visual Studio Code extension to create, configure, run, and deploy Aspire solutions.
4+
ms.date: 10/20/2025
5+
ms.topic: overview
6+
uid: dotnet/aspire/vscode-extension
7+
ai-usage: ai-assisted
8+
---
9+
10+
# Aspire Visual Studio Code extension
11+
12+
The Aspire Visual Studio Code extension provides a set of commands and tools to streamline your work with Aspire within Visual Studio Code. The extension includes commands to create projects, add integrations, configure solutions, and manage deployments. The extension requires the Aspire CLI and provides similar functionality on the Visual Studio Code command palette.
13+
14+
[!INCLUDE [aspire-prereqs](../includes/aspire-prereqs.md)]
15+
16+
In addition, before you can use the Aspire Visual Studio Code extension, you must have the [Aspire CLI](../cli/install.md) installed and available on your PATH.
17+
18+
## Install the Aspire extension
19+
20+
To install the Aspire VS Code extension:
21+
22+
1. Open VS Code.
23+
1. Open the Extensions view by selecting **View** > **Extensions** or pressing <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>X</kbd> (Windows/Linux) or <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>X</kbd> (macOS).
24+
1. Search for "Aspire" in the Extensions marketplace.
25+
1. Select the **Aspire** extension published by **Microsoft**.
26+
1. Select **Install**.
27+
28+
:::image type="content" source="media/install-aspire-code-extension.png" lightbox="media/install-aspire-code-extension.png" alt-text="A screenshot of VS Code showing how to install the Aspire extension.":::
29+
30+
Alternatively, you can install the extension directly from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=microsoft-aspire.aspire-vscode).
31+
32+
## Access extension commands
33+
34+
All Aspire extension commands are available from the VS Code Command Palette:
35+
36+
1. Open the Command Palette by pressing <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux) or <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (macOS).
37+
1. Type "Aspire" to filter and display all available Aspire commands.
38+
1. Select the desired command from the list.
39+
40+
All commands are grouped under the **Aspire** category in the Command Palette for easy discovery.
41+
42+
## Available commands
43+
44+
The Aspire VS Code extension provides the following commands:
45+
46+
| Command | Description | Availability |
47+
|---------|-------------|--------------|
48+
| Aspire: New Aspire project | Create a new Aspire apphost or starter app from a template. | Available |
49+
| Aspire: Add an integration | Add a hosting integration (`Aspire.Hosting.*`) to the Aspire apphost. | Available |
50+
| Aspire: Configure launch.json | Adds the default Aspire debugger launch configuration to your workspace's `launch.json`, which will detect and run the apphost in the workspace. | Available |
51+
| Aspire: Manage configuration settings | Manage configuration settings including feature flags. | Available |
52+
| Aspire: Open Aspire terminal | Open an Aspire VS Code terminal for working with Aspire projects. | Available |
53+
| Aspire: Publish deployment artifacts | Generates deployment artifacts for an Aspire apphost. | Preview |
54+
| Aspire: Deploy app | Deploy the contents of an Aspire apphost to its defined deployment targets. | Preview |
55+
| Aspire: Update integrations | Update hosting integrations and Aspire SDK in the apphost. | Preview |
56+
57+
## Create a new Aspire app
58+
59+
To create a new Aspire app using the extension:
60+
61+
1. Open the Command Palette (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> or <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>).
62+
1. Run the **Aspire: New Aspire project** command.
63+
1. Select the desired template:
64+
1. Specify the project name and location.
65+
66+
:::image type="content" source="media/code-extension-create-aspire-project.png" lightbox="media/code-extension-create-aspire-project.png" alt-text="A screenshot of VS Code showing how to create a new Aspire solution by using the Aspire extension.":::
67+
68+
The extension creates the project and opens it in VS Code.
69+
70+
## Add an integration to the Aspire solution
71+
72+
Aspire integrations provide pre-configured connections to various cloud services and dependencies. To add an integration:
73+
74+
1. Open the Command Palette.
75+
1. Run the **Aspire: Add an integration** command.
76+
1. Browse or search for the desired integration package.
77+
1. Select the integration to add it to your AppHost project.
78+
79+
The extension adds the appropriate NuGet package reference to your AppHost project.
80+
81+
> [!NOTE]
82+
> The **Add an integration** command adds a hosting integration to the AppHost project. It doesn't add the corresponding client integration to any consuming projects.
83+
84+
## Configure an Aspire solution
85+
86+
The Aspire extension includes several commands that configure the behavior of Aspire and the Aspire CLI during development:
87+
88+
### Configure launch.json for debugging
89+
90+
To run and debug your Aspire application in VS Code, you need to configure the `launch.json` file:
91+
92+
1. Open the Command Palette.
93+
1. Run the **Aspire: Configure launch.json** command.
94+
1. The extension adds a default Aspire debugger configuration to your workspace's `launch.json` file.
95+
96+
The default configuration looks like this:
97+
98+
```json
99+
{
100+
"type": "aspire",
101+
"request": "launch",
102+
"name": "Aspire: Launch Default AppHost",
103+
"program": "${workspaceFolder}"
104+
}
105+
```
106+
107+
You can customize the `program` field to point to a specific AppHost project file. For example:
108+
109+
```json
110+
{
111+
"type": "aspire",
112+
"request": "launch",
113+
"name": "Aspire: Launch MyAppHost",
114+
"program": "${workspaceFolder}/MyAppHost/MyAppHost.csproj"
115+
}
116+
```
117+
118+
### Manage configuration settings
119+
120+
The **Aspire: Manage configuration settings** command executes `aspire config` request options and displays the results in the VS Code terminal. Use `get` and `set` commands to configure the Aspire CLI. Use the `list` command to show current configuration values.
121+
122+
## Run an Aspire solution in development mode
123+
124+
To run your Aspire application in development mode:
125+
126+
1. Ensure you have configured `launch.json` as described in the [Configure launch.json for debugging](#configure-launchjson-for-debugging) section.
127+
1. Open the Run and Debug view by selecting **View** > **Run** or pressing <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd> (Windows/Linux) or <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd> (macOS).
128+
1. Select your Aspire launch configuration from the dropdown.
129+
1. Select the green **Start Debugging** button or press <kbd>F5</kbd>.
130+
131+
The extension builds and starts the AppHost project, launches the Aspire dashboard in your browser, and enables debugging for all resources in your solution.
132+
133+
Alternatively, you can open an Aspire VS Code terminal using `Aspire: Open Aspire terminal` and run `aspire run --start-debug-session` to start a VS Code debug session.
134+
135+
### Run or debug from the editor
136+
137+
When an AppHost project is detected in your workspace, you can also run or debug it directly from the editor. Use the run buttons in the editor title bar when viewing an AppHost file.
138+
139+
## Publish deployment artifacts
140+
141+
> [!IMPORTANT]
142+
> This feature is in **Preview**.
143+
144+
The **Aspire: Publish deployment artifacts** command generates deployment artifacts for your Aspire AppHost. This command serializes resources to disk, allowing them to be consumed by deployment tools.
145+
146+
To publish deployment artifacts:
147+
148+
1. Open the Command Palette.
149+
1. Run the **Aspire: Publish deployment artifacts** command.
150+
1. Select the output location for the generated artifacts.
151+
152+
The command invokes registered publishing callback annotations to generate artifacts such as:
153+
154+
- Bicep files for Azure resources.
155+
- Docker Compose YAML files.
156+
- Kubernetes Helm charts.
157+
158+
For more information about Aspire publishing, see [Aspire publishing and deployment overview](../deployment/overview.md).
159+
160+
## Deploy an Aspire solution
161+
162+
> [!IMPORTANT]
163+
> This feature is in **Preview**.
164+
165+
The **Aspire: Deploy app host** command deploys the contents of an Aspire AppHost to its defined deployment targets.
166+
167+
To deploy an Aspire solution:
168+
169+
1. Open the Command Palette.
170+
1. Run the **Aspire: Deploy app host** command.
171+
1. Follow the prompts to select deployment targets and provide any required configuration.
172+
173+
The command publishes deployment artifacts and then invokes deployment callback annotations to deploy resources to the specified targets.
174+
175+
For more information about Aspire deployment, see [Aspire publishing and deployment overview](../deployment/overview.md).
176+
177+
## Open Aspire terminal
178+
179+
The **Aspire: Open Aspire terminal** command opens a terminal window configured for working with Aspire projects. This terminal provides easy access to Aspire CLI commands and is preconfigured with the appropriate environment variables.
180+
181+
## Feedback and issues
182+
183+
To report issues or request features for the Aspire VS Code extension:
184+
185+
1. Visit the [Aspire GitHub repository](https://github.com/dotnet/aspire/issues).
186+
1. Create a new issue and add the `area-extension` label.
187+
188+
## See also
189+
190+
- [Aspire setup and tooling](setup-tooling.md)
191+
- [Aspire CLI Overview](../cli/overview.md)
192+
- [Aspire templates](aspire-sdk-templates.md)
193+
- [Aspire VS Code extension on the marketplace](https://marketplace.visualstudio.com/items?itemName=microsoft-aspire.aspire-vscode)

‎docs/fundamentals/media/code-extension-create-aspire-project.png‎

224 KB
Loading

‎docs/fundamentals/media/install-aspire-code-extension.png‎

440 KB
Loading

‎docs/fundamentals/setup-tooling.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -251,6 +251,8 @@ Once you create a new Aspire project, you run and debug the app, stepping throug
251251

252252
:::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 an Aspire project in Visual Studio Code.":::
253253

254+
The [Aspire Visual Studio Code extension](aspire-vscode-extension.md) provides additional commands and tooling to streamline working with Aspire projects, including commands to add integrations, configure launch settings, publish deployment artifacts, and deploy applications.
255+
254256
:::zone-end
255257

256258
## Aspire CLI

‎docs/toc.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ items:
2727
href: fundamentals/dotnet-aspire-sdk.md
2828
- name: Aspire templates
2929
href: fundamentals/aspire-sdk-templates.md
30+
- name: Aspire Visual Studio Code extension
31+
href: fundamentals/aspire-vscode-extension.md
32+
displayName: vscode,visual studio code,extension,vs code
3033
- name: GitHub Codespaces
3134
href: get-started/github-codespaces.md
3235
- name: Dev Containers

0 commit comments

Comments
 (0)