migrate-dotnet9-to-dotnet10

.NET 9 → .NET 10 の移行

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

使用するタイミング

• TargetFramework を net9.0 から net10.0 に更新するとき
• .NET 10 SDK の更新後にビルドエラーや新しい警告を解決するとき
• .NET 10 ランタイム、ASP.NET Core 10、または EF Core 10 の動作変更に対応するとき
• CI/CD パイプライン、Dockerfile、またはデプロイスクリプトを .NET 10 用に更新するとき
• コミュニティ製の System.Linq.Async パッケージから組み込みの System.Linq.AsyncEnumerable に移行するとき

使用しないタイミング

• プロジェクトがすでに net10.0 を対象としており、問題なくビルドできる場合 — 移行は完了しています
• .NET 8 以前からアップグレードする場合 — まず migrate-dotnet8-to-dotnet9 スキルを使用して net9.0 に到達し、その後このスキルに戻って net9.0 → net10.0 の移行を行ってください
• .NET Framework から移行する場合 — これは別個の、より大規模な作業です
• .NET 10 を対象に開始する新規プロジェクトの場合（移行は不要です）

入力

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

ワークフロー

読み込まれた参照ドキュメントに基づいて直接回答してください。 破壊的変更に関する情報を得るために、ファイルシステムを検索したりウェブページを取得したりしないでください。詳細な情報は参照ドキュメントに記載されています。該当する破壊的変更を特定し、具体的な修正方法を提示してください。例外： プロジェクトの依存関係にセキュリティ脆弱性（CVE）が適用される可能性がある場合は、公開済みのセキュリティ勧告を確認してください。参照ドキュメントには、公開後に判明した CVE が含まれていない場合があります。

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

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

1. プロジェクトのビルド方法とテスト方法を特定します。ビルドスクリプト、.sln／.slnx ファイル、または個別の .csproj ファイルを確認します。
2. dotnet --version を実行して、.NET 10 SDK がインストールされていることを確認します。インストールされていない場合は、作業を停止してユーザーに伝えてください。
3. 次の項目を調べて、プロジェクトで使用されている技術分野を特定します。
   • SDK 属性：Microsoft.NET.Sdk.Web → ASP.NET Core、<UseWPF> または <UseWindowsForms> を含む Microsoft.NET.Sdk.WindowsDesktop → WPF／WinForms
   • PackageReferences：Microsoft.EntityFrameworkCore.* → EF Core、Microsoft.Data.Sqlite → Sqlite、Microsoft.Extensions.Hosting → Generic Host／BackgroundService
   • Dockerfile の有無 → コンテナー関連の変更が該当
   • P/Invoke またはネイティブ相互運用の使用 → 相互運用関連の変更が該当
   • System.Linq.Async パッケージ参照 → AsyncEnumerable への移行が必要
   • ポリモーフィズムを用いた System.Text.Json の使用 → シリアル化関連の変更が該当
4. 関連する参照ドキュメントを記録します（ステップ 3 の参照ドキュメント読み込み表を参照）。
5. 現在の net9.0 を対象にクリーンビルド（dotnet build --no-incremental を実行するか、bin／obj を削除）を行い、クリーンなベースラインを確立します。既存の警告があれば記録します。

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

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

   <TargetFramework>net9.0</TargetFramework>
   

   変更後：

   <TargetFramework>net10.0</TargetFramework>
   

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

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

3. dotnet restore を実行します。次の点を確認してください。

   • NU1510：NuGet によって直接参照が削除されました。パッケージが共有フレームワークに含まれるようになった可能性があります。その場合は、明示的な <PackageReference> を削除してください。
   • バージョンを指定していない PackageReference はエラーになります — すべての <PackageReference> に Version を指定する必要があります（または CPM を使用してください）。
   • 推移的パッケージに対する NuGet の監査（dotnet restore で推移的な依存関係も監査されるようになりました）— 新たに表示された脆弱性の警告を確認してください。

4. クリーンビルドを実行します。すべてのエラーと新しい警告を収集します。これらはステップ 3 で対処します。

ステップ 3：ビルドエラーとソース互換性のない変更を解決する

コンパイルエラーと新しい警告に、順を追って対処します。プロジェクトの種類に応じて、適切なリファレンスドキュメントを読み込みます。

プロジェクトで使用しているもの…	リファレンスを読み込む
.NET 10 プロジェクト全般	references/csharp-compiler-dotnet9to10.md
.NET 10 プロジェクト全般	references/core-libraries-dotnet9to10.md
.NET 10 プロジェクト全般	references/sdk-msbuild-dotnet9to10.md
ASP.NET Core	references/aspnet-core-dotnet9to10.md
Entity Framework Core	references/efcore-dotnet9to10.md
暗号化 API	references/cryptography-dotnet9to10.md
Microsoft.Extensions.Hosting、BackgroundService、構成	references/extensions-hosting-dotnet9to10.md
System.Text.Json、XmlSerializer、HttpClient、MailAddress、Uri	references/serialization-networking-dotnet9to10.md
Windows Forms または WPF	references/winforms-wpf-dotnet9to10.md
Docker コンテナー、単一ファイルアプリ、ネイティブ相互運用	references/containers-interop-dotnet9to10.md

確認すべき、ソース互換性に関わる主な変更：

1. System.Linq.Async の競合 — System.Linq.Async パッケージ参照を削除するか、v7.0.0 にアップグレードします。推移的に取り込まれている場合は、<ExcludeAssets>compile</ExcludeAssets> を追加します。必要に応じて、SelectAwait の呼び出しを Select に変更します。

2. 新たに追加された非推奨化の警告（SYSLIB0058–SYSLIB0062）：

   • SYSLIB0058：SslStream.KeyExchangeAlgorithm／CipherAlgorithm／HashAlgorithm を NegotiatedCipherSuite に置き換えます。古いプロパティを弱い TLS 暗号スイートの拒否に使用していた場合は、新しい API を使って同等の検証ロジックを維持してください。
   • SYSLIB0059：SystemEvents.EventsThreadShutdown を AppDomain.ProcessExit に置き換えます。
   • SYSLIB0060：Rfc2898DeriveBytes のコンストラクターを Rfc2898DeriveBytes.Pbkdf2 に置き換えます。
   • SYSLIB0061：IComparer<TSource> を受け取る Queryable.MaxBy／MinBy オーバーロードを、IComparer<TKey> を受け取るものに置き換えます。
   • SYSLIB0062：XsltSettings.EnableScript の使用を置き換えます。

3. C# 14 のプロパティアクセサーにおける field キーワード — 識別子 field は、プロパティの get／set／init アクセサー内でコンテキストキーワードになりました。field という名前のローカル変数は CS9272（エラー）を引き起こします。this. を付けずに参照される、field という名前のクラスメンバーは CS9258（警告）を引き起こします。名前を変更する（例：fieldValue）か、@field としてエスケープして修正してください。references/csharp-compiler-dotnet9to10.md を参照してください。

4. C# 14 のコンテキストキーワード extension — extension という名前の型、エイリアス、または型パラメーターは使用できません。名前を変更するか、@extension としてエスケープしてください。

5. span パラメーターを含む C# 14 のオーバーロード解決 — 配列に対する .Contains() を含む式ツリーは、Enumerable.Contains ではなく MemoryExtensions.Contains にバインドされる場合があります。配列に対する Enumerable.Reverse は、インプレースの Span 拡張メソッドに解決される場合があります。IEnumerable<T> にキャストするか、.AsEnumerable() を使用するか、静的メソッドを明示的に呼び出して修正してください。詳細は references/csharp-compiler-dotnet9to10.md を参照してください。

6. ASP.NET Core の非推奨化（該当する場合）：

   • WebHostBuilder、IWebHost、WebHost は非推奨です — Host.CreateDefaultBuilder または WebApplication.CreateBuilder に移行してください
   • IActionContextAccessor／ActionContextAccessor は非推奨です
   • WithOpenApi 拡張メソッドは非推奨です
   • IncludeOpenAPIAnalyzers プロパティは非推奨です
   • IPNetwork と ForwardedHeadersOptions.KnownNetworks は非推奨です
   • Razor のランタイムコンパイルは非推奨です
   • Microsoft.Extensions.ApiDescription.Client パッケージは非推奨です
   • Microsoft.OpenApi v2.x の破壊的変更 — Microsoft.AspNetCore.OpenApi 10.0 は、名前空間とモデルを再構成した Microsoft.OpenApi v2.x を取り込みます。OpenApiString／OpenApiAny 型は削除されました（JsonNode を使用してください）。OpenApiSecurityScheme.Reference は OpenApiSecuritySchemeReference に置き換えられました。OpenAPI モデルオブジェクトのコレクションが null の場合があり、OpenApiSchema.Nullable は削除されました。移行パターンについては references/aspnet-core-dotnet9to10.md を参照してください。

7. SDK の変更：

   • dotnet new sln の既定の形式が SLNX になりました — 従来の形式が必要な場合は --format sln を使用してください
   • ファイルレベルのディレクティブで二重引用符は使用できなくなりました
   • .NET SDK から dnx.ps1 が削除されました
   • dotnet restore では project.json がサポートされなくなりました

8. EF Core のソースコード変更（該当する場合）— 以下については references/efcore-dotnet9to10.md を参照してください。

   • ExecuteUpdateAsync が通常のラムダ式を受け入れるようになりました（式ツリー構築コードを書き換える必要があります）
   • IDiscriminatorPropertySetConvention のシグネチャが変更されました
   • IRelationalCommandDiagnosticsLogger のメソッドに logCommandText パラメーターが追加されました

9. WinForms／WPF のソースコード変更（該当する場合）：

   • WPF と WinForms の両方を参照するアプリケーションでは、MenuItem 型と ContextMenu 型を明確に区別する必要があります
   • HtmlElement.InsertAdjacentElement のパラメーター名が変更されました
   • WPF では、空の ColumnDefinitions と RowDefinitions が使用できなくなりました

10. 暗号化のソースコード変更（該当する場合）：

• MLDsa と SlhDsa のメンバー名が SecretKey から PrivateKey に変更されました（例：ExportMLDsaSecretKey → ExportMLDsaPrivateKey、SecretKeySizeInBytes → PrivateKeySizeInBytes）
• Rfc2898DeriveBytes コンストラクターは非推奨です（SYSLIB0060）— Rfc2898DeriveBytes.Pbkdf2(password, salt, iterations, hashAlgorithm, outputLength) の静的メソッドに置き換えてください
• CoseSigner.Key が null になり得るようになりました — 使用前に null かどうかを確認してください
• X509Certificate.GetKeyAlgorithmParameters() と PublicKey.EncodedParameters は null を返す場合があります
• 環境変数名が CLR_OPENSSL_VERSION_OVERRIDE から DOTNET_OPENSSL_VERSION_OVERRIDE に変更されました

修正をひとまとまり適用するたびに、再度ビルドしてください。ビルドエラーがなくなるまで繰り返してください。

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

動作の変更によってビルドエラーは発生しませんが、実行時の動作が変わる可能性があります。該当する項目をそれぞれ確認し、以前の動作に依存していたかどうかを判断してください。

影響の大きい動作の変更（先に確認してください）：

1. SIGTERM シグナルの処理が削除されました — .NET ランタイムは、デフォルトの SIGTERM ハンドラーを登録しなくなりました。SIGTERM 時に AppDomain.ProcessExit または AssemblyLoadContext.Unloading が発生することに依存している場合：

   • ASP.NET Core と Generic Host のアプリには影響しません（独自のハンドラーを登録します）
   • Generic Host を使用しないコンソールアプリとコンテナー化されたアプリでは、PosixSignalRegistration.Create(PosixSignal.SIGTERM, _ => Environment.Exit(0)) を明示的に登録する必要があります

2. BackgroundService.ExecuteAsync はバックグラウンドスレッドで最初から最後まで実行されます — 最初の await より前の同期処理によって、起動がブロックされなくなりました。起動順序が重要な場合は、そのコードを StartAsync またはコンストラクターに移すか、IHostedLifecycleService を実装してください。

3. 構成の null 値が保持されるようになりました — JSON の null 値は、空の文字列に変換されなくなりました。デフォルト以外の値で初期化されたプロパティは、null で上書きされます。構成のバインドコードを確認してください。

4. Microsoft.Data.Sqlite の DateTimeOffset の変更（すべて影響大）：

   • オフセットを指定しない GetDateTimeOffset は UTC として扱うようになりました（以前はローカル時刻として扱われていました）
   • REAL 列への DateTimeOffset の書き込みでは、最初に UTC に変換されるようになりました
   • オフセットを指定した GetDateTime は、DateTimeKind.Utc の UTC を返すようになりました
   • 回避策：一時的な回避策として AppContext.SetSwitch("Microsoft.Data.Sqlite.Pre10TimeZoneHandling", true) を使用します

5. EF Core のパラメーター化コレクション — コレクションに対する .Contains() は、JSON／OPENJSON の代わりに複数のスカラー パラメーターを使用するようになりました。大規模なコレクションでは、クエリのパフォーマンスに影響する可能性があります。回避策：UseParameterizedCollectionMode(ParameterTranslationMode.Parameter) で元に戻します。

6. Azure SQL での EF Core の JSON データ型 — Azure SQL で互換性レベルが 170 以上の場合、nvarchar(max) の代わりに json データ型を使用するようになりました。既存の列を変更するマイグレーションが生成されます。回避策：互換性レベルを 160 に設定するか、HasColumnType("nvarchar(max)") を明示的に使用します。

7. System.Text.Json のプロパティ名の競合チェック — メタデータ名（$type、$id、$ref）と競合するプロパティを持つポリモーフィック型では、InvalidOperationException がスローされるようになりました。競合するプロパティに [JsonIgnore] を追加してください。

確認が必要なその他の動作の変更：

• BufferedStream.WriteByte は暗黙的にフラッシュしなくなりました — 必要に応じて、明示的な Flush() 呼び出しを追加してください
• デフォルトのトレースコンテキスト伝播が W3C 標準に更新されました
• DriveInfo.DriveFormat は、実際の Linux ファイルシステムの種類を返すようになりました
• LDAP の DirectoryControl の解析がより厳格になりました
• デフォルトの .NET コンテナーイメージが Debian から Ubuntu に切り替わりました（Debian イメージは提供されなくなりました）
• 単一ファイルアプリは、デフォルトでは実行ファイルのディレクトリ内でネイティブ ライブラリを検索しなくなりました
• DllImportSearchPath.AssemblyDirectory はアセンブリのディレクトリのみを検索します
• MailAddress は連続するピリオドを検証するようになりました
• ブラウザーの HTTP クライアントでは、HTTP レスポンスのストリーミングがデフォルトで有効になりました
• Uri の長さ制限がなくなりました — 信頼できないソースからの過大な入力を Uri で拒否していた場合は、明示的な長さ検証を追加してください
• 既知の API エンドポイントでは Cookie によるログインリダイレクトが無効になりました（ASP.NET Core）
• XmlSerializer は [Obsolete] プロパティを無視しなくなりました — 機密データを含む可能性のある非推奨プロパティを確認し、意図しないデータの公開を防ぐために [XmlIgnore] を追加してください
• dotnet restore は推移的パッケージを監査します
• dotnet watch は標準出力ではなく標準エラーにログを出力します
• dotnet CLI コマンドは、コマンドに関係しないデータを標準エラーにログ出力します
• NuGet に関するさまざまな動作の変更があります（references/sdk-msbuild-dotnet9to10.md を参照）
• StatusStrip はデフォルトで System RenderMode を使用します（WinForms）
• TreeView のチェックボックス画像の切り詰めが修正されました（WinForms）
• DynamicResource の誤った使用によってクラッシュが発生します（WPF）

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

1. Dockerfile: ベースイメージを更新します。デフォルトのタグは Debian ではなく Ubuntu を使用するようになりました。Debian イメージは .NET 10 向けには出荷されなくなりました。

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

2. CI/CD パイプライン: SDK バージョンの参照を更新します。global.json を使用している場合は、次を更新します:

   {
     "sdk": {
       "version": "10.0.100"
     }
   }
   

3. 環境変数の名前が変更されました:

   • DOTNET_OPENSSL_VERSION_OVERRIDE が古い名前を置き換えます
   • DOTNET_ICU_VERSION_OVERRIDE が古い名前を置き換えます
   • NUGET_ENABLE_ENHANCED_HTTP_RETRY は削除されました

4. OpenSSL の要件: Unix では OpenSSL 1.1.1 以降が必須になりました。macOS では OpenSSL の暗号プリミティブはサポートされなくなりました。

5. ソリューションファイルの形式: スクリプトで dotnet new sln を使用している場合、SLNX 形式を生成するようになったことに注意してください。古い形式が必要な場合は --format sln を渡してください。

ステップ 6: 検証する

1. 完全なクリーンビルドを実行します: dotnet build --no-incremental
2. すべてのテストを実行します: dotnet test
3. アプリケーションがコンテナ化されている場合は、コンテナイメージをビルドしてテストします
4. アプリケーションのスモークテストを実行し、特に次の点に注意してください:
   • シグナル処理 / グレースフルシャットダウンの動作
   • バックグラウンドサービスの起動順序
   • null 値を使用した構成のバインド
   • Sqlite での日付/時刻の処理
   • ポリモーフィック型を使用した JSON シリアル化
   • コレクションに対して .Contains() を使用する EF Core クエリ
5. セキュリティレビュー — 移行によってセキュリティ制御が弱まっていないことを確認します:
   • SslStream API の移行 (SYSLIB0058) 後も TLS 暗号スイートの検証ロジックが維持されている
   • 機密データを含む廃止されたプロパティがシリアル化から除外されている ([XmlIgnore]、[JsonIgnore])
   • 長さのゲートとして Uri が使用されていた場合、入力検証が依然としてサイズ超過の URI を拒否する
   • 例外ハンドラーが true を返す前に、セキュリティに関連するテレメトリ (認証失敗、アクセス違反) を出力する
   • 接続文字列が、バージョン情報を漏らさない明示的な Application Name を設定している
   • dotnet restore の監査が抑制されるのではなく、対処されている
6. 差分を確認し、意図しない動作変更が導入されていないことを確認します

参照ドキュメント

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

参照ファイル	読み込むタイミング
references/csharp-compiler-dotnet9to10.md	常に (C# 14 コンパイラーの破壊的変更 — field キーワード、extension キーワード、span オーバーロード)
references/core-libraries-dotnet9to10.md	常に (すべての .NET 10 プロジェクトに適用されます)
references/sdk-msbuild-dotnet9to10.md	常に (SDK およびビルドツールの変更)
references/aspnet-core-dotnet9to10.md	プロジェクトが ASP.NET Core を使用している場合
references/efcore-dotnet9to10.md	プロジェクトが Entity Framework Core または Microsoft.Data.Sqlite を使用している場合
references/cryptography-dotnet9to10.md	プロジェクトが System.Security.Cryptography または X.509 証明書を使用している場合
references/extensions-hosting-dotnet9to10.md	プロジェクトが Generic Host、BackgroundService、または Microsoft.Extensions.Configuration を使用している場合
references/serialization-networking-dotnet9to10.md	プロジェクトが System.Text.Json、XmlSerializer、HttpClient、またはネットワーク API を使用している場合
references/winforms-wpf-dotnet9to10.md	プロジェクトが Windows Forms または WPF を使用している場合
references/containers-interop-dotnet9to10.md	プロジェクトが Docker コンテナ、単一ファイル発行、またはネイティブ相互運用 (P/Invoke) を使用している場合