Pilih versi .NET yang akan digunakan

Artikel
02/06/2025

Artikel ini menjelaskan kebijakan yang digunakan oleh alat .NET, SDK, dan runtime untuk memilih versi. Kebijakan ini memberikan keseimbangan antara aplikasi yang berjalan menggunakan versi yang ditentukan dan memungkinkan kemudahan peningkatan mesin pengembang dan pengguna akhir. Kebijakan ini memungkinkan:

Penyebaran .NET yang mudah dan efisien, termasuk pembaruan keamanan dan keandalan.
Gunakan alat dan perintah terbaru yang terlepas dari target runtime.

Pemilihan versi terjadi:

Saat Anda menjalankan perintah SDK, SDK menggunakan versi terbaru yang diinstal.
Saat Anda membangun rakitan, pengenal kerangka kerja target menentukan API waktu build.
Saat Anda menjalankan aplikasi .NET, aplikasi yang bergantung pada kerangka kerja target akan meneruskan pembaruan.
Saat Anda menerbitkan aplikasi mandiri, penyebaran mandiri menyertakan runtime yang dipilih.

Sisa dokumen ini memeriksa keempat skenario tersebut.

SDK menggunakan versi terbaru yang diinstal

Perintah SDK mencakup dotnet new dan dotnet run. .NET CLI harus memilih versi SDK untuk setiap perintah dotnet. Ini menggunakan SDK terbaru yang diinstal pada komputer secara default, bahkan jika:

Proyek menargetkan versi runtime .NET sebelumnya.
Versi terbaru .NET SDK adalah versi pratinjau.

Anda dapat memanfaatkan fitur dan peningkatan SDK terbaru sambil menargetkan versi runtime .NET sebelumnya. Anda dapat menargetkan versi runtime yang berbeda dari .NET menggunakan alat SDK yang sama.

Dalam beberapa keadaan, Anda mungkin perlu menggunakan versi SDK tertentu. Anda menentukan versi tersebut dalam file global.json.

global.json dapat ditempatkan di mana saja dalam hierarki file. Anda mengontrol proyek mana yang diterapkan global.json tertentu berdasarkan tempatnya dalam sistem file. .NET CLI mencari file global.json secara berulang menavigasi jalur ke atas dari direktori kerja saat ini (yang belum tentu sama dengan direktori proyek). File global.json pertama yang ditemukan menentukan versi yang digunakan. Jika versi SDK tersebut diinstal, versi tersebut digunakan. Jika SDK yang ditentukan dalam global.json tidak ditemukan, .NET CLI menggunakan aturan yang cocok untuk memilih SDK yang kompatibel, atau gagal jika tidak ada yang ditemukan.

Contoh berikut menunjukkan sintaks global.json:

{
  "sdk": {
    "version": "5.0.0"
  }
}

Proses untuk memilih versi SDK adalah:

dotnet mencari file global.json secara iteratif menelusuri jalur ke atas secara terbalik mulai dari direktori kerja saat ini.
dotnet menggunakan SDK yang ditentukan dalam global.json pertama yang ditemukan.
dotnet menggunakan SDK terbaru yang diinstal jika tidak ada global.json yang ditemukan.

Untuk informasi lebih lanjut tentang pemilihan versi SDK, lihat bagian Aturan Pencocokan dan RollForward dalam artikel Gambaran Umumglobal.json.

Memperbarui versi SDK

Penting untuk memperbarui ke versi terbaru SDK secara teratur untuk mengadopsi fitur terbaru, peningkatan performa, dan perbaikan bug. Untuk memeriksa pembaruan SDK dengan mudah, gunakan perintah dotnet sdk check. Selain itu, jika Anda memilih versi tertentu menggunakan global.json, pertimbangkan alat seperti Dependabot untuk memperbarui versi SDK yang disematkan secara otomatis saat versi baru tersedia.

Moniker kerangka kerja target mendefinisikan API yang digunakan selama proses build.

Anda membangun proyek terhadap API yang ditentukan dalam kerangka kerja target moniker (TFM). Anda menentukan kerangka kerja target dalam file proyek. Atur elemen TargetFramework dalam file proyek Anda seperti yang diperlihatkan dalam contoh berikut:

<TargetFramework>net8.0</TargetFramework>

Anda dapat membangun proyek Anda terhadap beberapa TFM. Menetapkan beberapa kerangka target lebih sering dilakukan dalam konteks perpustakaan perangkat lunak, namun dapat pula diterapkan pada aplikasi. Anda menentukan properti TargetFrameworks (bentuk jamak dari TargetFramework). Kerangka kerja target dibatasi titik koma seperti yang ditunjukkan dalam contoh berikut:

<TargetFrameworks>net8.0;net47</TargetFrameworks>

SDK tertentu mendukung serangkaian kerangka kerja tetap, yang dibatasi pada kerangka kerja target dari runtime yang menyertainya. Misalnya, .NET 8 SDK menyertakan runtime .NET 8, yang merupakan implementasi dari kerangka kerja target net8.0. .NET 8 SDK mendukung net7.0, net6.0, dan net5.0, tetapi tidak net9.0 (atau lebih tinggi). Anda menginstal .NET 9 SDK untuk membangun untuk net9.0.

.NET Standard

.NET Standard adalah cara untuk menargetkan permukaan API yang dibagikan oleh implementasi .NET yang berbeda. Dimulai dengan rilis .NET 5, yang merupakan standar API itu sendiri, .NET Standard memiliki sedikit relevansi, kecuali untuk satu skenario: .NET Standard berguna ketika Anda ingin menargetkan .NET dan .NET Framework. .NET 5 mengimplementasikan semua versi .NET Standard.

Untuk informasi selengkapnya, lihat .NET 5 dan .NET Standard.

Pemajuan versi aplikasi yang bergantung pada kerangka kerja

Saat Anda menjalankan aplikasi dari sumber dengan dotnet run, dari penyebaran yang bergantung pada kerangka kerja dengan dotnet myapp.dll, atau dari berkas yang dapat dieksekusi bergantung pada kerangka kerja dengan myapp.exe, berkas dotnet yang dapat dieksekusi berfungsi sebagai host untuk aplikasi.

Host memilih versi patch terbaru yang diinstal pada komputer. Misalnya, jika Anda menentukan net5.0 dalam file proyek Anda, dan 5.0.2 adalah runtime .NET terbaru yang diinstal, runtime 5.0.2 digunakan.

Jika tidak ada versi 5.0.* yang dapat diterima yang ditemukan, versi 5.* baru akan digunakan. Misalnya, jika Anda menentukan net5.0 dan hanya 5.1.0 yang diinstal, aplikasi berjalan menggunakan runtime 5.1.0. Perilaku ini disebut sebagai "pembaruan versi minor secara bertahap." Versi-versi yang lebih lama juga tidak akan dipertimbangkan. Ketika tidak ada runtime yang dapat diterima yang diinstal, aplikasi tidak akan berjalan.

Beberapa contoh penggunaan menunjukkan perilaku, jika Anda menargetkan 5.0:

✔️ 5.0 ditetapkan. 5.0.3 adalah versi patch tertinggi yang diinstal. 5.0.3 digunakan.
❌ 5.0 telah ditentukan. Tidak ada versi 5.0.* yang diinstal. 3.1.1 adalah runtime tertinggi yang diinstal. Pesan kesalahan ditampilkan.
✔️ 5.0 ditentukan. Tidak ada versi 5.0.* yang diinstal. 5.1.0 adalah versi runtime tertinggi yang diinstal. 5.1.0 digunakan.
❌ 3.0 ditentukan. Tidak ada versi 3.x yang diinstal. 5.0.0 adalah runtime tertinggi yang diinstal. Pesan kesalahan ditampilkan.

Versi minor roll-forward menyebabkan satu efek samping yang dapat memengaruhi pengguna akhir. Pertimbangkan skenario berikut:

Aplikasi menentukan bahwa 5.0 diperlukan.
Saat dijalankan, versi 5.0.* tidak diinstal, namun, 5.1.0 adalah. Versi 5.1.0 akan digunakan.
Kemudian, pengguna menginstal 5.0.3 dan menjalankan aplikasi lagi, 5.0.3 sekarang akan digunakan.

Ada kemungkinan bahwa 5.0.3 dan 5.1.0 berperilaku berbeda, terutama untuk skenario seperti menserialisasikan data biner.

Mengendalikan perilaku roll-forward

Sebelum mengubah perilaku roll-forward default, biasakan diri Anda dengan kompatibilitas runtime .NET tingkat .

Perilaku roll-forward untuk aplikasi dapat dikonfigurasi dengan empat cara berbeda:

Pengaturan tingkat proyek dengan mengatur properti <RollForward>:

<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

File *.runtimeconfig.json.

File ini diproduksi saat Anda mengkompilasi aplikasi Anda. Jika properti <RollForward> diatur dalam proyek, properti tersebut direprovsi dalam file *.runtimeconfig.json sebagai pengaturan rollForward. Pengguna dapat mengedit file ini untuk mengubah perilaku aplikasi Anda.
```
{
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}
```
Properti --roll-forward <value> dari perintah dotnet.

Saat menjalankan aplikasi, Anda dapat mengontrol perilaku roll-forward melalui baris perintah:
```
dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor
```
Variabel lingkungan DOTNET_ROLL_FORWARD.

Didahulukan

Perilaku roll forward diatur oleh urutan berikut saat aplikasi Anda dijalankan, item bernomor lebih tinggi yang lebih diutamakan daripada item bernomor lebih rendah:

Pertama, file konfigurasi *.runtimeconfig.json dievaluasi.
Selanjutnya, variabel lingkungan DOTNET_ROLL_FORWARD dipertimbangkan, mengesampingkan pemeriksaan sebelumnya.
Akhirnya, parameter --roll-forward apa pun yang diteruskan ke aplikasi yang sedang berjalan menggantikan semua yang lain.

Nilai

Bagaimanapun Anda mengatur pengaturan roll-forward, gunakan salah satu nilai berikut untuk mengatur perilaku:

Nilai	Deskripsi
`Minor`	Default jika tidak ditentukan. Roll-forward ke versi minor terendah yang lebih tinggi, jika versi minor yang diminta hilang. Jika versi minor yang diminta ada, maka kebijakan `LatestPatch` digunakan.
`Major`	Lanjutkan ke versi utama tertinggi berikutnya yang tersedia dan versi minor terendah, jika versi utama yang diminta tidak ada. Jika versi utama yang diminta ada, maka kebijakan `Minor` digunakan.
`LatestPatch`	Roll-forward ke versi patch tertinggi. Nilai ini menonaktifkan roll-forward versi minor.
`LatestMinor`	Memperbarui ke versi minor tertinggi, bahkan jika versi minor yang diminta tersedia.
`LatestMajor`	Roll-forward ke versi mayor tertinggi dan versi minor tertinggi, bahkan jika versi mayor yang diminta ada.
`Disable`	Jangan roll-forward, hanya ikat ke versi yang ditentukan. Kebijakan ini tidak disarankan untuk penggunaan umum karena menonaktifkan kemampuan untuk meneruskan ke patch terbaru. Nilai ini hanya direkomendasikan untuk pengujian.

Penyebaran mandiri mencakup runtime yang dipilih

Anda dapat menerbitkan aplikasi sebagai distribusi mandiri . Pendekatan ini menggabungkan runtime dan pustaka .NET dengan aplikasi Anda. Penyebaran mandiri tidak memiliki dependensi pada lingkungan runtime. Pemilihan versi runtime terjadi pada waktu penerbitan, bukan waktu berjalan.

Peristiwa pemulihan yang terjadi saat penerbitan memilih versi patch terbaru dari keluarga runtime yang diberikan. Misalnya, jika .NET 5.0.3 adalah versi patch terbaru dalam keluarga runtime .NET 5, maka dotnet publish akan memilihnya. Kerangka kerja target (termasuk patch keamanan terbaru yang diinstal) dikemas dengan aplikasi.

Kesalahan terjadi jika versi minimum yang ditentukan untuk aplikasi tidak terpenuhi. dotnet publish mengikat ke versi patch runtime terbaru (dalam keluarga versi major.minor tertentu). dotnet publish tidak mendukung semantik roll-forward dari dotnet run. Untuk informasi selengkapnya tentang patch dan penyebaran mandiri, lihat artikel tentang pemilihan patch runtime dalam menyebarkan aplikasi .NET.

Penyebaran mandiri mungkin memerlukan versi patch tertentu. Anda dapat mengganti versi patch runtime minimum (menjadi versi yang lebih tinggi atau lebih rendah) dalam file proyek, seperti yang ditunjukkan dalam contoh berikut:

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

Elemen RuntimeFrameworkVersion mengambil alih kebijakan versi default. Untuk penyebaran mandiri, RuntimeFrameworkVersion menentukan versi kerangka kerja runtime yang tepat. Untuk aplikasi yang bergantung pada kerangka kerja, RuntimeFrameworkVersion menentukan versi kerangka kerja runtime minimum yang diperlukan.

Bagikan melalui