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 9
9
net9.0
2.1
.NET 8
8
net8.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.
* .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+
TFM net5.0, net6.0, net7.0, net8.0dan net.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, net9.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)
net9.0
(Versi berikutnya dari net8.0)
net9.0-android
(Versi berikutnya dari net8.0-android)
net9.0-browser
(Versi berikutnya dari net8.0-browser)
net9.0-ios
(Versi berikutnya dari net8.0-ios)
net9.0-maccatalyst
(Versi berikutnya dari net8.0-maccatalyst)
net9.0-macos
(Versi berikutnya dari net8.0-macos)
net9.0-tizen
(Versi berikutnya dari net8.0-tizen)
net9.0-tvos
(Versi berikutnya dari net8.0-tvos)
net9.0-windows
(Versi berikutnya dari net8.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, net9.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 net9.0-windows.
Model aplikasi lintas platform (Formulir Xamarin, ASP.NET Core) dan paket jembatan (Xamarin Essentials) setidaknya harus menargetkan TFM dasar, misalnya, net9.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 8
34,0
17.2
17.2
14,2
17,1
7,0
10.0
.NET 9
35,0
18,0
18,0
15.0
7,0
10.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:
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 9:
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:
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)
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.
Sumber untuk konten ini dapat ditemukan di GitHub, yang juga dapat Anda gunakan untuk membuat dan meninjau masalah dan menarik permintaan. Untuk informasi selengkapnya, lihat panduan kontributor kami.
Umpan balik .NET
.NET adalah proyek sumber terbuka. Pilih tautan untuk memberikan umpan balik:
Dalam modul ini, Anda akan mempelajari kapan, mengapa, dan bagaimana cara memodernisasi aplikasi ASP.NET Framework ke ASP.NET Core menggunakan Upgrade Assistant.