aspire-orchestration について
aspire-orchestration は、Aspire プロジェクト向けのエージェントスキルです。AppHost とリソースの起動、停止、待機、確認を案内し、ファイルロック、対象選択、破壊的操作に対する安全規則を設けています。
主な機能
- 01AppHost の起動と停止の管理
- 02リソースの待機と状態確認
- 03リソース単位の操作案内
- 04危険な停止操作の防止
- 05複数 AppHost の対象選択
活用シーン
- 01指定した AppHost の起動や停止
- 02操作前のリソース準備待ち
- 03実行中の AppHost とリソースの確認
- 04ワークツリーでのアプリの分離起動
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/aspire-orchestrationを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
evals/eval.yamlreferences/agent-workflows.mdapp-commands.mddetection.mdresource-management.mdsafety-guardrails.md詳細
Aspire のオーケストレーション
必須の遵守事項 — このスキルは、Aspire プロジェクトでエージェントが自らを損なうのを防ぎます。 これらのルールに違反すると、ファイルロック、孤立プロセス、ユーザーの不満につながります（#15801）。
前提条件
| 要件 | インストール |
|---|---|
| .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 |
ユーザーの環境で管理されているインストール方法を使用してください。npm、Nix、Homebrew、WinGet、 mise、インストールスクリプトに加えて、NativeAOT .NET グローバルツールもサポートされています。
検出
次のいずれかのシグナルがある場合に有効化します。
| シグナル | 検出方法 | 信頼度 |
|---|---|---|
| C# AppHost | Aspire.AppHost.Sdk を含む .csproj | ✅ 確定 |
| ファイルベースの C# AppHost | プロジェクト内の apphost.cs、または #:sdk Aspire.AppHost.Sdk を含む .cs ファイル | ✅ 確定 |
| TypeScript AppHost | プロジェクト内に現在の apphost.mts または旧形式の apphost.ts ファイルがある | ✅ 確定 |
| Aspire の設定 | プロジェクトルートに aspire.config.json がある | 高 |
| Aspire の設定 | .aspire/ ディレクトリがある | 高 |
| 生成された TS モジュール | .aspire/modules/ ディレクトリがある | 高 |
| サービスの既定値 | プロジェクト参照に Aspire.ServiceDefaults がある | 中 |
詳しいフィンガープリントの方法については、detection.md を参照してください。
VS Code の AppHost ライフサイクル
エージェントホストが aspire_apphost_start または aspire_apphost_stop を提供している場合は、git worktree からの起動に --isolated が必要で、ツールから指定できない場合を除き、ターミナルで aspire start または aspire stop を実行する前に、対応するツールを使用してください。ツールが遅延読み込みとして一覧表示されている場合は、ホストのツール検出機構を使って、まずそのコントラクトを読み込んでください。未読み込みの遅延ツールを使用不可とみなしてはいけません。
エディターのライフサイクルツールには、Aspire が検出した正確な appHostPath を渡してください。複数ルートのワークスペースでは、ツールのコントラクトで repo-a~1/MyApp.AppHost/MyApp.AppHost.csproj のようなセレクターが必要になる場合があります。
CLI の --apphost フラグは、そのセレクターネームスペースを理解しません。CLI で起動／停止をフォールバックする前に、選択した AppHost を実際のファイルシステム上のプロジェクトパスに解決し、そのパスを --apphost に渡してください。複数ルートのセレクターをそのままコピーしてはいけません。CLI のプロジェクトパスは、ワークスペース相対（MyApp.AppHost/MyApp.AppHost.csproj）または絶対パス（/workspaces/repo-a/MyApp.AppHost/MyApp.AppHost.csproj または
C:\workspaces\repo-a\MyApp.AppHost\MyApp.AppHost.csproj）を指定できます。現在のプラットフォームのネイティブなパス構文を使用してください。複数の AppHost が検出され、ユーザーが対象を明確にしていない場合は、推測したり、すべての AppHost に対してツールを呼び出したり、対象を指定しない CLI コマンドを実行したりせず、どれを使用するか尋ねてください。
選択した appHostPath が MyApp.AppHost/MyApp.AppHost.csproj のような通常のワークスペース相対プロジェクトパスである場合は、CLI でのフォールバックにもそのまま使用してください。CLI のためだけに絶対パスに変換してはいけません。
対象が明確でない場合は必ず停止してください。 確認の質問を 1 つだけして、ユーザーが AppHost を指定するまで待ってください。対象が確定するまではライフサイクルツールもターミナルコマンドも呼び出してはいけません。また、この確認を回避するコマンドを提示してはいけません。複数の AppHost を停止するのは、ユーザーがすべて停止するよう明示的に求めた場合に限ります。
起動する場合、ユーザーがデバッガーへのアタッチを明示的に求めていない限り、選択した正確な appHostPath を指定して、モード run で aspire_apphost_start を呼び出してください。git worktree では、エディターツールから Aspire の分離状態を現在指定できません。選択した AppHost をファイルシステム上のパスに解決し、代わりに
aspire start --non-interactive --isolated --apphost <filesystem-path> を使用してください。
run モードではデバッガーはアタッチされませんが、エディターが管理する Aspire セッションは存在するため、aspire_apphost_stop で停止できます。停止呼び出しの後は、次の結果マトリクスに厳密に従ってください。
| ツールの結果 | 次のアクション | CLI による停止は許可されますか？ |
|---|---|---|
stopped または notRunning | 結果を報告し、それ以上の停止操作は行いません | いいえ |
alreadyStopping、コントローラーが editor | エディターでの停止がすでに進行中であることを報告し、それ以上の停止操作は行いません | いいえ |
alreadyStarting、コントローラーが editor | aspire_apphost_stop を一度再試行します。同じ結果が返された場合は、起動がまだ進行中であることを報告し、それ以上の停止操作は行いません | いいえ |
notEditorOwned、コントローラーが external | ユーザーがその正確な AppHost の停止を依頼した場合は、ファイルシステム上のパスを特定し、aspire stop --non-interactive --apphost <filesystem-path> を実行します | はい |
failed、コントローラーが unknown | aspire_apphost_stop を一度再試行します。同じ結果が繰り返された場合は、上記と同じ対象を指定する CLI コマンドを使用します | 再試行後のみ |
ambiguousSession | 何も停止せず、エディターでユーザーに対象を明確にしてもらいます | 絶対に不可 |
| その他の拒否または失敗 | その結果を解決するか報告し、手段を変更しません | いいえ |
各行の条件は相互に排他的です。現在の結果に対してのみ対応し、別の行にあるコマンドを、将来の回避策として推測で提示しないでください。新しいツールの結果が返された場合にのみ、再評価してください。
ambiguousSession は、安全上の最終的な拒否です。 CLI によるフォールバックを実行したり、提案したりせず、ユーザーにそれを望むかどうか尋ねないでください。ユーザーが確認しても、曖昧なエディターセッションを CLI から終了して安全にできるわけではありません。
対応するエディターツールが利用できない場合、隔離されたワークツリーを起動する場合、または上記で明示的に許可された停止結果の場合にのみ、Aspire CLI のライフサイクルコマンドを直接使用してください。CLI によるフォールバックが許可されている場合は、まず選択した AppHost をファイルシステム上のパスに解決し、対象を正確に指定してください。
安全対策
| 状況 | ✅ 必ず行うこと | ❌ 絶対に行わないこと |
|---|---|---|
| Aspire アプリを起動する | 利用可能な場合は、正確な選択済み appHostPath を指定し、モードを run にして aspire_apphost_start を使用します。git ワークツリー内では、aspire_apphost_start が利用可能でも aspire start --non-interactive --isolated --apphost <filesystem-path> を使用します | AppHost に対して dotnet run を実行する |
| リソースの準備完了を待つ | aspire wait <resource> | curl や HTTP ポーリングループを使用する |
| リソースのコードが変更された | リソースコマンド、ランタイムのウォッチ／HMR、ダッシュボードのアクション、または IDE 管理のデバッグを優先します | ロックされたファイルに対して dotnet build を実行する |
| タスクが完了した | 利用可能な場合は、正確な選択済み appHostPath を指定して aspire_apphost_stop を使用し、その結果の判定表に従います | 許可されていない CLI フォールバックを使用する |
| 実行中の AppHost を確認する | aspire ps | プロセスを手動で調べる |
| リソースの状態を確認する | aspire describe | aspire ps --resources を使用する（13.5 で削除） |
| 永続リソースを削除する | aspire stop --force --apphost <filesystem-path> の前に、データの損失と正確な AppHost を確認します | --force と --all を併用する、または通常の停止に使用する |
| git ワークツリー内で作業する | aspire start --non-interactive --isolated --apphost <filesystem-path> | 分離を要求できない場合に aspire_apphost_start を使用する |
| AI エージェントから実行する | まず利用可能なライフサイクルツールを読み込み、CLI の --apphost フォールバックを <filesystem-path> に解決し、--non-interactive を追加します | 対話型ターミナルがあると想定する |
| 不慣れな API を編集する | aspire docs search <topic> の後、API リファレンスには aspire docs api search <query> を使用します | API の形式を推測する |
| C# AppHost API を調べる | ローカルシンボルの確認には（利用可能な場合）dotnet-inspect スキルを使用します | オーバーロードやビルダーチェーンを推測する |
| カスタムのダッシュボード／リソースコマンドを追加する | まず aspire docs search "custom resource commands" を実行します | ドキュメントを確認せずに WithCommand のパターンを作り出す |
| Aspire のサポートをインストールする | aspire add または aspire init を使用します | dotnet workload install aspire |
詳細なルールと復旧パターンについては、safety-guardrails.md を参照してください。
デフォルトのワークフロー
- ワークスペースが Aspire であることを確認します — AppHost を特定します
- ワークスペースが git worktree の場合は、選択された AppHost をファイルシステム上のプロジェクトパスに解決し、
aspire_apphost_startが利用可能な場合でもaspire start --non-interactive --isolated --apphost <filesystem-path>を使用します。エディターツールでは分離実行を要求できないためです。それ以外の場合は、利用可能であれば正確に選択されたappHostPathを指定し、モードrunでaspire_apphost_startを使用して起動します。このツールが利用できない場合は、選択された AppHost をファイルシステム上のプロジェクトパスに解決し、aspire start --non-interactive --apphost <filesystem-path>を使用します - リソースを操作する前に、
aspire wait <resource>を実行します aspire describeで状態を確認してから作業します- AppHost のコードを変更した場合は、同じライフサイクルの手順で再起動します。1 つのリソースのみを変更した場合は、そのリソースのコマンド／監視／HMR／デバッグのワークフローを優先します
- 利用可能であれば、正確に選択された
appHostPathを指定してaspire_apphost_stopで停止します。aspire stop --non-interactive --apphost <filesystem-path>を使用するのは、ドキュメントに記載されたフォールバックの結果の場合のみです
クイックリファレンス
| タスク | コマンド |
|---|---|
| アプリの起動（エージェント） | Git worktree の場合：aspire_apphost_start が利用可能でも aspire start --non-interactive --isolated --apphost <filesystem-path>。ツールでは分離実行を要求できないためです。それ以外の場合：aspire_apphost_start（モード run、正確に選択された appHostPath）。CLI のフォールバック：ツールが利用できない場合は aspire start --non-interactive --apphost <filesystem-path> |
| アプリの起動（人間） | aspire run（フォアグラウンド、ダッシュボード） |
| アプリの停止 | aspire_apphost_stop（正確に選択された appHostPath）。結果マトリックスのフォールバック：aspire stop --non-interactive --apphost <filesystem-path> |
| リソースの待機 | aspire wait <resource> |
| 実行中の AppHost の一覧表示 | aspire ps |
| リソースの状態確認 | aspire describe |
| 非表示のリソース（プロキシ、ヘルパー、マイグレーション）の表示 | aspire describe --include-hidden |
| リソースの操作 | aspire resource <resource-name> <command>（公開されている場合は stop、start、rebuild など） |
| リソースのコマンドの確認 | aspire resource <resource-name> --help |
| 実験的なリソースのターミナルへの接続 | features.terminalCommandsEnabled を有効にしてから、aspire terminal ps ／ aspire terminal attach を使用します |
| 新しいプロジェクトの作成 | aspire new aspire-starter |
| 既存のプロジェクトへの Aspire の追加 | aspire init（その後、構成の追加を aspireify スキルに引き継ぎます） |
| インテグレーションの追加 | aspire add <package> |
| インテグレーションの確認 | aspire integration list --format Json ／ aspire integration search <query> --format Json |
| CLI 自体のアップグレード | aspire update --self（管理対象のインストールでは、npm／.NET／Nix の更新コマンドが表示される場合があります） |
| プロジェクトのパッケージ参照の更新 | 承認後に aspire update --yes --non-interactive |
| 従来の TypeScript エントリポイントの移行 | パッケージ参照、構成、tsconfig、インポート、エントリポイントがすべて変更されることを説明します。パッケージの更新と移行について承認を得た後、aspire update --migrate --yes --non-interactive を実行します |
| 生成ファイルの復元 | aspire restore |
| 環境のメンテナンス | aspire cache clear、aspire certs trust、aspire certs clean |
| 環境の診断 | aspire doctor |
| 機械可読な出力 | --format Json（対応対象：ps、describe、start） |
| API リファレンスの検索 | aspire docs api search <query> --language csharp|typescript |
| API エントリの一覧表示 | aspire docs api list <scope> |
| API の詳細取得 | aspire docs api get <id> |
エラー処理
| 症状 | 原因 | 対処 |
|---|---|---|
ビルド中のファイルロックエラー（MSB3491、CS2012） | Aspire が実行中で、bin/、obj/、アセンブリをロックしています。 | 上記のライフサイクル経路を通じて AppHost を停止してから、再ビルドするか再起動してください。プロジェクトで恒久的なビルド障害が発生していると判断してはいけません。 |
| 「ポートはすでに使用されています」 | 前のインスタンスが実行中 | 停止してから、上記のライフサイクル経路を通じて再起動します |
| リソースが見つからない | アプリが起動していない、または名前が間違っている | aspire ps で AppHost を探し、aspire describe でリソースを確認します |
| リソースのビルドエラー | Aspire の問題ではなく、コードのエラー | コードを修正してから、リソースコマンド／watch／HMR／デバッグのワークフローを使用するか、AppHost のコードを変更した場合はライフサイクル経路を通じて再起動します |
| 環境の問題 | SDK またはツールが不足している | aspire doctor で診断します |
aspire start による JSON 解析の失敗 | 人間向け出力と JSON 出力が混在している（#15843） | 解析前に JSON 以外の行を除外します |
aspire ps がハングする | AppHost がブレークポイントで停止している（#15576） | タイムアウトを使用し、AppHost プロセスを確認します |
aspire agent init が失敗する | 非対話型のターミナル（#16264） | 標準のターミナルから実行します |
| Docker デーモンを利用できない | コンテナーを使用するリソースの起動に失敗する | Docker Desktop を起動してから、上記のライフサイクル経路を通じて再起動します |
| 複数の AppHost が検出された | 対象の AppHost が間違っている | --apphost <filesystem-path> を使用して明示的に指定します |
🔒 ファイルロックからの復旧（MSB3491 / CS2012）— 必ず最初に AppHost を停止する
ビルドが error MSB3491: Could not write to output file ... または
error CS2012: Cannot open ... for writing で失敗した場合、プロジェクト自体は正常です —
Aspire が実行中で、リソースの出力アセンブリをロックしています。
復旧方法は常に同じです。
正確な AppHost を特定し、利用可能な場合は最初に aspire_apphost_stop を呼び出します。CLI による
代替手段が許可されている場合は、以下のコマンドを使用する前に、選択した AppHost を
ファイルシステム上のパスに解決してください。ambiguousSession およびその他すべての代替手段がない場合は、
復旧を中止します。
# ✅ CLI stop only after the result matrix permits fallback
aspire stop --non-interactive --apphost <filesystem-path> # release the locks
# ... then either rebuild / restart one resource if the resource exposes commands ...
aspire resource <name> rebuild # example: C# project resource with rebuild command
# ... or restart the whole AppHost through aspire_apphost_start. If unavailable:
aspire start --non-interactive --apphost <filesystem-path>
# In a git worktree:
aspire start --non-interactive --isolated --apphost <filesystem-path>
| ❌ 絶対にしない | ✅ 必ず行う |
|---|---|
| プロジェクトで恒久的なビルド障害が発生しているとユーザーに伝える | ロックは Aspire が出力を保持しているためだと認識し、ライフサイクル経路を通じて AppHost を停止する |
ロックされたまま再度 dotnet build を実行する | 先に AppHost を停止してから dotnet build を実行する（またはリソースコマンド／watch／HMR／デバッグのワークフローを優先する） |
ロックを「修正」するために bin/ / obj/ を削除する | AppHost を停止する。削除できても、次のビルドで再びロックされる |
ロックを解除するために pkill dotnet または kill <PID> を実行する | エディターの停止ツール、または対象を正確に指定した CLI の代替手段で正常にシャットダウンする |
| ユーザーに「再起動」または「マシンを再起動」するよう伝える | ライフサイクル経路を通じて AppHost を停止する |
同じルールは、Aspire が管理するリソースのビルド中に発生する「ファイルは使用中です」、「ファイルにアクセスできません」、 または「別のプロセスが使用中です」というエラーにも適用されます。
引き継ぎルール
| シナリオ | 引き継ぎ先 |
|---|---|
aspire init 実行後の AppHost の配線（リポジトリをスキャンし、リソースを追加し、ServiceDefaults／OTel を設定） | → aspireify スキル（aspireify/SKILL.md）またはプロジェクトローカルの .agents/skills/aspireify/SKILL.md |
ブラウザーログ（Aspire.Hosting.Browsers／WithBrowserLogs()）とダッシュボードの作成 | → aspireify スキル（コードの編集）と aspire-monitoring（調査） |
カスタムリソースコマンド、引数、インタラクション、またはターミナル（WithCommand、CommandOptions.Arguments、IInteractionService、WithTerminal） | → aspireify スキル |
ライフサイクルフック（SubscribeBeforeStart、SubscribeAfterResourcesCreated、BeforeStart パイプラインフェーズ） | → aspireify スキル |
エンドポイントの作成（WithEndpoint の更新、ExcludeReferenceEndpoint フラグ） | → aspireify スキル |
デプロイ、発行、パイプラインのステップ、aspire destroy | → aspire-deployment スキル |
ログ、トレース、メトリクス、ダッシュボード、aspire dashboard run | → aspire-monitoring スキル |
| デプロイ済みアプリの診断 | → azure-diagnostics スキル（azure-skills） |
ランタイム設定と環境
| 変数 | 既定値 | 用途 |
|---|---|---|
ASPIRE_ENABLE_CONTAINER_TUNNEL | true | コンテナー トンネルにより、Docker Desktop、Docker Engine、Podman 間で一貫したホスト接続が提供されます。無効にするには false を設定します。 |
ASPIRE_ENVIRONMENT | 未設定 | 環境固有の構成プロファイルを選択します。読み込む appsettings.{environment}.json と、ダッシュボードのテレメトリで報告される環境を制御します。 |
ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE | true | Windows では、DCP が Aspire の信頼された開発者証明書を使用します。無効にするには false を設定します。 |
features.defaultWatchEnabled | 構成されていない場合は false | 対応する C# および TypeScript の AppHost で Aspire の既定の監視を有効にします。リソースのソース変更に対するリソースごとの再ビルド、再起動、またはホットリロードとして扱わないでください。 |
TypeScript AppHost に関する注意
検出では、現行の apphost.mts と従来の apphost.ts が対象になりますが、すべての TS AppHost の作成は aspireify に委任されます。CLI 主導の従来形式からの移行は、このオーケストレーションスキルが担当するプロジェクト保守作業であり、作成作業ではありません。移行では Aspire パッケージ、構成、tsconfig、インポートも更新されることを説明してください。変更全体の承認を得た後に限り、aspire update --migrate --yes --non-interactive を提案し、ソースの作成が残っている場合にのみ aspireify に引き継いでください。
引き継ぎ時に適用する現行ルール：
| ルール | 理由 |
|---|---|
非推奨の種類別ヘルパー（withEnvironmentEndpoint、withEnvironmentParameter、withEnvironmentConnectionString、withEnvironmentExpression、withEnvironmentFromOutput、withEnvironmentFromKeyVaultSecret）より、統一された withEnvironment(name, value) を優先する | 種類別ヘルパーは非推奨です。単一の API で、すべての値の型に対応できるようになりました |
.aspire/modules/ を直接編集しない | 生成されたファイルです。aspire add <package> で再生成し、欠落したファイルは aspire restore で復元してください |
API の検索には aspire docs api search <query> --language typescript を使用する | TS の API サーフェスは C# と異なります |
スキルの振り分け — プラグイン内の兄弟スキル
aspire init で AppHost のひな形と aspire.config.json が生成された後、AppHost の配線
（リポジトリをスキャン → リソースグラフを提案 → AppHost を編集 → Aspire.ServiceDefaults／OTel を配線 →
aspire start で検証）は、プラグイン内の aspireify スキルに引き継いでください：aspireify/SKILL.md。
ひな形の生成だけが必要な初回実行フローについては、プラグイン内の aspire-init スキルを参照してください：
aspire-init/SKILL.md。このオーケストレーションスキルはライフサイクル（開始／停止／待機／再起動）に専念し、AppHost コード自体は編集しません。
プロジェクトローカルのスキルの優先順位
aspire agent init で作成した .agents/skills/aspire/SKILL.md が存在する場合は、以下についてその指示に従ってください。
C# AppHost の編集、TS AppHost の編集、Playwright への引き継ぎ、調査ワークフロー。
このプラグインの安全性ガードレールは常に適用されます。
現在の Aspire で aspire init によりインストールされた .agents/skills/aspireify/SKILL.md がプロジェクトローカルに存在する場合、プロジェクトローカルの aspireify スキルが存在することをユーザーに警告し、インプラグイン内の同等スキルではなく、AppHost の接続設定についてはその指示に従ってください。上記のプロジェクトローカルの aspire スキルと同じ優先順位ルールが適用されます。プロジェクトローカルのスキルが優先されますが、プラグインのガードレールは引き続き適用されます。
参考資料
- safety-guardrails.md — 詳細なルールと復旧パターン
- detection.md — プロジェクトのフィンガープリント
- app-commands.md — アプリのライフサイクルとブートストラップコマンド
- resource-management.md — リソースの待機、再起動、操作
- agent-workflows.md — エージェントによる一般的な調査、統合、TypeScript、引き継ぎのワークフロー