Bagikan melalui

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

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

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.

version

  • Jenis: string

Versi .NET SDK 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 berada di Visual Studio, nilai defaultnya adalah true.
  • Jika Anda berada di Visual Studio, itu akan memakai status prarilis yang diminta. Artinya, jika Anda menggunakan versi Pratinjau Visual Studio atau mengatur opsi Gunakan pratinjau .NET SDK (di bawah Alat>Opsi>Lingkungan>Fitur Pratinjau), nilai defaultnya 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 .NET SDK terpasang 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 .NET SDK 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 .NET SDK, 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 .NET SDK 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 .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 8.0.302 --roll-forward latestFeature

Aturan pencocokan

Note

Aturan pencocokan diatur oleh poin masuk dotnet.exe, yang umum di semua runtime .NET yang terpasang. Aturan pencocokan untuk versi terbaru runtime .NET 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 berada di Visual Studio, versi prarilis akan dipertimbangkan.
    • Jika Anda berada di Visual Studio, itu akan memakai status prarilis yang diminta. Artinya, jika Anda menggunakan versi Pratinjau Visual Studio atau Anda mengatur opsi Gunakan pratinjau .NET SDK (di bawah Alat>Opsi>Lingkungan>Fitur Pratinjau), versi prarilis akan 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 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 dari .NET SDK:

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

    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 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), 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 lebih lanjut tentang perintah dotnet ef, 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, peningkatan tersebut akan menghapus versi .NET SDK sebelumnya yang digunakan untuk menginstal versi baru. Ini menghapus versi lama meskipun itu adalah versi .NET utama yang berbeda.

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

Lihat juga

  • Last updated on