# Aspire Visual Studio Code extension

The official Aspire extension for [Visual Studio Code](https://code.visualstudio.com/) turns VS Code into a first-class environment for building, debugging, and shipping polyglot Aspire apps.
Press <Kbd windows='F5' /> to build your AppHost, start your resources, and debug supported resource types — C#, TypeScript, Python, browser apps, and Azure Functions — alongside the Aspire dashboard.

:::note[Prerequisites]
A recent version of [Visual Studio Code](https://code.visualstudio.com/) and the **Aspire CLI** — install the CLI via the **Aspire: Install Aspire CLI (stable)** command from the Command Palette, or follow the [installation guide](/get-started/install-cli/).
:::

## Install the extension

1. Open VS Code.
1. Open the **Extensions** view (<Kbd windows='Ctrl+Shift+X' mac='Cmd+Shift+X' />).
1. Search for **Aspire** and install the extension published by **Microsoft**, or install it directly from the [VS Code Marketplace](https://aka.ms/aspire/vscode).

## Getting started

1. Open an existing Aspire project in VS Code, or create one with **Aspire: New Aspire project** from the Command Palette (<Kbd windows='Ctrl+Shift+P' mac='Cmd+Shift+P' />).
1. Run **Aspire: Configure launch.json file** to set up the debug configuration.
1. Press <Kbd windows='F5' /> to start debugging your Aspire app.

<ThemeImage
  dark={createProject}
  light={createProjectLight}
  alt="VS Code showing the Aspire: New Aspire project command palette with starter templates for Blazor, React + C#, Express + TypeScript, FastAPI + TypeScript, and an empty AppHost."
/>

<p><em>The <strong>Aspire: New Aspire project</strong> command, showing starter templates for Blazor, React + C#, Express + TypeScript, FastAPI + TypeScript, and an empty AppHost.</em></p>

The extension discovers your AppHost from `aspire.config.json`, so both project-based C# AppHosts (`*.csproj`) and TypeScript AppHosts (`apphost.ts`) work without extra configuration.

:::tip[Prefer a guided tour?]
**Help > Get Started > Get started with Aspire** opens a built-in walkthrough covering CLI install, project creation, running, and exploring the dashboard — all without leaving VS Code.
:::

## Scaffold and add integrations

The Command Palette has commands for the most common tasks:

- **Aspire: Add an integration** offers a selection of hosting integrations (`Aspire.Hosting.*`) to add to your AppHost.
- **Aspire: Initialize Aspire in an existing codebase** wires Aspire into a repo that has not yet been Aspirified.
- **Aspire: Update integrations** updates hosting integrations and the Aspire SDK.
- **Aspire: Open Aspire terminal** drops you into a terminal with the Aspire CLI already on `PATH` for anything the UI doesn't cover.
- **Aspire: Update Aspire CLI** and **Aspire: Install Aspire CLI** let you manage CLI installation.

## Live editor integration

When an AppHost is running, the extension paints live state directly into your editor.

**CodeLens** appears above each resource definition in C# and TypeScript AppHosts. It shows the current state and health and exposes one-click `Start`, `Stop`, `Restart`, and `View Logs` actions in addition to any custom commands the resource publishes. 

**Editor title bar buttons** add **Run Aspire AppHost** and **Debug Aspire AppHost** actions next to the standard Run/Debug buttons whenever you have an AppHost file open.

**Health-aware gutter decorations** provide an at-a-glance view of resource health and state without cluttering the editor with text using the following shapes and colors:

| Icon | Meaning |
|------|---------|
| ✓ (green checkmark) | Running and healthy |
| ⊙ (grey circle with check) | Completed — exited cleanly (exit code 0) |
| ⚠ (yellow triangle with `!`) | Running but unhealthy (health checks failing) |
| ✕ (red X) | Failed to start, exited with a non-zero exit code, or runtime unhealthy |
| ⌛ (blue hourglass) | Starting, stopping, building, or waiting |
| ○ (grey hollow circle) | Not yet started |

<ThemeImage
  dark={sidebarTree}
  light={sidebarTreeLight}
  alt="The Aspire view showing a tree of resources with health-aware icons and a hover tooltip listing endpoint URLs."
/>

## The Aspire view

Aspire registers an AppHost view to VS Code. **Workspace** mode shows the AppHost in your current workspace; toggle to **Global** in the view header to manage every running AppHost on your machine.

Each resource shows its type, state, health summary, and exit code, plus a health-aware icon and a markdown tooltip listing endpoint URLs. Resources with health checks expose an expandable **Health Checks** group; use **Expand all** on the AppHost item to open everything at once. You can right-click a resource to start, stop, or restart it, view its logs, run resource-specific commands, or open the dashboard.

## Run, debug, and deploy

**Aspire: Configure launch.json file** adds a minimal launch configuration `.vscode/launch.json` that supports AppHosts written in any language. AppHosts are discovered automatically in the workspace. 

<LearnMore>
To launch a specific AppHost, configure an [aspire.config.json](/reference/cli/configuration/) with an `appHost.path` property.
</LearnMore>

```json title=".vscode/launch.json — launch"
{
  "type": "aspire",
  "request": "launch",
  "name": "Aspire: Launch AppHost",
  "program": "${workspaceFolder}"
}
```

Four launch commands are supported:
- `run` runs the AppHost (default if command is omitted).
- `deploy` pushes to deployment targets defined in your AppHost.
- `publish` generates deployment artifacts like Kubernetes manifests or Bicep files without pushing to targets.
- `do` runs a specific pipeline step defined in your AppHost's deployment pipeline — set `step` to the name of the step you want to run.

All of these commands are debuggable; you can step into custom publishers and deployment steps just like application code.

<ThemeImage
  dark={debugSessions}
  light={debugSessionsLight}
  alt="VS Code Run & Debug view with multiple debug sessions attached — AppHost, a .NET project, a Node service, and a browser app — alongside the dashboard."
/>

The `debuggers` property forwards configuration to specific debuggers. Recognized keys are: `apphost`, `project` (C#/.NET), `node`, `python`, `browser`, and `azure-functions`.

Finally, you can specify `env` and `args` to set environment variables and command-line arguments for the AppHost process.

```json title=".vscode/launch.json — deploy with debugger settings, env, and args"
{
  "type": "aspire",
  "request": "launch",
  "name": "Aspire: Deploy AppHost",
  "program": "${workspaceFolder}",
  "command": "deploy",
  "env": {
    "MY_ENV_VAR": "value"
  },
  "args": [
    "--hello", "world"
  ],
  "debuggers": {
    "apphost": { "stopAtEntry": true },
    "project": { "console": "integratedTerminal" },
    "node": { "skipFiles": ["<node_internals>/**"] },
    "python": { "justMyCode": false }
  }
}
```

<LearnMore>
For more information, see [Aspire publishing and deployment overview](/deployment/deploy-with-aspire/).
</LearnMore>

## Language coverage

The extension detects each resource's language and attaches the right debugger:

| Language | Debugger | Required VS Code extension |
|---|---|---|
| Node.js / Browser apps | `js-debug` | None (built into VS Code) |
| Python | `debugpy` | [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) |
| C# / .NET | `coreclr` | [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) (recommended) or [C#](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp) |
| Azure Functions | Per language | [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions) plus the language extension for your function app (C#, JavaScript/TypeScript, or Python) |

## Feedback and issues

Found a bug or have an idea? File it on the [microsoft/aspire](https://github.com/microsoft/aspire/issues) repo:

- [Report a bug](https://github.com/microsoft/aspire/issues/new?template=10_bug_report.yml&labels=area-extension)
- [Request a feature](https://github.com/microsoft/aspire/issues/new?template=20_feature-request.yml&labels=area-extension)