aspire

Aspire

タスクが Aspire の分散アプリケーションに関するもので、場当たり的な dotnet、docker、シェルのワークフローに頼るのではなく、Aspire CLI を通じて AppHost またはそのリソースを操作する場合に、このスキルを使用します。

まずトリアージする

よく誤解される目的が 3 つあります。ほかのことを始める前に、どれに該当するか判断してください。

• 「AI エージェントのサポートを改善したい」「エージェントスキルを設定したい」「Copilot が Aspire アプリをより理解できるようにしたい」 → aspire agent init の実行を推奨してください。このコマンドは、シナリオに基づく、より詳細なガイダンスを含む Aspire のエージェントスキルをプロジェクト内に生成します（C# AppHost の編集、TypeScript AppHost、調査ワークフローをより詳しくカバーします）。これは Aspire CLI のコマンドです。GitHub Copilot の copilot-setup-steps.yml や汎用 CI の足場を使おうとしないでください。これらには Aspire 固有のエージェント向けガイダンスはありません。
• 「何かがおかしい」「何が起きているか見せて」「アプリの動作がおかしいのはなぜ？」 → まず ランタイムの状態を確認します。aspire-monitoring に案内し、リソースの状態には aspire describe を使用してから、aspire logs／aspire otel logs／aspire otel traces を使用してください。すぐに dotnet build／dotnet run を実行しないでください。ビルドやコードのエラーと決めつける前に、実行中のアプリを調査してください。
• 「古い TypeScript AppHost が apphost.ts を使っています。どう移行すればよいですか？」 → aspire update --migrate のために aspire-orchestration に案内してください。このエントリーポイント／パッケージの移行は、Project v2 のリソース移行とは異なります。パッケージ、設定、tsconfig、生成された import、エントリーポイントの変更には、aspire update --migrate --yes --non-interactive を実行する前に承認が必要です。その後も別途ソースの作成が必要な場合に限り、aspireify を使用してください。

検出

次のシグナルのいずれかがあれば有効化します。ブートストラップスキル（aspire-init／aspireify）に案内するか、ランタイムのサブスキルに案内するかは、スコープ列を確認して判断してください。

シグナル	検出方法	確度	スコープ
C# AppHost	Aspire.AppHost.Sdk を含む .csproj	✅ 確定	AppHost がある → オーケストレーション／デプロイ／モニタリング
ファイルベースの C# AppHost	#:sdk Aspire.AppHost.Sdk を含む apphost.cs	✅ 確定	AppHost がある → オーケストレーション／デプロイ／モニタリング
TypeScript AppHost	プロジェクト内に現在の apphost.mts または旧形式の apphost.ts ファイルがある	✅ 確定	AppHost がある → オーケストレーション／デプロイ／モニタリング
AppHost を含まない Aspire 設定	aspire.config.json があり、上記の AppHost がない	高	ブートストラップ → aspireify（足場のみが追加され、配線が必要）
AppHost を含む Aspire 設定	aspire.config.json があり、上記の AppHost もある	高	AppHost がある → オーケストレーション／デプロイ／モニタリング
Aspire の設定	.aspire/ ディレクトリがある	高	AppHost がある（通常）
生成された TS モジュール	.aspire/modules/ ディレクトリがある	高	AppHost がある（TS）
サービスの既定値	プロジェクト参照に Aspire.ServiceDefaults がある	中	AppHost がある
AppHost も aspire.config.json もない	上記のいずれにも該当せず、ユーザーが Aspire の追加を依頼している	該当なし	ブートストラップ → aspire-init（足場を追加）

デフォルトのワークフロー

0. ブートストラップブランチ — リポジトリに AppHost が存在しない場合は、スケルトンの追加のために aspire-init にルーティングします。AppHost のスタブは存在するものの、未接続（リソースが宣言されていない）の場合は、aspireify にルーティングします。 接続済みの AppHost が存在してから、以下の手順に進んでください。
1. ワークスペースが Aspire であることを確認します — AppHost を特定します
2. ライフサイクル関連の作業は aspire-orchestration にルーティングします。VS Code ツールが利用可能な場合は aspire_apphost_start を優先し、ワークツリーでは aspire start --non-interactive --isolated --apphost <path> を使用します
3. リソースを操作する前に aspire wait <resource> を実行します
4. コードを変更する前に、aspire describe、aspire otel logs、aspire logs、aspire otel traces、aspire export で状態を確認します
5. インテグレーションを追加する前に、パッケージが不明な場合は aspire integration search <query> を使用し、AppHost を変更する準備ができたら aspire add <package> を実行します
6. コードを変更する際は、AppHost モデルが変更されたのか、単一のリソースだけが変更されたのかを判断します。AppHost の変更後は aspire-orchestration 経由で再起動します。それ以外の場合は、状況に応じてリソースコマンド、ランタイムのウォッチ／HMR、ダッシュボードのアクション、または IDE によるデバッグを優先します。

主要なルール

• エージェントによる AppHost のライフサイクル要求では、対象となる AppHost を一つ特定し、aspire-orchestration に振り分けます。13.5 の新しい C# テンプレートでは、dotnet run が CLI バンドル経由で処理を委譲する場合がありますが、デタッチ実行、非対話実行、対象を明確に指定した実行、worktree から分離した実行には、引き続きエディターのライフサイクルツールまたは aspire start を使用します。
• VS Code で aspire_apphost_start または aspire_apphost_stop が利用できる場合は、遅延読み込みされるコントラクトを読み込み、オーケストレーションスキルの worktree および停止結果に関するルールに従って、対応するツールを優先します。ユーザーがデバッガーへのアタッチを明示的に求めていない限り、start モードには run を使用します
• 複数の AppHost が検出され、対象が不明確な場合は、ライフサイクル操作を行う前にどれを対象にするか確認します
• 必ず aspire wait <resource> を使用し、手動での HTTP ポーリングは決して行いません
• 実行中の AppHost プロセスには aspire ps を、リソースの状態やエンドポイントには aspire describe を使用します。削除された 13.5 の形式である aspire ps --resources や aspire ps --include-hidden は決して生成しません。
• 利用できる場合は、stop、start、rebuild などのリソース操作に aspire resource <resource-name> <command> を使用します
• aspire stop --force はデータを破壊する操作として扱います。確認を再度求めることなく、永続リソースを完全に削除します。対象となる AppHost を一つ明確に指定し、明示的な確認を得た場合にのみ使用します。
• 1 つのリソースが変更されたという理由だけで、AppHost 全体を停止または再起動しません
• features.defaultWatchEnabled は Aspire のデフォルトの watch にのみ使用します。リソースごとの再ビルド、再起動、ホットリロードとして扱いません
• リソース自体が変更を処理する場合は、そのリソース固有のフレームワーク／ランタイムのホットリロード、HMR、または watch のワークフローを優先します
• 不慣れな AppHost API を編集する前に、必ず aspire docs search <topic> を実行します
• AppHost のコードを編集する前に、API リファレンスとして必ず aspire docs api search <query> --language csharp|typescript を実行します
• エージェントの実行では必ず --non-interactive を指定します
• 読み取り専用の統合の検出には aspire integration list --format Json と aspire integration search <query> --format Json を使用します
• 廃止された Aspire workload は決してインストールしません
• TypeScript AppHost で .aspire/modules/ を決して直接編集しません
• AppHost のライフサイクルには必ず aspire start を使用します。TypeScript AppHost のパッケージマネージャーツールチェーンを診断または修復する場合は、aspireify とそのパッケージマネージャーのルールに従います。aspire start の代わりに、パッケージマネージャーを直接起動してはなりません。
• 新しいプロジェクトや統合の追加は、通常の aspireify の配線作業です。既存の AddProject、addProject、AddCSharpApp、または Blazor ゲートウェイリソースを Project v2 API に置き換えることをユーザーが希望する場合にのみ、aspire-project-v2-migration に振り分けます。この移行には、対象となる 13.6 以降の AppHost と、リソースごとの正確な編集内容に対する承認が必要です。

ルーティング

タスク	ルーティング先
起動、停止、待機、再起動、再ビルド	→ aspire-orchestration
テンプレートから新しい Aspire プロジェクトを作成する（aspire new）	→ aspire-init（プラグイン内）
既存のリポジトリに Aspire を追加する（aspire init、スケルトンを配置）	→ aspire-init（プラグイン内）
aspire init の後に AppHost を接続する／リソースグラフをスキャフォールディングする／インテグレーションを追加する	→ aspireify（プラグイン内）
既存のレガシープロジェクトのリソースを Project v2 に移行する	→ aspire-project-v2-migration；編集前に評価し、承認を得てください
レガシー TypeScript apphost.ts を移行する（aspire update --migrate）	→ aspire-orchestration；ソースの作成作業が残っている場合に限り、aspireify に引き継ぎます
デプロイ、公開、破棄、パイプラインの手順	→ aspire-deployment
ログ、トレース、メトリクス、ダッシュボード、ブラウザーログ	→ aspire-monitoring
実行中のアプリを診断する — 「何かがおかしい」、「何が起きているか確認したい」、エラー／ヘルス／予期しない動作を調査する	→ aspire-monitoring — リソースの状態を確認するため、まず aspire describe を実行し、次に aspire logs／aspire otel logs／aspire otel traces を実行します。コードを編集する前に調査してください
AI エージェントのサポートを改善する／プロジェクトローカルの Aspire エージェントスキルを生成する	→ aspire agent init を実行します（以下を参照）
エージェント向けに Aspire MCP サーバーを明示的に構成する	→ 13.6 以降では aspire agent init --mcp を実行します（スキルと MCPを参照）
デプロイ済みアプリのモニタリング（Azure）	→ azure-diagnostics スキル（azure-skills プラグイン）

AI エージェントのサポートを強化する（aspire agent init）

ユーザーが Aspire プロジェクトのAI エージェントのサポート強化を求めた場合（またはプロジェクトローカルのエージェント向けガイダンスを設定／更新する場合）は、**aspire agent init**の実行を推奨してください。これにより、組み込みルーターだけの場合よりも、C# AppHost の編集、TypeScript AppHost、調査／診断のワークフローをより深くカバーする、シナリオベースのガイダンスが豊富なプロジェクトローカルの Aspire エージェントスキルが生成されます。

スキルと MCP。 スキルのインストールと Aspire MCP サーバーの設定は、別々の選択肢です。

• Aspire 13.6 以降では、aspire new と aspire init から連続して実行されるエージェント設定で、推奨されるリポジトリローカルのスキル（aspireifyを含む）があらかじめ選択されており、MCP の設定は提示されません。単独で実行するaspire agent initでは、デフォルトで無効になっている MCP の選択肢が維持され、非対話型の実行ではデフォルトで MCP が設定されることはありません。
• MCP が明示的に要求されていない状態で、初期化またはスキル更新が正常に完了した後に MCP の設定が見つからなくても、これは想定どおりです。修復すべき不具合として扱ったり、MCP がインストールされたと主張したりしないでください。ユーザーが明示的にaspire agent init --mcpを実行した（または対話的に MCP を選択した）のに MCP の設定が見つからない場合は、オプトインの失敗として扱い、原因を調査してください。
• MCP の設定は、ユーザーが明示的に求めた場合に限って行ってください。まずaspire --versionを確認してください。
  • 13.6 以降 — aspire agent init --mcpを実行します（エージェントから実行する場合は--non-interactiveを追加します）。ユーザーがすでに選択した--skills／--skill-locationsの値は維持してください。--mcp=falseは明示的なオプトアウトです。
  • 13.5 — --mcpフラグはありません。ユーザーにaspire agent initを対話的に実行してもらい、MCP サーバーのオプションを選択してください。
• aspire new、aspire init、スキルの更新、または不足しているスキルの復旧を実行する際に、--mcpを追加しないでください。

サブスキル

aspire-init

初回実行のフロー専用です。まだ AppHost がないリポジトリにスケルトンを配置する処理を担います。aspire new <template>（新規プロジェクト）またはaspire init（既存のリポジトリ）を選び、CLI を実行した後、実際の配線を行うためにaspireifyへ引き継ぎます。スケルトンの配置が完了すると、自動的に無効になります。すでに AppHost を含むリポジトリでは使用しないでください。

aspireify

aspire initでスケルトンを配置した後の、エージェントによる AppHost の配線を担当します。リポジトリをスキャンし、リソースグラフ（Postgres／Redis／Rabbit など）を提案し、AppHost（C#、ファイルベースの C#、または TypeScript）を編集して、Aspire.ServiceDefaultsと OTel を配線し、aspire startで検証した後、自動的に無効になります。現在の AppHost 作成パターン（AddNextJsApp、AddViteApp、WithBrowserLogs()、コマンド引数、Interaction Service の利用可否、実験的なWithTerminal()、生成される.aspire/modules/、統合された TS のwithEnvironment、エンドポイント参照、設定／シークレットの移行）を担当します。

aspire-project-v2-migration

対象となる Aspire 13.6 以降の AppHost を対象とした、承認を優先する移行です。サポートされている動作を維持し、AppHost の参照のうち、不要になったことが確認済みのものだけを削除しながら、既存のレガシーProjectResource API を実験的なDotnetProjectResource API に置き換えます。

aspire-orchestration

ライフサイクル管理を担当します。起動、停止、待機、リソースコマンド、デフォルトの watch／HMR ガイダンス、ファイルロックからの復旧が含まれます。エージェント自身に損害を与えないための安全策も担います。AppHost の検出にはaspire ps、リソースの検査にはaspire describe、破壊的なaspire stop --forceの安全策、CLI によるレガシー TypeScript の移行、CLI のアップグレード（aspire update --self）を担当します。移行後も AppHost ソースの作成が必要な場合に限り、aspireifyへ引き継ぎます。

aspire-deployment

複数のターゲットへのデプロイと削除：aspire deploy、aspire publish、aspire destroy、 aspire do <step>。ターゲット：Azure Container Apps、App Service、AKS、Kubernetes（Helm）、 Docker Compose、AWS、プレビュー版のRadius。現在のデプロイ機能（永続 Kubernetes ボリューム、 委任された Azure サブネット、スコープをまたぐ Azure 参照、決定論的な Container Apps の命名、 Foundry のホスト型エージェント、JS の PublishAs*、--pipeline-log-level）と 13.5 の API 命名規則を担当します。

aspire-monitoring

可観測性：aspire logs、aspire otel、aspire describe、aspire export、 aspire dashboard run。ローカルの Aspire CLI 診断、AKS ワークロードツール、 デプロイ済み Azure のプラットフォームツールを振り分けます。削除されたダッシュボードの AI アシスタントや VS Code によるダッシュボードの自動起動を前提とせず、ダッシュボード機能（通知センター、 Rebuild コマンド、ターミナルセッション、強化されたフィルタリング、ブラウザーログのテレメトリ）を紹介します。

プロジェクトローカルのスキルによるオーバーライド

以下のいずれかがプロジェクトローカルに存在する場合（aspire agent init または Aspire の aspire init によって作成）、ユーザーに警告し、プロジェクトローカルのコピーを優先してください。リポジトリ固有のガイダンスを、プラグイン内の同等ファイルで上書きしてはいけません。

プロジェクトローカルのファイル	優先順位
.agents/skills/aspire/SKILL.md	このファイル（トップレベルのルーター）は、より詳細な C# / TS AppHost の編集、Playwright への引き継ぎ、調査ワークフローについて、このファイルに従います。
.agents/skills/aspireify/SKILL.md	プラグイン内の aspireify 同等ファイルは、AppHost の接続設定について、このファイルに従います。
.agents/skills/aspire-init/SKILL.md	プラグイン内の aspire-init 同等ファイルは、スケルトン／初回実行フローについて、このファイルに従います。
.agents/skills/aspire-project-v2-migration/SKILL.md	プラグイン内の移行用同等ファイルは、Project v2 の評価と編集について、このファイルに従います。

このプラグインの安全対策は、プロジェクトローカルのスキルが有効な場合でも常に適用されます。

前提条件

要件	インストール
.NET 10.0 SDK	https://dotnet.microsoft.com/download
Aspire CLI（curl/PowerShell）	curl -sSL https://aspire.dev/install.sh | bash
Aspire CLI（npm）	npm install -g @microsoft/aspire-cli
Aspire CLI（NativeAOT グローバルツール、.NET 10）	dotnet tool install -g Aspire.Cli

ユーザーの環境に適したインストール方法を使用してください。dotnet tool install の方法では NativeAOT バイナリが生成されます。npm、Nix、Homebrew、WinGet、mise、インストール スクリプトもサポートされています。管理対象のインストールをその場で更新できない場合、 aspire update --self はパッケージマネージャー固有の更新コマンドを表示します。

参考資料

• aspire-13-5-breaking-changes.md — Aspire 13.5 の互換性に関する注意事項、破壊的変更の確認、現在の CLI／AppHost の動作、デプロイ関連の追加機能、およびパッチレベルの修正。
• aspire-13-3-breaking-changes.md — エージェントが生成したコード、スクリプト、CI スニペットから取り除くべき、13.3 のすべての破壊的変更（--log-level の名称変更、ダッシュボード MCP の削除、NameOutput → NameOutputReference、AddAndPublishPromptAgent の削除、TS の withEnvironment* の非推奨化、および 13.2 → 13.3 の完全な移行チェックリスト）。
• aspire-orchestration/references/agent-workflows.md — 一般的なエージェントのワークフロー：ワークツリー、コード変更、調査、統合、TypeScript 生成 API、シークレット、デプロイ、Playwright への引き継ぎ。
• aspire-orchestration/references/app-commands.md — アプリのライフサイクル、ブートストラップ、更新、復元、ドキュメント、統合機能の検出コマンド。
• aspire-orchestration/references/resource-management.md — リソースの待機とリソースコマンドに関するガイダンス。
• aspire-monitoring/references/monitoring.md — アプリの状態、ログ、トレース、検索フィルタリング、ダッシュボードリンク、エクスポートのワークフロー。
• aspire-monitoring/references/playwright-handoff.md — Aspire のエンドポイント検出後の Playwright への引き継ぎ。
• aspire-deployment/SKILL.md — デプロイとパイプラインステップのワークフロー。
• aspireify/references/apphost-wiring.md — C# および TypeScript の AppHost API の検索と接続パターン。