SDK 樣式專案中的目標架構

2025-04-17

當您以應用程式或程式庫中的架構為目標時，您將指定要提供給應用程式或程式庫的一組 API。您可以在專案檔中使用目標 Framework Moniker (TFM) 來指定目標 Framework。

應用程式或程式庫可以將目標設為某個版本的 .NET Standard。 .NET Standard 版本代表跨所有 .NET 實作的標準化 API 集合。例如，程式庫可以將目標設為 .NET Standard 1.6，以存取跨 .NET Core 和 .NET Framework (兩者使用相同的程式碼基底) 運作的 API。

應用程式或程式庫也可以將目標設為特定 .NET 實作，以存取實作特定的 API。例如，以通用 Windows 平臺（UWP） uap10.0為目標的應用程式可以存取針對執行 Windows 10 之裝置所編譯的 API。

針對某些目標 Framework，例如 .NET Framework，API 是由該架構安裝在系統上的組件所定義，而且可能包含應用程式架構 API (例如 ASP.NET)。

針對以套件為基礎的目標 Framework (例如 .NET 5+、.NET Core 和 .NET Standard)，API 是由包含在應用程式或程式庫中的 NuGet 套件所定義。

目標框架	最新穩定版本	目標框架名稱 (TFM)	已實作 .NET Standard 版本
.NET 9	9	net9.0	2.1
.NET 8	8	net8.0	2.1
.NET Standard	2.1	netstandard2.1	N/A
.NET 核心	3.1	netcoreapp3.1	2.1
.NET Framework	4.8.1	net481	2.0

支援的目標框架

目標框架通常會被標識為 TFM。下表顯示 .NET SDK 和 NuGet 客戶端所支援的目標框架。對等項目會顯示在括弧內。例如，win81 是 netcore451 的對等 TFM。

目標框架	TFM
.NET 5+ (和 .NET Core)	netcoreapp1.0 netcoreapp1.1 netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1 net5.0* net6.0* net7.0* net8.0* net9.0*
.NET Standard	netstandard1.0 netstandard1.1 netstandard1.2 netstandard1.3 netstandard1.4 netstandard1.5 netstandard1.6 netstandard2.0 netstandard2.1
.NET Framework	net11 net20 net35 net40 net403 net45 net451 net452 net46 net461 net462 net47 net471 net472 net48 net481
Windows商店	netcore [netcore45] netcore45 [win] [win8] netcore451 [win81]
.NET nanoFramework	netnano1.0
.NET Micro Framework	netmf
Silverlight	sl4 sl5
Windows Phone	wp [wp7] wp7 wp75 wp8 wp81 wpa81
通用 Windows 平台	uap [uap10.0] uap10.0 [win10] [netcore50]

* .NET 5 和更新版本的 TFM 包含一些作業系統特定的變化。如需詳細資訊，請參閱下列章節 .NET 5+ 操作系統特定的 TFM。

.NET 5+ 操作系統特定的 TFM

net5.0、net6.0、net7.0、 net8.0和 net9.0 TTFM 包含跨不同平台運作的技術。指定特定作業系統的 TFM 可以讓您的應用程式使用作業系統專屬的 API，例如 Windows Forms 或 iOS 綁定。 OS 特定的 TFM 會繼承其基底 TFM 所提供的每個 API，例如net9.0 TFM。

.NET 5 引進了 net5.0-windows 操作系統特定的 TFM，其中包含適用於 WinForms、WPF 和 UWP API 的 Windows 特定繫結。 .NET 6 和更新版本有額外的 OS 特定 TFM，例如 net6.0-ios。

下表顯示 .NET 5+ TFM 的相容性。

TFM	與下列版本相容
`net5.0`	net1..4（帶有 NU1701 警告） netcoreapp1.3.1 (參考 WinForms 或 WPF 時發出警告) netstandard1..2.1
`net5.0-windows`	netcoreapp1..3.1 (加上繼承自 `net5.0` 的所有項目)
`net6.0`	(`net5.0` 的後續版本)
`net6.0-android`	`xamarin.android` (加上繼承自 `net6.0` 的其他所有項目)
`net6.0-ios`	繼承自 `net6.0` 的所有項目
`net6.0-maccatalyst`	繼承自 `net6.0` 的所有項目
`net6.0-macos`	繼承自 `net6.0` 的所有項目
`net6.0-tvos`	繼承自 `net6.0` 的所有項目
`net6.0-windows`	(`net5.0-windows` 的後續版本)
`net7.0`	(`net6.0` 的後續版本)
`net7.0-android`	(`net6.0-android` 的後續版本)
`net7.0-ios`	(`net6.0-ios` 的後續版本)
`net7.0-maccatalyst`	(`net6.0-maccatalyst` 的後續版本)
`net7.0-macos`	(`net6.0-macos` 的後續版本)
`net7.0-tizen`	`tizen40` (加上繼承自 `net7.0` 的其他所有項目)
`net7.0-tvos`	(`net6.0-tvos` 的後續版本)
`net7.0-windows`	(`net6.0-windows` 的後續版本)
`net8.0`	(`net7.0` 的後續版本)
`net8.0-android`	(`net7.0-android` 的後續版本)
`net8.0-browser`	繼承自 `net8.0` 的所有項目
`net8.0-ios`	(`net7.0-ios` 的後續版本)
`net8.0-maccatalyst`	(`net7.0-maccatalyst` 的後續版本)
`net8.0-macos`	(`net7.0-macos` 的後續版本)
`net8.0-tizen`	(`net7.0-tizen` 的後續版本)
`net8.0-tvos`	(`net7.0-tvos` 的後續版本)
`net8.0-windows`	(`net7.0-windows` 的後續版本)
`net9.0`	(`net8.0` 的後續版本)
`net9.0-android`	(`net8.0-android` 的後續版本)
`net9.0-browser`	(`net8.0-browser` 的後續版本)
`net9.0-ios`	(`net8.0-ios` 的後續版本)
`net9.0-maccatalyst`	(`net8.0-maccatalyst` 的後續版本)
`net9.0-macos`	(`net8.0-macos` 的後續版本)
`net9.0-tizen`	(`net8.0-tizen` 的後續版本)
`net9.0-tvos`	(`net8.0-tvos` 的後續版本)
`net9.0-windows`	(`net8.0-windows` 的後續版本)

若要讓您的應用程式可移植到不同的平台，但仍可存取 OS 特定的 API，您可以使用 #if 前置處理器指示詞，以多個 OS 特定的 TFM 為目標，並新增平台防護。如需可用符號的清單，請參閱前置處理器符號。

建議的目標

使用這些指南來判定應用程式中要使用的 TFM：

可移植到多個平台的應用程式應以基底 TFM 為目標，例如 net9.0。這包括大部分的程式庫，但也包含 ASP.NET Core 和 Entity Framework。
平台特定程式庫應以平台特定類別為目標。例如，WinForms 和 WPF 專案應該以 net9.0-windows 為目標。
跨平臺應用程式模型（例如，ASP.NET Core）至少應以基底 TFM 為目標， net9.0但也可能以其他平臺特定類別為目標，以點亮更多 API 或功能。

TFM 中的 OS 版本

您也可以在 OS 特定 TFM 結尾指定選擇性 OS 版本，例如 net6.0-ios15.0。版本會指出您的應用程式或程式庫可以使用哪些 API。但不會控制應用程式或程式庫在執行階段支援的 OS 版本。其用來選取專案所編譯的參考元件，以及從 NuGet 套件中選取資產。將此版本視為「平台版本」或「OS API 版本」，以釐清其與執行階段 OS 版本。

.NET SDK 的設計目的是要能夠支援個別平台的新發行 API，而不需要基底 TFM 的新版本。這可讓您存取平台特定功能，而不需要等待 .NET 的主要版本。您可以藉由遞增 TFM 中的平台版本來取得這些新發行 API 的存取權。例如，如果 Android 平臺在 .NET 6.0.x SDK 更新中新增 API 層級 32 API，您可以使用 TFM net6.0-android32.0來存取它們。

當 OS 特定的 TFM 未明確指定平台版本時，其具有可從基底 TFM 和平台名稱推斷的隱含值。例如，.NET 9 中 Android 的預設平臺版本是 35.0，這表示 net9.0-android 是標準 netp.0-android35.0 TFM 的簡寫。速記表單僅供專案檔使用，且會在傳遞至 NuGet 等其他工具之前，由 .NET SDK 的 MSBuild 目標擴充至標準格式。

下表顯示每個 .NET 版本 的預設 目標平臺版本（TPV）。 如果您想要使用最新的系結，請使用預設值（也就是不要指定 OS 版本）。

.NET 版本	安卓	iOS	Mac Catalyst	macOS	tvOS	Tizen	窗戶
.NET 8	34.0	17.2	17.2	14.2	17.1	10.0	7.0
.NET 9	35.0	18.0	18.0	15.0		10.0	7.0

從 .NET 9 開始，當服務版本引進對更新 TPV 的支援，且該 TPV 的主要版本號碼與最初發行 .NET 版本時相同時，該 .NET 版本最初支援的 TPV 仍將受到支援。例如，針對 .NET 9，最早支援的 iOS 版本 18.0 仍會維持支援，即使服務版本新增最新 iOS 18.x 版本的支援也一樣。 如果您需要針對 .NET 版本使用最早的系結，請在 TFM 中使用特定的 OS 版本號碼。

注意

在 .NET 8 和更早版本中的 Apple 平臺（iOS、macOS、tvOS 和 Mac Catalyst）上，預設 TPV 是目前已安裝工作負載中最新支援的版本。這表示，例如，如果在該工作負載中新增了新版 iOS 的支援，更新 .NET 8 中的 iOS 工作負載可能會導致較高的預設 TPV。在上表中，預設 TPV 是所指定 .NET 版本初始版本中的版本。

從 .NET 9 開始，此特殊行為只適用於 可執行 的專案。預設標準平台版本 (TPV) 在圖書館項目中現在會在主要 .NET 發佈中維持不變，與所有其他平台相同。

優先順序

如果您的應用程式參考的套件包含多個針對不同目標框架（TFM）的資產，通常會優先選擇版本號碼較接近的資產。例如，如果您的應用程式目標為 net6.0-ios，而套件會提供 net6.0 和 net5.0-ios 的資產，則會使用 net6.0 資產。如需詳細資訊，請參閱優先權。

支援舊版作業系統

雖然平台特定應用程式或程式庫是針對該 OS 特定版本的 API 進行編譯，但您可以將 SupportedOSPlatformVersion 屬性新增至專案檔，使其與舊版 OS 相容。 SupportedOSPlatformVersion 屬性指出執行應用程式或程式庫所需的最低 OS 版本。如果您未在專案中明確指定此最小執行階段 OS 版本，則會預設為 TFM 的平台版本。

若要讓應用程式在舊版作業系統上正確執行，則其無法呼叫不存在於該作業系統版本的 API。不過，您可以新增對較新 API 呼叫的防護，使其只在支援的作業系統版本上執行時呼叫。此模式可讓您設計應用程式或程式庫，以支援在舊版作業系統上執行，同時利用較新的作業系統功能在較新的作業系統版本上執行。

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>

如何指定目標框架

目標框架會在專案檔中指定。指定單一目標 Framework 時，請使用 TargetFramework 項目。下列主控台應用程式項目檔示範如何以 .NET 9 為目標：

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

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

</Project>

當您指定多個目標 Framework 時，您可以有條件地參考每個目標 Framework 的組件。在您的程式碼中，您可以使用前置處理器符號搭配 if-then-else 邏輯，有條件地對這些組件進行編譯。

下列程式庫專案是以 .NET Standard (netstandard1.4) 以及 .NET Framework (net40 和 net45) 的 API 為目標。使用含有多個目標 Framework 的複數 TargetFrameworks 元素。當針對兩個 .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 樣式專案時，組建系統知道代表目標 Framework 的前置處理器符號，如支援的目標 Framework 版本表格中所示。若要將 .NET Standard、.NET Core 或 .NET 5+ TFM 轉換成前置處理器符號、以底線取代點和連字號，並將小寫字母變更為大寫 (例如，netstandard1.4 的符號會成為 NETSTANDARD1_4)。

您可以透過 DisableImplicitFrameworkDefines 屬性停用這些符號的產生。如需此屬性的詳細資訊，請參閱 DisableImplicitFrameworkDefines。

.NET目標框架的前置處理器符號完整清單是：

目標框架	符號	其他符號 (適用於 .NET 5+ SDK)	平台符號（僅可用於特定情境）當您指定作業系統特定的 TFM 時
.NET Framework	`NETFRAMEWORK`、`NET481`、`NET48`、`NET472`、`NET471`、`NET47`、`NET462`、`NET461`、`NET46`、`NET452`、`NET451`、`NET45`、`NET40`、`NET35`、`NET20`	`NET48_OR_GREATER`、`NET472_OR_GREATER`、`NET471_OR_GREATER`、`NET47_OR_GREATER`、`NET462_OR_GREATER`、`NET461_OR_GREATER`、`NET46_OR_GREATER`、`NET452_OR_GREATER`、`NET451_OR_GREATER`、`NET45_OR_GREATER`、`NET40_OR_GREATER`、`NET35_OR_GREATER`、`NET20_OR_GREATER`
.NET Standard	`NETSTANDARD`、`NETSTANDARD2_1`、`NETSTANDARD2_0`、`NETSTANDARD1_6`、`NETSTANDARD1_5`、`NETSTANDARD1_4`、`NETSTANDARD1_3`、、`NETSTANDARD1_2`、、 `NETSTANDARD1_1NETSTANDARD1_0`	`NETSTANDARD2_1_OR_GREATER`、`NETSTANDARD2_0_OR_GREATER`、`NETSTANDARD1_6_OR_GREATER`、`NETSTANDARD1_5_OR_GREATER`、`NETSTANDARD1_4_OR_GREATER`、`NETSTANDARD1_3_OR_GREATER`、`NETSTANDARD1_2_OR_GREATER`、 `NETSTANDARD1_1_OR_GREATERNETSTANDARD1_0_OR_GREATER`
.NET 5+ (和 .NET Core)	`NET`、`NET9_0`、`NET8_0`、`NET7_0`、`NET6_0`、`NET5_0`、`NETCOREAPP`、`NETCOREAPP3_1`、`NETCOREAPP3_0`、`NETCOREAPP2_2`、`NETCOREAPP2_1`、`NETCOREAPP2_0`、`NETCOREAPP1_1`、`NETCOREAPP1_0`	`NET9_0_OR_GREATER`、`NET8_0_OR_GREATER`、`NET7_0_OR_GREATER`、`NET6_0_OR_GREATER`、`NET5_0_OR_GREATER`、`NETCOREAPP3_1_OR_GREATER`、`NETCOREAPP3_0_OR_GREATER`、`NETCOREAPP2_2_OR_GREATER`、`NETCOREAPP2_1_OR_GREATER`、`NETCOREAPP2_0_OR_GREATER`、`NETCOREAPP1_1_OR_GREATER`、`NETCOREAPP1_0_OR_GREATER`	`ANDROID`、`BROWSER`、`IOS`、`MACCATALYST`、`MACOS`、`TVOS`、、、 `WINDOWS` `[OS][version]` (例如 `IOS15_1`)、 `[OS][version]_OR_GREATER` (例如 `IOS15_1_OR_GREATER`)

注意

無論您的目標版本為何，系統都會定義無版本符號。
系統只會針對您設定為目標的版本定義版本特定符號。
系統會針對您的目標版本和所有更早版本定義 <framework>_OR_GREATER 符號。舉例來說，如果您要以 .NET Framework 2.0 為目標，則會定義下列符號：NET20、NET20_OR_GREATER、NET11_OR_GREATER 與 NET10_OR_GREATER。
NETSTANDARD<x>_<y>_OR_GREATER 符號只會針對 .NET Standard 目標定義，而不是針對實作 .NET Standard 的目標，例如 .NET Core 和 .NET Framework。
這些與 MSBuild TargetFramework 屬性和 NuGet 使用的目標框架標記不同。

已過時的目標框架

下列目標框架已廢止。以這些目標框架為對象的套件應該移轉至所指出的替代項目。

已被取代的 TFM	取代
aspnet50 aspnetcore50 dnxcore50 dnx dnx45 dnx451 dnx452	netcoreapp
dotnet dotnet50 dotnet51 dotnet52 dotnet53 dotnet54 dotnet55 dotnet56	netstandard
netcore50	uap10.0
贏得	netcore45
Windows 8	netcore45
Windows 8.1	netcore451
Windows 10	uap10.0
winrt	netcore45

共用方式為