Pilih versi .NET yang akan digunakan

Artikel
05/10/2023

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 independen dari runtime target.

Pemilihan versi terjadi:

Saat Anda menjalankan perintah SDK, SDK menggunakan versi terbaru yang diinstal.
Saat Anda membangun perakitan, moniker kerangka kerja target menentukan API waktu build.
Saat Anda menjalankan aplikasi .NET, aplikasi dependen kerangka kerja target bergulir ke depan.
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 meliputi dotnet new dan dotnet run. .NET CLI harus memilih versi SDK untuk setiap dotnet perintah. Ini menggunakan SDK terbaru yang diinstal pada komputer secara default, bahkan jika:

Proyek menargetkan versi runtime .NET yang lebih lama.
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.

Pada kesempatan yang jarang terjadi, Anda mungkin perlu menggunakan versi SDK yang lebih lama. Anda menentukan versi tersebut dalam file global.json. Kebijakan "gunakan terbaru" berarti Anda hanya menggunakan global.json untuk menentukan versi .NET SDK yang lebih lama dari versi terbaru yang diinstal.

global.json dapat ditempatkan di mana saja dalam hierarki file. CLI mencari ke atas dari direktori proyek untuk global.json pertama yang ditemukannya. 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. 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:

dotnetmencari file global.json secara berulang menavigasi balik jalur ke atas dari direktori kerja saat ini.
dotnetmenggunakan SDK yang ditentukan dalam global.json pertama yang ditemukan.
dotnet menggunakan SDK terbaru yang diinstal jika tidak ada global.json yang ditemukan.

Untuk informasi selengkapnya tentang pemilihan versi SDK, lihat bagian Aturan pencocokan dan rollForward dari artikel gambaran umum global.json.

Moniker kerangka kerja target menentukan API waktu build

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

<TargetFramework>net8.0</TargetFramework>

Anda dapat membangun proyek Anda terhadap beberapa TFM. Mengatur beberapa kerangka kerja target lebih umum untuk pustaka tetapi juga dapat dilakukan dengan aplikasi. Anda menentukan TargetFrameworks properti (jamak 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 ke kerangka kerja target runtime yang dikirimkannya. Misalnya, .NET 8 SDK menyertakan runtime .NET 8, yang merupakan implementasi dari net8.0 kerangka kerja target. .NET 8 SDK mendukung net7.0, , net6.0dan net5.0, tetapi tidak net9.0 (atau lebih tinggi). Anda menginstal .NET 9 SDK untuk membangun untuk net9.0.

.NET Standar

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

Roll-forward 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 executable yang bergantung pada kerangka kerja dengan myapp.exe, yang dotnet dapat dieksekusi adalah 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 merupakan runtime .NET terbaru yang diinstal, 5.0.2 runtime digunakan.

Jika tidak ada versi yang dapat 5.0.* diterima yang ditemukan, versi baru 5.* akan digunakan. Misalnya, jika Anda menentukan net5.0 dan hanya 5.1.0 diinstal, aplikasi berjalan menggunakan 5.1.0 runtime. Perilaku ini disebut sebagai "versi minor roll-forward." Versi yang lebih rendah 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 ditentukan. 5.0.3 adalah versi patch tertinggi yang diinstal. 5.0.3 digunakan.
❌ 5.0 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.

Roll-forward versi minor memiliki 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.

Mengontrol perilaku roll-forward

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

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

Pengaturan tingkat proyek dengan mengatur <RollForward> properti:

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

File.*.runtimeconfig.json

File ini diproduksi saat Anda mengkompilasi aplikasi Anda. <RollForward> Jika properti diatur dalam proyek, properti akan direproduseri dalam *.runtimeconfig.json file sebagai rollForward pengaturan. 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 dotnet perintah --roll-forward <value> .

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 DOTNET_ROLL_FORWARD lingkungan.

Prioritas

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

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

Nilai

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

Nilai	Deskripsi
`Minor`	Default jika tidak ditentukan. Pindah ke versi kecil terendah yang lebih tinggi, jika versi kecil yang diminta tidak ada. Jika ada versi kecil yang diminta, kebijakan `LatestPatch` digunakan.
`Major`	Pindah ke versi besar yang lebih tinggi yang tersedia, dan versi kecil terendah, jika versi besar yang diminta tidak ada. Jika ada versi besar yang diminta, kebijakan `Minor` digunakan.
`LatestPatch`	Maju ke versi patch paling tinggi. Nilai ini menonaktifkan pindah ke versi kecil.
`LatestMinor`	Pindah ke versi kecil tertinggi, meskipun ada versi kecil yang diminta.
`LatestMajor`	Pindah ke versi besar tertinggi dan kecil tertinggi, meskipun ada versi besar yang diminta.
`Disable`	Jangan pindah, hanya ikat ke versi yang ditentukan. Kebijakan ini tidak disarankan untuk penggunaan umum karena menonaktifkan kemampuan untuk berpindah ke patch terbaru. Nilai ini hanya disarankan 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 run time.

Peristiwa pemulihan yang terjadi saat penerbitan memilih versi patch terbaru dari keluarga runtime yang diberikan. Misalnya, dotnet publish akan memilih .NET 5.0.3 jika ini adalah versi patch terbaru dalam keluarga runtime .NET 5. 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 mengambil alih versi patch runtime minimum (ke versi yang lebih tinggi atau lebih rendah) dalam file proyek, seperti yang ditunjukkan dalam contoh berikut:

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

Elemen ini 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.