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

Makale
02/06/2025

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:

BIR SDK komutu çalıştırdığınızda, SDK en son yüklü sürümü kullanır.
Bir derleme oluşturduğunuzda, hedef çerçeve takma adları derleme zamanı API'lerinitanımlar.
Bir .NET uygulaması çalıştırdığınızda, hedef çerçeve bağımlı uygulamalarıileriye taşır.
Bağımsız bir uygulama yayımladığınızda, bağımsız dağıtımlar seçilen çalışma zamanınıiçerir.

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

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

SDK komutları dotnet new ve dotnet runiçerir. .NET CLI, her dotnet komutu 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.

Bazı durumlarda SDK'nın belirli bir sürümünü kullanmanız gerekebilir. Belirttiğiniz sürüm, global.json dosyasındayer alır.

global.json dosya hiyerarşisinde herhangi bir yere yerleştirilebilir. Belirli bir global.json hangi projeler için geçerli olduğunu dosya sistemindeki konumuna göre denetlersiniz. .NET CLI, geçerli çalışma dizininden (proje diziniyle aynı olması gerekmez) 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:

dotnet, geçerli çalışma dizininden itibaren dizin yolunu yukarı doğru ters yönde arayarak bir global.json dosyasını yinelemeli olarak arar.
dotnet, bulunan ilk global.json'te belirtilen SDK'yi kullanır.
dotnet, global.json bulunamazsa en son yüklenen SDK'yi 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.

SDK sürümünü güncelleştirme

En son özellikleri, performans iyileştirmelerini ve hata düzeltmelerini benimsemek için SDK'nın en son sürümüne düzenli olarak güncelleştirme yapmak önemlidir. SDK güncelleştirmelerini kolayca denetlemek içindotnet sdk checkkomutunu kullanın. Ayrıca, global.jsonkullanarak belirli bir sürümü seçerseniz, yeni sürümler kullanıma sunulduktan sonra sabitlenmiş SDK sürümünü otomatik olarak güncelleştirmek için Dependabot gibi bir aracı göz önünde bulundurun.

Derleme zamanındaki API'leri tanımlayan hedef çerçeve takma adları

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

<TargetFramework>net8.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. TargetFrameworks özelliği belirtirsiniz (TargetFramework'in çoğulu). Hedef çerçeveler, aşağıdaki örnekte gösterildiği gibi noktalı virgülle ayrılmıştır:

<TargetFrameworks>net8.0;net47</TargetFrameworks>

Belirli bir SDK, birlikte verildiği çalışma zamanının hedef çerçevesiyle sınırlı, sabit bir çerçeve kümesini destekler. Örneğin, .NET 8 SDK'sı, net8.0 hedef çerçevesinin bir uygulaması olan .NET 8 çalışma zamanını içerir. .NET 8 SDK'sı net7.0, net6.0ve net5.0destekler, ancak net9.0 (veya üzerini) desteklemez. .NET 9 SDK'sını net9.0için derleme yapmak üzere 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 için otomatik sürüm güncellemesi

Kaynak koddan dotnet runile bir uygulamayı, çerçeveye bağımlı dağıtımdotnet myapp.dllile veya myapp.exeiçeren çerçeveye bağımlı yürütülebilir ile çalıştırdığınızda, dotnet yürütülebilir dosyası, uygulamanın ana bilgisayar olur.

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

Kabul edilebilir 5.0.* sürümü bulunmazsa yeni bir 5.* sürümü kullanılır. Örneğin, net5.0 belirttiyseniz ve yalnızca 5.1.0 yüklendiyse, uygulama 5.1.0 çalışma zamanını kullanarak çalışır. Bu davranışa "küçük sürüm ileri alma" adı verilir. Daha eski sürümler de göz önünde bulundurulmayacaktır. 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 olarak belirtilmiştir. 5.0.3, yüklenen en yüksek yama sürümüdür. 5.0.3 kullanılır.
❌ 5.0 olarak belirtilmiştir. 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 belirtilmiştir. 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 olarak belirtilmiştir. 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.

Küçük sürüm yükseltmesinin, son kullanıcıları etkileyebilecek bir yan etkisi vardır. Aşağıdaki senaryoyu göz önünde bulundurun:

Uygulama, 5.0'ın gerekli olduğunu belirtir.
Ç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.
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.

İlerletme davranışını denetleme

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

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

<RollForward> özelliğini ayarlayarak proje düzeyi ayarı:

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

*.runtimeconfig.json dosyası.

Bu dosya, uygulamanızı derlediğinizde oluşturulur. <RollForward> özelliği projede ayarlandıysa, *.runtimeconfig.json dosyasında rollForward ayarı olarak 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"
    }
  }
}
```
dotnet komutunun --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
```
DOTNET_ROLL_FORWARD ortam 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:

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

Değer

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

Değer	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` ilkesi kullanılır.
`Major`	İstenen ana sürüm mevcut değilse, bir sonraki kullanılabilir daha yüksek ana sürüme ve en düşük ikincil sürüme geç. İstenen ana sürüm varsa, `Minor` ilkesi 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 taşıma.
`LatestMajor`	İstenen ana sürüm mevcut olsa bile, en yüksek ana ve en yüksek ikincil sürüme yükseltin.
`Disable`	İleriye doğru geçmeyin, yalnızca belirtilen sürüme bağlanın. Bu ilke, sonraki yamaları yükleme yeteneğ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ıştırma sırasında değil, yayımlama sırasında gerçekleşir.

Yayımlama sırasında gerçekleşen geri yükleme olayı, belirtilen çalışma zamanı ailesinin en güncel düzeltme eki sürümünü seçer. Örneğin, dotnet publish .NET 5 çalışma zamanı ailesindeki en son düzeltme eki 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ğlanır (belirli bir major.minor sürüm ailesi içinde). dotnet publish, dotnet run'in ileri dönüş semantiğini desteklemez. .NET uygulamalarını dağıtmada çalışma zamanı düzeltme eki seçimi makalesine bakarak düzeltme ekleri ve bağımsız dağıtımlar hakkında daha fazla bilgi edinebilirsiniz.

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>

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

Ayrıca bkz.

Dependabot tarafından desteklenen ekosistemler ve depolar.
.NET'i indir ve yükle.
.NET'inzaten yüklü olup olmadığını denetleme.
.NET Çalışma Zamanı ve SDKnasıl kaldırılır?

Aracılığıyla paylaş