gambaran umum global.json

Artikel
01/10/2024

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

File global.json memungkinkan Anda menentukan versi .NET SDK mana yang digunakan saat Anda menjalankan perintah .NET CLI. Memilih versi .NET SDK independen dari menentukan versi runtime target proyek. Versi .NET SDK menunjukkan versi .NET CLI 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 6.0.300 atau pita fitur atau patch yang lebih baru untuk 6.0 yang diinstal pada komputer:

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

.NET SDK mencari file global.json di direktori kerja saat ini (yang belum tentu sama dengan direktori proyek) atau salah satu direktori induknya.

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

skema global.json

sdk

Jenis: object

Menentukan informasi tentang .NET SDK untuk dipilih.

versi

Jenis: string

Versi .NET SDK yang akan digunakan.

Bidang ini:

Tidak memiliki dukungan kartubebas; artinya, Anda harus menentukan nomor versi lengkap.
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 berada 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 opsi Gunakan pratinjau .NET SDK (di bawah Fitur Pratinjau Lingkungan>Opsi>Alat>), nilai defaultnya adalah .true Jika tidak, nilai defaultnya adalah false.

rollForward

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

Kebijakan roll-forward yang akan digunakan saat memilih versi SDK, baik sebagai fallback saat versi SDK tertentu hilang atau sebagai arahan untuk menggunakan versi yang lebih tinggi. Versi harus ditentukan dengan rollForward nilai, kecuali Anda mengaturnya ke latestMajor. Perilaku roll forward default ditentukan oleh aturan yang cocok.

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:

Nilai	Perilaku
`patch`	Menggunakan versi yang ditentukan. Jika tidak ditemukan, gulung maju ke tingkat patch terbaru. Jika tidak ditemukan, gagal. Nilai ini adalah perilaku warisan dari versi SDK sebelumnya.
`feature`	Menggunakan tingkat patch terbaru untuk pita utama, minor, dan fitur yang ditentukan. Jika tidak ditemukan, gulir ke band fitur yang lebih tinggi berikutnya dalam mayor/minor yang sama dan menggunakan tingkat patch terbaru untuk pita fitur tersebut. Jika tidak ditemukan, gagal.
`minor`	Menggunakan tingkat patch terbaru untuk pita utama, minor, dan fitur yang ditentukan. Jika tidak ditemukan, gulir ke band fitur yang lebih tinggi berikutnya dalam versi mayor/minor yang sama dan menggunakan tingkat patch terbaru untuk pita fitur tersebut. Jika tidak ditemukan, gulir ke minor dan band fitur yang lebih tinggi berikutnya dalam mayor yang sama dan menggunakan tingkat patch terbaru untuk band fitur tersebut. Jika tidak ditemukan, gagal.
`major`	Menggunakan tingkat patch terbaru untuk pita utama, minor, dan fitur yang ditentukan. Jika tidak ditemukan, gulir ke band fitur yang lebih tinggi berikutnya dalam versi mayor/minor yang sama dan menggunakan tingkat patch terbaru untuk pita fitur tersebut. Jika tidak ditemukan, gulir ke minor dan band fitur yang lebih tinggi berikutnya dalam mayor yang sama dan menggunakan tingkat patch terbaru untuk band fitur tersebut. Jika tidak ditemukan, gulung maju ke band fitur, minor, dan utama yang lebih tinggi berikutnya dan menggunakan tingkat patch terbaru untuk pita fitur tersebut. Jika tidak ditemukan, gagal.
`latestPatch`	Menggunakan tingkat patch terbaru yang diinstal yang cocok dengan pita utama, minor, dan fitur yang diminta dengan tingkat patch yang lebih besar dari atau sama dengan nilai yang ditentukan. Jika tidak ditemukan, gagal.
`latestFeature`	Menggunakan pita fitur dan tingkat patch terpasang tertinggi yang cocok dengan mayor dan minor yang diminta dengan pita fitur dan tingkat patch yang lebih besar dari atau sama dengan nilai yang ditentukan. Jika tidak ditemukan, 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, gagal.
`latestMajor`	Menggunakan .NET SDK terpasang tertinggi dengan versi yang lebih besar dari atau sama dengan nilai yang ditentukan. Jika tidak ditemukan, gagal.
`disable`	Tidak bergulir ke depan. Kecocokan yang tepat diperlukan.

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.

Komentar di global.json

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

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

Contoh

Contoh berikut menunjukkan cara tidak menggunakan 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 2.2.200 dan memungkinkan 2.2.200 atau versi yang lebih baru, termasuk 3.0.xxx dan 3.1.xxx.

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

Contoh berikut menunjukkan cara menggunakan versi yang ditentukan dengan tepat:

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

Contoh berikut menunjukkan cara menggunakan band fitur terbaru dan versi patch yang diinstal dari versi utama dan minor tertentu. JSON yang ditampilkan melarang versi SDK apa pun yang lebih lama dari 3.1.102 dan mengizinkan 3.1.102 atau versi 3.1.xxx yang lebih baru, seperti 3.1.103 atau 3.1.200.

{
  "sdk": {
    "version": "3.1.102",
    "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 3.1.102 dan mengizinkan 3.1.102 atau versi 3.1.1xx yang lebih baru, seperti 3.1.103 atau 3.1.199.

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

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 .NET SDK 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 6.0.100

Aturan kecocokan

Catatan

Aturan pencocokan diatur oleh dotnet.exe titik masuk, yang umum di semua runtime yang diinstal .NET yang diinstal. Aturan pencocokan untuk versi terbaru runtime .NET yang diinstal digunakan saat Anda memiliki beberapa runtime yang diinstal berdampingan atau jika atau 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 atau 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 berada 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 .NET SDK (di bawah Fitur Pratinjau Lingkungan>Opsi>Alat>), versi prarilis dipertimbangkan; jika tidak, hanya versi rilis yang 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 rollForward nilai yang ditetapkan, nilai tersebut menggunakan latestPatch sebagai kebijakan default rollForward . Jika tidak, periksa setiap nilai dan perilakunya di bagian rollForward .
- Apakah versi prarilis dipertimbangkan dan apa perilaku default saat allowPrerelease tidak diatur dijelaskan di bagian allowPrerelease .

Memecahkan masalah peringatan build

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

Anda bekerja dengan versi pratinjau .NET Core SDK. Anda dapat menentukan versi SDK melalui file global.json dalam proyek saat ini. Selengkapnya di https://go.microsoft.com/fwlink/?linkid=869452.

Anda menggunakan versi pratinjau .NET. Melihat: https://aka.ms/dotnet-core-preview

Versi .NET SDK memiliki riwayat dan komitmen untuk menjadi 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 Entity Framework Core .NET Command-line Tools ini hanya mendukung versi 2.0 atau yang lebih tinggi. Untuk informasi tentang menggunakan versi alat yang lebih lama, lihat https://go.microsoft.com/fwlink/?linkid=871254.

Dimulai dengan .NET Core 2.1 SDK (versi 2.1.300), dotnet ef perintah 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 dotnet ef perintah, lihat Alat Baris Perintah EF Core .NET.
Jika Anda menggunakan global.json untuk tetap menggunakan versi .NET SDK tertentu, perhatikan bahwa Visual Studio hanya pernah menginstal satu salinan .NET SDK. Jadi, jika Anda meningkatkan versi Visual Studio, versi sebelumnya akan menghapus .NET SDK yang digunakan untuk menginstal versi baru. Ini menghapus versi lama meskipun versi .NET utama yang berbeda.

Untuk menghindari Visual Studio menghapus versi .NET SDK, Anda harus menginstal .NET SDK yang berdiri sendiri dari halaman unduhan. Perhatikan bahwa jika Anda melakukannya, Anda tidak akan mendapatkan pembaruan otomatis untuk versi .NET SDK tersebut lagi melalui Visual Studio dan mungkin berisiko untuk masalah keamanan.

Lihat juga

Bagaimana SDK proyek diselesaikan