dotnet-version-upgrade

dotnet-version-upgrade

.NET のバージョンアップグレードを計画し、実行するための包括的なガイドです。このスキルは、[skill:dotnet-version-detection] の構造化された出力（現在の TFM、SDK バージョン、プレビュー フラグ）を受け取り、定義済みの 3 つのアップグレードレーンに基づいて、実行可能なアップグレードの指針を提供します。TFM の移行、パッケージの更新、破壊的変更の検出、非推奨 API の置き換え、テストによる検証を扱います。

対象外： TFM の検出ロジック（[skill:dotnet-version-detection] が担当）、マルチターゲットプロジェクトのセットアップとポリフィル戦略（[skill:dotnet-multi-targeting] を参照）、クラウドデプロイの構成、CI/CD パイプラインの変更。

相互参照：[skill:dotnet-version-detection] では TFM の解決とバージョンマトリックスを、[skill:dotnet-multi-targeting] では移行時に下位互換性を維持するためのポリフィル優先のマルチターゲット戦略を扱います。

---

アップグレードレーン

プロジェクトの要件とエコシステムの制約に基づいて、適切なアップグレードレーンを選択してください。

レーン	パス	用途	リスクレベル
本番環境（既定）	net8.0 -> net10.0	LTS から LTS への移行。ほとんどのアプリに推奨	低 -- 両バージョンとも LTS で、サポート期間が長い
段階的な本番環境向け移行	net8.0 -> net9.0 -> net10.0	エコシステムの依存関係により段階的な移行が必要な場合	中 -- 中間の STS バージョンはサポート期間が短い
実験用	net10.0 -> net11.0 (preview)	今後の機能を本番環境以外で試す場合	高 -- プレビュー API は変更または削除される可能性がある

レーン選択の判断フロー

1. NuGet の依存関係はすべて、移行先の LTS で利用できますか？ はい -> 本番環境向けレーン（LTS から LTS へ直接移行）。
2. 中間バージョンが必要な依存関係はありますか？ はい -> 段階的な本番環境向け移行レーン。
3. 研究開発または概念実証のためにプレビュー機能を試しますか？ はい -> 実験用レーン。

---

本番環境向けレーン：LTS から LTS へ（net8.0 -> net10.0）

推奨される既定のアップグレードパスです。.NET 8 と .NET 10 はどちらも長期サポート（LTS）リリースであり、文書化された破壊的変更に基づいて安定した移行を行えます。

アップグレードチェックリスト

ステップ 1：プロジェクトファイルの TFM を更新する

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
</PropertyGroup>


<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
</PropertyGroup>

共有プロパティを使用するソリューションの場合：

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
</PropertyGroup>

ステップ 2：global.json の SDK バージョンを更新する

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestFeature"
  }
}

ステップ 3：NuGet パッケージを更新する

dotnet-outdated を使用して古いパッケージを検出し、TFM との互換性のために更新が必要なパッケージを特定します。

# Install dotnet-outdated as a global tool
dotnet tool install -g dotnet-outdated-tool

# Check for outdated packages across the solution
dotnet outdated

# Check a specific project
dotnet outdated MyProject/MyProject.csproj

# Auto-upgrade to latest stable versions
dotnet outdated --upgrade

# Upgrade only to the latest minor/patch (safer)
dotnet outdated --upgrade --version-lock major

ASP.NET Core 共有フレームワークのパッケージについては、バージョン参照を移行先の TFM に合わせて更新します。

<ItemGroup>
  
  <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.*" />
  <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.*" />
</ItemGroup>

ステップ 4：破壊的変更を確認する

# Build to surface warnings and errors
dotnet build --warnaserror

# Run analyzers for deprecated API usage
dotnet build /p:TreatWarningsAsErrors=true

公式の破壊的変更一覧を確認してください。

• .NET 9 の破壊的変更
• .NET 10 の破壊的変更

ステップ 5：非推奨 API を置き換える

net8.0 から net10.0 への移行時によく使われる置き換え：

非推奨	置き換え	備考
BinaryFormatter	System.Text.Json または MessagePack	BinaryFormatter は net9.0 以降で PlatformNotSupportedException をスローします
Thread.Abort()	CancellationToken による協調的キャンセル	Thread.Abort() は PlatformNotSupportedException をスローします
WebRequest / HttpWebRequest	IHttpClientFactory を介した HttpClient	非推奨（SYSLIB0014）のため、HttpClient に移行してください

推奨される最新化（非推奨ではありませんが、パフォーマンスと AOT 対応性が向上します）：

パターン	改善策	備考
ソース生成を使わない Regex	[GeneratedRegex] 属性	ソース生成された正規表現は高速で、AOT に対応しています

ステップ 6：テストを実行して検証する

# Run full test suite
dotnet test --configuration Release

# Enable trim/AOT analyzers to surface compatibility warnings without publishing
dotnet build --configuration Release /p:EnableTrimAnalyzer=true /p:EnableAotAnalyzer=true

.NET Upgrade Assistant

.NET Upgrade Assistant は、移行プロセスの一部を自動化します。プロジェクト数が多い大規模なソリューションで特に役立ちます。

# Install as a global tool
dotnet tool install -g upgrade-assistant

# Analyze a project (non-destructive, reports recommendations)
upgrade-assistant analyze MyProject/MyProject.csproj

# Perform the upgrade (modifies files)
upgrade-assistant upgrade MyProject/MyProject.csproj

Upgrade Assistant を使用する場合：

• プロジェクト数が多く、依存関係グラフが複雑な大規模なソリューション
• レガシーな .NET Framework から最新の .NET への移行
• アップグレードを確定する前に、包括的な依存関係分析が必要な場合

制限事項：

• すべての破壊的変更に対応できるとは限らないため、手動でのレビューが引き続き必要です
• カスタムの MSBuild 拡張機能やサードパーティ製のビルドツールには、手動での調整が必要になる場合があります
• ランタイムの動作の違いは更新されないため、テストカバレッジが不可欠です
• 依存関係が少ない小規模なプロジェクトでは不要です（TFM を手動で更新するほうが簡単です）

---

本番環境向けの段階的な移行ルート：net8.0 -> net9.0 -> net10.0

エコシステム上の制約によって LTS から LTS への直接移行が妨げられる場合は、段階的な移行ルートを使用してください。.NET 9（STS）を経由することで、段階的な移行が可能になります。

.NET 9 を経由して段階的に移行する場合

• サードパーティパッケージとの互換性： 重要な依存関係が net9.0 のみをサポートしていて（net10.0 はまだサポートしていない）、今すぐ net8.0 からアップグレードする必要がある場合。
• 破壊的変更の範囲が広い： net8.0 から net10.0 への移行で発生する破壊的変更が一度に対処するには多すぎる場合。段階的に進めることでリスクを軽減できます。
• 段階的な検証： 次のステップに進む前に、各ステップで動作の変更を検証したい場合。

.NET 9 の概要

.NET 9 は標準サポート期間（STS）のリリースです。

• GA： 2024 年 11 月
• サポート終了： 2026 年 5 月（GA から 18 か月後）
• C# バージョン： C# 13

.NET 9 はサポート終了が近づいているため、net9.0 で移行を止めないでください。最初の移行を始める前に、2 回目の移行（net9.0 -> net10.0）を計画してください。

段階的アップグレードのチェックリスト

ステップ 1：net8.0 -> net9.0

1. .csproj / Directory.Build.props で TFM を net9.0 に更新します
2. global.json を SDK 9.0.xxx に更新します
3. dotnet outdated --upgrade を実行してパッケージを更新します
4. .NET 9 の破壊的変更を確認します
5. BinaryFormatter -> System.Text.Json など、SYSLIB の診断や CS0618 の警告で指摘された非推奨 API を置き換えます
6. dotnet test --configuration Release を実行して検証します
7. ステージング環境にデプロイし、監視しながら本番環境で検証します

ステップ 2：net9.0 -> net10.0

1. .csproj / Directory.Build.props で TFM を net10.0 に更新します
2. global.json を SDK 10.0.xxx に更新します
3. 再度 dotnet outdated --upgrade を実行します
4. .NET 10 の破壊的変更を確認します
5. net9.0 から net10.0 の間に導入された追加の非推奨 API を置き換えます
6. dotnet test --configuration Release を実行して検証します
7. ステージング環境にデプロイし、net9.0 固有の回避策を削除します

タイムラインの指針： .NET 9 のサポート期間内（2026 年 5 月より前）に、両方のステップを完了してください。サポート対象外の STS リリースで本番ワークロードを実行すると、セキュリティパッチが適用されていない脆弱性にさらされます。

---

実験的な移行ルート：net10.0 -> net11.0（プレビュー）

今後の機能を本番以外の環境で試すためのルートです。.NET 11 は現在プレビュー段階であり、API は GA の前に変更または削除される可能性があります。

ガードレール

• 本番環境では使用しないでください。 プレビューを対象とするコードを本番環境にデプロイしないでください。
• ブランチまたはプロジェクトを分けてください。 実験的な作業を本番コードベースから分離してください。
• プレビュー SDK を固定してください。 global.json を使用して特定のプレビュー SDK バージョンを固定し、プレビュー間で予期しない動作変更が起きないようにしてください。
• プレビュー間の破壊的変更を想定してください。 [RequiresPreviewFeatures] とマークされた API は、プレビューリリース間で形が変わる可能性があります。

プレビュー機能を有効にする

ステップ 1：プレビュー SDK をインストールする

# Verify installed SDKs
dotnet --list-sdks

# Example: 11.0.100-preview.1.xxxxx should appear

ステップ 2：global.json でプレビュー SDK を指定する

{
  "sdk": {
    "version": "11.0.100-preview.1.25120.13",
    "rollForward": "disable"
  }
}

プレビュー間で SDK バージョンが自動的に進むのを防ぐには、"rollForward": "disable" を使用します。

ステップ 3：TFM を設定してプレビュー機能を有効にする

<PropertyGroup>
  <TargetFramework>net11.0</TargetFramework>
  <LangVersion>preview</LangVersion>
  <EnablePreviewFeatures>true</EnablePreviewFeatures>
</PropertyGroup>

ステップ 4：runtime-async を有効にする（任意）

runtime-async は、async/await をコンパイラーが生成する状態マシンからランタイムレベルの実行に移すことで、割り当てを減らし、非同期処理が多いワークロードのパフォーマンスを向上させます。

<PropertyGroup>
  <TargetFramework>net11.0</TargetFramework>
  <LangVersion>preview</LangVersion>
  <EnablePreviewFeatures>true</EnablePreviewFeatures>
  <Features>$(Features);runtime-async=on</Features>
</PropertyGroup>

runtime-async を使用するには、EnablePreviewFeatures と Features フラグの両方が必要です。これは実験的な機能であり、GA までに大きく変更される可能性があります。

実験的機能へのアップグレードチェックリスト

1. .NET 11 プレビュー SDK をインストールし、"rollForward": "disable" を指定して global.json で固定します
2. TFM を net11.0 に更新し、<LangVersion>preview</LangVersion> と <EnablePreviewFeatures>true</EnablePreviewFeatures> を設定します
3. dotnet outdated を実行して、パッケージがプレビュー TFM と互換性があるか確認します
4. ビルドして警告を確認します。プレビュー SDK では、新しい SYSLIB 診断や CA2252（プレビュー機能の使用）が表示されることがあります
5. 新しいアナライザーのバージョンで検出された非推奨 API を置き換えます
6. dotnet test を実行して検証します。サードパーティ製パッケージの一部がプレビュー TFM に対応していない可能性があります
7. 将来の本番環境へのアップグレード計画に備えて、確認結果を記録します

.NET 11 プレビューで試すこと

機能	分野	備考
Runtime-async	パフォーマンス	ランタイムレベルの Async/await。明示的な有効化が必要
Zstandard compression	I/O	System.IO.Compression.Zstandard。Brotli より 2～7 倍高速
BFloat16	数値演算	AI/ML ワークロード向けの System.Numerics.BFloat16
Happy Eyeballs	ネットワーク	デュアルスタック IPv4/IPv6 用の ConnectAlgorithm.Parallel
C# 15 preview features	言語	コレクション式の引数（with() 構文）
CoreCLR on WASM	ランタイム	Blazor WASM 向けの Mono の実験的な代替

---

破壊的変更の検出

アップグレード時に破壊的変更を特定し、解決するための体系的なアプローチです。

ビルド時の検出

# Clean build to surface all warnings (not just incremental)
dotnet clean && dotnet build --no-incremental

# Treat warnings as errors to catch deprecation notices
dotnet build /p:TreatWarningsAsErrors=true

# List specific obsolete API warnings
dotnet build 2>&1 | grep -E "CS0618|CS0612"

• CS0618：メッセージ付きの [Obsolete] メンバーの使用
• CS0612：メッセージなしの [Obsolete] メンバーの使用
• CS8073：式が常に同じ値に評価される（型の動作の変更）

アナライザーの診断

.NET アナライザーを有効にして、追加の問題を検出します。

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
  <AnalysisLevel>latest-recommended</AnalysisLevel>
</PropertyGroup>

アップグレードで重要なアナライザーのカテゴリ：

• CA1422：プラットフォーム互換性（対象プラットフォームで API が削除されています）
• CA1416：ガードなしでのプラットフォーム固有 API の使用
• CA2252：プレビュー機能の使用許可
• SYSLIB0XXX：システム API の非推奨に関する診断（例：BinaryFormatter の SYSLIB0011）

API 差分ツール

ライブラリの作成者は、API 互換性ツールを使用して公開 API の変更を検証します。

# Package validation detects breaking changes against a baseline
dotnet pack /p:EnablePackageValidation=true /p:PackageValidationBaselineVersion=1.0.0

# Standalone API comparison
dotnet tool install -g Microsoft.DotNet.ApiCompat.Tool
apicompat --left-assembly bin/Release/net8.0/MyLib.dll \
          --right-assembly bin/Release/net10.0/MyLib.dll

抑制ファイルや CI 統合を含む、API 互換性検証ワークフローの詳細については、[skill:dotnet-multi-targeting] を参照してください。

---

パッケージ更新の戦略

dotnet-outdated

dotnet-outdated ツールを使用すると、パッケージの古さを包括的に把握できます。

# Install
dotnet tool install -g dotnet-outdated-tool

# Show all outdated packages with current vs latest versions
dotnet outdated

# Lock major version, show only minor/patch updates (safer incremental upgrades)
dotnet outdated --version-lock major

# Auto-upgrade with version locking to avoid unexpected major bumps
dotnet outdated --upgrade --version-lock major

# Output as JSON for CI integration
dotnet outdated --output-format json

Central Package Management

Central Package Management（Directory.Packages.props）を使用するソリューションでは、バージョンを一元的に更新します。

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    
    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.*" />
    <PackageVersion Include="Microsoft.Extensions.Http" Version="10.*" />
    <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.*" />
    
    <PackageVersion Include="Serilog" Version="4.*" />
  </ItemGroup>
</Project>

Directory.Packages.props は、プロジェクトディレクトリから階層を上にたどって解決されます。モノレポ構成では、ネストされた Directory.Packages.props ファイルがルートレベルの設定を上書きしていないことを確認してください。

ASP.NET Core 共有フレームワークパッケージ

ASP.NET Core 共有フレームワークパッケージのメジャーバージョンは、対象の TFM と一致させる必要があります。有効な方法は 2 つあります。

<ItemGroup>
  
  <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.*" />

  
  <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.1" />
</ItemGroup>

再現性の高い CI には固定バージョンが推奨されます。探索的なアップグレードでは、浮動バージョンが役立ちます。いずれの場合も、メジャーバージョンは TFM と一致している必要があります（例：net10.0 では 10.x）。

---

エージェントの注意点

1. エコシステムとの互換性を検証せずに .NET 9 を飛ばさないでください。 LTS から LTS への移行（net8.0 -> net10.0）が推奨されるデフォルトですが、一部のサードパーティパッケージでは、中間段階として net9.0 のみをサポートしている場合があります。移行先を選ぶ前に、パッケージの互換性を確認してください。

2. プレビュー SDK で本番ワークロードを実行しないでください。 .NET 11 のプレビュー API は不安定であり、プレビューリリース間で変更されます。実験的な作業は、プレビュー SDK のバージョンを固定した個別のブランチまたはプロジェクトに分離してください。

3. .NET 9 STS のサポート期間を12か月と決めつけないでください。 STS のライフサイクルは GA から18か月です。.NET 9 の GA は2024年11月だったため、サポート終了は2026年5月です。リリース年ではなく、実際の GA 日から必ず計算してください。

4. ASP.NET 共有フレームワークパッケージのメジャーバージョンを TFM に合わせてください。 Microsoft.AspNetCore.Mvc.Testing のようなパッケージは、メジャーバージョンをプロジェクトの TFM に合わせる必要があります（例：net10.0 には 10.x）。決定論的な CI を実現するには正確なバージョンを固定し、探索的なアップグレード中はワイルドカード（例：10.*）を使用してください。

5. TFM の検出を再実装しないでください。 このスキルは [skill:dotnet-version-detection] の構造化された出力を使用します。現在のバージョンを特定するために .csproj ファイルを解析せず、検出スキルの出力（TFM、C# バージョン、SDK バージョン、警告）を使用してください。

6. dotnet-outdated --upgrade を完全な解決策とみなさないでください。 パッケージのバージョンは更新されますが、それらのパッケージ内の破壊的な API 変更には対応しません。パッケージのアップグレード後は、必ずビルドとテストを行い、変更履歴を確認してください。

7. プレビュー SDK で "rollForward": "latestMajor" を使用しないでください。 これにより、破壊的変更を含む別のプレビューバージョンに気付かないまま進む可能性があります。再現可能なビルドを維持するため、プレビュー SDK では "rollForward": "disable" を使用してください。

8. Directory.Packages.props の階層を忘れないでください。 モノレポ構造では、ネストされた Directory.Packages.props ファイルが親階層の設定を上書きします。アップグレード時には、プロジェクトディレクトリから上位階層を検索し、パッケージの解決に影響する可能性があるすべての Directory.Packages.props ファイルを見つけてください。

9. アップグレード時に SYSLIB 診断コードを無視しないでください。 これらのシステムレベルの非推奨警告（BinaryFormatter の SYSLIB0011、WebRequest の SYSLIB0014 など）は、単なるコンパイル時の警告ではなく、新しい TFM では実行時に例外がスローされる API を示しています。

---

前提条件

• 対象 TFM 用の .NET SDK がインストールされていること（例：net10.0 へのアップグレードには .NET 10 SDK）
• dotnet-outdated-tool（パッケージの古さの検出用）：dotnet tool install -g dotnet-outdated-tool
• upgrade-assistant（任意、自動移行用）：dotnet tool install -g upgrade-assistant
• [skill:dotnet-version-detection] の出力（現在の TFM、SDK バージョン、プレビューフラグ）

---

参考資料

最終確認日：2026-02-12

• .NET のサポートポリシーとライフサイクル
• .NET 9 の破壊的変更
• .NET 10 の破壊的変更
• .NET Upgrade Assistant
• dotnet-outdated ツール
• 中央パッケージ管理
• ターゲットフレームワークモニカー
• .NET アナライザーの概要
• パッケージの検証