global.json’a genel bakış

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

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 8.0 için 8.0.300 veya sonraki bir özellik bandını veya düzeltme ekini seçer:

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

.NET SDK, geçerli çalışma dizininde (proje diziniyle aynı olması gerekmeyebilir) veya üst dizinlerinden birinde global.json bir dosya arar.

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

şemayı global.json

sdk

Tür: object

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

sürüm

• Tür: string

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

Bu alan:

• Joker karakter desteği yoktur; başka bir ifadeyle, tam sürüm numarasını belirtmeniz gerekir.
• 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'dan çalıştırıp çalıştırmadığınıza bağlıdır:

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

rollForward

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

Belirli bir SDK sürümü eksik olduğunda geri dönüş olarak veya daha sonraki bir sürümü kullanmak için yönerge olarak BIR SDK sürümü seçerken kullanılacak ileri sarma ilkesi. sürümü olarak ayarlanmadığı latestMajorsürece bir rollForward değerle belirtilmelidir. Varsayılan ileri sarma davranışı eşleşen kurallar tarafından belirlenir.

Kullanılabilir ilkeleri ve bunların davranışlarını anlamak için, biçiminde bir SDK sürümü x.y.znniç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 düzeltme eki sürümüdür.

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

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?

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.*/
  }
}

Örnekler

Aşağıdaki örnekte, yayın öncesi sürümlerin kullanımına nasıl izin verilmiy kullanılacağı gösterilmektedir:

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

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'in zaten yüklü olup olmadığını denetleme.

Makinenize ek .NET SDK sürümleri yüklemek için İndirme .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ı

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 rollForward latestMajoreş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ğilseniz , yayın öncesi sürümler dikkate alınır.
  • Visual Studio'daysanız, istenen ön sürüm durumunu kullanır. Başka bir ifadeyle, Visual Studio'nun Önizleme sürümünü kullanıyorsanız veya .NET SDK'sının önizlemelerini kullan seçeneğini (Araçlar>Seçenekleri>Ortam>Önizleme Özellikleri altında) ayarlarsanız, ön sürümler dikkate alınır; aksi takdirde yalnızca sürüm sürümleri dikkate alınır.

• SDK sürümünü belirtmeyen ancak bir değer belirten bir global.json dosyası bulunursa, en yüksek yüklü SDK sürümü kullanılır (ayarına latestMajorrollForward eşdeğerdir).allowPrerelease 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 rollForward ilke olarak kullanırlatestPatch. Aksi takdirde rollForward bölümünde her değeri ve bunların davranışını denetleyin.
  • Yayın öncesi sürümlerin dikkate alınıp alınmadığı ve ayarlanmamışsa allowPrerelease 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'in ö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}' hedef çerçevesi '. NETCoreApp' sürümü '{targetFrameworkVersion}'. 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) dotnet ef ile başlayarak, komut SDK'ya eklenir. Projenizi derlemek için makinenize .NET Core 2.0 SDK (sürüm 2.1.201) veya önceki bir sürümü yükleyin ve global.json dosyasını kullanarak istediğiniz SDK sürümünü tanımlayın. Komut hakkında dotnet ef 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'nun .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.

Visual Studio'nun .NET SDK sürümlerini kaldırmasını önlemek için, indirme 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ı riski altında olabilirsiniz.

Ayrıca bkz.

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