aspire-project-v2-migration

Aspire プロジェクト v2 への移行

サポート対象のレガシー .NET プロジェクトリソースを、アプリケーションの動作を暗黙に変更することなく、実験的な DotnetProjectResource モデルに移行します。このスキルは、Aspire 13.6 以降を対象とする AppHost で初めて適用されます。

承認の境界：「Project v2 に移行して」という依頼で承認されるのは、評価までであり、提示されていない変更ではありません。リソースごと、ファイルごとの具体的な計画を提示し、 AppHost、パッケージ、プロジェクト参照、またはアプリケーションのファイルを変更する前に承認を得てください。明示的に承認された範囲のみを適用してください。

必須条件

1. 対象となる AppHost を一つ特定し、無関係なローカル変更を保持してください。
2. プロジェクトファイル、中央パッケージ管理、ファイルディレクティブ、または解決済みのポリグロット設定から、AppHost の実際の Aspire SDK／ホスティングバージョンを特定してください。
3. バージョンが 13.6 より古い、特定できない、または競合している場合は、変更せずに中止してください。Aspire CLI のバージョン、.NET SDK、またはサービスの TargetFramework から適格性を推測しないでください。また、Aspire を暗黙にアップグレードしないでください。
4. インストール済み／解決済みのパッケージで、アプリが使用する AddDotnetProject、発行、EF、Blazor の各機能を含め、必要なすべての API が公開されていることを確認してください。 開発用パッケージは開発ビルドの根拠であり、リリース済みパッケージの根拠ではありません。
5. 生成された .aspire/modules/ ファイルを手動で編集しないでください。
6. 慣れていない API やプレビュー API の形状を前提とする前に、aspire docs search と aspire docs api search ... --language csharp|typescript を使用してください。
7. TypeScript では、フラット DTO を使用する、解決済みの生成済み addDotnetProject(name, path, options?: DotnetProjectOptions) API が必要です。古いハンドルのみを受け取るターゲットビルドでは、別の移行経路をサポートするのではなく、機能要件を満たさないものとして停止してください。 レガシーソースの ProjectResourceOptions 値は、引き続き RPC ハンドルです。

発行と TypeScript のオプションに関する変更は上流にマージされていますが、バージョンラベルが 13.6 であるだけでは、利用者のパッケージにそれらが含まれている証明にはなりません。 マージ済み API のベースラインと発行に関する境界については、compatibility-and-validation.md を参照してください。

プロジェクトローカルのスキルによる上書き

.agents/skills/aspire-project-v2-migration/SKILL.md が存在する場合は、ユーザーに警告し、これらの安全条件を維持したうえで、プロジェクトローカルのスキルに従ってください。

ワークフロー

1. 実際の動作を棚卸しする

アプリケーションのワークスペースでは読み取り専用の評価を行います。ソースと、すでに解決済みのメタデータを調査してください。承認を得る前に、機能を確認する場合であっても、SDK ファイルを復元、ビルド、実行、再生成しないでください。適格性や API の確認に準備が必要な場合は、ワークスペースを黙って変更するのではなく、その前提条件を説明して承認を求めてください。

選択された AppHost と、すべてのレガシー候補を調査してください。

• AddProject<Projects.T>、パス／ディレクトリを指定する AddProject、AddCSharpApp および同等のポリグロット機能。
• 文書化されている Blazor ゲートウェイのパターンと、関連付けられた EF 操作。
• 名前、パス、オプション、アプリケーション引数、環境コールバック、エンドポイント、起動設定、参照、待機条件、ヘルスチェック、レプリカ、ビルド／発行構成、デプロイ注釈。
• AppHost の ProjectReference ／ファイルベースの #:project エッジと、生成されたプロジェクトメタデータを使用するすべての箇所。Projects.* は実際の IProjectMetadata、プロジェクト参照メタデータ、AspireProjectMetadataTypeName を使って解決してください。型名からパスを推測しないでください。
• キャスト、制約、GetProjectResources()、パブリッシャー、イメージマネージャー、直接コンストラクター、専用サブクラスなど、ProjectResource と連動するカスタムコード。
• SDK の選択、カスタムビルドプロパティ、ビルド専用の要件、ファイルアプリの AOT 設定、既存のローカル変更。
• Blazor ゲートウェイの発行について、変更前後の実効的なターゲットフレームワーク、SDK、ランタイム／ベースイメージと OS／プラットフォーム、プロセスユーザー、作業ディレクトリ、エントリーポイント、ポート構成。AppHost のターゲットフレームワークから、パッケージ化されたゲートウェイのファイルアプリの発行フレームワークを特定することはできません。

すでに移行済みのアプリ、または該当するリソースがないアプリは変更不要です。

2. 分類して提案する

編集前に、次の表を提示します。

リソース	現在の API とソース	置き換え案	維持する動作／意図的な変更	パッケージと参照の編集	分類
api	AddProject<Projects.Api> → 解決されたパス	AddDotnetProject("api", path)	引数、プロファイル、エンドポイント、環境変数、参照、待機、レプリカ、発行	Aspire.Hosting.Dotnet を追加；排他的に使用されていることが確認できた依存関係のみ削除	サポート対象／要判断／サポート対象外

以下について説明します。

• ASPIREDOTNETPROJECT001 は実験的な API に関する診断です。
• プロジェクト v2 リソースは実行可能ファイルを基準に識別され、初回ビルドが調整されます。
• 既知の発行または検証上の相違点、特に Blazor ゲートウェイの発行、EF のカスタムビルド入力、OS 間でのファイルアプリの Native AOT について説明します。
• 変更するファイルとリソースの範囲、ならびに従来のまま残すリソースを明確にします。

この具体的な計画について承認を求めます。対象範囲と残すリソースが明示的に承認されるまでは、「安全そうに見える」一部だけを移行してはいけません。

Blazor ゲートウェイの場合、API の置き換えや「Dockerfile から SDK へ」の切り替えだけが承認されても、フレームワーク、ベースイメージ、プロセスユーザーの暗黙的な変更が承認されたことにはなりません。解決済みのデプロイ上の相違点を列挙し、編集前にそれらについて明示的な承認を得ます。ランタイム／OS の互換性と、非 root ユーザーにおけるファイル／ボリュームの権限への影響を簡潔に説明します。変更される値を列挙するだけでは、十分な情報に基づく承認にはなりません。読み取り専用の調査でそれらの値を確定できない場合は、ゲートウェイを要判断に分類し、解明に必要な準備作業について承認を求めます。既定値をでっち上げたり、デプロイが同等だと仮定したりしてはいけません。この評価の最後には、ゲートウェイについて、対象を限定した調査への承認を求めるか、ゲートウェイを維持して独自の発行ポリシーを確認するかを尋ねます。API の編集についてだけ尋ねても、ゲートウェイの承認範囲は解決されません。

ゲートウェイが未解決のまま評価を送信する前に、最後の質問を確認します。ゲートウェイの対象を限定した調査を行うか、ゲートウェイを維持して独自の発行ポリシーを確認するかを、ユーザーに明確に選択してもらう必要があります。ゲートウェイが要判断のまま、API の編集承認だけを求めて終えてはいけません。

評価の最後には、承認が何を意味するかを説明するだけでなく、実際に承認を求めます。利用可能な場合はホストのユーザー質問ツールを使用します。そうでない場合は、列挙したリソースおよびファイルの変更をユーザーが承認するか、明示的に尋ねます。回答を受け取るまでは編集しません。ユーザーが応答できないことは承認を意味しません。

承認後、検証が許可され、実行可能な場合は、使い捨てのコピーで従来の動作を記録します。移行の前後で同じ適合ツールチェーンを使用し、移行に起因するものとして扱わず、既存の失敗として報告します。

3. 承認済みのマッピングを適用する

migration-patterns.md を読み込み、言語固有のマッピングに厳密に従ってください。

• 対象としている AppHost と互換性のあるバージョンの Aspire.Hosting.Dotnet を追加し、中央パッケージ管理とリポジトリの規約を維持してください。
• TypeScript では、フラットな DotnetProjectOptions オブジェクトを使用してください。レガシーソースで確立されている値を維持し、addProject、addCSharpApp、共有の ProjectResourceOptions ハンドルを再設計しないでください。
• Aspire CLI で通常のインテグレーション取得／再生成フローを利用できる場合は、それを使用してください。生成された SDK モジュールを手動で編集しないでください。
• Fluent な構成とアプリケーション引数は、元の実行時の役割を維持してください。
• 承認済みリソースに関連付けられた、単純なローカルの IResourceBuilder<ProjectResource> 注釈のみを更新してください。公開／カスタムのコントラクトを広範に書き換えないでください。
• C# の移行では、編集した AppHost がコンパイルできるよう、ASPIREDOTNETPROJECT001 に限定的に対処する必要があります。承認済みの Project v2 宣言の直前と直後に、#pragma warning disable ASPIREDOTNETPROJECT001／#pragma warning restore ASPIREDOTNETPROJECT001 を対で配置することを推奨します。リポジトリの規約と承認済みの移行範囲に照らして同程度に限定できる場合に限り、プロジェクトレベルの NoWarn を使用してください。無関係な診断を抑制したり、範囲を限定しない抑制を残したりしないでください。 IDotnetProgramResource 用に選択した AddEFMigrations オーバーロードにも、該当する EF 宣言の周囲に対となる ASPIREPROJECTS001 の抑制が必要です。レガシーのオーバーロードでは不要でした。このコンパイルに必要な編集も承認範囲に含めてください。 クライアント／ゲートウェイの呼び出しで必要となる既存の ASPIREBLAZOR001 のスコープは維持してください。

4. プロジェクト参照を慎重に整理する

AppHost の ProjectReference または #:project は、承認済みの移行対象リソースのためだけに存在しており、生成メタデータを使用する箇所も残っていないと確認できた場合に限り削除してください。次の参照は維持してください。

• コード／ライブラリ参照、およびサービスからライブラリへの参照。
• 未移行のリソース、EF 移行メタデータ、Blazor WASM メタデータ、条件付きコード、その他の Projects.* の使用箇所に使われている参照。
• 意図が不明確な参照、および目的が確認できていないビルド専用の参照。

ReferenceOutputAssembly="false" でも AppHost の参照はビルドに参加する可能性があり、安全な整理の代わりにはなりません。

5. ビルドと実行時の意図を維持する

実行時の WithEnvironment の値は実行時のまま維持してください。確立された承認済みの MSBuild 入力に限り WithBuildEnvironment を追加してください。環境構成を一括で移動したり、実行時の作業ディレクトリをビルドコンテキストとして扱ったりしないでください。

サポートされているイメージの識別情報、出力先、形式、ターゲットプラットフォームの設定には WithContainerBuildOptions を使用してください。これらの設定を、禁止されているビルド環境プロパティに変換しないでください。

6. 検証と報告

編集が承認された後：

1. リポジトリの規約に従って復元／ビルドします。
2. 分離が必要な場合は、正確な AppHost を aspire start --non-interactive --isolated --apphost <path> で起動します。
3. 手動でポーリングするのではなく、aspire wait <resource> --apphost <path> --non-interactive と構造化された Aspire の検査を使用します。
4. 維持されている名前、パス、引数、環境、エンドポイント、参照、待機条件、レプリカ、起動プロファイル、公開の意図を検証します。
5. コンパイル、ローカル実行、生成された公開アーティファクト、イメージビルドの証拠を区別します。aspire publish はイメージがビルドされた証拠ではありません。承認された検証段階のみを実行し、暗黙の確認としてイメージをプッシュしたりデプロイしたりしないでください。未実行、スキップ、または利用できないチェックに合格したと主張しないでください。 承認されたゲートウェイのイメージ変更では、正確に受け入れられたターゲットの契約と、変更されていない動作をそれぞれ検証します。「イメージの同等性」ではなく、意図的な差異を報告してください。スモークテストに合格しても、新たなフレームワーク／ユーザー変更が許可されるわけではありません。
6. 移行評価を再度実行し、冪等性を証明します。パッケージ、リソース、抑制、構成の編集が重複していないことを確認します。

移行済み、意図的に維持、ブロックされたリソースに加え、実際に行った検証と手動でのフォローアップを報告します。検証に失敗した場合は、ユーザーの編集を維持してください。

互換性の境界

判断マトリクスの全文はcompatibility-and-validation.mdを参照してください。次のものを自動的に置き換えてはいけません。

• Azure Functions または未知の特殊な ProjectResource サブタイプ
• F# または Visual Basic のサービス
• new ProjectResource(...) の直接呼び出し
• ユーザーの判断なしにカスタムパブリッシャー、イメージマネージャー、キャスト、ジェネリック制約、GetProjectResources() の使用箇所を変更すること
• ファイルアプリのビルド専用環境またはファイルアプリの EF CLI 操作

IDotnetProgramResource は識別用マーカーです。それ自体で公開を構成するわけではありません。SupportsDotnetProgramPublishing() は機能のチェックであり、すべての ProjectResource 制約を書き換える理由にはなりません。

ファイルベースの .cs 候補ごとに、評価では .NET 10 以降が必要であること、WithBuildEnvironment または EF CLI 操作をサポートしないこと、実行時の WithEnvironment の値は変更せず維持されること、ユーザーが別途 PublishAot=false を承認するか、ターゲット OS の公開環境を選択しない限り Native AOT を維持することを明示しなければなりません。

明確な証拠と承認がない限り、ファイルアプリの Native AOT を無効にしたり、カスタムの公開モデルを置き換えたり、未完成のウォッチ／ホットリロード／部分実行の動作を約束したりしないでください。

振り分け

リクエスト	振り分け先
レガシーのプロジェクトリソースを Project v2 に移行する	このスキル
Aspire のパッケージまたは CLI のみをアップグレードする	aspire-orchestration
AppHost を作成または接続する	aspire-init / aspireify
起動、停止、待機、または再ビルドのみを行う	aspire-orchestration
移行後にデプロイまたは公開する	aspire-deployment
実行時の動作を診断する	aspire-monitoring