global.json’a genel bakış

Bu makale: ✔️ .NET Core 3.1 SDK ve sonraki sürümleri için geçerlidir

global.json dosyası, .NET CLI komutlarını çalıştırdığınızda hangi .NET SDK sürümünün kullanılacağını tanımlamanızı sağlar. .NET SDK sürümünün seçilmesi, projenin hedefledikleri çalışma zamanı sürümünü belirtmekten bağımsızdır. .NET SDK sürümü, .NET CLI'nin hangi sürümünün kullanıldığını gösterir. Bu makalede, global.json kullanarak SDK sürümünü seçme açıklanmaktadır.

Makinenizde yüklü olan en son SDK sürümünü her zaman kullanmak istiyorsanız, global.json dosyası gerekmez. Ancak CI (sürekli tümleştirme) senaryolarında genellikle kullanılan SDK sürümü için kabul edilebilir bir aralık belirtmek istersiniz. global.json dosyası, kabul edilebilir bir rollForward sürüm aralığı belirtmek için esnek yollar sağlayan bir özelliğe sahiptir. Örneğin, aşağıdaki global.json dosyası makineye yüklenen 10.0 için 10.0.100 veya sonraki bir özellik bandını veya düzeltme ekini seçer:

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

global.json dosyasını aramak için .NET SDK'sında iki bileşene güvenirsiniz. Her bir bileşen farklı bir konumdan başlar ve üst dizinlerde yukarıya doğru arama yapar.

• .NET SDK muxerdotnet CLI komutlarını işler. Proje diziniyle aynı olması gerekmeyen geçerli çalışma dizininden başlar.
• .NET MSBuild proje SDK çözümleyicisi derlemeler sırasında proje SDK'larını çözümler. Varsa, çözüm dosyasını içeren dizinden başlar. Çözüm dosyası yoksa, geçerli proje dosyasını içeren dizinden başlar. Hiçbir dosya yoksa geçerli çalışma dizinini kullanır.

SDK sürümü yerine çalışma zamanı sürümünü belirtme hakkında bilgi için bkz . Hedef çerçeveler.

global.json şeması

sdk

Tür: object

Seçecek .NET SDK'sı hakkındaki bilgileri belirtir.

version

• Tür: string

Kullanılacak .NET SDK sürümü.

Bu alan:

• 10.0.100 gibi tam sürüm numarasını gerektirir.
• 10, 10.0 veya 10.0.x gibi sürüm numaralarını desteklemez.
• Wildcard desteği yok.
• Sürüm aralıklarını desteklemez.

allowPrerelease

• Tür: boolean
• Şu tarihten itibaren kullanılabilir: .NET Core 3.0 SDK.

Kullanılacak SDK sürümünü seçerken SDK çözümleyicisinin yayın öncesi sürümleri göz önünde bulundurması gerekip gerekmediğini gösterir.

Bu değeri açıkça ayarlamazsanız, varsayılan değer Visual Studio çalıştırıp çalıştırmadığınıza bağlıdır:

• Visual Studio'da değilseniz, varsayılan değer true'dir.
• Visual Studio'daysanız, istenen yayın öncesi durumunu kullanır. Yani, Visual Studio'nun Önizleme sürümünü kullanıyorsanız veya .NET SDK önizlemelerini kullan seçeneğini ayarlarsanız (Araçlar>Seçenekler>Ortam>Önizleme Özellikleri altında), varsayılan değer true'dir. Aksi takdirde, varsayılan değer şeklindedir false.

rollForward

• Tür: string
• Şu tarihten itibaren kullanılabilir: .NET Core 3.0 SDK.

Eksik bir SDK sürümü olduğunda alternatif olarak ya da daha sonraki bir sürümü kullanma talimatı olarak SDK sürümü seçildiğinde kullanılacak ileri sürüm geçiş politikası. Bir sürümrollForward değeri ile belirtilmelidir, aksi takdirde bunu latestMajor olarak ayarlıyorsanız. Varsayılan ileri sarma davranışı eşleşen kurallar tarafından belirlenir.

Kullanılabilir ilkeleri ve bunların davranışlarını anlamak için, x.y.znn biçimindeki bir SDK sürümü için aşağıdaki tanımları göz önünde bulundurun:

• x ana sürümdür.
• y ikincil sürümdür.
• z özellik bandıdır.
• nn yama sürümüdür.

Aşağıdaki tabloda anahtar için olası değerler gösterilmektedir rollForward :

Value	Behavior
patch	Belirtilen sürümü kullanır. Eğer bulunamazsa, güncel yama seviyesine yükseltilir. Bulunamazsa başarısız olur. Bu değer, SDK'nın önceki sürümlerindeki eski davranıştır.
feature	Belirtilen major, minor ve feature bandı için en son yama seviyesini kullanır. Bulunamazsa, aynı ana/ikincil küme içinde bir sonraki daha yüksek özellik bandına ilerler ve bu özellik bandı için en son düzeltme seviyesini kullanır. Bulunamazsa başarısız olur.
minor	Belirtilen major, minor ve feature bandı için en son yama seviyesini kullanır. Bulunamazsa, aynı ana/ikincil sürümde sonraki daha yüksek özellik bandına ileri doğru yuvarlanır ve bu özellik bandı için en son düzeltme eki düzeyini kullanır. Bulunamadığında, aynı ana sürümde bir sonrakine geçilir ve daha yüksek seviyedeki ikincil ve özellik grubuna geçerek o özellik grubunun en son düzeltme eki seviyesini kullanır. Bulunamazsa başarısız olur.
major	Belirtilen major, minor ve feature bandı için en son yama seviyesini kullanır. Bulunamazsa, aynı ana/ikincil sürümde sonraki daha yüksek özellik bandına ileri doğru yuvarlanır ve bu özellik bandı için en son düzeltme eki düzeyini kullanır. Bulunamadığında, aynı ana sürümde bir sonrakine geçilir ve daha yüksek seviyedeki ikincil ve özellik grubuna geçerek o özellik grubunun en son düzeltme eki seviyesini kullanır. Bulunamazsa, daha yüksek bir ana, ikincil ve özellik bandına ilerler ve o özellik bandı için en son yama seviyesini kullanır. Bulunamazsa başarısız olur.
latestPatch	İstenen birincil, ikincil ve özellik bandıyla eşleşen en son yüklenen düzeltme eki seviyesini kullanır; bu düzeltme eki seviyesi, belirtilen değerden büyük veya eşit bir düzeyde olmalıdır. Bulunamazsa başarısız olur.
latestFeature	İstenen ana ve ikincil ile eşleşen özellik bandı ve düzeltme eki düzeyinin en yüksek yüklü halini ve belirtilen değerden büyük veya eşit bir özellik bandı ve düzeltme eki düzeyini kullanır. Bulunamazsa başarısız olur.
latestMinor	Belirtilen değerden büyük veya buna eşit olan küçük sürüm, özellik bandı ve düzeltme seviyesi ile eşleşen, istenen ana sürüme sahip en yüksek yüklü küçük sürüm, özellik bandı ve düzeltme seviyesini kullanır. Bulunamazsa başarısız olur.
latestMajor	Belirtilen değerden büyük veya buna eşit bir sürüme sahip en yüksek yüklü .NET SDK'sını kullanır. Bulunamazsa başarısız olur.
disable	İleriye doğru ilerlemiyor. Tam eşleşme gereklidir.

paths

• Dizi: string
• Şu tarihten itibaren kullanılabilir: .NET 10 SDK.

Uyumlu bir .NET SDK'sı aranırken dikkate alınması gereken konumları belirtir. Yollar, global.json dosyasının konumuna göre veya mutlak olabilir. Özel değer $host$ , çalışan dotnet yürütülebilir dosyaya karşılık gelen konumu temsil eder.

Bu yollar tanımlanma sırasına göre aranarak eşleşen ilk SDK kullanılır.

Bu özellik, sistemde genel olarak yüklenmemiş yerel SDK yüklemelerinin (depo köküne göre SDK'lar gibi) kullanılmasını veya özel bir klasöre yerleştirilmesini sağlar.

"Yollar" özelliği yalnızca dotnet run gibi .NET SDK'sını çalıştıran komutları kullanırken çalışır. Bu, yerel uygulama başlatıcı app.exe ile çalıştırma, dotnet app.dll ile çalışma veya dotnet exec app.dll ile çalıştırma gibi senaryoları ETKILEMEZ. "Yollar" özelliğini kullanmak için gibi dotnet runSDK komutlarını kullanmanız gerekir.

errorMessage

• Tür: string
• Şu tarihten itibaren kullanılabilir: .NET 10 SDK.

SDK çözümleyicisi uyumlu bir .NET SDK'sını bulamadıklarında görüntülenen özel bir hata iletisi belirtir.

msbuild-sdks

Tür: object

Proje SDK'sı sürümünü her bir proje yerine tek bir yerde denetlemenize olanak tanır. Daha fazla bilgi için bkz . Proje SDK'ları nasıl çözümlenir?

test

• Tür: object

Testler hakkındaki bilgileri belirtir.

runner

• Tür: string
• Şu tarihten itibaren kullanılabilir: .NET 10.0 SDK.

Testleri bulup çalıştırmak için test çalıştırıcısı.

global.json açıklamaları

global.json dosyalarındaki açıklamalar JavaScript veya C# stili açıklamalar kullanılarak desteklenir. Örneğin:

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

Examples

Aşağıdaki örnek, yayın öncesi sürümlerin kullanılmasına nasıl izin verilmeyeceğini göstermektedir.

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

Aşağıdaki örnekte, yüklü olan ve belirtilen sürümden daha büyük veya eşit olan en yüksek sürümün nasıl kullanılacağı gösterilmektedir. Gösterilen JSON, 7.0.200'den önceki tüm SDK sürümlerine izin vermemektedir ve 8.0.xxx dahil olmak üzere 7.0.200 veya sonraki sürümlere izin verir.

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

Aşağıdaki örnekte, tam olarak belirtilen sürümün nasıl kullanılacağı gösterilmektedir:

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

Aşağıdaki örnekte, belirli bir ana ve ikincil sürümün yüklü en son özellik bandının ve düzeltme eki sürümünün nasıl kullanılacağı gösterilmektedir. Gösterilen JSON, 8.0.302'den önceki sdk sürümlerine izin vermemektedir ve 8.0.302 veya 8.0.303 veya 8.0.402 gibi herhangi bir sonraki 8.0.xxx sürümüne izin verir.

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

Aşağıdaki örnekte, belirli bir sürümün yüklü en yüksek düzeltme eki sürümünün nasıl kullanılacağı gösterilmektedir. Gösterilen JSON, 8.0.102'den önceki sdk sürümlerine izin vermemektedir ve 8.0.102 veya 8.0.103 veya 8.0.199 gibi daha sonraki 8.0.1xx sürümlerine izin verir.

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

Aşağıdaki örnekte ek SDK arama yollarının ve özel bir hata iletisinin nasıl belirtileceğini gösterilmektedir:

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

Aşağıdaki örnekte geçersiz bir sürüm belirtilmiştir. Komutun dotnet --info çıktısı şu hata iletisini gösterir: "'10.0' sürümü 'sdk/version' değeri için geçerli değil."

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

Aşağıdaki örnek, test çalıştırıcısı olarak Microsoft.Testing.Platform'yi nasıl belirteceğinizi gösterir.

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

global.json ve .NET CLI

global.json dosyasında sdk sürümü ayarlamak için makinenizde hangi SDK sürümlerinin yüklü olduğunu bilmek yararlı olur. Bunun nasıl yapılacağını öğrenmek için bkz. .NET zaten yüklü olup olmadığını denetleme.

Makinenize ek .NET SDK sürümleri yüklemek için İndir .NET sayfasını ziyaret edin.

Aşağıdaki örneğe benzer şekilde dotnet new komutunu yürüterek geçerli dizinde yeni bir global.json dosyası oluşturabilirsiniz:

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

Eşleştirme kuralları

Note

Eşleşen kurallar, tüm yüklü .NET çalışma zamanlarında ortak olan dotnet.exe giriş noktası tarafından yönetilir. .NET Çalışma Zamanı'nın en son yüklü sürümü için eşleşen kurallar, yan yana yüklenmiş birden çok çalışma zamanınız olduğunda veya global.json dosyası kullanıyorsanız kullanılır.

SDK'nın hangi sürümünün kullanılacağını belirlerken aşağıdaki kurallar geçerlidir:

• global.json dosyası bulunamazsa veya global.json SDK sürümünü belirtmezse ve bir allowPrerelease değer belirtmezse, en yüksek yüklü SDK sürümü kullanılır (ayarına rollForwardlatestMajoreşdeğerdir). Yayın öncesi SDK sürümlerinin dikkate alınıp alınmayacağı, nasıl dotnet çağrıldığına bağlıdır:

  • Visual Studio'da değil iseniz, yayın öncesi sürümler dikkate alınır.
  • Visual Studio'daysanız, istenen yayın öncesi durumunu kullanır. Yani, Visual Studio Önizleme sürümünü kullanıyorsanız veya .NET SDK Önizlemelerini Kullan seçeneğini (Araçlar>Seçenekler>Ortam>Önizleme Özellikleri) ayarlarsanız, yayın öncesi sürümler dikkate alınır; aksi takdirde, yalnızca sürüm sonrası sürümler dikkate alınır.

• Eğer SDK sürümünü belirtmeyen ancak bir değeri belirten bir allowPrerelease dosyası bulunursa, en yüksek yüklü SDK sürümü kullanılır (bu, rollForward ayarını latestMajor olarak belirlemeye eşdeğerdir). En son SDK sürümünün yayın veya yayın öncesi olup olmadığı değerine allowPrereleasebağlıdır. true yayın öncesi sürümlerin dikkate alınıyor olduğunu gösterir; false yalnızca sürüm sürümlerinin dikkate alındığını gösterir.

• bir global.json dosyası bulunursa ve bir SDK sürümü belirtirse:

  • rollForward Hiçbir değer ayarlanmadıysa, varsayılan patch ilke olarak kullanırrollForward. Aksi takdirde, rollForward bölümündeki her bir değeri ve bunların davranışını denetleyin.
  • Yayın öncesi sürümlerin dikkate alınıp alınmadığı ve allowPrerelease ayarlanmamışsa varsayılan davranışın ne olduğu, allowPrerelease bölümünde açıklanmıştır.

Derleme uyarılarıyla ilgili sorunları giderme

• Aşağıdaki uyarılar, projenizin .NET SDK'sının yayın öncesi sürümü kullanılarak derlendiğini gösterir:

  .NET önizleme sürümünü kullanıyorsunuz. Bkz. https://aka.ms/dotnet-support-policy

  .NET SDK sürümlerinin geçmişi ve yüksek kaliteli olma taahhüdü vardır. Ancak, yayın öncesi bir sürüm kullanmak istemiyorsanız allowPrerelease bölümünde kullanabileceğiniz farklı stratejileri denetleyin. .NET Core 3.0 veya üzeri çalışma zamanı veya SDK'sı yüklü olmayan makineler için bir global.json dosyası oluşturmanız ve kullanmak istediğiniz tam sürümü belirtmeniz gerekir.

• Aşağıdaki uyarı, projenizin .NET Core 2.1 SDK ve sonraki sürümleriyle uyumlu olmayan EF Core 1.0 veya 1.1'i hedeflediğini gösterir:

  Başlangıç projesi '{startupProject}' '.NETCoreApp' sürüm '{targetFrameworkVersion}' çerçevesini hedefliyor. Entity Framework Core .NET Komut Satırı Araçları'nın bu sürümü yalnızca sürüm 2.0 veya üzerini destekler. Araçların eski sürümlerini kullanma hakkında bilgi için bkz https://go.microsoft.com/fwlink/?linkid=871254. .

  .NET Core 2.1 SDK'sı (sürüm 2.1.300) ile başlayarak dotnet ef komutu SDK'ya eklenir. Projenizi derlemek için makinenize Core 2.0 SDK (sürüm 2.1.201) veya önceki .NET yükleyin ve global.json dosyasını kullanarak istediğiniz SDK sürümünü tanımlayın. dotnet ef komutu hakkında daha fazla bilgi için bkz. EF Core .NET Komut Satırı Araçları.

• .NET SDK'sının belirli bir sürümünde kalmak için global.json kullanıyorsanız Visual Studio .NET SDK'sının yalnızca tek bir kopyasını yüklediğini unutmayın. Bu nedenle, Visual Studio sürümünüzü yükseltirseniz, yeni sürümü yüklemek için kullandığı .NET SDK'sının önceki sürümünü kaldırır. Farklı bir ana .NET sürümü olsa bile eski sürümü kaldırır.

.NET SDK'sının sürümlerinin Visual Studio kaldırılmasını önlemek için download sayfasından tek başına .NET SDK'sını yükleyin. Ancak bunu yaparsanız, Visual Studio aracılığıyla artık .NET SDK'sının bu sürümünde otomatik güncelleştirmeler almazsınız ve güvenlik sorunları için risk altında olabilirsiniz.

Ayrıca bakınız

• Proje SDK'ları nasıl çözümlenir?