convert-to-cpm

一元的なパッケージ管理への変換

プロジェクトの動作を維持し、レビュー可能な変換前後の証拠を残しながら、パッケージのバージョンを Directory.Packages.props に一元化します。

まずモードを選択する

ビルドを実行したりファイルを変更したりする前に、次の手順を行います。

1. ガードモード -- 対象範囲内のプロジェクトで packages.config が使用されている場合は、作業を停止します。CPM には PackageReference が必要であることを説明し、先に移行することを推奨します。ファイルの作成や変更は行いません。
2. パッケージメンテナンスモード -- パッケージの更新、調整、バージョン引き上げ、同期の依頼は、CPM への変換ではなく、パッケージの編集を許可するものです。指定された対象範囲を監査し、依頼されたバージョンを決定して、既存のプロジェクトまたは共有ファイル内のバージョン宣言を更新します。適用される global.json の場所を定めるディレクトリから、影響を受けるすべての CLI ターゲットを復元・ビルドします。バージョンまたは調整方針が曖昧な場合に限り、質問してください。Directory.Packages.props の作成や変更、CPM のためのバージョン削除、変換成果物の取得は行いません。パッケージ作業を完了したら、恒久的な対応として CPM を推奨します。
3. 変換モード -- ユーザーが CPM の採用、有効化、または変換を明示的に依頼した場合に限り使用します。以下のワークフローに従ってください。

対象範囲が不明確な場合は、作業を進める前に一度だけ質問してください。

既定の実行計画

• ガード：対象を絞った最小限の検出を行ってから、回答して停止します。
• パッケージメンテナンス：簡潔に監査し、既存の場所にある依頼対象のパッケージバージョンだけを編集して、影響を受けるターゲットを検証してから、CPM を推奨します。変換に関する資料を読んだり、変換ワークフローに移行したりしないでください。
• 変換：不要な往復を避けるため、事前確認、ベースライン、監査・変更、最終検証、レポート作成をまとめて行います。新たな CPM 固有の証拠によって対象を絞った追加対応が必要な場合に限り、ステージを再確認します。

この計画は効率化のための既定の方針であり、厳格な上限ではありません。作業を減らすために、対象範囲内のプロジェクト、インポートされた .props／.targets ファイル、検出された複雑な要素、必要な検証、成果物を省略してはいけません。可能な場合は、必要な作業をまとめて行ってください。

入力

入力	必須	ルール
対象範囲	はい	調査または変換するプロジェクトを含むプロジェクト、ソリューション、またはディレクトリ
競合解決方針	パッケージメンテナンス、または競合がある場合の変換では必須	ユーザーが「最高バージョンを使用する」などの方針をすでに提示している場合は、再度確認せずに適用し、その影響を記録します。提示されていない場合は、監査の後に停止し、編集前に確認します。

必要な場合にのみ参照資料を読む

参照資料をすべて先読みしないでください。

条件	読む資料
変換のベースライン取得、またはパッケージ差分の作成に着手する	baseline-comparison.md
競合、条件付き参照、共有インポート、セキュリティ上の懸念、または VersionOverride が検出された	audit-complexities.md
配置が不明確、または条件付きの PackageVersion／VersionOverride が必要	directory-packages-props.md
パッケージバージョンで MSBuild プロパティが使用されている	msbuild-property-handling.md
変換後に復元またはビルドが失敗した	validation-and-errors.md
最終レポートを作成する	report-template.md

変換ワークフロー

1. 対象範囲と事前確認

• プロジェクト／ソリューションの対象範囲を確定します。ソリューションの場合は、そのプロジェクトを列挙します。ディレクトリの場合は、そのディレクトリ以下のみを検索し、対象範囲全体を網羅する明示的な対象セットを作成します。該当する各 .sln／.slnx を使用し、ソリューションで網羅されていない各プロジェクトを追加します。対象範囲内のすべてのプロジェクトが網羅されていることを確認し、複数の対象に含まれるプロジェクトの作業が重複しないようにします。対象の重複やリポジトリの境界によって意図する範囲が曖昧な場合に限り、確認を求めます。対象を1つ選ぶことで対象範囲内のプロジェクトが漏れるような選択をユーザーに求めてはいけません。
• CPM の管理範囲は CLI の対象とは分けて判断します。1つの中央バージョンポリシーを共有するプロジェクトをグループ化し、既存の最寄りのファイルによる境界を尊重しながら、各グループの最初の共通の祖先に Directory.Packages.props を1つ配置します。複数の CLI 対象で1つの CPM ファイルを共有できます。独立したプロジェクトグループには、それぞれ別のファイルが必要になる場合があります。
• packages.config の有無を確認し、見つかった場合は Guard モードに切り替えて停止します。
• 対象範囲とその祖先にある Directory.Packages.props を確認します。CPM がすでに完全に有効な場合は、その旨を報告して停止します。部分的なファイルがある場合は保持し、その意図する範囲が曖昧な場合に限り確認を求めます。
• 確定した対象範囲内に共通の成果物ディレクトリを1つ選びます。通常は、対象の最初の共通の祖先とします。すべての binlog、パッケージスナップショット、レポートには、そのディレクトリへの明示的なパスを使用します。
• 各対象の .NET コマンドは、その対象のソリューション／プロジェクトディレクトリ、または適用される global.json が決まる別のディレクトリから実行します。無関係な親ワークスペースから実行してはいけません。
• ユーザーが対象範囲を指定した場合、無関係なプロジェクトやホストツールの設定を調べてはいけません。

2. ベースラインの取得

baseline-comparison.md を読みます。各対象について、その対象のコマンドディレクトリから有効な SDK を一度だけ特定し、そのバージョンに対応する文書化済みのコマンド構文を選択します。SDK の解決に失敗した場合、または SDK が要求されたソリューション形式を処理できない場合は、前提条件を報告して停止します。ユーザーが求めない限り、ホスト SDK やリポジトリの SDK ポリシーを変更してはいけません。

次に、1つのコマンドバッチを使って以下を行います。

1. 明示したすべての対象をクリーン、復元、ビルドします。対象が1つの場合は baseline.binlog を、複数の場合は対象ごとに一意の baseline-<target-key>.binlog を使用します。
2. 復元を再実行せずに、すべての対象について解決済みパッケージを書き出します。対象が1つの場合は baseline-packages.json を、複数の場合はそれぞれに対応する baseline-packages-<target-key>.json を使用します。
3. 通常のコマンド出力は簡潔に保ちます。必要に応じて全出力を成果物に保存します。失敗時に調べるのはエラーのみとし、binlog をテキストとして読んではいけません。

編集を始める前に、すべてのベースラインを完了します。ベースラインのビルドが1つでも失敗した場合は、ファイルを変更せずに停止し、すでに作成されたすべての成果物を保持します。

3. 対象を絞ったチェックリストで監査する

すべてのベースラインスナップショットに加え、対象範囲内のプロジェクト、.props、.targets ファイルを対象にしたスキャンを1回実施します。次の項目を特定します。

• パッケージ ID、解決されたバージョン、使用しているプロジェクト
• バージョンの競合
• MSBuild プロパティに基づくバージョンとその定義
• 条件付きの PackageReference 項目
• パッケージ参照を含むインポート済みファイル
• 既存の VersionOverride の使用箇所

対象範囲が複雑な場合は、上記の該当するすべての項目について、すべてのプロジェクトとインポート済みファイルを確認してください。最初の競合が見つかった時点で確認を止めないでください。

デフォルトでは、範囲の広い --outdated や --deprecated のスキャンを実行しないでください。編集前に、ユーザーがセキュリティ情報を求めている場合、既知のアドバイザリを確認する必要がある場合、または競合の解決によってプロジェクトがパッケージのメジャーバージョンをまたぐ場合は、対象を絞った --vulnerable --include-transitive クエリを試みてください。簡潔な調査結果、「アドバイザリは見つかりませんでした」、または確認を実行できなかった理由を記録します。認証、パッケージソース、またはオフライン環境の制約により高リスクの確認を実施できない場合は、不確実性を明示し、安全とみなして黙って進めるのではなく、ユーザーの方針を確認してください。CPM への変換にあたり、対象範囲ですでに使用されている最高バージョンを超えてアップグレードしないでください。

競合とその影響を提示します。追加のオンラインスキャンは行わず、メジャーバージョンの整合を高リスク、マイナー／パッチバージョンの整合を中リスクとして明示的に分類してください。ユーザーが競合解決の方針を提示している場合は、その方針に沿って進めます。そうでない場合は、未解決の判断事項を尋ね、編集前に停止します。

4. CPM ファイルを作成し、参照を更新する

• 管理スコープを算出し、必要な各 Directory.Packages.props を作成または更新して、ManagePackageVersionsCentrally を true に設定します。
• パッケージごとに PackageVersion を1つ追加し、必須のターゲットフレームワーク条件を維持したうえで、アルファベット順に並べます。
• プロジェクトおよびインポート済みファイル内の管理対象 PackageReference 項目から、Version のみを削除します。
• 条件、空白、PrivateAssets、IncludeAssets、ExcludeAssets、GeneratePathProperty、Aliases など、その他すべてのメタデータを維持します。
• 選択した方針で必要な場合に限り、VersionOverride を使用します。

MSBuild バージョンプロパティについては、msbuild-property-handling.md に従ってください。ユーザーの指示でインライン化する場合は、同じ変更バッチ内でリテラル値の PackageVersion を追加し、不要になったプロパティ定義を削除します。最終検証の前に、次の項目を個別に確認してください。

1. 対象範囲内のプロジェクト、.props、.targets ファイルに $(PropertyName) の参照が残っていないこと。
2. 削除対象として選択した各プロパティについて、<PropertyName>...</PropertyName> の定義が残っていないこと。

$() 参照のスキャンだけを根拠に、XML プロパティ定義が削除されたと判断しないでください。

5. 検証と比較

baseline-comparison.md を使用して、すべてのプロジェクト、共有ファイル、プロパティの編集後の最終的なオンディスク状態を検証します。1 つのコマンドバッチで次を実行します。

1. すべての CPM 編集後に、すべての明示的なターゲットをクリーン、復元、ビルドします。1 つのターゲットには after-cpm.binlog を、複数のターゲットにはそれぞれ対応する after-cpm-<target-key>.binlog を使用します。
2. 再度復元せずに、すべてのターゲットの解決済みパッケージを書き込みます。1 つのターゲットには after-cpm-packages.json を、複数のターゲットにはそれぞれ対応する after-cpm-packages-<target-key>.json を使用します。
3. 完全な JSON ファイルを出力したり再読み込みしたりせずに、プロジェクトごとの変更/未変更の簡潔な比較を生成します。
4. 解決されたバージョンが変更され、リポジトリが影響を受けるプロジェクトに対して定型的でスコープされたテストコマンドを公開している場合は、--no-build --no-restore を付けて実行し、結果を記録します。テストに相当なセットアップ、広範なインフラストラクチャ、またはユーザーの承認が必要な場合は、代わりに正確なスコープ付きコマンドを推奨します。バージョンに依存しない変換では、自動テストの実行は必要ありません。

復元またはビルドが CPM 関連のエラーで失敗した場合は、validation-and-errors.md を読み、関連するエラー行のみを確認し、対象を絞った修正を行い、影響を受ける検証を再実行します。SDK、認証、パッケージソース、ファイルロック、テストホスト、その他の環境的な失敗については、マシンを変更したり調査を拡大したりせずに、ブロッカーを報告します。

ビルドが成功した後にテストの実行が失敗した場合は、CPM のパッケージ解決が原因かどうかを判断するのに十分な出力のみを確認します。証拠が CPM の欠陥を明確に示す場合にのみ、対象を絞った修正を適用します。それ以外の場合は、テストホスト、SDK、出力ディレクトリ、依存関係コピーのデバッグに拡大することなく、失敗と推奨されるユーザーアクションを記録します。

6. レポートの作成

report-template.md を今すぐ読んでください。それより早く読まないでください。他の成果物の隣に convert-to-cpm.md を作成します。これには、6 つの必須セクション、すべての明示的なターゲットと CPM 管理スコープ、具体的な競合の影響、集約されたパッケージ比較、リスクレベル、フォローアップ、成果物の使用状況、および検査または変更したすべての共有 .props/.targets ファイルの名前を含める必要があります。最終的な回答では、これらの共有ファイル、リスクレベル、および条件付き参照とターゲットフレームワークがどのように保持されたかに言及します。検証によって欠落または不正確な証拠が見つからない限り、検証後にレポートを書き直すことは避けてください。

必須の変換成果物

レポートと各ターゲットの 4 つの証拠ファイルを保持してください。これらは一時ファイルではありません。1 つのターゲットの場合、5 つの成果物は次のとおりです。

• baseline.binlog
• after-cpm.binlog
• baseline-packages.json
• after-cpm-packages.json
• convert-to-cpm.md

複数のターゲットの場合、4 つの固定された証拠名を、baseline-api.binlog、after-cpm-api.binlog、baseline-packages-api.json、after-cpm-packages-api.json など、ターゲットキーごとに一意のペアに置き換えます。集約された convert-to-cpm.md は 1 つだけ保持します。

効率性のルール

• サポートされている場合は、独立した読み取りと編集をバッチ処理します。
• 完全なビルドログとパッケージ JSON は会話に含めないでください。簡潔な要約と成果物のパスを返します。
• 成功したコマンドを繰り返したり、成功した出力を再読み込みしたりしないでください。
• 変換モードでは、パッケージのアップグレード、広範な古い/非推奨のスキャン、テストの繰り返し、無関係なリポジトリの調査を行わないでください。上記で定義された単一の条件付き脆弱性クエリとテストの実行は、完全な高リスク変換検証の一部です。パッケージメンテナンスでは、要求されたアップグレードと、それらを解決するために必要な 1 つのスコープ付きバージョン検出クエリを実行できます。
• SDK をインストールまたは削除したり、一時的な SDK セレクターを作成したり、ロールフォワードポリシーを変更したり、SDK 内部のアセンブリを呼び出したり、無関係なプロセスを強制終了したり、ホストツール/一時インフラストラクチャをクリーンアップしたりしないでください。環境の前提条件を報告して停止します。

検証

• 明示的に指定されたすべてのターゲットで変換前と変換後のビルドが成功し、すべてのターゲットの binlog が存在する
• 管理対象のすべての PackageReference に Version がないか、意図的に VersionOverride を使用している
• 管理対象のすべてのパッケージに正しい中央の PackageVersion が指定されている
• 条件とバージョン以外のメタデータが保持されている
• 変更前後のパッケージ比較に説明のつかない変更がない
• インライン化されたバージョンプロパティに、残存する $() 参照も古い XML 定義もない
• レポートとターゲットごとの変換前・変換後の成果物がすべて存在する