Kerangka kerja target dalam proyek gaya SDK
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 | xamarin.ios (ditambah segala sesuatu yang lain diwariskan dari net6.0) |
| net6.0-maccatalyst | xamarin.ios (ditambah segala sesuatu yang lain diwariskan dari net6.0) |
| net6.0-macos | xamarin.mac (ditambah segala sesuatu yang lain diwariskan dari net6.0) |
| net6.0-tvos | xamarin.tvos (ditambah segala sesuatu yang lain 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 iOS di .NET 6 adalah 15.0, yang berarti singkatan net6.0-ios untuk TFM kanonis net6.0-ios15.0 . Versi platform tersirat untuk TFM dasar yang lebih baru mungkin lebih tinggi, misalnya, TFM di masa mendatang net8.0-ios dapat memetakan ke net8.0-ios16.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 | Platform | Default TPV |
|---|---|---|
| .NET 6 | Android | 31.0 |
| .NET 7 | Android | 33.0 |
| .NET 8 | Android | 34,0 |
| .NET 6 | iOS | 15.0 |
| .NET 7 | iOS | 16.1 |
| .NET 8 | iOS | 17.2 |
| .NET 6 | Mac Catalyst | 15.0 |
| .NET 7 | Mac Catalyst | 16.1 |
| .NET 8 | Mac Catalyst | 17.2 |
| .NET 6 | macOS | 12.0 |
| .NET 7 | macOS | 13.0 |
| .NET 8 | macOS | 14,2 |
| .NET 6 | tvOS | 15,1 |
| .NET 7 | tvOS | 16.1 |
| .NET 8 | tvOS | 17,1 |
| .NET 7 | Tizen | 7,0 |
| .NET 8 | Tizen | 8.0 |
| .NET 6 | Windows | 7,0 |
| .NET 7 | Windows | 7,0 |
| .NET 8 | Windows | 7,0 |
.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 iOS menambahkan API iOS 15.1 dalam pembaruan .NET 6.0.x SDK, Anda dapat mengaksesnya dengan menggunakan TFM net6.0-ios15.1.
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_GREATERditentukan 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, danNET10_OR_GREATER. - Simbol
NETSTANDARD<x>_<y>_OR_GREATERhanya 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
TargetFrameworkdan 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 |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk