diff --git a/.gitignore b/.gitignore index 26f9578fb..4af3eb8dc 100644 --- a/.gitignore +++ b/.gitignore @@ -454,3 +454,7 @@ FodyWeavers.xsd bin/ obj/ tmp-ts-validation/ +.playwright-mcp/ + +# Generated TwoSlash types +src/frontend/.twoslash-types/ diff --git a/src/frontend/src/assets/get-started/code-extension-create-aspire-project-light.png b/src/frontend/src/assets/get-started/code-extension-create-aspire-project-light.png index c44094cf4..fef527670 100644 Binary files a/src/frontend/src/assets/get-started/code-extension-create-aspire-project-light.png and b/src/frontend/src/assets/get-started/code-extension-create-aspire-project-light.png differ diff --git a/src/frontend/src/assets/get-started/code-extension-create-aspire-project.png b/src/frontend/src/assets/get-started/code-extension-create-aspire-project.png index d25978dc7..9670f31e4 100644 Binary files a/src/frontend/src/assets/get-started/code-extension-create-aspire-project.png and b/src/frontend/src/assets/get-started/code-extension-create-aspire-project.png differ diff --git a/src/frontend/src/assets/get-started/code-extension-debug-light.png b/src/frontend/src/assets/get-started/code-extension-debug-light.png new file mode 100644 index 000000000..14438107c Binary files /dev/null and b/src/frontend/src/assets/get-started/code-extension-debug-light.png differ diff --git a/src/frontend/src/assets/get-started/code-extension-debug.png b/src/frontend/src/assets/get-started/code-extension-debug.png new file mode 100644 index 000000000..905955b05 Binary files /dev/null and b/src/frontend/src/assets/get-started/code-extension-debug.png differ diff --git a/src/frontend/src/assets/get-started/code-extension-sidebar-light.png b/src/frontend/src/assets/get-started/code-extension-sidebar-light.png new file mode 100644 index 000000000..9c61b2b87 Binary files /dev/null and b/src/frontend/src/assets/get-started/code-extension-sidebar-light.png differ diff --git a/src/frontend/src/assets/get-started/code-extension-sidebar.png b/src/frontend/src/assets/get-started/code-extension-sidebar.png new file mode 100644 index 000000000..d7b314ee8 Binary files /dev/null and b/src/frontend/src/assets/get-started/code-extension-sidebar.png differ diff --git a/src/frontend/src/assets/get-started/install-aspire-code-extension-light.png b/src/frontend/src/assets/get-started/install-aspire-code-extension-light.png deleted file mode 100644 index 6fdb15a9a..000000000 Binary files a/src/frontend/src/assets/get-started/install-aspire-code-extension-light.png and /dev/null differ diff --git a/src/frontend/src/assets/get-started/install-aspire-code-extension.png b/src/frontend/src/assets/get-started/install-aspire-code-extension.png deleted file mode 100644 index 7c874a7e8..000000000 Binary files a/src/frontend/src/assets/get-started/install-aspire-code-extension.png and /dev/null differ diff --git a/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx b/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx index e4d5bae2a..36dc147fd 100644 --- a/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx +++ b/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx @@ -3,34 +3,23 @@ title: Aspire Visual Studio Code extension description: Learn how to use the Aspire Visual Studio Code extension to create, configure, run, and deploy Aspire solutions. --- -import { Aside, Steps } from '@astrojs/starlight/components'; +import { Steps } from '@astrojs/starlight/components'; import ThemeImage from '@components/ThemeImage.astro'; import LearnMore from '@components/LearnMore.astro'; -import installExtension from '@assets/get-started/install-aspire-code-extension.png'; -import installExtensionLight from '@assets/get-started/install-aspire-code-extension-light.png'; import createProject from '@assets/get-started/code-extension-create-aspire-project.png'; import createProjectLight from '@assets/get-started/code-extension-create-aspire-project-light.png'; +import sidebarTree from '@assets/get-started/code-extension-sidebar.png'; +import sidebarTreeLight from '@assets/get-started/code-extension-sidebar-light.png'; +import debugSessions from '@assets/get-started/code-extension-debug.png'; +import debugSessionsLight from '@assets/get-started/code-extension-debug-light.png'; import { Kbd } from 'starlight-kbd/components'; -The official Aspire extension for VS Code. Run, debug, and deploy your Aspire apps without leaving the editor, with debugging support for C#, Python, Node.js, and more. +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 to build your AppHost, start your resources, and debug supported resource types — C#, TypeScript, Python, browser apps, and Azure Functions — alongside the Aspire dashboard. -## Features at a glance - -| Feature | Description | -|---------|-------------| -| **Run & debug** | Start your whole app and attach debuggers to every service with | -| **Dashboard** | View resources, endpoints, logs, traces, and metrics while your app runs | -| **Sidebar** | Browse running apphosts and resources in the Activity Bar | -| **Integrations** | Add databases, queues, and cloud services from the Command Palette | -| **Scaffolding** | Create new Aspire projects from templates | -| **Deploy** | Generate deployment artifacts or push to cloud targets | -| **MCP** | Let AI tools like GitHub Copilot see your running app via the Model Context Protocol | -| **Multi-language** | Debug C#, Python, Node.js, Azure Functions, and browser apps together | - -## Prerequisites - -- **Aspire CLI** — Install via the **Aspire: Install Aspire CLI (stable)** command in VS Code, or follow the [installation guide](/get-started/install-cli/). -- **VS Code 1.98** or later. +:::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 @@ -38,162 +27,147 @@ The official Aspire extension for VS Code. Run, debug, and deploy your Aspire ap 1. Open VS Code. 1. Open the **Extensions** view (). -1. Search for **Aspire** and install the extension published by **Microsoft**. +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 -Or install 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 (). +1. Run **Aspire: Configure launch.json file** to set up the debug configuration. +1. Press to start debugging your Aspire app. -Open your Aspire project in VS Code, or create one with **Aspire: New Aspire project** from the Command Palette. Run **Aspire: Configure launch.json file** to set up the debug configuration, then press . The extension builds your apphost, starts your services, attaches debuggers, and opens the dashboard. + -There's also a built-in walkthrough at **Help > Get Started > Get started with Aspire** that covers the basics step by step. +

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

-## Running and debugging +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. -### Launch 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. +::: -Add an entry to `.vscode/launch.json` pointing at your apphost project: +## Scaffold and add integrations -```json title=".vscode/launch.json — launch" -{ - "type": "aspire", - "request": "launch", - "name": "Aspire: Launch MyAppHost", - "program": "${workspaceFolder}/MyAppHost/MyAppHost.csproj" -} -``` +The Command Palette has commands for the most common tasks: -Or run **Aspire: Configure launch.json file** from the Command Palette to generate one automatically. +- **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. -When you press , the extension builds the apphost, starts all resources (services, containers, databases) in the right order, attaches debuggers based on each service's language, and opens the dashboard. +## Live editor integration -You can also right-click an AppHost file in the Explorer and select **Run Aspire apphost** or **Debug Aspire apphost**. +When an AppHost is running, the extension paints live state directly into your editor. -### Deploy, publish, and pipeline steps +**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. -The `command` property in the launch config supports more than just running: +**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. -- **`deploy`** — Push to your defined deployment targets. -- **`publish`** — Generate deployment artifacts (manifests, Bicep files, etc.). -- **`do`** — Run a specific pipeline step. Set `step` to the step name. +**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: -```json title=".vscode/launch.json — deploy" -{ - "type": "aspire", - "request": "launch", - "name": "Aspire: Deploy MyAppHost", - "program": "${workspaceFolder}/MyAppHost/MyAppHost.csproj", - "command": "deploy" -} -``` +| 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 | + + + +## 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. -For more information, see [Aspire publishing and deployment overview](/deployment/overview/). +To launch a specific AppHost, configure an [aspire.config.json](/reference/cli/configuration/) with an `appHost.path` property. -### Customizing debugger settings per language - -The `debuggers` property lets you pass debug configuration specific to a language. Use `project` for C#/.NET services, `python` for Python, and `apphost` for the apphost itself: -```json title=".vscode/launch.json — debugger settings" +```json title=".vscode/launch.json — launch" { "type": "aspire", "request": "launch", - "name": "Aspire: Launch MyAppHost", - "program": "${workspaceFolder}/MyAppHost/MyAppHost.csproj", - "debuggers": { - "project": { - "console": "integratedTerminal", - "logging": { "moduleLoad": false } - }, - "apphost": { - "stopAtEntry": true - } - } + "name": "Aspire: Launch AppHost", + "program": "${workspaceFolder}" } ``` -## The Aspire sidebar - -The extension adds an **Aspire** panel to the Activity Bar with a live tree of your resources. In **Workspace** mode you see resources from the apphost in your current workspace, updating in real time. Switch to **Global** mode with the toggle in the panel header to see every running apphost on your machine. - -Right-click a resource to start, stop, or restart it, view its logs, run resource-specific commands, or open the dashboard. - -## Commands - -All commands are available from the Command Palette () under **Aspire**. - -| Command | Description | -|---------|-------------| -| **New Aspire project** | Create a new apphost or starter app from a template | -| **Initialize Aspire in an existing codebase** | Add Aspire to an existing project | -| **Add an integration** | Add a hosting integration (`Aspire.Hosting.*`) | -| **Update integrations** | Update hosting integrations and the Aspire SDK | -| **Publish deployment artifacts** | Generate deployment manifests | -| **Deploy app** | Deploy to your defined targets | -| **Execute pipeline step** | Run a pipeline step and its dependencies (`aspire do`) | -| **Configure launch.json file** | Add the Aspire debug config to your workspace | -| **Extension settings** | Open Aspire extension settings | -| **Open local Aspire settings** | Open `.aspire/settings.json` for this workspace | -| **Open global Aspire settings** | Open `~/.aspire/globalsettings.json` | -| **Open Aspire terminal** | Open a terminal with the Aspire CLI ready | -| **Install Aspire CLI (stable)** | Install the latest stable CLI | -| **Install Aspire CLI (daily)** | Install the daily preview build | -| **Update Aspire CLI** | Update the CLI | -| **Verify Aspire CLI installation** | Check that the CLI works | - -## Language and debugger support - -The extension detects each resource's language and attaches the right debugger. Some languages need a companion extension: - -| Language | Debugger | Extension needed | -|----------|----------|------------------| -| C# / .NET | coreclr | [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) or [C#](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp) | -| Python | debugpy | [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) | -| Node.js | js-debug (built-in) | None | -| Browser apps | js-debug (built-in) | None | -| Azure Functions | Varies by language | [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions) + language extension | - -Node.js and browser debugging work out of the box — VS Code includes a built-in JavaScript debugger. C# Dev Kit gives you richer build integration than the standalone C# extension, but either works for debugging. Azure Functions debugging supports C#, JavaScript/TypeScript, and Python. +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. -## Extension settings +All of these commands are debuggable; you can step into custom publishers and deployment steps just like application code. -Configure the extension under **Settings > Aspire**, or jump there with **Aspire: Extension settings**. + -| Setting | Default | Description | -|---------|---------|-------------| -| `aspire.aspireCliExecutablePath` | `""` | Path to the Aspire CLI. Leave empty to use `aspire` from PATH. | -| `aspire.dashboardBrowser` | `openExternalBrowser` | Which browser opens the dashboard — system default, or Chrome/Edge/Firefox as a debug session. | -| `aspire.enableAspireDashboardAutoLaunch` | `true` | Open the dashboard automatically when you start debugging. | -| `aspire.registerMcpServerInWorkspace` | `false` | Register the Aspire MCP server (see [MCP Server Integration](#mcp-server-integration)). | +The `debuggers` property forwards configuration to specific debuggers. Recognized keys are: `apphost`, `project` (C#/.NET), `node`, `python`, `browser`, and `azure-functions`. -There are more settings for verbose logging, startup prompts, and polling intervals — run **Aspire: Extension settings** to see them all. +Finally, you can specify `env` and `args` to set environment variables and command-line arguments for the AppHost process. -The extension also provides IntelliSense and validation when editing `.aspire/settings.json` (workspace-level) and `~/.aspire/globalsettings.json` (user-level). Use the **Open local/global Aspire settings** commands to open them. +```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": ["/**"] }, + "python": { "justMyCode": false } + } +} +``` -## MCP server integration + +For more information, see [Aspire publishing and deployment overview](/deployment/overview/). + -The extension can register an Aspire [MCP](https://modelcontextprotocol.io/) server with VS Code. This lets AI tools — GitHub Copilot included — see your running app's resources, endpoints, and configuration for better context when helping you write code. +## Language coverage -Turn it on by setting `aspire.registerMcpServerInWorkspace` to `true`. When enabled, the extension registers the MCP server definition via the Aspire CLI whenever a workspace is open and the CLI is available. +The extension detects each resource's language and attaches the right debugger: - -For more information, see [Use AI coding agents](/get-started/ai-coding-agents/). - +| 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 diff --git a/src/frontend/src/content/docs/ja/get-started/aspire-vscode-extension.mdx b/src/frontend/src/content/docs/ja/get-started/aspire-vscode-extension.mdx index 38df58a42..71fa54e91 100644 --- a/src/frontend/src/content/docs/ja/get-started/aspire-vscode-extension.mdx +++ b/src/frontend/src/content/docs/ja/get-started/aspire-vscode-extension.mdx @@ -5,229 +5,173 @@ description: Aspire Visual Studio Code 拡張機能を使用して、Aspire ソ import { Steps } from '@astrojs/starlight/components'; import ThemeImage from '@components/ThemeImage.astro'; -import installExtension from '@assets/get-started/install-aspire-code-extension.png'; -import installExtensionLight from '@assets/get-started/install-aspire-code-extension-light.png'; +import LearnMore from '@components/LearnMore.astro'; import createProject from '@assets/get-started/code-extension-create-aspire-project.png'; import createProjectLight from '@assets/get-started/code-extension-create-aspire-project-light.png'; +import sidebarTree from '@assets/get-started/code-extension-sidebar.png'; +import sidebarTreeLight from '@assets/get-started/code-extension-sidebar-light.png'; +import debugSessions from '@assets/get-started/code-extension-debug.png'; +import debugSessionsLight from '@assets/get-started/code-extension-debug-light.png'; import { Kbd } from 'starlight-kbd/components'; -Aspire Visual Studio Code 拡張機能は、Visual Studio Code 内で Aspire を扱う作業を効率化するための一連のコマンドとツールを提供します。この拡張機能には、プロジェクトの作成、統合の追加、ソリューションの構成、デプロイの管理を行うためのコマンドが含まれています。また、この拡張機能は Aspire CLI を必要とし、Visual Studio Code のコマンドパレット上で同様の機能を提供します。 +[Visual Studio Code](https://code.visualstudio.com/) 用の公式 Aspire 拡張機能は、ポリグロットな Aspire アプリの構築、デバッグ、リリースを一流の体験で行える環境へ VS Code を進化させます。 + を押すだけで、AppHost のビルド、リソースの起動、サポート対象リソース (C#、TypeScript、Python、ブラウザー アプリ、Azure Functions) のデバッグを、Aspire ダッシュボードと並行して実行できます。 -## 前提条件 - -Aspire Visual Studio Code 拡張機能を使用するには、次が必要です: - -- [Aspire CLI](/reference/cli/overview/) がインストールされており、PATH に含まれていること - -## Aspire 拡張機能のインストール +:::note[前提条件] +最新の [Visual Studio Code](https://code.visualstudio.com/) と **Aspire CLI** が必要です。CLI は、コマンド パレットから **Aspire: Install Aspire CLI (stable)** コマンドを実行してインストールするか、[インストール ガイド](/ja/get-started/install-cli/) の手順に従ってインストールしてください。 +::: -Aspire VS Code 拡張機能をインストールするには、次の手順を実行します: +## 拡張機能をインストールする 1. VS Code を開きます。 -1. **表示** > **拡張機能** を選択するか、 を押して **拡張機能** ビューを開きます。 -1. 拡張機能マーケットプレースで「aspire」を検索します。 -1. **Microsoft** が公開している **Aspire** 拡張機能を選択します。 -1. **インストール** を選択します。 +1. **拡張機能** ビュー () を開きます。 +1. **Aspire** で検索し、**Microsoft** が発行している拡張機能をインストールするか、[VS Code Marketplace](https://aka.ms/aspire/vscode) から直接インストールします。 - - -または、 [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=microsoft-aspire.aspire-vscode) から拡張機能を直接インストールすることもできます。 - -## 拡張機能コマンドへのアクセス - -Aspire 拡張機能のすべてのコマンドは、VS Code のコマンドパレットから利用できます: +## はじめに -1. を押してコマンドパレットを開きます。 -1. 「Aspire」と入力して、利用可能なすべての Aspire コマンドを絞り込み表示します。 -1. 一覧から目的のコマンドを選択します。 - - - -すべてのコマンドは、見つけやすいようにコマンドパレット内の **Aspire** カテゴリにまとめられています。 - -## 利用可能なコマンド - -Aspire VS Code 拡張機能では、次のコマンドが提供されています: - -| Command | Description | Availability | -|--|--|--| -| Aspire: New Aspire project | テンプレートから新しい Aspire apphost またはスターター アプリを作成します。 | 利用可能 | -| Aspire: Add an integration | Aspire apphost にホスティング統合 (`Aspire.Hosting.*`) を追加します。 | 利用可能 | -| Aspire: Configure launch.json | ワークスペースの `launch.json` に既定の Aspire デバッガー起動構成を追加します。これにより、ワークスペース内の apphost を検出して実行します。 | 利用可能 | -| Aspire: Manage configuration settings | 機能フラグを含む構成設定を管理します。 | 利用可能 | -| Aspire: Open Aspire terminal | Aspire プロジェクトで作業するための Aspire VS Code ターミナルを開きます。 | 利用可能 | -| Aspire: Publish deployment artifacts | Aspire apphost 用のデプロイ成果物を生成します。 | プレビュー | -| Aspire: Deploy app | Aspire apphost の内容を、定義されたデプロイ先にデプロイします。 | プレビュー | -| Aspire: Update integrations | apphost 内のホスティング統合および Aspire SDK を更新します。 | プレビュー | - -## 新しい Aspire アプリを作成する - -拡張機能を使用して新しい Aspire アプリを作成するには、次の手順を実行します: - - - -1. コマンドパレットを開きます。 () -1. **Aspire: New Aspire project** コマンドを実行します。 -1. 使用するテンプレートを選択します。 -1. プロジェクト名と保存場所を指定します。 +1. VS Code で既存の Aspire プロジェクトを開くか、コマンド パレット () から **Aspire: New Aspire project** を実行して新しいプロジェクトを作成します。 +1. **Aspire: Configure launch.json file** を実行し、デバッグ構成をセットアップします。 +1. を押して、Aspire アプリのデバッグを開始します。 -拡張機能によりプロジェクトが作成され、VS Code で開かれます。 +

Aspire: New Aspire project コマンドで、Blazor、React + C#、Express + TypeScript、FastAPI + TypeScript、空の AppHost のスターター テンプレートが表示されている様子。

-## Aspire ソリューションに統合を追加する +拡張機能は `aspire.config.json` を読み取って AppHost を自動検出するため、プロジェクト形式の C# AppHost (`*.csproj`) と TypeScript AppHost (`apphost.ts`) のいずれも、追加の設定なしで利用できます。 -Aspire の統合機能は、さまざまなクラウド サービスや依存関係への事前構成済みの接続を提供します。統合を追加するには、次の手順を実行します: +:::tip[ガイド付きツアーを試したい場合] +**ヘルプ** > **ようこそ** > **Get started with Aspire** を選択すると、CLI のインストール、プロジェクトの作成、実行、ダッシュボードの確認までを網羅した組み込みのウォークスルーが、VS Code を開いたまま起動します。 +::: - +## スキャフォルドと統合の追加 -1. コマンドパレットを開きます。 -1. **Aspire: Add an integration** コマンドを実行します。 -1. 追加したい統合パッケージを参照するか、検索します。 -1. 統合を選択して、AppHost プロジェクトに追加します。 +コマンド パレットには、よく使うタスク向けのコマンドが用意されています: - +- **Aspire: Add an integration** は、AppHost に追加できるホスティング統合 (`Aspire.Hosting.*`) の一覧を表示します。 +- **Aspire: Initialize Aspire in an existing codebase** は、まだ Aspire 化されていないリポジトリに Aspire を組み込みます。 +- **Aspire: Update integrations** は、ホスティング統合と Aspire SDK を更新します。 +- **Aspire: Open Aspire terminal** は、Aspire CLI へ `PATH` が通った状態のターミナルを開き、UI でカバーされない操作を実行できるようにします。 +- **Aspire: Update Aspire CLI** および **Aspire: Install Aspire CLI** で、CLI のインストールを管理できます。 -拡張機能により、適切な NuGet パッケージ参照が AppHost プロジェクトに追加されます。 +## エディターとのライブ連携 -:::note -**Add an integration** コマンドは、AppHost プロジェクトにホスティング統合を追加します。対応するクライアント統合は、利用側のプロジェクトには追加されません。 -::: +AppHost の実行中、拡張機能はライブの状態をエディター上に直接表示します。 -## Aspire ソリューションを構成する +**CodeLens** は、C# および TypeScript の AppHost 内の各リソース定義の上に表示されます。現在の状態と正常性を示し、リソースが公開するカスタム コマンドに加えて、`Start`、`Stop`、`Restart`、`View Logs` といったワンクリックのアクションを提供します。 -Aspire 拡張機能には、開発時における Aspire および Aspire CLI の動作を構成するための複数のコマンドが含まれています: +**エディターのタイトル バー ボタン** により、AppHost ファイルを開いている際は、標準の実行/デバッグ ボタンの隣に **Run Aspire AppHost** および **Debug Aspire AppHost** アクションが追加されます。 -### デバッグ用に launch.json を構成する +**正常性に応じたガター装飾** を使うと、エディターをテキストで埋めることなく、リソースの正常性と状態をひと目で把握できます。次の形と色で表示されます: -VS Code で Aspire アプリケーションを実行およびデバッグするには、 `launch.json` ファイルを構成する必要があります: +| アイコン | 意味 | +|------|---------| +| ✓ (緑のチェック) | 実行中で正常 | +| ⊙ (灰色の円にチェック) | 完了 — 正常終了 (終了コード 0) | +| ⚠ (黄色の三角形に `!`) | 実行中だが異常 (ヘルス チェックに失敗) | +| ✕ (赤の X) | 起動に失敗、終了コードが非 0 で終了、または実行中に異常 | +| ⌛ (青の砂時計) | 起動中、停止中、ビルド中、または待機中 | +| ○ (灰色の中抜き円) | 未開始 | - + -1. コマンドパレットを開きます。 -1. **Aspire: Configure launch.json** コマンドを実行します。 -1. 拡張機能により、既定の Aspire デバッガー構成がワークスペースの `launch.json` ファイルに追加されます。 +## Aspire ビュー - +Aspire は VS Code に AppHost ビューを登録します。**Workspace** モードでは現在のワークスペース内の AppHost が表示され、ビューのヘッダーで **Global** に切り替えると、マシン上で実行中のすべての AppHost を管理できます。 -既定の構成は次のとおりです: +各リソースには、種類、状態、正常性のサマリー、終了コードに加えて、正常性に応じたアイコンと、エンドポイント URL の一覧を含む Markdown のツールチップが表示されます。ヘルス チェックを持つリソースには、展開可能な **Health Checks** グループが表示されます。AppHost 項目で **Expand all** を実行すると、すべてを一度に展開できます。リソースを右クリックすると、開始、停止、再起動、ログの表示、リソース固有のコマンドの実行、ダッシュボードのオープンといった操作を行えます。 -```json title='.vscode/launch.json' -{ - "type": "aspire", - "request": "launch", - "name": "Aspire: Launch Default AppHost", - "program": "${workspaceFolder}" -} -``` +## 実行、デバッグ、デプロイ + +**Aspire: Configure launch.json file** は、任意の言語で記述された AppHost に対応する最小限の起動構成を `.vscode/launch.json` に追加します。AppHost はワークスペース内から自動的に検出されます。 -`program` フィールドは、特定の AppHost プロジェクト ファイルを指すようにカスタマイズできます。たとえば次のようになります: + +特定の AppHost を起動したい場合は、[aspire.config.json](/ja/reference/cli/configuration/) に `appHost.path` プロパティを設定してください。 + -```json title='.vscode/launch.json' + +```json title=".vscode/launch.json — launch" { "type": "aspire", "request": "launch", - "name": "Aspire: Launch MyAppHost", - "program": "${workspaceFolder}/MyAppHost/MyAppHost.csproj" + "name": "Aspire: Launch AppHost", + "program": "${workspaceFolder}" } ``` -### 構成設定の管理 +サポートされている起動コマンドは次の 4 つです: +- `run` は AppHost を実行します (省略した場合の既定)。 +- `deploy` は、AppHost で定義されたデプロイ先にプッシュします。 +- `publish` は、ターゲットへのプッシュを行わずに、Kubernetes マニフェストや Bicep ファイルなどのデプロイ成果物を生成します。 +- `do` は、AppHost のデプロイ パイプラインで定義された特定のステップを実行します。`step` には、実行するステップ名を設定します。 -**Aspire: Manage configuration settings** コマンドは、 `aspire config` の要求オプションを実行し、その結果を VS Code のターミナルに表示します。 `get` および `set` コマンドを使用して Aspire CLI を構成できます。 `list` コマンドを使用すると、現在の構成値を表示できます。 +これらのコマンドはすべてデバッグ可能で、アプリケーション コードと同様に、カスタム パブリッシャーやデプロイ ステップへステップ インできます。 -## 開発モードで Aspire ソリューションを実行する - -Aspire アプリケーションを開発モードで実行するには、次の手順を行います: - - - -1. [デバッグ用に launch.json を構成する](#デバッグ用に-launchjson-を構成する) セクションで説明されているとおり、 `launch.json` が構成されていることを確認します。 -1. **表示** > **実行** を選択するか、 を押して 「実行とデバッグ」 ビューを開きます。 -1. ドロップダウンから Aspire の起動構成を選択します。 -1. 緑色の **Start Debugging** ボタンを選択するか、 を押します。 - - - -拡張機能は AppHost プロジェクトをビルドして起動し、Aspire ダッシュボードをブラウザーで開き、ソリューション内のすべてのリソースに対してデバッグを有効にします。 - -または、 `Aspire: Open Aspire terminal` を使用して Aspire VS Code ターミナルを開き、 `aspire run --start-debug-session` を実行することで、VS Code のデバッグ セッションを開始することもできます。 - -### エディターから実行またはデバッグする - -ワークスペース内で AppHost プロジェクトが検出されると、エディターから直接実行またはデバッグすることもできます。AppHost ファイルを表示している際に、エディターのタイトル バーにある実行ボタンを使用してください。 - -## デプロイ成果物の発行 - -:::caution -この機能は **プレビュー** です。 -::: - -**Aspire: Publish deployment artifacts** コマンドは、Aspire AppHost 用のデプロイ成果物を生成します。このコマンドはリソースをディスクにシリアル化し、デプロイ ツールで利用できるようにします。 - -デプロイ成果物を発行するには、次の手順を実行します: - - - -1. コマンドパレットを開きます。 -1. **Aspire: Publish deployment artifacts** コマンドを実行します。 -1. 生成された成果物の出力先を選択します。 - - - -このコマンドは、登録されている発行コールバック アノテーションを呼び出し、次のような成果物を生成します: - -- Azure リソース用の Bicep ファイル。 -- Docker Compose の YAML ファイル。 -- Kubernetes の Helm チャート。 - -Aspire の発行について詳しくは、[Aspire の発行とデプロイの概要](/ja/deployment/overview/)を参照してください。 - -## Aspire ソリューションをデプロイする - -:::caution -この機能は **プレビュー** です。 -::: - -**Aspire: Deploy app** コマンドは、Aspire AppHost の内容を、定義されているデプロイ先にデプロイします。 - -Aspire ソリューションをデプロイするには、次の手順を実行します: + - +`debuggers` プロパティは、特定のデバッガーへ構成を渡します。利用できるキーは `apphost`、`project` (C#/.NET)、`node`、`python`、`browser`、`azure-functions` です。 -1. コマンドパレットを開きます。 -1. **Aspire: Deploy app** コマンドを実行します。 -1. プロンプトに従って、デプロイ先を選択し、必要な構成を指定します。 +また、AppHost プロセスの環境変数とコマンド ライン引数は、`env` と `args` で指定できます。 - +```json title=".vscode/launch.json — debugger 設定、env、args を伴う deploy" +{ + "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": ["/**"] }, + "python": { "justMyCode": false } + } +} +``` -このコマンドはデプロイ成果物を発行した後、デプロイ コールバック アノテーションを呼び出して、指定されたデプロイ先にリソースをデプロイします。 + +詳しくは、[Aspire の発行とデプロイの概要](/ja/deployment/overview/) を参照してください。 + -Aspire のデプロイについて詳しくは、[Aspire の発行とデプロイの概要](/ja/deployment/overview/) を参照してください。 +## 対応言語 -## Aspire ターミナルを開く +拡張機能は各リソースの言語を検出し、それに応じたデバッガーをアタッチします: -**Aspire: Open Aspire terminal** コマンドは、Aspire プロジェクトでの作業用に構成されたターミナル ウィンドウを開きます。このターミナルでは Aspire CLI コマンドに簡単にアクセスでき、適切な環境変数が事前に設定されています。 +| 言語 | デバッガー | 必要な VS Code 拡張機能 | +|---|---|---| +| Node.js / ブラウザー アプリ | `js-debug` | なし (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) (推奨) または [C#](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp) | +| Azure Functions | 言語ごとに異なる | [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions) と、Function アプリの言語拡張機能 (C#、JavaScript/TypeScript、または Python) | ## フィードバックと問題の報告 -Aspire VS Code 拡張機能に関する問題の報告や機能の要望を行うには、次の手順を実行します: +不具合の報告や機能のリクエストは、[microsoft/aspire](https://github.com/microsoft/aspire/issues) リポジトリで受け付けています: -1. [Aspire GitHub リポジトリ](https://github.com/microsoft/aspire/issues) にアクセスします。 -1. 新しい Issue を作成し、 `area-extension` ラベルを追加します。 +- [バグを報告する](https://github.com/microsoft/aspire/issues/new?template=10_bug_report.yml&labels=area-extension) +- [機能をリクエストする](https://github.com/microsoft/aspire/issues/new?template=20_feature-request.yml&labels=area-extension) diff --git a/src/frontend/src/content/docs/reference/cli/configuration.mdx b/src/frontend/src/content/docs/reference/cli/configuration.mdx index 6e1c1eaee..538515ae2 100644 --- a/src/frontend/src/content/docs/reference/cli/configuration.mdx +++ b/src/frontend/src/content/docs/reference/cli/configuration.mdx @@ -87,22 +87,7 @@ latest release. ### Associate the schema in Visual Studio Code -If you prefer not to commit a `$schema` property, you can associate the schema -with `aspire.config.json` in your user or workspace `settings.json`: - -```json title=".vscode/settings.json" -{ - "json.schemas": [ - { - "fileMatch": ["aspire.config.json"], - "url": "https://aspire.dev/reference/cli/configuration/schema.json" - } - ] -} -``` - -VS Code also honors the `$schema` property automatically, so either approach -enables completions and validation in the built-in JSON language service. +With the [Aspire VS Code extension](/get-started/aspire-vscode-extension/) installed, the schema is registered for `aspire.config.json` automatically. Without the extension, add a `$schema` property to the top of `aspire.config.json` (see above) or map the schema manually in `.vscode/settings.json` under `json.schemas`. ### Other editors