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ıldığını tanımlamanızı sağlar. .NET SDK sürümünün seçilmesi, projenin hedefle olduğu çalışma zamanı sürümünü belirtmekten bağımsızdır. .NET SDK sürümü, .NET CLI'nın 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ı 6.0.300'ü veya makinede yüklü olan 6.0 için herhangi bir sonraki özellik bandını veya düzeltme ekini seçer:

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

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

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.

sürüm

  • Türü: string

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

Bu alan:

  • Joker karakter desteği yoktur; yani, 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 çalıştırıp çalıştırmadığınıza bağlıdır:

  • Visual Studio içinde değilseniz, varsayılan değer olurtrue.
  • Visual Studio'daysanız, istenen ön sürüm durumunu kullanır. Yani, Visual Studio Önizleme sürümünü kullanıyorsanız veya .NET SDK'sının önizlemelerini kullan seçeneğini ayarlarsanız (AraçlarSeçeneklerEnvironmentPreview>>>Özellikleri'nin altında), varsayılan değer olurtrue. 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 yüksek bir sürümü kullanmaya yönelik bir yönerge olarak SDK sürümünü seçerken kullanılacak ileri sarma ilkesi. Bir sürümü olarak ayarlamadığınız 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, bir SDK sürümü için biçiminde x.y.znnaş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 :

Değer Davranış
patch Belirtilen sürümü kullanır.
Bulunamazsa en son düzeltme eki düzeyine ileriye doğru ilerler.
Bulunamazsa başarısız olur.

Bu değer, SDK'nın önceki sürümlerindeki eski davranıştır.
feature Belirtilen ana, ikincil ve özellik bandı için en son yama düzeyini kullanır.
Bulunamazsa, aynı ana/ikincil içindeki bir sonraki daha yüksek özellik bandına ileri doğru döner ve bu özellik bandı için en son düzeltme eki düzeyini kullanır.
Bulunamazsa başarısız olur.
minor Belirtilen ana, ikincil ve özellik bandı için en son yama düzeyini kullanır.
Bulunamazsa, aynı ana/ikincil sürümde sonraki daha yüksek özellik bandına ileri doğru döner ve bu özellik bandı için en son düzeltme eki düzeyini kullanır.
Bulunamazsa, aynı ana daldaki sonraki daha yüksek ikincil ve özellik bandına ileri sarılarak bu özellik bandı için en son yama düzeyini kullanır.
Bulunamazsa başarısız olur.
major Belirtilen ana, ikincil ve özellik bandı için en son yama düzeyini kullanır.
Bulunamazsa, aynı ana/ikincil sürümde sonraki daha yüksek özellik bandına ileri doğru döner ve bu özellik bandı için en son düzeltme eki düzeyini kullanır.
Bulunamazsa, aynı ana daldaki sonraki daha yüksek ikincil ve özellik bandına ileri sarılarak bu özellik bandı için en son yama düzeyini kullanır.
Bulunamazsa, sonraki daha yüksek ana, ikincil ve özellik bandına ileri doğru döner ve bu özellik bandı için en son yama düzeyini kullanır.
Bulunamazsa başarısız olur.
latestPatch İstenen ana, ikincil ve özellik bandıyla eşleşen ve belirtilen değerden büyük veya eşit olan en son yüklü düzeltme eki düzeyini kullanır.
Bulunamazsa başarısız olur.
latestFeature İstenen ana ve alt öğeyle eşleşen en yüksek yüklü özellik bandını ve düzeltme eki düzeyini belirtilen değerden büyük veya eşit bir özellik bandı ve düzeltme eki düzeyiyle kullanır.
Bulunamazsa başarısız olur.
latestMinor İstenen ana değerle eşleşen en yüksek yüklü ikincil, özellik bandı ve düzeltme eki düzeyini belirtilen değerden büyük veya eşit olan ikincil, özellik bandı ve düzeltme eki düzeyini kullanır.
Bulunamazsa başarısız olur.
latestMajor En yüksek yüklü .NET SDK'sını belirtilen değerden daha büyük veya eşit bir sürümle kullanır.
Bulunamazsa başarısız olur.
disable İleriye doğru ilerlemiyor. Tam eşleşme gerekiyor.

msbuild-sdks

Türü: object

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

Örnekler

Aşağıdaki örnekte, yayın öncesi sürümlerin nasıl kullanılmadığı 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, 2.2.200'den önceki sdk sürümlerine izin vermemektedir ve 3.0.xxx ve 3.1.xxx dahil olmak üzere 2.2.200 veya sonraki sürümlerine izin verir.

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

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

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

Aşağıdaki örnekte, belirli bir ana ve ikincil sürümün yüklü en son özellik bandı ve düzeltme eki sürümünün nasıl kullanılacağı gösterilmektedir. Gösterilen JSON, 3.1.102'den önceki herhangi bir SDK sürümüne izin vermemektedir ve 3.1.102 veya sonraki bir 3.1.xxx sürümüne izin verir( örneğin, 3.1.103 veya 3.1.200).

{
  "sdk": {
    "version": "3.1.102",
    "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, 3.1.102'den önceki tüm SDK sürümlerine izin vermemektedir ve 3.1.102 veya sonraki 3.1.1xx sürümlerine izin verir( örneğin, 3.1.103 veya 3.1.199).

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

global.json ve .NET CLI

global.json dosyasında bir SDK sürümü ayarlamak için makinenizde hangi SDK sürümlerinin yüklü olduğunu bilmeniz 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 .NET'i İndir 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 6.0.100

Eşleşen kurallar

Not

Eşleşen kurallar, tüm yüklü .NET yüklü çalışma zamanlarında ortak olan giriş noktası tarafından dotnet.exe 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 zamanlarınız varsa 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 bir SDK sürümü veya 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 değilseniz, yayın öncesi sürümler dikkate alınır.
    • Visual Studio'daysanız, istenen ön sürüm durumunu kullanır. Yani, Visual Studio Önizleme sürümünü kullanıyorsanız veya .NET SDK'sının önizlemelerini kullan seçeneğini (AraçlarSeçeneklerEnvironmentPreview>>>Ö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 allowPrerelease bir global.json dosyası bulunursa, en yüksek yüklü SDK sürümü kullanılır (ayarına rollForwardlatestMajoreşdeğerdir). En son SDK sürümünün yayınlanıp yayımlanmayabileceği veya ön sürüm olup olmadığı değerine allowPrereleasebağlıdır. true yayın öncesi sürümlerin dikkate alındiğini gösterir; false yalnızca sürüm sürümlerinin dikkate alındığını gösterir.

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

    • rollForward Hiçbir değer ayarlı değilse, 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 ayarlı olmadığında 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 Core SDK'sının önizleme sürümüyle çalışıyorsunuz. SDK sürümünü geçerli projedeki global.json dosyası aracılığıyla tanımlayabilirsiniz. https://go.microsoft.com/fwlink/?linkid=869452Adresinde daha fazla bilgi.

    .NET'in önizleme sürümünü kullanıyorsunuz. Bkz. https://aka.ms/dotnet-core-preview

    .NET SDK sürümlerinin geçmişi ve yüksek kaliteli olma taahhüdü vardır. Ancak, yayın öncesi 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:

    '{startupProject}' başlangıç projesi hedef çerçevesi '. '{targetFrameworkVersion}' NETCoreApp' sürümü. Entity Framework Core .NET Komut Satırı Araçları'nın bu sürümü yalnızca 2.0 veya üzeri sürümleri 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ünü yükleyin ve global.json dosyasını kullanarak istenen 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ı.

Ayrıca bkz.