Kerangka kerja target dalam proyek gaya SDK

Artikel
10/18/2024

Saat menargetkan kerangka kerja di aplikasi atau pustaka, Anda menentukan kumpulan API yang ingin Anda sediakan untuk aplikasi atau pustaka. Anda menentukan kerangka kerja target dalam file proyek Anda menggunakan moniker kerangka kerja target (TFM).

Aplikasi atau pustaka dapat menargetkan versi .NET Standard. Versi Standar .NET mewakili set API standar di semua implementasi .NET. Misalnya, pustaka dapat menargetkan .NET Standard 1.6 dan mendapatkan akses ke API yang berfungsi di .NET Core dan .NET Framework menggunakan basis kode yang sama.

Aplikasi atau pustaka juga dapat menargetkan implementasi .NET tertentu untuk mendapatkan akses ke API khusus implementasi. Misalnya, aplikasi yang menargetkan Xamarin.iOS (misalnya, Xamarin.iOS10) memiliki akses ke pembungkus API iOS yang disediakan Xamarin untuk iOS 10, atau aplikasi yang menargetkan Universal Windows Platform (UWP, uap10.0) memiliki akses ke API yang dikompilasi untuk perangkat yang berjalan Windows 10.

Untuk beberapa kerangka kerja target, seperti .NET Framework, API ditentukan oleh assembly yang diinstal kerangka kerja pada sistem dan dapat mencakup API kerangka kerja aplikasi (misalnya, ASP.NET).

Untuk kerangka kerja target berbasis paket (misalnya, .NET 5+, .NET Core, dan .NET Standard), API ditentukan oleh paket NuGet yang disertakan dalam aplikasi atau pustaka.

Versi terbaru

Tabel berikut mendefinisikan kerangka kerja target yang paling umum, bagaimana kerangka kerja target direferensikan, dan versi .NET Standard mana yang mereka terapkan. Versi kerangka kerja target ini adalah versi stabil terbaru. Versi prarilis tidak ditampilkan. Moniker kerangka kerja target (TFM) adalah format token standar untuk menentukan kerangka kerja target aplikasi atau pustaka .NET.

Kerangka kerja target	Terbaru versi stabil	Moniker kerangka kerja target (TFM)	Dilaksanakan Versi Standar .NET
.NET 8	8	net8.0	2.1
.NET 7	7	net7.0	2.1
.NET 6	6	net6.0	2.1
.NET 5	5	net5.0	2.1
.NET Standar	2.1	netstandard2.1	T/A
.NET Core	3.1	netcoreapp3.1	2.1
.NET Framework	4.8.1	net481	2.0

Kerangka kerja target yang didukung

Kerangka kerja target biasanya dirujuk oleh TFM. Tabel berikut ini memperlihatkan kerangka kerja target yang didukung oleh .NET SDK dan klien NuGet. Setara ditampilkan dalam tanda kurung siku. Misalnya, win81 setara dengan TFM ke netcore451.

Kerangka Target	TFM
.NET 5+ (dan .NET Core)	netcoreapp1.0 netcoreapp1.1 netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1 net5.0* net6.0* net7.0* net8.0*
.NET Standar	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
Bursa Windows	netcore [netcore45] netcore45 [win] [win8] netcore451 [win81]
.NET Kerangka kerja Mikro	netmf
Silverlight	sl4 sl5
Windows Phone	wp [wp7] wp7 wp75 wp8 wp81 wpa81
Platform Windows Universal	uap [uap10.0] uap10.0 [win10] [netcore50]

* .NET 5 dan TFM yang lebih baru mencakup beberapa variasi khusus sistem operasi. Untuk informasi selengkapnya, lihat bagian berikut, TFM khusus OS .NET 5+.

TFM khusus OS .NET 5+

net5.0TFM , net6.0, net7.0, dan net8.0 mencakup teknologi yang berfungsi di berbagai platform. Menentukan TFM khusus OS membuat API yang khusus untuk sistem operasi tersedia untuk aplikasi Anda, misalnya, Formulir Windows atau pengikatan iOS. TFM khusus OS juga mewarisi setiap API yang tersedia untuk TFM dasar mereka, misalnya, net6.0 TFM.

.NET 5 memperkenalkan net5.0-windows TFM khusus OS, yang mencakup pengikatan khusus Windows untuk Api WinForms, WPF, dan UWP. .NET 6 dan versi yang lebih baru memiliki TFM khusus OS tambahan, misalnya, net6.0-ios.

Tabel berikut ini memperlihatkan kompatibilitas .NET 5+ TFM.

TFM	Kompatibel dengan
net5.0	net1.. 4 (dengan peringatan NU1701) netcoreapp1.. 3.1 (peringatan ketika WinForms atau WPF dirujuk) netstandard1..2.1
net5.0-windows	netcoreapp1.. 3.1 (ditambah segala sesuatu yang lain yang diwarisi dari `net5.0`)
net6.0	(Versi berikutnya dari `net5.0`)
net6.0-android	`xamarin.android` (ditambah segala sesuatu yang lain diwariskan dari `net6.0`)
net6.0-ios	Segala sesuatu yang diwariskan dari `net6.0`
net6.0-maccatalyst	Segala sesuatu yang diwariskan dari `net6.0`
net6.0-macos	Segala sesuatu yang diwariskan dari `net6.0`
net6.0-tvos	Segala sesuatu yang diwariskan dari `net6.0`
net6.0-windows	(Versi berikutnya dari `net5.0-windows`)
net7.0	(Versi berikutnya dari `net6.0`)
net7.0-android	(Versi berikutnya dari `net6.0-android`)
net7.0-ios	(Versi berikutnya dari `net6.0-ios`)
net7.0-maccatalyst	(Versi berikutnya dari `net6.0-maccatalyst`)
net7.0-macos	(Versi berikutnya dari `net6.0-macos`)
net7.0-tizen	`tizen40` (ditambah segala sesuatu yang lain diwariskan dari `net7.0`)
net7.0-tvos	(Versi berikutnya dari `net6.0-tvos`)
net7.0-windows	(Versi berikutnya dari `net6.0-windows`)
net8.0	(Versi berikutnya dari `net7.0`)
net8.0-android	(Versi berikutnya dari `net7.0-android`)
net8.0-browser	Segala sesuatu yang diwariskan dari `net8.0`
net8.0-ios	(Versi berikutnya dari `net7.0-ios`)
net8.0-maccatalyst	(Versi berikutnya dari `net7.0-maccatalyst`)
net8.0-macos	(Versi berikutnya dari `net7.0-macos`)
net8.0-tizen	(Versi berikutnya dari `net7.0-tizen`)
net8.0-tvos	(Versi berikutnya dari `net7.0-tvos`)
net8.0-windows	(Versi berikutnya dari `net7.0-windows`)

Untuk membuat aplikasi Anda portabel di berbagai platform tetapi masih memiliki akses ke API khusus OS, Anda dapat menargetkan beberapa TFM khusus OS dan menambahkan penjaga platform di sekitar panggilan API khusus OS menggunakan #if arahan praprosesor. Untuk daftar simbol yang tersedia, lihat Simbol pra-prosesor.

Target yang disarankan

Gunakan panduan ini untuk menentukan TFM mana yang akan digunakan di aplikasi Anda:

Aplikasi yang portabel ke beberapa platform harus menargetkan TFM dasar, misalnya, net8.0. Ini termasuk sebagian besar pustaka tetapi juga ASP.NET Core dan Entity Framework.
Pustaka khusus platform harus menargetkan ragam khusus platform. Misalnya, proyek WinForms dan WPF harus menargetkan net8.0-windows.
Model aplikasi lintas platform (Formulir Xamarin, ASP.NET Core) dan paket jembatan (Xamarin Essentials) setidaknya harus menargetkan TFM dasar, misalnya, net8.0, tetapi mungkin juga menargetkan rasa khusus platform tambahan untuk menyalakan lebih banyak API atau fitur.

Versi OS dalam TFM

Anda juga dapat menentukan versi OS opsional di akhir TFM khusus OS, misalnya, net6.0-ios15.0. Versi menunjukkan API mana yang tersedia untuk aplikasi atau pustaka Anda. Ini tidak mengontrol versi OS yang didukung aplikasi atau pustaka Anda pada waktu proses. Ini digunakan untuk memilih assembly referensi yang dikompilasi proyek Anda, dan untuk memilih aset dari paket NuGet. Anggap versi ini sebagai "versi platform" atau "versi OS API" untuk membedakannya dari versi OS run-time.

Ketika TFM khusus OS tidak menentukan versi platform secara eksplisit, TFM tersebut memiliki nilai tersirat yang dapat disimpulkan dari TFM dasar dan nama platform. Misalnya, nilai platform default untuk Android di .NET 6 adalah 31.0, yang berarti singkatan net6.0-android untuk TFM kanonis net6.0-android31.0 . Versi platform tersirat untuk TFM dasar yang lebih baru mungkin lebih tinggi, misalnya, TFM di masa mendatang net8.0-android dapat memetakan ke net8.0-android34.0. Formulir singkatan dimaksudkan untuk digunakan dalam file proyek saja, dan diperluas ke bentuk kanonis oleh target MSBuild .NET SDK sebelum diteruskan ke alat lain, seperti NuGet.

Tabel berikut menunjukkan nilai platform target default (TPV) untuk setiap rilis .NET.

Versi .NET	Android	iOS	Mac Catalyst	macOS	tvOS	Tizen	Windows
.NET 6	31.0	15.0	15.0	12.0	15,1	-	7,0
.NET 7	33.0	16.1	16.1	13.0	16.1	7,0	7,0
.NET 8	34,0	17.2	17.2	14,2	17,1	8.0	7,0

Catatan

Pada platform Apple (iOS, macOS, tvOS, dan Mac Catalyst) di .NET 8 dan yang lebih lama, TPV default adalah versi terbaru yang didukung dalam beban kerja yang saat ini diinstal. Itu berarti bahwa memperbarui beban kerja iOS di .NET 8, misalnya, dapat mengakibatkan TPV default yang lebih tinggi, jika dukungan untuk versi baru iOS telah ditambahkan dalam beban kerja tersebut. Dalam tabel sebelumnya, TPV default adalah yang ada dalam rilis awal untuk versi .NET yang dinyatakan.

Mulai dari .NET 9, perilaku khusus ini hanya berlaku untuk proyek yang dapat dieksekusi. TPV default untuk proyek pustaka sekarang tetap sama untuk keseluruhan rilis .NET utama, seperti semua platform lainnya.

.NET SDK dirancang untuk dapat mendukung API yang baru dirilis untuk platform individual tanpa versi baru TFM dasar. Ini memungkinkan Anda mengakses fungsionalitas khusus platform tanpa menunggu rilis utama .NET. Anda dapat memperoleh akses ke API yang baru dirilis ini dengan menambah versi platform di TFM. Misalnya, jika platform Android menambahkan API level 32 api dalam pembaruan .NET 6.0.x SDK, Anda dapat mengaksesnya dengan menggunakan TFM net6.0-android32.0.

Prioritas

Jika aplikasi Anda mereferensikan paket yang memiliki beberapa aset untuk TFM yang berbeda, aset yang lebih dekat dalam nomor versi lebih disukai. Misalnya, jika aplikasi Anda menargetkan net6.0-ios dan paket menawarkan aset untuk net6.0 dan net5.0-ios, net6.0 aset digunakan. Untuk informasi selengkapnya, lihat Prioritas.

Mendukung versi OS yang lebih lama

Meskipun aplikasi atau pustaka khusus platform dikompilasi terhadap API dari versi OS tertentu, Anda dapat membuatnya kompatibel dengan versi OS sebelumnya dengan menambahkan SupportedOSPlatformVersion properti ke file proyek Anda. Properti SupportedOSPlatformVersion menunjukkan versi OS minimum yang diperlukan untuk menjalankan aplikasi atau pustaka Anda. Jika Anda tidak secara eksplisit menentukan versi OS run-time minimum ini dalam proyek, versi tersebut default ke versi platform dari TFM.

Agar aplikasi Anda berjalan dengan benar pada versi OS yang lebih lama, aplikasi tidak dapat memanggil API yang tidak ada pada versi OS tersebut. Namun, Anda dapat menambahkan penjaga di sekitar panggilan ke API yang lebih baru sehingga hanya dipanggil saat berjalan pada versi OS yang mendukungnya. Pola ini memungkinkan Anda merancang aplikasi atau pustaka untuk mendukung berjalan pada versi OS yang lebih lama sambil memanfaatkan fungsionalitas OS yang lebih baru saat berjalan pada versi OS yang lebih baru.

Nilai SupportedOSPlatformVersion (baik eksplisit atau default) digunakan oleh penganalisis kompatibilitas platform, yang mendeteksi dan memperingatkan tentang panggilan yang tidak dijaga ke API yang lebih baru. Ini dibakar ke dalam assembly yang dikompilasi proyek sebagai atribut assembly UnsupportedOSPlatformAttribute, sehingga penganalisis kompatibilitas platform dapat mendeteksi panggilan yang tidak terjaga ke API assembly tersebut dari proyek dengan nilai yang lebih rendah SupportedOSPlatformVersion. Pada beberapa platform, nilainya SupportedOSPlatformVersion memengaruhi proses pengemasan dan build aplikasi khusus platform, yang tercakup dalam dokumentasi untuk platform tersebut.

Berikut adalah contoh kutipan file proyek yang menggunakan TargetFramework properti MSBuild dan SupportedOSPlatformVersion untuk menentukan bahwa aplikasi atau pustaka memiliki akses ke API iOS 15.0 tetapi mendukung berjalan di iOS 13.0 ke atas:

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

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

</Project>

Cara menentukan kerangka kerja target

Kerangka kerja target ditentukan dalam file proyek. Saat kerangka kerja target tunggal ditentukan, gunakan elemen TargetFramework. File proyek aplikasi konsol berikut menunjukkan cara menargetkan .NET 8:

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

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

</Project>

Saat Menentukan beberapa kerangka kerja target, Anda dapat mereferensikan assembly secara kondisional untuk setiap kerangka kerja target. Dalam kode Anda, Anda dapat mengkompilasi secara kondisional terhadap rakitan tersebut dengan menggunakan simbol prapemrosesan dengan logika if-then-else .

Proyek pustaka berikut menargetkan API .NET Standard (netstandard1.4) dan .NET Framework (net40 dan net45). Gunakan elemen TargetFrameworks jamak dengan beberapa kerangka kerja target. Atribut termasuk Condition paket khusus implementasi saat pustaka dikompilasi untuk dua TFM .NET Framework:

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

Dalam pustaka atau aplikasi, Anda menulis kode kondisional menggunakan direktif pra-prosesor untuk dikompilasi untuk setiap kerangka kerja target:

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

Simbol prapemroscesor

Sistem build mengetahui simbol pra-prosesor yang mewakili kerangka kerja target yang ditampilkan dalam tabel Versi kerangka kerja target yang didukung saat Anda menggunakan proyek bergaya SDK. Untuk mengonversi .NET Standard, .NET Core, atau .NET 5+ TFM ke simbol praprosesor, ganti titik dan tanda hubung dengan garis bawah, dan ubah huruf kecil menjadi huruf besar (misalnya, simbol untuk netstandard1.4 adalah NETSTANDARD1_4).

Anda dapat menonaktifkan pembuatan simbol-simbol ini melalui DisableImplicitFrameworkDefines properti. Untuk informasi selengkapnya tentang properti ini, lihat DisableImplicitFrameworkDefines.

Daftar lengkap simbol pra-prosesor untuk kerangka kerja target .NET adalah:

Kerangka Kerja Target	Simbol	Simbol tambahan (tersedia dalam .NET 5+ SDK)	Simbol platform (hanya tersedia saat Anda menentukan TFM khusus OS)
.NET Framework	`NETFRAMEWORK`, , `NET472NET48`, `NET471`, `NET47`, `NET462`, `NET461`, `NET46`, `NET452`, `NET451`, `NET45`, `NET40`, , , `NET35NET20`	`NET48_OR_GREATER`, , `NET472_OR_GREATERNET471_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_GREATERNET20_OR_GREATER`
.NET Standar	`NETSTANDARD`, , `NETSTANDARD2_1NETSTANDARD2_0`, `NETSTANDARD1_6`, `NETSTANDARD1_5`, `NETSTANDARD1_4`, `NETSTANDARD1_3`, `NETSTANDARD1_2`, , `NETSTANDARD1_1`,`NETSTANDARD1_0`	`NETSTANDARD2_1_OR_GREATER`, , `NETSTANDARD1_6_OR_GREATERNETSTANDARD2_0_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+ (dan .NET Core)	`NET`, , `NET8_0NET7_0`, `NET6_0`, `NET5_0`, `NETCOREAPP`, `NETCOREAPP3_1`, `NETCOREAPP3_0`, `NETCOREAPP2_2`, `NETCOREAPP2_1`, , `NETCOREAPP2_0`, , `NETCOREAPP1_1NETCOREAPP1_0`	`NET8_0_OR_GREATER`, , `NET7_0_OR_GREATERNET6_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_GREATERNETCOREAPP1_0_OR_GREATER`	`ANDROID`, , `IOSBROWSER`, `MACCATALYST`, `MACOS`, `TVOS`, , `WINDOWS`, `[OS][version]` (misalnya `IOS15_1`), `[OS][version]_OR_GREATER` (misalnya `IOS15_1_OR_GREATER`)

Catatan

Simbol tanpa versi ditentukan terlepas dari versi yang Anda targetkan.
Simbol khusus versi hanya ditentukan untuk versi yang Anda targetkan.
Simbol <framework>_OR_GREATER ditentukan untuk versi yang Anda targetkan dan semua versi sebelumnya. Misalnya, jika Anda menargetkan .NET Framework 2.0, simbol berikut ditentukan: NET20, NET20_OR_GREATER, NET11_OR_GREATER, dan NET10_OR_GREATER.
Simbol NETSTANDARD<x>_<y>_OR_GREATER hanya didefinisikan untuk target .NET Standard, dan bukan untuk target yang mengimplementasikan .NET Standard, seperti .NET Core dan .NET Framework.
Ini berbeda dari moniker kerangka kerja target (TFM) yang digunakan oleh properti MSBuild TargetFramework dan NuGet.

Kerangka kerja target yang didukung

Kerangka kerja target berikut tidak digunakan lagi. Paket yang menargetkan kerangka kerja target ini harus bermigrasi ke pengganti yang ditunjukkan.

TFM yang tidak digunakan lagi	Penggantian
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

Bagikan melalui

Kerangka kerja target dalam proyek gaya SDK

Versi terbaru

Kerangka kerja target yang didukung

TFM khusus OS .NET 5+

Target yang disarankan

Versi OS dalam TFM

Prioritas

Mendukung versi OS yang lebih lama

Cara menentukan kerangka kerja target

Simbol prapemroscesor

Kerangka kerja target yang didukung

Lihat juga

Sumber Daya Tambahan: