migrate-dotnet10-to-dotnet11

.NET 10 → .NET 11 の移行

.NET 10 のプロジェクトまたはソリューションを .NET 11 に移行し、すべての破壊的変更を体系的に解決します。移行後のプロジェクトは net11.0 をターゲットとし、問題なくビルドでき、テストに合格し、.NET 11 で導入された動作、ソース互換性、バイナリ互換性に関するすべての変更に対応します。

注: .NET 11 は現在プレビュー段階です。このスキルでは、Preview 3 までにドキュメント化された破壊的変更を扱います。

使用する場合

• TargetFramework を net10.0 から net11.0 にアップグレードする場合
• .NET 11 SDK の更新後にビルドエラーや新しい警告を解決する場合
• .NET 11 ランタイム、ASP.NET Core 11、または EF Core 11 の動作変更に対応する場合
• .NET 11 に合わせて CI/CD パイプライン、Dockerfile、またはデプロイスクリプトを更新する場合
• SDK のアップグレード後に C# 15 コンパイラの破壊的変更を修正する場合

使用しない場合

• プロジェクトがすでに net11.0 をターゲットとし、問題なくビルドできる場合 — 移行は完了しています
• .NET 9 以前からアップグレードする場合 — まず .NET 9→10 の破壊的変更に対応してください
• .NET Framework から移行する場合 — これは別個の、より大規模な作業です
• .NET 11 で開始する新規プロジェクトの場合（移行は不要です）

入力

入力	必須	説明
プロジェクトまたはソリューションのパス	はい	移行する .csproj、.sln、または .slnx のエントリーポイント
ビルドコマンド	いいえ	ビルド方法（例：dotnet build、リポジトリのビルドスクリプト）。指定がない場合は自動検出します
テストコマンド	いいえ	テストの実行方法（例：dotnet test）。指定がない場合は自動検出します
プロジェクトの種類に関するヒント	いいえ	プロジェクトが ASP.NET Core、EF Core、Cosmos DB などを使用しているかどうか。指定がない場合は PackageReferences と SDK 属性から自動検出します

ワークフロー

.NET 11 の破壊的変更に関する情報は、読み込まれた参照ドキュメントから直接回答してください。 該当する変更を特定するために、必要に応じてローカルリポジトリ（プロジェクト／ソリューションファイル、ソースコード、構成、ビルド／テストスクリプト）を調査できます。破壊的変更に関する情報を得るために、ウェブページやその他の外部ソースを取得しないでください。読み込まれた参照ドキュメントが信頼できる情報源です。どの破壊的変更が該当するかを特定し、具体的な修正方法を提示してください。

コミット戦略： 論理的な区切りごとにコミットしてください。TFM の更新後（ステップ 2）、ビルドエラーの解決後（ステップ 3）、動作変更への対応後（ステップ 4）、インフラストラクチャの更新後（ステップ 5）にコミットします。これにより、各コミットの対象が明確になり、レビューしやすくなります。

ステップ 1：プロジェクトを評価する

1. プロジェクトのビルド方法とテスト方法を確認します。ビルドスクリプト、.sln／.slnx ファイル、または個別の .csproj ファイルを探します。
2. dotnet --version を実行して、.NET 11 SDK がインストールされていることを確認します。インストールされていない場合は、作業を中止してユーザーに知らせます。
3. 次の項目を調べて、プロジェクトで使用されている技術領域を特定します。
   • SDK 属性：Microsoft.NET.Sdk.Web → ASP.NET Core、<UseWPF> または <UseWindowsForms> を含む Microsoft.NET.Sdk.WindowsDesktop → WPF／WinForms
   • PackageReferences：Microsoft.EntityFrameworkCore.* → EF Core、Microsoft.EntityFrameworkCore.Cosmos → Cosmos DB プロバイダー
   • Dockerfile の有無 → コンテナー関連の変更が該当
   • 暗号化 API の使用状況 → macOS で DSA に影響あり、AIA 証明書ダウンロードの変更が該当
   • 圧縮 API の使用状況 → DeflateStream／GZipStream／ZipArchive の変更が該当
   • TAR API の使用状況 → ヘッダーのチェックサム検証と HardLink エントリの変更が該当
   • SafePipeHandle と併用した NamedPipeClientStream の使用状況 → SYSLIB0063 コンストラクターの非推奨化が該当
   • BackgroundService の使用状況 → 未処理の例外が発生すると、ホストが停止するようになりました
   • Microsoft.OpenApi の直接使用状況 → ASP.NET Core OpenAPI の v3 API における破壊的変更が該当
   • Entra ID 認証を使用する EF Core SQL Server → SqlClient 7.0 の認証依存関係の変更が該当
   • Unix 上の NativeAOT ネイティブライブラリ → 出力ファイル名のプレフィックスが変更されました
4. 関連する参照ドキュメントを記録します（ステップ 3 の参照ドキュメント読み込み表を参照してください）。
5. 現在の net10.0 ターゲットでクリーンビルド（dotnet build --no-incremental を実行するか、bin／obj を削除）を行い、クリーンなベースラインを確立します。既存の警告を記録します。

ステップ 2：ターゲットフレームワークを更新する

1. 各 .csproj（一元管理されている場合は Directory.Build.props）で、次のように変更します。

   <TargetFramework>net10.0</TargetFramework>
   

   次のようにします。

   <TargetFramework>net11.0</TargetFramework>
   

   マルチターゲットのプロジェクトでは、<TargetFrameworks> に net11.0 を追加するか、net10.0 を置き換えます。

2. すべての Microsoft.Extensions.*、Microsoft.AspNetCore.*、Microsoft.EntityFrameworkCore.* およびその他の Microsoft パッケージ参照を、バージョン 11.0.x に更新します。Central Package Management（Directory.Packages.props）を使用している場合は、そこでバージョンを更新します。

3. dotnet restore を実行します。続行する前に、復元時のエラーを修正します。

4. dotnet build を実行します。すべてのエラーと警告を記録します。これらにはステップ 3 で対処します。

ステップ 3：ソース互換性を損なう変更とコンパイル時の変更を修正する

プロジェクトのテクノロジー領域に基づいて、参照ドキュメントを読み込みます。

参照ファイル	読み込むタイミング
references/csharp-compiler-dotnet10to11.md	常に（C# 15 コンパイラーの破壊的変更）
references/core-libraries-dotnet10to11.md	常に（すべての .NET 11 プロジェクトに適用）
references/sdk-msbuild-dotnet10to11.md	常に（SDK とビルドツールの変更）
references/aspnetcore-dotnet10to11.md	プロジェクトで ASP.NET Core（OpenAPI、Blazor）を使用している場合
references/efcore-dotnet10to11.md	プロジェクトで Entity Framework Core を使用している場合
references/cryptography-dotnet10to11.md	プロジェクトで暗号化 API、mTLS を使用している場合、または macOS を対象としている場合
references/runtime-jit-dotnet10to11.md	古いハードウェアや組み込みデバイスにデプロイする場合、または NativeAOT を使用する場合

各ビルドエラーに体系的に対処します。よくあるパターンは次のとおりです。

1. C# 15 の Span コレクション式の safe-context — Span<T>／ReadOnlySpan<T> 型のコレクション式は、declaration-block の safe-context を持つようになりました。Span コレクション式を外側のスコープにある変数に代入するコードはエラーになります。配列型を使用するか、式を適切なスコープに移動してください。

2. ref readonly デリゲート／ローカル関数には InAttribute が必要 — ref readonly を返すメソッドからデリゲートを生成する場合や、ref readonly ローカル関数を使用する場合は、System.Runtime.InteropServices.InAttribute を利用できることを確認してください。

3. 属性内の nameof(this.) — this. 修飾子を削除し、nameof(this.P) ではなく nameof(P) を使用してください。

4. コレクション式内の with()（C# 15） — with(...) はメソッド呼び出しではなく、コンストラクター引数として扱われるようになりました。with という名前のメソッドを呼び出すには、@with(...) を使用してください。

5. インターフェイスをオペランドとする動的な &&／|| — 左オペランドがインターフェイス型で、右オペランドが dynamic の &&／|| は、コンパイル時エラーになりました。具象型または dynamic にキャストしてください。

6. EF Core Cosmos の同期 I/O が廃止 — Cosmos プロバイダーでの ToList()、SaveChanges() などは、常に例外をスローします。非同期版に置き換えてください。

7. SYSLIB0063：NamedPipeClientStream の isConnected パラメーターが非推奨に — bool isConnected を受け取るコンストラクターのオーバーロードは非推奨になりました。isConnected 引数を削除し、新しい 3 パラメーターのコンストラクターを使用してください。TreatWarningsAsErrors を設定しているプロジェクトでは、ビルドに失敗します。

8. when の switch 式アームの解析 — (X.Y) when は、キャスト式ではなく、when 句を伴う定数パターンとして解析されるようになりました。そのため、既存コードのコンパイルに失敗したり、意味が変わったりすることがあります。when を使用する switch 式を確認し、必要に応じて構文を調整してください。

9. Microsoft.OpenApi v3 の破壊的変更 — Microsoft.AspNetCore.OpenApi は、Microsoft.OpenApi 3.x に依存するようになりました。Microsoft.OpenApi 型（OpenApiDocument、OpenApiSchema など）を直接使用するコードでは、コンパイルエラーが発生します。v3 アップグレードガイドに従ってください。

10. EF Core Design パッケージが推移的に参照されなくなった — Microsoft.EntityFrameworkCore.Tools と .Tasks は、.Design に依存しなくなりました。必要な場合は、PackageReference を明示的に追加してください。

11. EFOptimizeContext MSBuild プロパティが削除 — <EFScaffoldModelStage> および <EFPrecompileQueriesStage> に置き換えてください。

ステップ 4：動作の変更に対応する

これらの変更は正常にコンパイルできますが、実行時の動作が変わります。それぞれを確認し、影響を判断してください。

1. DeflateStream/GZipStream の空のペイロード — 空のペイロードでもヘッダーとフッターが書き込まれるようになりました。出力がゼロバイトかどうかをコードで確認している場合は、チェックを更新してください。

2. MemoryStream の最大容量 — 最大容量が更新され、例外の動作も変わりました。大きな MemoryStream を作成するコードや、特定の例外型に依存するコードを確認してください。

3. TAR ヘッダーのチェックサム検証 — TAR の読み取り API でチェックサムが検証されるようになりました。破損した TAR ファイルや手作業で作成した TAR ファイルは、読み取りに失敗する可能性があります。

4. ZipArchive.CreateAsync の先行読み込み — ZipArchive.CreateAsync はエントリを先行して読み込むようになりました。大きなアーカイブではメモリ使用量に影響する可能性があります。

5. Environment.TickCount の一貫性 — Windows のタイムアウト動作に合わせて一貫性が保たれるようになりました。特定のティックカウント動作に依存するコードは、調整が必要な場合があります。

6. macOS での DSA の削除 — macOS では DSA 暗号操作が例外をスローします。別のアルゴリズム（RSA、ECDSA）を使用してください。

7. Japanese Calendar の最小日付 — サポートされる最小日付が修正されました。非常に古い Japanese Calendar の日付を使用するコードに影響する可能性があります。

8. ハードウェアの最小要件 — x86/x64 のベースラインが x86-64-v2 に引き上げられました。Windows Arm64 では LSE が必要です。デプロイ先が要件を満たしていることを確認してください。

9. .NET Framework の Mono 起動ターゲット — 自動設定されなくなりました。Linux で .NET Framework アプリに Mono を使用する場合は、明示的に指定してください。

10. 未処理の BackgroundService 例外によるホストの停止 — ExecuteAsync() からの例外が伝播し、ホストがクラッシュするようになりました。アプリケーションを停止させたくないバックグラウンドサービスでは、try/catch を追加してください。

11. ZipArchive の CRC32 検証 — ZIP の読み取り時に CRC32 チェックサムが検証されるようになりました。以前は正常に処理できていた破損または途中で切り詰められたアーカイブでも、InvalidDataException がスローされるようになります。

12. TarWriter による HardLink エントリの出力 — ハードリンクされたファイルは、データを複製するのではなく HardLink エントリとして書き込まれるようになりました。.NET が生成した tar アーカイブを扱う側では、HardLink エントリに対応する必要があります。

13. AIA による証明書のダウンロードを無効化 — サーバー側のクライアント証明書検証では、デフォルトで AIA 経由の中間 CA のダウンロードが行われなくなりました。完全な証明書チェーンを事前にインストールするか、クライアントから中間証明書を送信してください。

14. Blazor Virtualize の OverscanCount のデフォルト値を変更 — OverscanCount のデフォルト値が 3 から 15 に変更されました。パフォーマンスが重要な場合は、明示的に設定してください。

15. Microsoft.Data.SqlClient 7.0 — Entra ID 認証を分離 — Azure/Entra ID 認証の依存関係がコア SqlClient パッケージから削除されました。Entra ID 認証を使用する場合は、Microsoft.Data.SqlClient.Extensions.Azure を追加してください。

16. SELECT から SqlVector<T> を除外 — ベクトルプロパティは自動読み込みされなくなりました。ベクトル値を含めるには、明示的なプロジェクションを使用してください。

17. SQLitePCLRaw の暗号化バンドルを削除 — SQLitePCLRaw 3.0 では、bundle_e_sqlcipher などの暗号化バンドルパッケージが削除されました。

18. NativeAOT の Unix ネイティブライブラリに lib プレフィックスを追加 — Linux/macOS では、出力ファイル名に lib プレフィックスが含まれるようになりました（例：libMyLib.so）。

ステップ 5：インフラストラクチャを更新する

1. Dockerfile：ベースイメージを 10.0 から 11.0 に更新します。

   # Before
   FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
   FROM mcr.microsoft.com/dotnet/aspnet:10.0
   # After
   FROM mcr.microsoft.com/dotnet/sdk:11.0 AS build
   FROM mcr.microsoft.com/dotnet/aspnet:11.0
   

2. CI/CD パイプライン：SDK バージョンの参照を更新します。global.json を使用している場合は、他のキー（rollForward やテスト構成など）を保持したまま、既存ファイル内の sdk.version を更新してください。

    {
      "sdk": {
   -    "version": "10.0.100",
   -    "rollForward": "latestFeature"
   +    "version": "11.0.100-preview.3",
   +    "rollForward": "latestFeature"
      },
      "otherSettings": {
        "...": "..."
      }
    }
   

3. ハードウェアのデプロイ先：すべてのデプロイ先が、更新されたハードウェアの最小要件（x86/x64 では x86-64-v2、Windows Arm64 では LSE）を満たしていることを確認してください。

ステップ 6：検証

1. クリーンビルドを実行します：dotnet build --no-incremental
2. すべてのテストを実行します：dotnet test
3. アプリケーションがコンテナ化されている場合は、コンテナイメージをビルドしてテストします
4. アプリケーションのスモークテストを実施し、特に次の点に注意します：
   • 空のストリームでの圧縮動作
   • TAR ファイルの読み取り（チェックサム検証と HardLink エントリ）
   • EF Core Cosmos DB 操作（非同期である必要があります）
   • macOS での DSA の使用
   • メモリを大量に消費する MemoryStream の使用
   • Span コレクション式の代入
   • BackgroundService の例外処理
   • mTLS／クライアント証明書チェーンの検証
   • Entra ID 認証を使用する EF Core SQL Server
   • Unix での NativeAOT 出力ファイル名
5. 差分を確認し、意図しない動作変更が導入されていないことを確認します

参考資料

references/ フォルダーには、技術領域ごとに整理された破壊的変更の詳細情報が含まれています。移行対象のプロジェクトに関連する参考資料のみを読み込んでください：

参考ファイル	読み込むタイミング
references/csharp-compiler-dotnet10to11.md	常に（C# 15 コンパイラーの破壊的変更）
references/core-libraries-dotnet10to11.md	常に（すべての .NET 11 プロジェクトに適用）
references/sdk-msbuild-dotnet10to11.md	常に（SDK およびビルドツールの変更）
references/aspnetcore-dotnet10to11.md	プロジェクトで ASP.NET Core を使用する場合（OpenAPI、Blazor）
references/efcore-dotnet10to11.md	プロジェクトで Entity Framework Core を使用する場合
references/cryptography-dotnet10to11.md	プロジェクトで暗号化 API、mTLS を使用する場合、または macOS を対象とする場合
references/runtime-jit-dotnet10to11.md	古いハードウェアや組み込みデバイスにデプロイする場合、または NativeAOT を使用する場合