Vscode Extension

Aspire VS Code Extension

This skill covers working on the Aspire VS Code extension, which lives entirely under extension/. It is a TypeScript extension built with yarn (pinned via packageManager in extension/package.json) and webpack, and it communicates with the Aspire CLI over RPC.

Orientation

All commands below are run from the extension/ directory unless noted.

Prerequisites

Do NOT run the repo-root ./build.sh when you are only working on the Aspire CLI and/or the VS Code extension. The root build compiles the entire product (all of src/, native AOT, packages) and is slow and unnecessary for this work. Root restore is needed only to bootstrap the repository's .NET SDK. Check the SDK from the repository root:

• If ./.dotnet/dotnet --version (Linux/macOS) or .\.dotnet\dotnet.exe --version (Windows) succeeds, add .dotnet to PATH (export PATH="$PWD/.dotnet:$PATH" on Linux/macOS or $env:PATH = "$PWD\.dotnet;$env:PATH" in PowerShell) and skip root restore.
• Otherwise, if dotnet --version succeeds, skip root restore and use that host.
• If neither succeeds, run ./restore.sh (Linux/macOS) or .\restore.cmd (Windows) once, then add the installed .dotnet directory to PATH as shown above.

The extension build script does not install .NET.

Once the required SDK is available, build the extension and CLI together with the extension build script. From extension/, run ./build.sh (Linux/macOS) or ./build.ps1 (Windows). This script builds the Aspire CLI (dotnet build ../src/Aspire.Cli/Aspire.Cli.csproj) and the extension, and installs extension dependencies (seeds Corepack and runs corepack yarn install). You do not install Yarn yourself — it is pinned via packageManager.

For changes limited to extension/, src/Aspire.Cli/, and/or tests/Aspire.Cli*/, start with the extension build script once either SDK check succeeds. It performs the project restore and build steps needed by this workflow. Run targeted CLI test projects separately after the build.

Use yarn for extension commands (corepack yarn ... or yarn run ...), not npm / npx. The dependency graph and scripts are pinned for Yarn via extension/package.json and yarn.lock.

If corepack yarn install fails with registry 401/404 or EACCES, see the Troubleshooting section of extension/CONTRIBUTING.md — these are environment/npm-mirror issues, not code issues.

Extension ↔ CLI compatibility (IMPORTANT)

The extension and the Aspire CLI are tightly coupled: new features or changes in the extension often require corresponding changes in the CLI. When you add or modify extension behavior, expect to also touch src/Aspire.Cli/ and rebuild both with extension/build.sh / extension/build.ps1.

When you change a CLI contract or expectation (command output shape, JSON schema, new flags, new behavior the extension relies on), you must remain backwards compatible and keep working with older Aspire CLI versions. A user may have a newer extension paired with an older aspire CLI on their PATH. Do not assume the CLI supports a capability just because the current build does.

Detect what the installed CLI supports at runtime instead of assuming, by reading capabilities from extension functionality that wraps aspire config info.

Hidden or probe-style CLI calls from the extension should avoid paying for or emitting interactive startup UX. When the extension runs a CLI command for JSON or other machine-readable output, pass --nologo when the target CLI version supports it, keep the command's stdout parseable, and add a fallback/retry path for older CLIs that reject --nologo. Add or update CLI-side machine-readable detection if you introduce a new structured-output flag or hidden JSON command. This prevents first-run/banner/identity text from corrupting stdout and keeps extension startup comparable to direct aspire run / aspire start.

Develop / modify the extension

• Prefer TypeScript (.ts) files; never create .js source files for extension code.
• Use static imports, not dynamic imports, unless dynamic import is absolutely necessary.
• Use the latest TypeScript features consistent with the existing code style.
• New user-facing commands, views, settings, or debugger config go in the contributes section of extension/package.json.

Localization (REQUIRED for any user-facing string)

Every string shown to the user must be localized. There are two surfaces:

• TypeScript code → add to extension/src/loc/strings.ts using vscode.l10n.t(...). Follow the existing pattern (plain const for static strings, an arrow function for strings with placeholders like {0}). Import from loc/strings rather than inlining literals.
• package.json manifest (command titles, view names, setting descriptions, debugger properties) → use a %key% reference and define the key in extension/package.nls.json.

Do not hand-edit generated localization bundles (the l10n/ output, *.xlf, or */localize/templatestrings.*.json); translation is handled by a dedicated workflow. The npm scripts l10n:export / l10n:import (run automatically by precompile/prepackage/prewatch) regenerate the l10n bundle from package.nls.json and the vscode.l10n.t calls.

Build

From extension/:

yarn run compile      # one-off webpack build to ./dist
yarn run watch        # incremental webpack build (use while iterating)
yarn run package      # production build (minified, hidden source maps)

watch, compile, and package are preceded by prewatch/precompile/prepackage, which run generate-version, generate-schema, and the l10n export/import. The VS Code task yarn: watch extension (the default build task) runs yarn run watch.

To produce a .vsix, the full MSBuild path is extension/Extension.proj (used by CI/signing); for local iteration yarn run package plus the launch configs below is usually enough.