GitHub Copilot modernizationを使うと、.NETアプリのアップグレードを「評価・計画・実行」の3段階に分け、依存関係の調査からコード修正、ビルド、テストまで支援できます。
2026年7月9日に確認された今回の更新で重要なのは、既存の.NETアプリに強制的な変更が入ることではありません。主な変更点は、開発環境ごとの起動方法、CLIプラグイン、進捗確認ファイル、対応シナリオの整理です。GitHub Copilot modernizationを利用していない環境では、直ちにアプリを修正する必要はありません。一方、旧CLIコマンドやexecution-log.mdを前提にした手順書・自動化処理は見直しが必要です。
Microsoft Learn上の最終更新日は2026年7月8日で、GitHub上でも同日に関連ドキュメントの修正が行われています。本記事では、日本時間の2026年7月9日に確認された更新として扱います。(Microsoft Learn)
2026年7月9日更新で何が変わったのか
今回の直接的な変更は、GitHub Copilot modernizationの起動方法を環境別に明確化したことです。同時期に更新されたインストール、対応シナリオ、トラブルシューティングの公式文書まで含めると、実務上は次の差分を押さえる必要があります。(GitHub)
| 対象 | 現在の仕様 | 既存運用への影響 |
|---|---|---|
| Visual Studio | ソリューションまたはプロジェクトの「Modernize」、または@Modernizeで起動 | 従来の起動方法を継続できる |
| Visual Studio Code | @modernize-dotnetで起動 | CLIと同じ名前ではなくなったため、環境を区別する必要がある |
| GitHub Copilot CLI | @upgradeに続けてアップグレード内容を入力 | CLIで@modernize-dotnetを使っていた手順書は修正が必要 |
| GitHub Copilotアプリ | Agentピッカーから「Upgrade」を選択 | 旧GitHub.com coding agent前提の説明を見直す |
| CLIプラグイン | microsoft/upgrade-agent-pluginsからupgrade-agentを導入 | 旧マーケットプレース名や旧プラグイン名では導入できない可能性がある |
| 進捗・エラー確認 | tasks.mdとtasks/{taskId}/progress-details.mdを確認 | execution-log.mdを読む自動処理や運用手順は変更が必要 |
| 対応範囲 | .NET Framework 4.8.1へのアップグレード、新しいモダナイゼーションシナリオなどを追加 | .NETへの全面移行が難しい案件でも段階的な対応を検討しやすくなった |
特に間違えやすいのが、CLIとVisual Studio Codeの呼び出し名です。CLIは@upgradeに変わりましたが、Visual Studio Codeでは引き続き@modernize-dotnetを使います。すべての環境を一律に@upgradeへ置き換えないようにしてください。(Microsoft Learn)
GitHub Copilot CLIの現在のインストールコマンドは次のとおりです。
/plugin marketplace add microsoft/upgrade-agent-plugins
/plugin install upgrade-agent@upgrade-agent-pluginsインストール後は/agentを実行し、エージェント一覧にupgrade-agentが表示されることを確認します。(Microsoft Learn)
execution-log.mdに依存した運用は修正が必要
以前のドキュメントでは、複雑な失敗を調べる際にexecution-log.mdを参照する手順が案内されていました。現在は、このファイルではなく、次の順序で確認します。
.github/upgrades/{scenarioId}/tasks.mdを開く- 失敗したタスクIDを確認する
tasks/{taskId}/progress-details.mdを開く- 実行内容、エラー、検証結果を確認する
execution-log.mdはエージェントの更新に伴って削除されています。CIの成果物収集、監査スクリプト、社内手順書などでファイル名を固定している場合は、今回の更新に合わせた修正が必要です。(GitHub)
GitHub Copilot modernizationが実行する3段階のワークフロー
GitHub Copilot modernizationは、単にプロジェクトファイルのTargetFrameworkを書き換えるツールではありません。コードベース、依存関係、NuGetパッケージ、破壊的変更、テスト状況を調査し、レビュー可能なMarkdownファイルを生成しながら処理を進めます。(Microsoft Learn)
| 段階 | 主な生成ファイル | 確認する内容 |
|---|---|---|
| 評価 | assessment.md、upgrade-options.md | 破壊的変更、API互換性、非推奨API、依存関係、対象プロジェクト |
| 計画 | plan.md、scenario-instructions.md | アップグレード順序、パッケージ更新、技術移行、リスク軽減策 |
| 実行 | tasks.md、tasks/{taskId}/task.md、progress-details.md | タスクごとの変更内容、ビルド結果、テスト結果、失敗内容 |
評価段階
最初にプロジェクト構造と依存関係が分析され、assessment.mdが作成されます。評価結果には、破壊的変更、API互換性の問題、非推奨パターン、アップグレード対象範囲などが含まれます。
この段階では、次の点を人間が確認する必要があります。
- 対象外にしたいプロジェクトが含まれていないか
- 独自ライブラリや社内NuGetパッケージが正しく認識されているか
- Windows固有APIやネイティブDLLへの依存が漏れていないか
- 生成コードが通常のソースコードとして扱われていないか
- テストプロジェクトがアップグレード対象に含まれているか
評価結果が不完全なまま計画へ進むと、その後の修正範囲も不正確になります。コード変更が始まる前に問題を見つけられるため、最も時間をかけるべき段階です。(Microsoft Learn)
計画段階
評価後は、upgrade-options.mdでアップグレード方法を決めます。主な選択肢は次のとおりです。
- ボトムアップ、トップダウン、一括アップグレード
- 既存プロジェクトを直接変更するインプレース方式
- 新旧実装を並行して保持するサイドバイサイド方式
- EF6からEF Coreなどの技術移行を同時に行うか
- Central Package Managementを導入するか
- 非互換パッケージやプラットフォーム固有機能をどう扱うか
決定内容からplan.mdが生成されます。計画は編集できますが、依存元を残したまま依存先プロジェクトを計画から削除すると、アップグレード経路が成立しなくなる可能性があります。プロジェクト間の依存順序を崩さないことが重要です。(Microsoft Learn)
実行段階
実行段階では、計画が複数のタスクに分割されます。各タスクでは、コード変更、ビルド、テスト、結果記録、コミットが順番に行われます。
エージェントが変更したコードは、必ずコンパイルできるとは限りません。公式トラブルシューティングでも、特殊なAPIや一般的でないコードパターンでは、生成コードにエラーが含まれる可能性があると説明されています。エージェントが修正を繰り返しても解決できない場合は、開発者が手動修正し、その内容を伝えて処理を継続します。(Microsoft Learn)
既存実装との互換性に影響はあるのか
今回の更新だけで、既存の.NETアプリが自動的に変更されたり、ビルドできなくなったりすることはありません。GitHub Copilot modernizationを明示的に起動し、アップグレードを実行したときに初めてワークスペース内のファイルが変更されます。
公式FAQでは、エージェントが変更する範囲はワークスペースと.github/upgrades/フォルダー内に限定されると説明されています。(Microsoft Learn)
実務上の互換性は、次のように判断できます。
| 現在の利用状況 | 対応要否 |
|---|---|
| GitHub Copilot modernizationを利用していない | 今回の更新に対する緊急対応は不要 |
Visual Studioで@Modernizeを利用している | 基本的に従来どおり利用可能 |
Visual Studio Codeで@modernize-dotnetを利用している | 基本的に従来どおり利用可能 |
Copilot CLIで@modernize-dotnetを利用している | @upgradeへ変更する |
| 旧CLIプラグインを導入している | 新しいマーケットプレースとプラグインへ切り替える |
execution-log.mdを収集・解析している | tasks.mdとprogress-details.mdへ変更する |
| GitHub.comの旧coding agentを前提にしている | GitHub CopilotアプリのUpgradeエージェントを再確認する |
.github/upgrades/をGit管理から除外している | 中断・再開や監査が必要なら管理対象に含める |
既存の.github/upgrades/{scenarioId}がある場合、エージェントは前回の作業を再開するか、新しく開始するかを確認します。アップグレード途中の状態を維持したい場合は、このフォルダーを削除しないでください。状態ファイルが失われると、前回作業を復元できず、再評価と再計画が必要になります。(Microsoft Learn)
対応している.NETアプリとアップグレード先
GitHub Copilot modernizationは、C#とVisual Basicの両方に対応しています。対象には、ASP.NET Core、MVC、Razor Pages、Web API、ASP.NET Web Forms、Blazor、Azure Functions、WPF、Windows Forms、WinUI、.NET MAUI、Xamarin、コンソールアプリ、クラスライブラリ、MSTest・NUnit・xUnitのテストプロジェクトなどが含まれます。(Microsoft Learn)
公式に示されている主なアップグレード経路は次のとおりです。
| 現在の環境 | 対応する移行先 |
|---|---|
| .NET Frameworkの各バージョン | .NET 8以降 |
| .NET Frameworkの各バージョン | .NET Framework 4.8.1 |
| .NET Core 1.x～3.x | .NET 8以降 |
| .NET 5以降 | .NET 8以降 |
.NET Framework 4.8.1への経路が追加されたことで、業務都合や依存ライブラリの制約から直ちに最新.NETへ移行できないシステムでも、段階的なアップグレードを検討できます。ただし、.NET Framework 4.8.1への更新は、最新.NETへのモダナイゼーションと同じではありません。将来的なクロスプラットフォーム化、コンテナー化、最新ASP.NET Coreへの移行を目的とする場合は、別途.NET 8以降への移行計画が必要です。(GitHub)
現在の.NETバージョンから対応優先度を判断する
2026年7月14日時点の公式サポートポリシーでは、.NET 10は2028年11月14日までサポートされるLTSです。一方、.NET 8と.NET 9は、いずれも2026年11月10日にサポート終了予定です。.NET 6、.NET 7、.NET Core 3.1以前はすでにサポートを終了しています。(Microsoft)
| 現在のバージョン | 対応優先度 | 推奨する判断 |
|---|---|---|
| .NET 10 | 低い | フレームワーク更新より、パッケージや個別技術のモダナイゼーションを検討する |
| .NET 8または.NET 9 | 高い | 2026年11月10日までの運用計画を確認し、.NET 10への評価を開始する |
| .NET 6または.NET 7 | 非常に高い | サポート終了済みのため、優先してアップグレード計画を作成する |
| .NET Core 3.1以前 | 非常に高い | API・パッケージ差分が大きいため、小規模なパイロットから始める |
| .NET Framework | システムごとに判断 | 4.8.1への延命か、最新.NETへの本格移行かを分けて検討する |
新しいアップグレード案件では、依存パッケージや実行OSが対応している限り、.NET 10 LTSを第一候補にするのが現実的です。.NET 8を新たな移行先に選ぶ場合は、移行完了直後に次のアップグレードが必要にならないかを確認してください。
GitHub Copilot modernizationの利用条件
利用条件は開発環境によって異なります。
| 環境 | 主な条件 | 起動方法 |
|---|---|---|
| Visual Studio | Windows、Visual Studio 2026またはVisual Studio 2022 17.14.17以降、.NETデスクトップ開発ワークロード、Copilot関連コンポーネント | 「Modernize」または@Modernize |
| Visual Studio Code | VS Code、GitHub Copilot拡張機能、GitHub Copilot modernization拡張機能 | @modernize-dotnet |
| GitHub Copilot CLI | GitHub Copilot CLI、upgrade-agentプラグイン | @upgrade |
| GitHub Copilotアプリ | GitHub Copilotアプリ、upgrade-agent-pluginsマーケットプレース | Agentピッカーの「Upgrade」 |
いずれの環境でもGitHub Copilotの利用権限とインターネット接続が必要です。Visual Studioでは、GitHub Copilotと「GitHub Copilot app modernization」のオプションコンポーネントを有効にします。(Microsoft Learn)
Gitは事実上の必須条件として扱う
公式FAQでは、ローカルGitリポジトリが必要条件として挙げられています。一方、ベストプラクティスとトラブルシューティングでは、Git管理されていないフォルダーでも変更自体は可能であり、その場合はブランチ作成やコミットを省略すると説明されています。公式文書内で表現に差がある状態です。(Microsoft Learn)
実務では、Gitを事実上の必須条件として扱うのが安全です。少なくともローカルリポジトリを作成し、アップグレード前の状態をコミットしてください。
git init
git add .
git commit -m "Baseline before GitHub Copilot modernization"Gitを使うことで、タスクごとの変更確認、失敗したコミットの取り消し、必要な変更だけのcherry-pickが可能になります。
安全に.NETアプリをアップグレードする手順
現在のビルドとテストを正常化する
エージェントを起動する前に、現在のコードが正常にビルド・テストできることを確認します。
git status
dotnet restore
dotnet build --configuration Release
dotnet test --configuration Release既存のテスト失敗が残ったままでは、アップグレードによる失敗と従来から存在する失敗を区別できません。修正できない既知の失敗がある場合は、テスト名、失敗理由、許容条件をscenario-instructions.mdに記録します。(Microsoft Learn)
専用ブランチを作成する
本番修正や機能開発とアップグレード変更を混在させないよう、専用ブランチを作成します。
git switch -c chore/dotnet-modernization-pilot初回は、クラスライブラリや社内ツールなど、比較的影響の小さいプロジェクトで一連の流れを試すと安全です。大規模ソリューションを最初から一括変換すると、リポジトリ固有の問題とフレームワーク差分が同時に表面化し、原因の切り分けが難しくなります。(Microsoft Learn)
ガイド付きモードで具体的に依頼する
最初の実行では、自動モードではなくガイド付きモードを選びます。ガイド付きモードでは、評価、計画、実行の主要な境界で処理が止まり、人間が内容を確認できます。(Microsoft Learn)
依頼内容は「アップグレードして」の一文だけで終わらせず、対象、除外範囲、互換性要件、検証方法を指定します。
このソリューションを.NET 6から.NET 10へアップグレードしてください。
ガイド付きモードを使用してください。
条件:
- 公開APIのシグネチャを維持する
- 既存のJSONレスポンス形式を変更しない
- src/Generated配下の自動生成コードは変更しない
- EF6からEF Coreへの移行は今回の対象外とする
- タスクごとにコミットする
- 各タスク後にrestore、Releaseビルド、全テストを実行する「最新化して」のような曖昧な依頼では、フレームワーク更新、JSONライブラリ移行、SDK形式への変換など、意図と異なるシナリオが選ばれる可能性があります。目標バージョンと対象技術を明記してください。(Microsoft Learn)
assessment.mdをレビューする
評価が終わっても、すぐに実行へ進めてはいけません。少なくとも次の項目を確認します。
- 全プロジェクトとテストプロジェクトが認識されているか
- プロジェクト参照の依存順序が正しいか
- 更新不能または代替が必要なNuGetパッケージがないか
- 独自MSBuildターゲットや条件付きインポートが認識されているか
- Windows固有機能、COM、ネイティブDLLへの依存がないか
- 認証、シリアライズ、データアクセスの破壊的変更が抽出されているか
- 対象外とするプロジェクトやコードが明確になっているか
不足している情報は、チャットで伝えるだけでなく、assessment.mdまたはscenario-instructions.mdにも記録します。
アップグレード戦略を選ぶ
| 戦略 | 適するケース | 注意点 |
|---|---|---|
| ボトムアップ | 共通ライブラリを複数アプリが参照している | 下位ライブラリの公開API互換性を維持する必要がある |
| トップダウン | 主要アプリを早く動作確認したい | 依存ライブラリとの一時的な不整合が起きやすい |
| 一括 | 小規模で強く結合したソリューション | 変更量が大きく、失敗時の切り分けが難しい |
| インプレース | 既存プロジェクトをそのまま更新できる | 必ず専用ブランチとロールバック手段を用意する |
| サイドバイサイド | 長期並行稼働や段階移行が必要 | 新旧コードの二重管理期間が発生する |
| マルチターゲット | ライブラリ利用者を段階的に移行したい | 条件付きコンパイルやパッケージ管理が複雑になる |
プロジェクト数が少なくても、認証基盤、データアクセス層、外部連携が密結合している場合は、一括方式よりボトムアップまたはサイドバイサイド方式が安全です。
テスト時に注意すべきポイント
GitHub Copilot modernizationがビルドとテストを実行しても、それだけで既存実装との互換性が保証されるわけではありません。公式文書も、アップグレード完了後に、失敗したテスト、コンパイルエラー、NuGetパッケージ互換性を確認し、アプリを十分にテストするよう求めています。(Microsoft Learn)
| テスト対象 | 確認内容 |
|---|---|
| ビルド | Release構成、警告の増加、条件付きコンパイル、プラットフォーム指定 |
| 単体テスト | 既存の期待値、例外型、境界値、日時・カルチャ依存処理 |
| API互換性 | URL、HTTPステータス、ヘッダー、OpenAPI定義、公開メソッド |
| シリアライズ | JSONのプロパティ名、null処理、列挙値、日付形式、大小文字 |
| データベース | SQL生成、トランザクション、遅延読み込み、マイグレーション |
| 認証・認可 | Cookie、トークン、クレーム、セッション、有効期限 |
| 外部連携 | メッセージ形式、再試行、タイムアウト、TLS、SDK互換性 |
| OS依存処理 | ファイルパス、文字コード、レジストリ、COM、ネイティブDLL |
| 性能 | 起動時間、メモリ、GC、主要APIの応答時間、バッチ処理時間 |
| 配置 | コンテナー、IIS、Windowsサービス、環境変数、ロールバック |
テストコードの変更もレビューする
AIエージェントがテストを修正した結果、すべてのテストが成功することがあります。しかし、アサーションが削除されたり、期待値が新しい挙動に合わせて安易に変更されたりすれば、テスト成功の意味が失われます。
テストコードに変更が入った場合は、次の点を差分で確認してください。
- アサーション数が減っていないか
- 例外を握りつぶしていないか
- テスト対象の呼び出し自体が削除されていないか
- モックが過剰に使われ、実際の挙動を検証しなくなっていないか
- 「新しい挙動に合わせただけ」の期待値変更になっていないか
テストを通すことではなく、既存仕様を維持できていることが目的です。
境界部分のテストを優先する
100％のコードカバレッジを目指す必要はありません。公式ベストプラクティスでは、API境界、シリアライズ、データベースアクセス、認証など、アップグレードの影響を受けやすい箇所を優先するよう案内されています。(Microsoft Learn)
特にWeb APIでは、アップグレード前のレスポンスを保存し、アップグレード後のレスポンスと比較する契約テストが有効です。データベース処理では、本番相当のデータ量とインデックス構成を使い、結果だけでなく実行時間も比較してください。
private NuGetフィードを事前に認証する
社内パッケージフィードへの認証が切れていると、dotnet restoreが失敗し、エージェントは互換性評価やビルドを進められません。事前に開発者の端末で手動のdotnet restoreが成功することを確認します。複雑な.targetsファイルや独自ビルド処理がある場合は、その存在をscenario-instructions.mdへ明記してください。(Microsoft Learn)
チームで導入するときの管理策
scenario-instructions.mdを運用ルールとして使う
scenario-instructions.mdには、アップグレード全体で維持すべき要件を記録します。チャット内だけの指示よりも、セッションをまたいで適用されやすくなります。(Microsoft Learn)
記載例は次のとおりです。
Target framework: net10.0
Workflow mode: Guided
Compatibility requirements:
- Preserve public API signatures
- Preserve existing JSON and XML schemas
- Do not change database column names
- Keep Windows authentication enabled
Excluded scope:
- Do not migrate EF6 to EF Core
- Do not modify src/Generated
- Do not replace the logging framework
Validation:
- Run dotnet restore after package changes
- Run Release build after every task
- Run unit, integration, and contract tests
- Commit one completed task at a time
Known existing failures:
- LegacyReportTests.ExportCsv fails in the existing baselineタスク単位でレビューとコミットを行う
アップグレード全体を1コミットにまとめると、問題が起きたときに原因を特定できません。タスクごとにコミットし、次の内容をPull Requestで確認します。
- プロジェクトファイルとパッケージ更新
- API置き換え
- テストコードの変更
- 設定ファイルの変更
- 削除されたコード
- 新たに追加された互換レイヤー
assessment.mdとplan.mdの決定内容
タスクごとのコミットがあれば、必要な変更だけをcherry-pickして採用できます。(Microsoft Learn)
.github/upgradesの取り扱いを決める
.github/upgrades/には、評価結果、依存関係、計画、カスタム指示、エラー内容が保存されます。公式文書では、これらのカスタムタスクデータはリポジトリ内に保持されると説明されています。(Microsoft Learn)
中断・再開、レビュー、監査が必要な間はGit管理に含めるのが適切です。ただし、内部構成や技術的な弱点が記録される可能性があるため、公開リポジトリへ追加する前に内容を確認してください。
公式FAQでは、コードベースをモデル学習に使用せず、アップグレード完了後にセッションデータを削除すると説明されています。また、テレメトリはプロジェクト種別、アップグレード意図、所要時間などに限定され、開発環境の設定から無効化できるとされています。ただし、組織でGitHub Copilotの利用基準、機密情報、外部送信、テレメトリに関する規程がある場合は、その規程を優先してください。(Microsoft Learn)
失敗しやすいポイントと対処方法
最初から自動モードを使う
初回から自動モードを選ぶと、評価や計画の問題を見落としたまま大量のコード変更が進む可能性があります。まずガイド付きモードで、評価、選択肢、計画、タスクを確認してください。
正常にビルドできない状態から開始する
既存エラーとアップグレード起因のエラーが混在します。アップグレード前のビルド・テスト結果をCI上でも保存し、比較できるようにします。
フレームワーク更新と技術刷新を同時に行う
.NETのバージョンアップ、EF6からEF Coreへの移行、JSONライブラリの変更、認証方式の変更を一度に実施すると、問題の原因を特定しにくくなります。
原則として、次の順序で分離します。
- ターゲットフレームワークと必要最低限のパッケージを更新する
- 既存機能の互換性を確認する
- データアクセスやシリアライズなどを個別シナリオで更新する
- Azure移行やアーキテクチャ変更を行う
plan.mdの依存関係を壊す
計画を短くするために、共通ライブラリだけを対象外にすると、依存するアプリ側のアップグレードが成立しないことがあります。除外する場合は、対象外プロジェクトが新しいターゲットフレームワークから参照可能かを先に確認してください。
.github/upgradesを途中で削除する
状態ファイルがなくなると、エージェントは前回の作業を再開できません。破損した場合は、無理に手作業で復元するより、「再評価して再計画する」と指示した方が安全です。(Microsoft Learn)
大規模ソリューションを一度に処理する
公式トラブルシューティングでは、50を超えるプロジェクトを持つ大規模ソリューションは、関連プロジェクトごとのバッチに分けることが推奨されています。まず代表的な1プロジェクトを最後までアップグレードし、共通する問題を洗い出してください。(Microsoft Learn)
対応要否を判断するチェックリスト
次のいずれかに該当する場合は、今回の更新内容を踏まえて対応を開始する必要があります。
- Copilot CLIで
@modernize-dotnetを使っている - 旧
dotnet/modernize-dotnetマーケットプレースを登録している execution-log.mdを監査・ログ収集に利用している- GitHub.comの旧coding agentを前提に社内手順を作っている
- .NET 8または.NET 9を2026年11月10日以降も運用する予定がある
- .NET 6、.NET 7、.NET Core 3.1以前を利用している
- .NET Frameworkから.NETまたは4.8.1への更新を検討している
- 依存パッケージが多く、手作業での互換性調査に時間がかかっている
反対に、GitHub Copilot modernizationを利用しておらず、現在の.NETバージョンもサポート期間内で、直近のアップグレード計画がない場合は、今回の更新だけを理由にコードを変更する必要はありません。
まず評価だけを実行し、計画をレビューする
GitHub Copilot modernizationの価値は、AIにすべてを任せることではなく、従来は手作業だった依存関係調査、互換性確認、計画作成、反復的な修正を構造化できる点にあります。
最初に行うべき作業は、いきなり本番アプリを変換することではありません。
- 現在の.NETバージョンとサポート期限を確認する
dotnet restore、dotnet build、dotnet testを正常化する- 専用ブランチを作成する
- ガイド付きモードで評価だけを実行する
assessment.mdとupgrade-options.mdを人間がレビューする- テスト範囲とロールバック方法を決めてから実行へ進む
今回の更新によって、Visual Studio、Visual Studio Code、Copilot CLI、GitHub Copilotアプリごとの起動方法が明確になりました。既存アプリへの強制的な互換性影響はありませんが、旧CLI手順、旧プラグイン、旧ログファイルに依存する運用は早めに更新してください。
コメント