# 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](/get-started/glossary/#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** 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='Command+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='Command+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. The extension discovers the AppHost, starts the app, attaches supported debuggers, and opens the dashboard.

*Open a repo, let the extension find the AppHost, press <Kbd windows='F5' />, then use the Aspire view and dashboard while the app runs.*

<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.mts`) 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. **Install Aspire CLI** shows a package-manager picker (WinGet, Homebrew, npm, .NET tool, or mise, depending on your platform) plus a **Daily build (dev)** option and a link to the full [installation guide](/get-started/install-cli/) for every option, including the install script.

## 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.

<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, open the dashboard, or open an interactive terminal session (for resources configured with [`WithTerminal()`](/app-host/with-terminal/)).

:::note[Renamed polling setting]
`aspire.globalAppHostsPollingInterval` is deprecated. Use `aspire.appHostsPollingInterval` to configure how often the Aspire view polls for running AppHosts.
:::

## Run, debug, and deploy

:::note[Debugging]
The Aspire Dashboard is no longer opened by default when the AppHost starts, as most operations can be performed using the Aspire view inside VS Code. To launch the dashboard, use the **Open Dashboard** CodeLens, the **Aspire: Open Dashboard** command, or open it from the Aspire view.
:::

**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`.

For `project`, the extension normally generates a `serverReadyAction` from the project's `launchSettings.json` to automatically open the browser when the server is ready. Set `debuggers.project.serverReadyAction` explicitly to override this generated default with your own action and pattern:

:::note[AppHost behavior]
A .NET AppHost also uses the `project` debugger, so `debuggers.project.serverReadyAction` is included in its debug configuration. If you set both `debuggers.apphost.serverReadyAction` and `debuggers.project.serverReadyAction`, the `project` value takes precedence.
:::

```json title=".vscode/launch.json — override debuggers.project.serverReadyAction"
{
  "debuggers": {
    "project": {
      "serverReadyAction": {
        "action": "openIntegratedBrowser",
        "pattern": "\\bNow listening on:\\s+(https?://\\S+)"
      }
    }
  }
}
```

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)