gambaran umum global.json

Artikel ini berlaku untuk: ✔️ .NET Core 3.1 SDK dan versi yang lebih baru

File global.json memungkinkan Anda menentukan versi SDK .NET mana yang digunakan saat Anda menjalankan perintah CLI .NET. Memilih versi SDK .NET independen dari menentukan versi runtime target proyek. Versi SDK .NET menunjukkan versi CLI .NET mana yang digunakan. Artikel ini menjelaskan cara memilih versi SDK dengan menggunakan global.json.

Jika Anda selalu ingin menggunakan versi SDK terbaru yang diinstal pada komputer Anda, tidak diperlukan file global.json . Namun, dalam skenario CI (integrasi berkelanjutan), Anda biasanya ingin menentukan rentang yang dapat diterima untuk versi SDK yang digunakan. File global.json memiliki rollForward fitur yang menyediakan cara fleksibel untuk menentukan rentang versi yang dapat diterima. Misalnya, file global.json berikut memilih 10.0.100 atau kelompok fitur atau patch yang lebih baru dari 10.0 yang telah diinstal pada komputer.

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestFeature"
  }
}

Anda mengandalkan dua komponen di SDK .NET untuk mencari file global.json. Setiap komponen dimulai dari lokasi yang berbeda dan mencari melalui direktori leluhur:

• SDK muxer .NET menangani perintah CLI dotnet. Ini dimulai dari direktori kerja saat ini, yang belum tentu sama dengan direktori proyek.
• .NET pemecah masalah SDK proyek MSBuild menyelesaikan SDK proyek selama build. Ini dimulai dari direktori yang berisi file solusi, jika ada. Jika tidak ada file solusi, file tersebut dimulai dari direktori yang berisi file proyek saat ini. Jika kedua file tidak ada, maka akan menggunakan direktori kerja saat ini.

Untuk informasi tentang menentukan versi runtime, bukan versi SDK, lihat Kerangka kerja target.

skema global.json

sdk

Jenis: object

Menentukan informasi tentang SDK .NET untuk dipilih.

version

• Jenis: string

Versi SDK .NET yang akan digunakan.

Bidang ini:

• Memerlukan nomor versi lengkap, seperti 10.0.100.
• Tidak mendukung nomor versi seperti 10, 10.0, atau 10.0.x.
• Tidak memiliki dukungan wildcard.
• Tidak mendukung rentang versi.

allowPrerelease

• Jenis: boolean
• Tersedia sejak: .NET Core 3.0 SDK.

Menunjukkan apakah pemecah masalah SDK harus mempertimbangkan versi prarilis saat memilih versi SDK yang akan digunakan.

Jika Anda tidak mengatur nilai ini secara eksplisit, nilai default bergantung pada apakah Anda menjalankan dari Visual Studio:

• Jika Anda tidak di Visual Studio, nilai defaultnya adalah true.
• Jika Anda berada di Visual Studio, itu menggunakan status prarilis yang diminta. Artinya, jika Anda menggunakan versi Pratinjau Visual Studio atau Anda mengatur Gunakan pratinjau dari .NET SDK (di bawah Alat>Opsi>Environment>Preview Features), nilai default adalah true. Jika tidak, nilai defaultnya adalah false.

rollForward

• Jenis: string
• Tersedia sejak: .NET Core 3.0 SDK.

Kebijakan melanjutkan penggunaan versi yang lebih baru yang akan digunakan saat memilih versi SDK, baik sebagai cadangan ketika versi SDK tertentu hilang atau sebagai arahan untuk menggunakan versi yang lebih baru. Versi harus ditentukan dengan nilai rollForward, kecuali Anda mengaturnya ke latestMajor. Perilaku roll forward default ditentukan oleh aturan pencocokan.

Untuk memahami kebijakan yang tersedia dan perilakunya, pertimbangkan definisi berikut untuk versi SDK dalam format x.y.znn:

• x adalah versi utama.
• y adalah versi minor.
• z adalah band fitur.
• nn adalah versi patch.

Tabel berikut ini memperlihatkan kemungkinan nilai untuk rollForward kunci:

Value	Behavior
patch	Menggunakan versi yang ditentukan. Jika tidak ditemukan, gulung maju ke tingkat patch terbaru. Jika tidak ditemukan, maka gagal. Nilai ini adalah perilaku warisan dari versi SDK sebelumnya.
feature	Menggunakan tingkat patch terbaru untuk patch utama, minor, dan fitur yang ditentukan. Jika tidak ditemukan, melanjutkan ke pita fitur lebih tinggi berikutnya dalam versi mayor/minor yang sama dan menggunakan tingkat patch terbaru untuk pita fitur tersebut. Jika tidak ditemukan, maka gagal.
minor	Menggunakan tingkat patch terbaru untuk patch utama, minor, dan fitur yang ditentukan. Jika tidak ditemukan, melanjutkan ke kelompok fitur yang lebih tinggi berikutnya dalam versi mayor/minor yang sama dan menggunakan tingkat patch terbaru untuk kelompok fitur tersebut. Jika tidak ditemukan, lanjutkan ke minor dan band fitur berikutnya yang lebih tinggi dalam mayor yang sama, dan gunakan tingkat patch terbaru untuk band fitur tersebut. Jika tidak ditemukan, maka gagal.
major	Menggunakan tingkat patch terbaru untuk patch utama, minor, dan fitur yang ditentukan. Jika tidak ditemukan, melanjutkan ke kelompok fitur yang lebih tinggi berikutnya dalam versi mayor/minor yang sama dan menggunakan tingkat patch terbaru untuk kelompok fitur tersebut. Jika tidak ditemukan, lanjutkan ke minor dan band fitur berikutnya yang lebih tinggi dalam mayor yang sama, dan gunakan tingkat patch terbaru untuk band fitur tersebut. Jika tidak ditemukan, melanjutkan ke yang utama, minor, dan fitur yang lebih tinggi berikutnya dan menggunakan patch level terbaru untuk band fitur tersebut. Jika tidak ditemukan, maka gagal.
latestPatch	Menggunakan tingkat patch terbaru yang diinstal yang cocok dengan versi besar, minor, dan fitur yang diminta, dengan tingkat patch yang lebih besar atau sama dengan nilai yang ditentukan. Jika tidak ditemukan, maka gagal.
latestFeature	Menggunakan pita fitur dan tingkat patch terpasang tertinggi yang cocok dengan mayor dan minor yang diminta, serta pita fitur dan tingkat patch yang lebih besar atau sama dengan nilai yang ditentukan. Jika tidak ditemukan, maka gagal.
latestMinor	Menggunakan tingkat minor, band fitur, dan patch terpasang tertinggi yang cocok dengan mayor yang diminta dengan tingkat minor, band fitur, dan patch yang lebih besar dari atau sama dengan nilai yang ditentukan. Jika tidak ditemukan, maka gagal.
latestMajor	Menggunakan SDK .NET terinstal tertinggi dengan versi yang lebih besar dari atau sama dengan nilai yang ditentukan. Jika tidak ditemukan, maka gagal.
disable	Tidak bergerak ke depan. Kecocokan yang tepat diperlukan.

paths

• Jenis: Array dari string
• Tersedia sejak: .NET 10 SDK.

Menentukan lokasi yang harus dipertimbangkan saat mencari SDK .NET yang kompatibel. Jalur dapat absolut atau relatif terhadap lokasi file global.json . Nilai $host$ khusus mewakili lokasi yang sesuai dengan executable yang sedang berjalan dotnet .

Jalur ini dicari dalam urutan yang ditentukan dan SDK pencocokan pertama digunakan.

Fitur ini memungkinkan penggunaan penginstalan SDK lokal (seperti SDK relatif terhadap akar repositori atau ditempatkan dalam folder kustom) yang tidak diinstal secara global pada sistem.

Fitur "jalur" hanya berfungsi saat menggunakan perintah yang melibatkan SDK .NET, seperti dotnet run. Ini TIDAK memengaruhi skenario seperti menjalankan peluncur apphost asli (app.exe), menjalankan dengan dotnet app.dll, atau menjalankan dengan dotnet exec app.dll. Untuk menggunakan fitur "jalur", Anda harus menggunakan perintah SDK seperti dotnet run.

errorMessage

• Jenis: string
• Tersedia sejak: .NET 10 SDK.

Menentukan pesan kesalahan kustom yang ditampilkan saat pemecah masalah SDK tidak dapat menemukan SDK .NET yang kompatibel.

msbuild-sdks

Jenis: object

Memungkinkan Anda mengontrol versi SDK proyek di satu tempat daripada di setiap proyek individual. Untuk informasi selengkapnya, lihat Bagaimana SDK proyek diselesaikan.

test

• Jenis: object

Menentukan informasi tentang pengujian.

runner

• Jenis: string
• Tersedia sejak: .NET 10.0 SDK.

Pengelola pengujian untuk menemukan/menjalankan pengujian.

Komentar di global.json

Komentar dalam file global.json didukung menggunakan komentar gaya JavaScript atau C#. Contohnya:

{
   // This is a comment.
  "sdk": {
    "version": "8.0.300" /* This is comment 2*/
  /* This is a
  multiline comment.*/
  }
}

Examples

Contoh berikut menunjukkan cara melarang penggunaan versi prarilis:

{
  "sdk": {
    "allowPrerelease": false
  }
}

Contoh berikut menunjukkan cara menggunakan versi tertinggi yang diinstal yang lebih besar atau sama dengan versi yang ditentukan. JSON yang ditampilkan melarang versi SDK apa pun yang lebih lama dari 7.0.200 dan memungkinkan 7.0.200 atau versi yang lebih baru, termasuk 8.0.xxx.

{
  "sdk": {
    "version": "7.0.200",
    "rollForward": "latestMajor"
  }
}

Contoh berikut menunjukkan cara menggunakan versi yang ditentukan dengan tepat:

{
  "sdk": {
    "version": "8.0.302",
    "rollForward": "disable"
  }
}

Contoh berikut menunjukkan cara menggunakan kelompok fitur terbaru dan versi patch terbaru yang diinstal dari versi utama dan versi minor tertentu. JSON yang ditampilkan melarang versi SDK apa pun yang lebih lama dari 8.0.302 dan memungkinkan 8.0.302 atau versi 8.0.xxx yang lebih baru, seperti 8.0.303 atau 8.0.402.

{
  "sdk": {
    "version": "8.0.302",
    "rollForward": "latestFeature"
  }
}

Contoh berikut menunjukkan cara menggunakan versi patch tertinggi yang diinstal dari versi tertentu. JSON yang ditampilkan melarang versi SDK apa pun yang lebih lama dari 8.0.102 dan mengizinkan 8.0.102 atau versi 8.0.1xx yang lebih baru, seperti 8.0.103 atau 8.0.199.

{
  "sdk": {
    "version": "8.0.102",
    "rollForward": "latestPatch"
  }
}

Contoh berikut menunjukkan cara menentukan jalur pencarian SDK tambahan dan pesan kesalahan kustom:

{
  "sdk": {
    "version": "10.0.100",
    "paths": [ ".dotnet", "$host$" ],
    "errorMessage": "The required .NET SDK wasn't found. Please run ./install.sh to install it."
  }
}

Contoh berikut menunjukkan versi yang ditentukan tidak valid. Output perintah dotnet --info menunjukkan pesan kesalahan: "Versi '10.0' tidak valid untuk nilai 'sdk/version'."

{
  "sdk": {
    "version": "10.0",
    "rollForward": "latestFeature"
  }
}

Contoh berikut menunjukkan cara menentukan Microsoft.Testing.Platform sebagai runner pengujian:

{
    "test": {
        "runner": "Microsoft.Testing.Platform"
    }
}

global.json dan .NET CLI

Untuk mengatur versi SDK dalam file global.json , sangat membantu untuk mengetahui versi SDK mana yang diinstal di komputer Anda. Untuk informasi tentang cara melakukannya, lihat Cara memeriksa apakah .NET sudah diinstal.

Untuk menginstal versi SDK .NET tambahan di komputer Anda, kunjungi halaman Unduh .NET.

Anda dapat membuat file global.json baru di direktori saat ini dengan menjalankan perintah baru dotnet, mirip dengan contoh berikut:

dotnet new globaljson --sdk-version 8.0.302 --roll-forward latestFeature

Aturan pencocokan

Note

Aturan pencocokan diatur oleh titik masuk dotnet.exe, yaitu titik awal yang umum di semua runtime .NET yang diinstal. Aturan pencocokan untuk versi terbaru .NET Runtime yang diinstal digunakan saat Anda memiliki beberapa runtime yang diinstal berdampingan atau jika Anda menggunakan file global.json.

Aturan berikut berlaku saat menentukan versi SDK mana yang akan digunakan:

• Jika tidak ada file global.json yang ditemukan, atau global.json tidak menentukan versi SDK dan tidak menentukan allowPrerelease nilai, versi SDK tertinggi yang diinstal digunakan (setara dengan pengaturan rollForward ke latestMajor). Apakah versi SDK prarilis dianggap tergantung pada cara dotnet dipanggil:

  • Jika Anda tidak di Visual Studio, versi prarilis akan dipertimbangkan.
  • Jika Anda berada di Visual Studio, itu menggunakan status prarilis yang diminta. Artinya, jika Anda menggunakan versi Pratinjau Visual Studio atau Anda mengatur opsi Gunakan pratinjau dari .NET SDK (di bawah Tools>Options>Environment>Preview Features), versi prarilis akan dipertimbangkan; jika tidak, hanya versi rilis yang akan dipertimbangkan.

• Jika file global.json ditemukan yang tidak menentukan versi SDK tetapi menentukan allowPrerelease nilai, versi SDK tertinggi yang diinstal digunakan (setara dengan pengaturan rollForward ke latestMajor). Apakah versi SDK terbaru dapat rilis atau prarilis tergantung pada nilai allowPrerelease. true menunjukkan versi prarilis dipertimbangkan; false menunjukkan bahwa hanya versi rilis yang dipertimbangkan.

• Jika file global.json ditemukan dan menentukan versi SDK:

  • Jika tidak ada nilai rollForward yang diatur, maka nilai tersebut akan menggunakan patch sebagai kebijakan rollForward default. Jika tidak, periksa setiap nilai dan perilakunya di bagian rollForward .
  • Apakah versi prarilis diperhitungkan dan bagaimana perilaku bawaan ketika allowPrerelease tidak ditetapkan dijelaskan di bagian allowPrerelease.

Memecahkan masalah peringatan kompilasi

• Peringatan berikut menunjukkan bahwa proyek Anda dikompilasi menggunakan versi prarilis SDK .NET:

  Anda menggunakan versi pratinjau .NET. Lihat: https://aka.ms/dotnet-support-policy

  .NET versi SDK memiliki riwayat dan komitmen berkualitas tinggi. Namun, jika Anda tidak ingin menggunakan versi prarilis, periksa berbagai strategi yang dapat Anda gunakan di bagian allowPrerelease . Untuk komputer yang belum pernah menginstal .NET Core 3.0 atau runtime atau SDK yang lebih tinggi, Anda perlu membuat file global.json dan menentukan versi yang tepat yang ingin Anda gunakan.

• Peringatan berikut menunjukkan bahwa proyek Anda menargetkan EF Core 1.0 atau 1.1, yang tidak kompatibel dengan .NET Core 2.1 SDK dan versi yang lebih baru:

  Proyek startup '{startupProject}' menargetkan kerangka kerja '. NETCoreApp' versi '{targetFrameworkVersion}'. Versi alat baris perintah Entity Framework Core .NET ini hanya mendukung versi 2.0 atau yang lebih tinggi. Untuk informasi tentang cara menggunakan versi lebih lama dari alat, lihat https://go.microsoft.com/fwlink/?linkid=871254.

  Dimulai dengan .NET Core 2.1 SDK (versi 2.1.300), perintah dotnet ef disertakan dalam SDK. Untuk mengkompilasi proyek Anda, instal .NET Core 2.0 SDK (versi 2.1.201) atau yang lebih lama di komputer Anda dan tentukan versi SDK yang diinginkan menggunakan file global.json. Untuk informasi selengkapnya tentang perintah dotnet ef, lihat Alat Baris Perintah EF Core .NET.

• Jika Anda menggunakan global.json untuk tetap menggunakan versi SDK .NET tertentu, perhatikan bahwa Visual Studio hanya pernah menginstal satu salinan SDK .NET. Jadi, jika Anda memperbarui versi Visual Studio Anda, program tersebut akan menghapus versi sebelumnya dari .NET SDK yang digunakan untuk menginstal versi baru. Ini akan menghapus versi lama bahkan jika merupakan versi utama .NET yang berbeda.

Untuk menghindari Visual Studio menghapus versi SDK .NET, instal SDK .NET mandiri dari halaman download. Namun, jika ya, Anda tidak akan mendapatkan pembaruan otomatis untuk versi SDK .NET tersebut lagi melalui Visual Studio dan mungkin berisiko untuk masalah keamanan.

Lihat juga

• Bagaimana SDK proyek diselesaikan