新しい .NET バージョンにアップグレードする

新しい .NET バージョンは毎年リリースされます。 多くの開発者は、新しいバージョンが利用可能になるとすぐにアップグレード プロセスを開始しますが、使用しているバージョンがサポートされなくなるまで待つ開発者もいます。 アップグレード プロセスには、考慮すべき複数の側面があります。

新しい .NET バージョンにアップグレードする一般的な理由:

• 現在使用されている .NET バージョンがサポートされなくなった
• 新しいバージョンで新しいオペレーティング システムがサポートされている
• 新しいバージョンに重要な API、パフォーマンス、またはセキュリティ機能がある

開発環境をアップグレードする

新しい .NET バージョンにアップグレードする場合、.NET SDK がインストールするプライマリ コンポーネントです。 これには、更新された .NET CLI、ビルド システム、ランタイム バージョンが含まれています。

.NET Web サイトでは、サポートされているオペレーティング システムとアーキテクチャでダウンロードして使用できるインストーラーとアーカイブが提供されています。

一部のオペレーティング システムには、新しい .NET バージョンのインストールにも使用できるパッケージ マネージャーがあり、それが好ましい場合があります。

• macOS
• リナックス
• ウィンドウズ

Visual Studio では、新しい .NET SDK バージョンが自動的にインストールされます。 Visual Studio ユーザーの場合は、新しい Visual Studio バージョンにアップグレードするだけで十分です。

ソース コードをアップグレードする

アプリをアップグレードするために必要な変更は、プロジェクト ファイル内の TargetFramework プロパティを新しい .NET バージョンに更新することだけです。

その方法は次のとおりです。

• プロジェクト ファイル (*.csproj、*.vbproj、または *.fsproj ファイル) を開きます。
• <TargetFramework> プロパティの値を、たとえば、net6.0 から net8.0 に変更します。
• <TargetFrameworks> プロパティが使用されている場合は、同じパターンが適用されます。

ヒント

GitHub Copilot アプリの最新化 - アップグレード機能では、これらの変更を自動的に行うことができます。

次の手順では、新しい SDK でプロジェクト (またはソリューション) をビルドします。 追加の変更が必要な場合は、ガイドする警告とエラーが SDK によって示されます。

新しい SDK バージョンでワークロードを復元するには、dotnet workload restore を実行する必要がある場合があります。

その他のリソース:

• .NET 9 の破壊的変更
• ASP.NET Core アプリを移行する
• .NET MAUI を .NET 7 から .NET 8 にアップグレードする

バージョン固定

.NET SDK、Visual Studio、その他のコンポーネントなどの開発ツールをアップグレードすると、ビルド プロセスに影響する新しい動作、アナライザーの警告、または破壊的変更が発生する可能性があります。 バージョンにピン留めすることで、プロジェクトで特定のコンポーネントが更新されるタイミングを制御しながら、開発環境をアップグレードできます。

バージョンのピン留めには、いくつかの利点があります。

• 予測可能なビルド: 異なるマシンと CI/CD 環境間でビルド結果の一貫性を確保します。
• 段階的な導入: 新機能を一度に導入するのではなく、段階的に導入できます。
• 予期しない変更を回避する: 新しいアナライザー ルール、SDK の動作、またはパッケージ バージョンがビルド エラーの原因にならないようにします。
• チームの調整: ツールの更新時にチームを個別にアップグレードするのではなく、計画された時間に一緒にアップグレードできます。
• デバッグとトラブルシューティング: 変更されたバージョンを制御するときに、問題を簡単に分離できます。

次のセクションでは、.NET プロジェクトのさまざまなコンポーネントのバージョンを制御するためのさまざまなメカニズムについて説明します。

• global.jsonを使用して SDK のバージョンを制御する
• アナライザーの動作を制御する
• NuGet パッケージのバージョンを制御する
• MSBuild のバージョンを制御する

global.json を使用して SDK のバージョンを制御する

global.jsonファイルを使用して、プロジェクトまたはソリューションの .NET SDK バージョンをピン留 め できます。 このファイルは、.NET CLI コマンドの実行時に使用する SDK バージョンを指定し、プロジェクトが対象とするランタイム バージョンに依存しません。

ソリューションのルート ディレクトリに global.json ファイルを作成します。

dotnet new globaljson --sdk-version 9.0.100 --roll-forward latestFeature

このコマンドは、SDK をバージョン 9.0.100 以降のパッチまたは機能バンドにピン留めする次の global.json ファイルを 9.0 メジャー バージョン内に作成します。

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

rollForward ポリシーは、正確なバージョンが使用できない場合の SDK バージョンの選択方法を制御します。 この構成により、Visual Studio をアップグレードするか、新しい SDK をインストールするときに、 global.json ファイルを明示的に更新するまで、プロジェクトで SDK 9.0.x が引き続き使用されるようになります。

詳細については、「 global.json の概要」を参照してください。

アナライザーの動作を制御する

コード アナライザーは、新しい警告を導入したり、バージョン間の動作を変更したりできます。 AnalysisLevel プロパティを使用して、アナライザーのバージョンを制御して一貫性のあるビルドを維持できます。 このプロパティを使用すると、特定のバージョンのアナライザー ルールにロックできます。これにより、SDK をアップグレードするときに新しいルールが導入されなくなります。

<PropertyGroup>
  <AnalysisLevel>9.0</AnalysisLevel>
</PropertyGroup>

9.0に設定すると、.NET 10 SDK を使用している場合でも、.NET 9 に付属するアナライザー ルールのみが有効になります。 これにより、新しい .NET 10 アナライザー ルールに対処する準備ができるまで、ビルドに影響を与えるのを防ぐことができます。

詳細については、「 AnalysisLevel」を参照してください。

NuGet パッケージのバージョンを制御する

プロジェクト間でパッケージ バージョンを一貫して管理することで、予期しない更新を防ぎ、信頼性の高いビルドを維持できます。

• パッケージ ロック ファイル
• 中央パッケージ管理
• パッケージ ソース マッピング

パッケージ ロック ファイル

パッケージ ロック ファイルを使用すると、パッケージの復元操作で、異なる環境間でまったく同じパッケージ バージョンが使用されるようになります。 ロック ファイル (packages.lock.json) は、すべてのパッケージとその依存関係の正確なバージョンを記録します。

プロジェクト ファイルでロック ファイルを有効にします。

<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>

ロック ファイルが最新でない場合にビルドが失敗することを確認するには:

<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
  <RestoreLockedMode>true</RestoreLockedMode>
</PropertyGroup>

ロック ファイルを有効にした後、 dotnet restore を実行して packages.lock.json ファイルを生成します。 このファイルをソース管理にコミットします。

中央パッケージ管理

中央パッケージ管理 (CPM) を使用すると、ソリューション内のすべてのプロジェクトのパッケージ バージョンを 1 か所で管理できます。 この方法により、バージョン管理が簡素化され、プロジェクト間の一貫性が確保されます。

ソリューション ルートに Directory.Packages.props ファイルを作成します。

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

  <ItemGroup>
    <PackageVersion Include="Azure.Identity" Version="1.17.0" />
    <PackageVersion Include="Microsoft.Extensions.AI" Version="9.10.1" />
  </ItemGroup>
</Project>

プロジェクト ファイルで、バージョンを指定せずにパッケージを参照します。

<ItemGroup>
  <PackageReference Include="Azure.Identity" />
  <PackageReference Include="Microsoft.Extensions.AI" />
</ItemGroup>

パッケージのソース マッピング

パッケージ ソース マッピングを使用すると、特定のパッケージに使用する NuGet フィードを制御できるため、セキュリティと信頼性が向上します。

nuget.config ファイルでソース マッピングを構成します。

<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso" value="https://contoso.com/packages/" />
  </packageSources>

  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="contoso">
      <package pattern="Contoso.*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

この構成により、 Contoso. 以降のすべてのパッケージは contoso フィードからのみ復元され、他のパッケージは nuget.orgから取得されます。

詳細については、「 NuGet パッケージの復元」を参照してください。

MSBuild のバージョンを制御する

Visual Studio では、複数のバージョンのサイド バイ サイド インストールがサポートされています。 たとえば、Visual Studio 2026 と Visual Studio 2022 を同じコンピューターにインストールできます。 各 Visual Studio バージョンには、対応する .NET SDK が含まれています。 Visual Studio を更新すると、付属の SDK バージョンも更新されます。 ただし、 .NET ダウンロード ページとは別にインストールすることで、古いバージョンの SDK を引き続き使用できます。

MSBuild のバージョンは、Visual Studio のバージョンに対応しています。 たとえば、Visual Studio 2022 バージョン 17.8 には MSBuild 17.8 が含まれています。 .NET SDK には、MSBuild も含まれています。 dotnet buildを使用する場合は、global.jsonで指定された SDK または最新のインストール済み SDK に含まれる MSBuild バージョンを使用します。

特定の MSBuild バージョンを使用するには:

• global.json で指定されたピン留めされた SDK バージョンと一緒に dotnet build を使用します。
• 適切な Visual Studio 開発者コマンド プロンプトを起動し、その Visual Studio バージョンの MSBuild の環境を設定します。
• 特定の Visual Studio インストール (たとえば、 "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe") から MSBuild を直接呼び出します。

詳細については、 .NET SDK、MSBuild、Visual Studio のバージョン管理に関するページを参照してください。

継続的インテグレーション (CI) を更新する

CI パイプラインは、プロジェクト ファイルや Dockerfile と同様の更新プロセスに従います。 通常、バージョン値のみを変更すれば、CI パイプラインを更新できます。

ホスティング環境を更新する

アプリケーションをホストするために使用されるパターンは多数あります。 ホスティング環境に .NET ランタイムが含まれている場合は、新しいバージョンの .NET ランタイムをインストールする必要があります。 Linux では、依存関係をインストールする必要がありますが、通常、.NET バージョン間で変更されることはありません。

コンテナーの場合、FROM ステートメントを、新しいバージョン番号を含むように変更する必要があります。

次の Dockerfile の例では、ASP.NET Core 9.0 イメージのプルを示します。

FROM mcr.microsoft.com/dotnet/aspnet:9.0

Azure App Service のようなクラウド サービスでは、構成の変更が必要です。

こちらも参照ください

• .NET 10 での破壊的変更
• ASP.NET Core アプリを移行する