SDK スタイルのプロジェクトでのターゲット フレームワーク

アプリまたはライブラリでフレームワークをターゲットに設定するときは、アプリまたはライブラリで使用できるようにする API のセットを指定します。 プロジェクト ファイルでターゲット フレームワークを指定するには、ターゲット フレームワーク モニカー (TFM) を使用します。

アプリまたはライブラリでは、.NET Standard のバージョンをターゲットにできます。 .NET Standard のバージョンは、.NET のすべての実装で標準化された API のセットを表します。 たとえば、ライブラリは、.NET Standard 1.6 をターゲットにして、.NET Core と .NET Framework で機能する API に同じコードベースを使ってアクセスできます。

また、アプリまたはライブラリは、.NET の特定の実装をターゲットにして、実装固有の API にアクセスすることもできます。 たとえば、Xamarin.iOS (Xamarin.iOS10 など) をターゲットにするアプリからは Xamarin が提供する iOS 10 用の iOS API ラッパーにアクセスでき、ユニバーサル Windows プラットフォーム (UWP、uap10.0) をターゲットにするアプリからは Windows 10 を実行するデバイス用にコンパイルできる API にアクセスできます。

.NET Framework などの一部のターゲット フレームワークでは、API はフレームワークがシステムにインストールするアセンブリによって定義され、アプリケーション フレームワーク API (ASP.NET など) を含む場合があります。

パッケージベースのターゲット フレームワーク (.NET 5+、.NET Core、.NET Standard など) では、API はアプリまたはライブラリに含まれる NuGet パッケージによって定義されます。

最新バージョン

次の表では、最も一般的なターゲット フレームワーク、それらの参照方法、およびそれらが実装する .NET Standard のバージョンを定義します。 これらのターゲット フレームワークのバージョンは、最新の安定したバージョンです。 プレリリース バージョンは記載されていません。 "ターゲット フレームワーク モニカー" (TFM) は、.NET アプリまたはライブラリのターゲット フレームワークを指定するための標準化されたトークン形式です。

サポート対象のターゲット フレームワーク

ターゲット フレームワークは、通常、TFM によって参照されます。 次の表に、.NET SDK および NuGet クライアントによってサポートされるターゲット フレームワークを示します。 同等のものがかっこ内に示されています。 たとえば、win81 は netcore451 と同等の TFM です。

* .NET 5 以降の TFM には、オペレーティング システム固有のバリエーションがいくつか含まれています。 詳細については、次のセクション「.NET 5+ OS 固有の TFM」を参照してください。

.NET 5+ OS 固有の TFM

net5.0、net6.0、net7.0、net8.0、net.0の TFM には、さまざまなプラットフォームで動作するテクノロジが含まれています。 "OS 固有の TFM" を指定すると、オペレーティング システムに固有の API がアプリで使用できるようになります (Windows フォームや iOS バインディングなど)。 OS 固有の TFM は、ベース TFM で使用可能なすべての API (net9.0 TFM など) も継承します。

.NET 5 で、net5.0-windows OS 固有の TFM が導入されました。これには、WinForms、WPF、UWP の各 API 用の Windows 固有のバインドが含まれています。 .NET 6 以降のバージョンには、OS 固有の TFM が追加されています (例: net6.0-ios)。

次の表に、.NET 5+ TFM の互換性を示します。

異なるプラットフォーム間でアプリを移植可能にしつつ、OS 固有の API に引き続きアクセスするために、OS 固有の複数の TFM をターゲットにして、#if プリプロセッサ ディレクティブを使用して OS 固有の API 呼び出しに対してプラットフォーム ガードを追加することができます。 使用可能なシンボルの一覧については、「プリプロセッサ シンボル」 を参照してください。

推奨されるターゲット

次のガイドラインを使用して、アプリで使用する TFM を決定します。

• 複数のプラットフォームに移植可能なアプリの場合、ベース TFM (net9.0 など) をターゲットにする必要があります。 これにはほとんどのライブラリと、ASP.NET Core と Entity Framework も含まれます。
• プラットフォーム固有のライブラリの場合、プラットフォーム固有のフレーバーをターゲットにする必要があります。 たとえば、WinForms プロジェクトと WPF プロジェクトは net9.0-windows をターゲットにする必要があります。
• クロスプラットフォーム アプリケーション モデル (Xamarin Forms、ASP.NET Core) とブリッジ パック (Xamarin Essentials) の場合、少なくともベース TFM (net9.0 など) をターゲットにする必要がありますが、さらに多くの API または機能を利用するために、プラットフォーム固有の追加のフレーバーをターゲットとすることもできます。

TFM 内の OS バージョン

OS 固有の TFM の末尾でオプションの OS バージョンを指定することもできます (例: net6.0-ios15.0)。 バージョンによって、アプリまたはライブラリで使用できる API を指定します。 これは、アプリまたはライブラリで実行時にサポートされる OS バージョンの制御は行いません。 これは、プロジェクトのコンパイルに使用する参照アセンブリを選択し、NuGet パッケージからアセットを選択するために使用されます。 このバージョンは、実行時の OS バージョンと区別するために、"プラットフォーム バージョン" または "OS API バージョン" と考えてください。

OS 固有の TFM でプラットフォーム バージョンが明示的に指定されていない場合は、ベース TFM とプラットフォーム名から推論できる暗黙の値を持ちます。 たとえば、.NET 6 での Android の既定のプラットフォーム値は 31.0 です。これは、net6.0-android が正規の net6.0-android31.0 TFM の短縮形であることを意味しています。 新しいベース TFM の暗黙のプラットフォーム バージョンはより新しくなる可能性があります。たとえば、将来の net8.0-android TFM は net8.0-android34.0 にマップされる可能性があります。 この短縮形はプロジェクト ファイル内での使用のみを目的としており、NuGet などの他のツールに渡される前に、.NET SDK の MSBuild ターゲットによって正規の形式に拡張されます。

次の表に、各 .NET リリースの既定のターゲット プラットフォーム値 (TPV) を示します。

.NET SDK は、新しいバージョンのベース TFM を使用せずに、個別のプラットフォーム用に新しくリリースされた API をサポートできるように設計されています。 これにより、.NET のメジャー リリースを待つことなく、プラットフォーム固有の機能にアクセスできます。 TFM のプラットフォーム バージョンをインクリメントすることで、これらの新しくリリースされた API にアクセスできます。 たとえば、Android プラットフォームで .NET 6.0.x SDK の更新プログラムに API level 32 API が追加された場合は、TFM net6.0-android32.0 を使用してアクセスできます。

優先順位

アプリが、異なる TFM の複数のアセットを含むパッケージを参照する場合、バージョン番号が近いアセットが優先されます。 たとえば、アプリが net6.0-ios をターゲットとし、パッケージが net6.0 と net5.0-ios のアセットを提供する場合、net6.0 のアセットが使用されます。 詳細については、「優先順位」を参照してください。

以前のバージョンの OS をサポートする

プラットフォーム固有のアプリまたはライブラリはその OS の特定のバージョンの API に対してコンパイルされますが、プロジェクト ファイルに SupportedOSPlatformVersion プロパティを追加することで、以前のバージョンの OS と互換性を持たせることができます。 SupportedOSPlatformVersion プロパティにより、アプリまたはライブラリを実行するために必要な最小 OS バージョンを指定できます。 この最小のランタイム OS バージョンをプロジェクトで明示的に指定しない場合は、既定で TFM のプラットフォーム バージョンが使用されます。

以前のバージョンの OS でアプリを正常に実行するために、そのバージョンの OS には存在しない API を呼び出すことはできません。 ただし、新しい API の呼び出しにガードを追加して、その API がサポートされているバージョンの OS で実行する場合にのみ呼び出されるようにすることができます。 このパターンを使用すると、新しいバージョンの OS での実行時には新しい OS 機能を利用しながら、以前のバージョンの OS での実行もサポートされるようにアプリまたはライブラリを設計することができます。

SupportedOSPlatformVersion の値 (明示的でも既定値でも) はプラットフォーム互換性アナライザーによって使用され、新しい API へのガードなしの呼び出しが検出されて警告されます。 これは、プロジェクトのコンパイル済みアセンブリに UnsupportedOSPlatformAttribute アセンブリ属性として書き込まれます。これにより、プラットフォーム互換性アナライザーで、より小さい SupportedOSPlatformVersion 値でのプロジェクトからそのアセンブリの API へのガードなしの呼び出しを検出できるようになります。 プラットフォームによっては、SupportedOSPlatformVersion 値がプラットフォーム固有のアプリのパッケージ化とビルド プロセスに影響します。これはそれらのプラットフォームに関するドキュメントで説明されています。

TargetFramework および SupportedOSPlatformVersion MSBuild プロパティを使用して、アプリまたはライブラリが iOS 15.0 API にアクセスできるが、iOS 13.0 以降での実行がサポートされていることを指定するプロジェクト ファイル例の抜粋を次に示します。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0-ios15.0</TargetFramework>
    <SupportedOSPlatformVersion>13.0</SupportedOSPlatformVersion>
  </PropertyGroup>
  ...

</Project>

ターゲット フレームワークを指定する方法

ターゲット フレームワークはプロジェクト ファイルで指定します。 単一のターゲット フレームワークを指定するときは、TargetFramework 要素を使用します。 次のコンソール アプリ プロジェクト ファイルは、.NET 9 をターゲットにする方法を示しています。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

</Project>

複数のターゲット フレームワークを指定するときは、各ターゲット フレームワークに対するアセンブリを条件付きで参照できます。 コードでは、プリプロセッサ シンボル と if-then-else ロジックを使うことで、これらのアセンブリに対して条件付きでコンパイルできます。

次のライブラリ プロジェクトでは、.NET Standard (netstandard1.4) と .NET Framework (net40 および net45) の API がターゲットにされています。 ターゲット フレームワークが複数あるときは、複数形の TargetFrameworks 要素を使用します。 ライブラリが 2 つの .NET Framework TFM に対してコンパイルされる場合、Condition 属性には実装固有のパッケージが含まれます。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFrameworks>netstandard1.4;net40;net45</TargetFrameworks>
  </PropertyGroup>

  <!-- Conditionally obtain references for the .NET Framework 4.0 target -->
  <ItemGroup Condition=" '$(TargetFramework)' == 'net40' ">
    <Reference Include="System.Net" />
  </ItemGroup>

  <!-- Conditionally obtain references for the .NET Framework 4.5 target -->
  <ItemGroup Condition=" '$(TargetFramework)' == 'net45' ">
    <Reference Include="System.Net.Http" />
    <Reference Include="System.Threading.Tasks" />
  </ItemGroup>

</Project>

ライブラリまたはアプリ内で、プリプロセッサ ディレクティブを使用して各ターゲット フレームワーク用にコンパイルするための条件付きコードを記述します。

public class MyClass
{
    static void Main()
    {
#if NET40
        Console.WriteLine("Target framework: .NET Framework 4.0");
#elif NET45
        Console.WriteLine("Target framework: .NET Framework 4.5");
#else
        Console.WriteLine("Target framework: .NET Standard 1.4");
#endif
    }
}

プリプロセッサ シンボル

SDK スタイル プロジェクトを使用する場合、ビルド システムは、「サポートされるターゲット フレームワークのバージョン」の表で示されているターゲット フレームワークを表すプリプロセッサ シンボルを認識します。 .NET Standard、.NET Core、または NET 5+ TFM を表すシンボルを使うときは、ドットとハイフンをアンダースコアに置き換え、小文字を大文字に変更します (たとえば、netstandard1.4 のシンボルは NETSTANDARD1_4 です)。

DisableImplicitFrameworkDefines プロパティを使用して、これらのシンボルの生成を無効にすることができます。 このプロパティの詳細については、「DisableImplicitFrameworkDefines」を参照してください。

.NET ターゲット フレームワークのプリプロセッサ シンボルの完全な一覧を次に示します。

非推奨のターゲット フレームワーク

次のターゲット フレームワークは非推奨とされます。 これらのターゲット フレームワークをターゲットにするパッケージは、指定されている代替のものに移行する必要があります。

関連項目

• .NET 5 でのターゲット フレームワーク名
• デスクトップ アプリで Windows ランタイム API を呼び出す
• クロス プラットフォーム ツールによるライブラリの作成
• .NET Standard
• .NET Core バージョン管理
• NuGet Tools GitHub リポジトリ
• .NET のフレームワーク プロファイル
• プラットフォーム互換性アナライザー