Kullanılacak .NET sürümünü seçin

  • Makale

Bu makalede sürümleri seçmek için .NET araçları, SDK ve çalışma zamanı tarafından kullanılan ilkeler açıklanmaktadır. Bu ilkeler, belirtilen sürümleri kullanan uygulamaları çalıştırma ile hem geliştirici hem de son kullanıcı makinelerini yükseltme kolaylığı sağlayan bir denge sağlar. Bu ilkeler şunları etkinleştirir:

  • Güvenlik ve güvenilirlik güncelleştirmeleri de dahil olmak üzere .NET'in kolay ve verimli dağıtımı.
  • Hedef çalışma zamanından bağımsız olarak en son araçları ve komutları kullanın.

Sürüm seçimi gerçekleşir:

Bu belgenin geri kalanında bu dört senaryo incelenir.

SDK en son yüklü sürümü kullanır

SDK komutları ve dotnet runiçerirdotnet new. .NET CLI her dotnet komut için bir SDK sürümü seçmelidir. Aşağıdakiler olsa bile makinede varsayılan olarak yüklü olan en son SDK'yı kullanır:

  • Proje, .NET çalışma zamanının önceki bir sürümünü hedefler.
  • .NET SDK'sının en son sürümü bir önizleme sürümüdür.

Önceki .NET çalışma zamanı sürümlerini hedeflerken en son SDK özelliklerinden ve geliştirmelerinden yararlanabilirsiniz. Aynı SDK araçlarını kullanarak .NET'in farklı çalışma zamanı sürümlerini hedefleyebilirsiniz.

Nadir durumlarda SDK'nın önceki bir sürümünü kullanmanız gerekebilir. Bu sürümü bir global.json dosyasında belirtirsiniz. "En son kullan" ilkesi, yalnızca en son yüklenen sürümden önceki bir .NET SDK sürümünü belirtmek için global.json kullandığınız anlamına gelir.

global.json dosya hiyerarşisinde herhangi bir yere yerleştirilebilir. CLI, bulduğu ilk global.json proje dizininden yukarı doğru arar. Belirli bir global.json hangi projeler için geçerli olduğunu dosya sistemindeki yerine göre denetlersiniz. .NET CLI, geçerli çalışma dizininden yukarı doğru ilerleyen bir global.json dosyasını yinelemeli olarak arar. Bulunan ilk global.json dosyası kullanılan sürümü belirtir. Bu SDK sürümü yüklüyse, bu sürüm kullanılır. global.json belirtilen SDK bulunamazsa, .NET CLI uyumlu bir SDK seçmek için eşleşen kuralları kullanır veya hiçbir sdk bulunmazsa başarısız olur.

Aşağıdaki örnekte global.json söz dizimi gösterilmektedir:

{
  "sdk": {
    "version": "5.0.0"
  }
}

SDK sürümünü seçme işlemi şu şekildedir:

  1. dotnet geçerli çalışma dizininden yukarı doğru ilerleyen bir global.json dosyasını yinelemeli olarak ters olarak arar.
  2. dotnet bulunan ilk global.json belirtilen SDK'yi kullanır.
  3. dotnetglobal.json bulunamazsa en son yüklü SDK'sını kullanır.

SDK sürümü seçimi hakkında daha fazla bilgi için global.json genel bakış makalesinin Eşleştirme kuralları ve rollForward bölümlerine bakın.

Hedef Çerçeve Takma Adlar derleme zamanı API'lerini tanımlar

Projenizi Bir Hedef Çerçeve Takma Adı'nda (TFM) tanımlanan API'lere karşı oluşturursunuz. Proje dosyasında hedef çerçeveyi belirtirsiniz. TargetFramework Proje dosyanızdaki öğesini aşağıdaki örnekte gösterildiği gibi ayarlayın:

<TargetFramework>net5.0</TargetFramework>

Projenizi birden çok TFM'ye göre oluşturabilirsiniz. Birden çok hedef çerçevenin ayarlanması kitaplıklar için daha yaygındır, ancak uygulamalarla da yapılabilir. Bir TargetFrameworks özellik belirtirsiniz (çoğul olarak TargetFramework). Hedef çerçeveler, aşağıdaki örnekte gösterildiği gibi noktalı virgülle ayrılmıştır:

<TargetFrameworks>net5.0;netcoreapp3.1;net47</TargetFrameworks>

Belirli bir SDK, birlikte verildiği çalışma zamanının hedef çerçevesine eşlenmiş sabit bir çerçeve kümesini destekler. Örneğin, .NET 5 SDK'sı hedef çerçevenin bir uygulaması net5.0 olan .NET 5 çalışma zamanını içerir. .NET 5 SDK'sı , , vb. desteklernetcoreapp2.0, ancak (veya üzerini) desteklemez net6.0 . netcoreapp3.0netcoreapp2.1 için derlenecek net6.0.NET 6 SDK'sını yüklersiniz.

.NET Standard

.NET Standard, farklı .NET uygulamaları tarafından paylaşılan bir API yüzeyini hedeflemenin bir yoluydu. API standardı olan .NET 5'in yayımlanmasından başlayarak, .NET Standard'ın tek bir senaryo dışında çok az ilgisi vardır: .NET Standard, hem .NET hem de .NET Framework'i hedeflemek istediğinizde kullanışlıdır. .NET 5 tüm .NET Standard sürümlerini uygular.

Daha fazla bilgi için bkz . .NET 5 ve .NET Standard.

Çerçeveye bağımlı uygulamalar ileri sarma

ile kaynaktan veya ile dotnet runçerçeveye bağımlı bir dağıtımdan veya ile myapp.exedotnet myapp.dllçerçeveye bağımlı bir yürütülebilir dosyadan bir uygulama çalıştırdığınızda dotnet yürütülebilir dosya, uygulamanın konağıdır.

Konak, makinede yüklü olan en son düzeltme eki sürümünü seçer. Örneğin, proje dosyanızda belirttiyseniz net5.0 ve 5.0.2 en son .NET çalışma zamanı yüklüyse, 5.0.2 çalışma zamanı kullanılır.

Kabul edilebilir 5.0.* bir sürüm bulunmazsa yeni 5.* bir sürüm kullanılır. Örneğin, belirttiyseniz net5.0 ve yalnızca 5.1.0 yüklüyse, uygulama çalışma zamanını kullanarak 5.1.0 çalışır. Bu davranışa "ikincil sürüm ileri sarma" adı verilir. Alt sürümler de dikkate alınmaz. Kabul edilebilir bir çalışma zamanı yüklenmediğinde uygulama çalışmaz.

5.0'ı hedeflerseniz, birkaç kullanım örneği davranışı gösterir:

  • ✔️ 5.0 belirtilir. 5.0.3, yüklenen en yüksek yama sürümüdür. 5.0.3 kullanılır.
  • ❌ 5.0 belirtilir. 5.0.* sürümü yüklü değil. 3.1.1, yüklenen en yüksek çalışma zamanıdır. Bir hata iletisi görüntülenir.
  • ✔️ 5.0 belirtilir. 5.0.* sürümü yüklü değil. 5.1.0, yüklenen en yüksek çalışma zamanı sürümüdür. 5.1.0 kullanılır.
  • ❌ 3.0 belirtilir. 3.x sürümü yüklü değil. 5.0.0, yüklenen en yüksek çalışma zamanıdır. Bir hata iletisi görüntülenir.

İkincil sürüm ileri sarma, son kullanıcıları etkileyebilecek tek bir yan etkiye sahiptir. Aşağıdaki senaryoyu değerlendirin:

  1. Uygulama, 5.0'ın gerekli olduğunu belirtir.
  2. Çalıştırıldığında sürüm 5.0.* yüklü değildir, ancak 5.1.0 yüklüdür. Sürüm 5.1.0 kullanılacaktır.
  3. Daha sonra, kullanıcı 5.0.3'ü yükler ve uygulamayı yeniden çalıştırır, 5.0.3 artık kullanılır.

5.0.3 ve 5.1.0'ın özellikle ikili verileri seri hale getirme gibi senaryolarda farklı davranması mümkündür.

İleri sarma davranışını denetleme

Varsayılan ileri sarma davranışını geçersiz kılmadan önce .NET çalışma zamanı uyumluluk düzeyi hakkında bilgi sahibi olun.

Bir uygulamanın ileri sarma davranışı dört farklı yolla yapılandırılabilir:

  1. Özelliğini ayarlayarak <RollForward> proje düzeyi ayarı:

    <PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

  2. Dosya *.runtimeconfig.json .

    Bu dosya, uygulamanızı derlediğinizde oluşturulur. <RollForward> Özellik projede ayarlandıysa, ayar olarak rollForward dosyada *.runtimeconfig.json yeniden üretilir. Kullanıcılar uygulamanızın davranışını değiştirmek için bu dosyayı düzenleyebilir.

    {
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}

  3. Komutun dotnet--roll-forward <value> özelliği.

    Bir uygulamayı çalıştırdığınızda, komut satırı aracılığıyla ileri sarma davranışını denetleyebilirsiniz:

    dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor

  4. Ortam DOTNET_ROLL_FORWARD değişkeni.

Öncelik

İleri sarma davranışı, uygulamanız çalıştırıldığında aşağıdaki sırayla ayarlanır ve daha yüksek numaralı öğeler daha düşük numaralı öğelerden önceliklidir:

  1. İlk olarak *.runtimeconfig.json yapılandırma dosyası değerlendirilir.
  2. Ardından ortam DOTNET_ROLL_FORWARD değişkeni, önceki denetimi geçersiz kılarak dikkate alınır.
  3. Son olarak, çalışan uygulamaya geçirilen tüm --roll-forward parametreler diğer her şeyi geçersiz kılar.

Değerler

Öte yandan ileri sarma ayarını ayarladığınızda, davranışı ayarlamak için aşağıdaki değerlerden birini kullanın:

Value Açıklama
Minor Belirtilmezse varsayılan .
İstenen ikincil sürüm eksikse, en düşük daha yüksek ikincil sürüme ileri sarma. İstenen ikincil sürüm varsa, LatestPatch ilke kullanılır.
Major İstenen ana sürüm eksikse sonraki kullanılabilir daha yüksek ana sürüme ve en düşük ikincil sürüme ileri sarma. İstenen ana sürüm varsa, Minor ilke kullanılır.
LatestPatch En yüksek yama sürümüne ileri sarma. Bu değer ikincil sürüm ileri sarmayı devre dışı bırakır.
LatestMinor İstenen ikincil sürüm mevcut olsa bile en yüksek ikincil sürüme ileri sarma.
LatestMajor İstenen ana dal mevcut olsa bile en yüksek ana ve en yüksek ikincil sürüme ileri sarma.
Disable İletmeyin, yalnızca belirtilen sürüme bağlayın. Bu ilke, en son düzeltme eklerine iletme özelliğini devre dışı bırakması nedeniyle genel kullanım için önerilmez. Bu değer yalnızca test için önerilir.

Bağımsız dağıtımlar seçili çalışma zamanını içerir

Bir uygulamayı bağımsız dağıtım olarak yayımlayabilirsiniz. Bu yaklaşım, .NET çalışma zamanını ve kitaplıklarını uygulamanızla birlikte paketler. Bağımsız dağıtımların çalışma zamanı ortamlarına bağımlılığı yoktur. Çalışma zamanı sürümü seçimi, çalışma zamanında değil yayımlama zamanında gerçekleşir.

Yayımlama sırasında gerçekleşen geri yükleme olayı, verilen çalışma zamanı ailesinin en son düzeltme eki sürümünü seçer. Örneğin, dotnet publish .NET 5 çalışma zamanı ailesindeki en son yama sürümüyse .NET 5.0.3'i seçer. Hedef çerçeve (en son yüklenen güvenlik düzeltme ekleri dahil) uygulamayla birlikte paketlenir.

Bir uygulama için belirtilen en düşük sürüm karşılanmadıysa bir hata oluşur. dotnet publish en son çalışma zamanı düzeltme eki sürümüne bağlar (belirli bir major.minor sürüm ailesi içinde). dotnet publish öğesinin ileri sarma semantiğini desteklemez dotnet run. Düzeltme ekleri ve bağımsız dağıtımlar hakkında daha fazla bilgi için .NET uygulamalarını dağıtmada çalışma zamanı düzeltme eki seçimi makalesine bakın.

Bağımsız dağıtımlar belirli bir düzeltme eki sürümü gerektirebilir. Aşağıdaki örnekte gösterildiği gibi proje dosyasındaki en düşük çalışma zamanı düzeltme eki sürümünü (daha yüksek veya daha düşük sürümlere) geçersiz kılabilirsiniz:

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

öğesi varsayılan RuntimeFrameworkVersion sürüm ilkesini geçersiz kılar. Bağımsız dağıtımlar için tam RuntimeFrameworkVersion çalışma zamanı çerçevesi sürümünü belirtir. Çerçeveye bağımlı uygulamalar için, RuntimeFrameworkVersion gerekli en düşük çalışma zamanı çerçevesi sürümünü belirtir.

Ayrıca bkz.