SDK 樣式專案中的目標 framework

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

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

應用程式或程式庫也可以將目標設為特定 .NET 實作,以存取實作特定的 API。 例如,以 xamarin 為目標的應用程式 (例如, Xamarin.iOS10) 可存取適用于 iOS 10 的 xamarin 提供的 ios API 包裝函式,或是以通用 Windows 平臺 (UWP 為目標的應用程式, uap10.0) 可以存取針對執行 Windows 10 的裝置進行編譯的 api。

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

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

最新版本

下表定義最常見的目標 framework、其參考方式,以及它們所執行的 .NET Standard 版本。 這些目標 Framework 版本是最新穩定版本。 不顯示發行前版本。 目標 framework 標記 (TFM) 是標準化的標記格式,用於指定 .NET 應用程式或程式庫的目標 framework。

目標架構 最新
穩定版本
目標 framework 標記 (TFM) 已實作
.NET Standard 版本
.NET 5 5.0 net 5。0 N/A
.NET Standard 2.1 netstandard 2。1 N/A
.NET Core 3.1 netcoreapp 3。1 2.1
.NET Framework 4.8 net48 2.0

支援的目標 framework

目標 Framework 通常會由 TFM 參考。 下表顯示 .net SDK 和 NuGet 用戶端所支援的目標 framework。 對等項目會顯示在括弧內。 例如,win81netcore451 的對等 TFM。

目標 Framework TFM
.NET 5 + (和 .NET Core) netcoreapp1.0
netcoreapp1.1
netcoreapp2.0
netcoreapp2.1
netcoreapp2.2
netcoreapp 3。0
netcoreapp 3。1
net 5.0
net 6.0
.NET Standard netstandard1.0
netstandard1.1
netstandard1.2
netstandard1.3
netstandard1.4
netstandard1.5
netstandard1.6
netstandard2.0
netstandard 2。1
.NET Framework net11
net20
net35
net40
net403
net45
net451
net452
net46
net461
net462
net47
net471
net472
net48
Windows 市集 netcore [netcore45]
netcore45 [win] [win8]
netcore451 [win81]
.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 + OS 特定 tfm

.NET 5 + OS 專用 Tfm

net5.0net6.0 tfm 包含跨不同平臺運作的技術。 指定 作業系統特定的 TFM ,可讓您的應用程式使用的作業系統專用 api,例如 Windows Forms 或 iOS 系結。 作業系統專用的 Tfm 也會繼承其基底 TFM 可用的每個 API,例如 net5.0 TFM。

.net 5 引進了 net5.0-windows OS 特定的 TFM,其中包含適用于 WinForms、WPF 和 UWP api 的 Windows 特定系結。 .NET 6 引進更進一步的 OS 專用 Tfm。

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

TFM 相容于
net 5。0 net1..具有 NU1701 警告的 4 ()
netcoreapp1..3.1 (參考 WinForms 或 WPF 時發出警告)
netstandard1..2.1
net 5.0-windows netcoreapp1..3.1 (以及繼承自) 的其他專案 net5.0
net 6。0 (後續的 net5.0) 版本
net 6.0-android xamarin.android (+ 繼承自) 的其他專案 net6.0
net 6.0-ios xamarin.ios (+ 繼承自) 的其他專案 net6.0
net 6.0-macos xamarin.mac (+ 繼承自) 的其他專案 net6.0
net 6.0-maccatalyst xamarin.ios (+ 繼承自) 的其他專案 net6.0
net 6.0-tvos xamarin.tvos (+ 繼承自) 的其他專案 net6.0
net 6.0-windows (後續的 net5.0-windows) 版本

若要讓您的應用程式可在不同平臺上移植,但仍可存取 OS 專屬的 Api,您可以將目標設為多個 OS 專屬的 Tfm,並使用預處理器指示詞來為 OS 專屬的 API 呼叫新增平臺防護 #if

建議的目標

使用這些指導方針來判斷要在您的應用程式中使用的 TFM:

  • 可移植至多個平臺的應用程式應該以基底 TFM 為目標,例如 net5.0 。 這包括大部分的程式庫,但也 ASP.NET Core 和 Entity Framework。

  • 平臺特定程式庫應以平臺特定的類別為目標。 例如,WinForms 和 WPF 專案應以或為目標 net5.0-windows net6.0-windows

  • 跨平臺應用程式模型 (xamarin 表單、ASP.NET Core) 和橋接器套件 (xamarin Essentials) 至少應以基底 TFM 為目標, net6.0 但可能也會以其他平臺特定的類別為目標,以加速更多 api 或功能。

Tfm 中的作業系統版本

您也可以在 OS 特定 TFM 的結尾指定選用的 OS 版本,例如 net6.0-ios15.0 。 版本指出您的應用程式或程式庫可以使用哪些 Api。 它不會控制您的應用程式或程式庫在執行時間所支援的作業系統版本。 它是用來選取您的專案編譯依據的參考元件,以及從 NuGet 套件中選取資產。 請將此版本視為「平臺版本」或「作業系統 API 版本」,以將它與執行時間作業系統版本區別。

當 OS 特定 TFM 未明確指定平臺版本時,其具有隱含的值,可從基底 TFM 和平臺名稱推斷。 例如,.NET 6 中的 iOS 預設平臺值是 15.0 ,這表示 net6.0-ios 標準 TFM 的速記 net6.0-ios15.0 。 較新基底 TFM 的隱含平臺版本可能較高,例如未來的 TFM 可能會 net7.0-ios 對應到 net7.0-ios16.0 。 速記格式只適用于專案檔,在傳遞至其他工具之前(例如 NuGet),.net SDK 的 MSBuild 目標會將其擴充為標準格式。

.NET SDK 的設計目的是要能夠針對個別平臺支援新發行的 Api,而不需要新版本的基底 TFM。 這可讓您存取平臺專屬的功能,而不需等候 .NET 的主要版本。 您可以藉由遞增 TFM 中的平臺版本,取得這些新發行之 Api 的存取權。 例如,如果 iOS 平臺在 .NET 6.0. x SDK 更新中新增了 iOS 15.1 Api,您可以使用 TFM 來存取它們 net6.0-ios15.1

支援較舊的作業系統版本

雖然平臺專屬的應用程式或程式庫是針對該作業系統特定版本的 Api 進行編譯,您也可以將屬性新增至您的專案檔,使其與舊版作業系統相容 SupportedOSPlatformVersionSupportedOSPlatformVersion屬性指出執行您的應用程式或程式庫所需的最低作業系統版本。 如果您未在專案中明確指定此執行時間最低的 OS 版本,則會預設為 TFM 中的平臺版本。

若要讓您的應用程式在較舊的作業系統版本上正確執行,它無法呼叫該作業系統版本上不存在的 Api。 不過,您可以新增對較新 Api 之呼叫的防護,因此只有在支援它們的作業系統版本上執行時,才會呼叫它們。 此模式可讓您設計應用程式或程式庫以支援在較舊的作業系統版本上執行,同時在較新的作業系統版本上執行較新的 OS 功能。

SupportedOSPlatformVersion值 (平臺相容性分析器是否使用明確或預設) ,其會偵測並警告有關較新 api 的 unguarded 呼叫。 它會以元件屬性的形式燒錄至專案的已編譯元件 UnsupportedOSPlatformAttribute ,讓平臺相容性分析器可以從值較低的專案偵測該元件之 api 的 unguarded 呼叫 SupportedOSPlatformVersion 。 在某些平臺上,此 SupportedOSPlatformVersion 值會影響平臺特定的應用程式封裝和組建程式,這些平臺會在檔中說明。

以下是使用 TargetFrameworkSupportedOSPlatformVersion 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

目標 framework 是在專案檔中指定。 當指定單一目標 framework 時,請使用 TargetFramework 元素。 下列主控台應用程式專案檔會示範如何將目標設為 .NET 5:

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

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

</Project>

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

下列程式庫專案的目標是 .NET Standard (netstandard1.4) 和 .NET Framework (net40net45) 的 api。 使用具有多個目標 framework 的複數 TargetFrameworks 元素Condition當您針對兩個 .NET Framework tfm 編譯程式庫時,屬性會包含特定的執行套件:

<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>

在您的程式庫或應用程式中,您可以使用 預處理器 指示詞,針對每個目標 framework 編譯條件式程式碼:

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.4NETSTANDARD1_4) 。

.NET 目標 framework 的預處理器符號完整清單如下:

目標 Framework 符號 .NET 5 + SDK 中提供的其他符號
.NET Framework NETFRAMEWORK, 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_1, NETSTANDARD1_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_GREATER, NETSTANDARD1_0_OR_GREATER
.NET 5 + (和 .NET Core) NET, NET6_0, NET6_0_ANDROID, NET6_0_IOS, NET6_0_MACOS, NET6_0_MACCATALYST, NET6_0_TVOS, NET6_0_WINDOWS, NET5_0, NETCOREAPP, NETCOREAPP3_1, NETCOREAPP3_0, NETCOREAPP2_2, NETCOREAPP2_1, NETCOREAPP2_0, NETCOREAPP1_1, NETCOREAPP1_0 NET6_0_OR_GREATER, NET6_0_ANDROID_OR_GREATER, NET6_0_IOS_OR_GREATER, NET6_0_MACOS_OR_GREATER, NET6_0_MACCATALYST_OR_GREATER, NET6_0_TVOS_OR_GREATER, NET6_0_WINDOWS_OR_GREATER, NET5_0_OR_GREATER, NETCOREAPP_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

注意

  • 無論您的目標版本為何,都會定義無版本符號。
  • 僅針對您的目標版本定義版本特定的符號。
  • 這些 <framework>_OR_GREATER 符號會針對您的目標版本和所有較早的版本而定義。 例如,如果您的目標是 .NET Framework 2.0,則會定義下列符號: NET_2_0NET_2_0_OR_GREATERNET_1_1_OR_GREATERNET_1_0_OR_GREATER

已被取代的目標 Framework

下列目標 Framework 已被取代。 以這些目標 framework 為目標的套件應該遷移至指示的取代。

已被取代的 TFM 取代
aspnet50
aspnetcore50
dnxcore50
dnx
dnx45
dnx451
dnx452
netcoreapp
dotnet
dotnet50
dotnet51
dotnet52
dotnet53
dotnet54
dotnet55
dotnet56
netstandard
netcore50 uap10.0
win netcore45
win8 netcore45
win81 netcore451
win10 uap10.0
winrt netcore45

另請參閱