Aracılığıyla paylaş

Package versioning

Belirli bir pakete her zaman paket tanımlayıcısı ve tam sürüm numarası kullanılır. Örneğin, nuget.org Entity Framework sürüm 4.1.10311 sürüm 6.1.3 (en son kararlı sürüm) ve 6.2.0-beta1gibi çeşitli yayın öncesi sürümlere kadar birçok farklı paket mevcuttur.

Paket oluştururken, isteğe bağlı yayın öncesi metin soneki ile belirli bir sürüm numarası atarsınız. Öte yandan paketleri kullanırken, tam sürüm numarasını veya kabul edilebilir sürüm aralığını belirtebilirsiniz.

Aşağıdaki belge, NuGet 4.3.0+ ve Visual Studio 2017 sürüm 15.3+ tarafından desteklenen AnlamSal Sürüm oluşturma 2.0.0 standardını izler. SemVer v2.0.0 bazı semantiği eski istemcilerde desteklenmez.

Bu konuda:

Version basics

Belirli bir sürüm numarası, Major.Minor.Patch[-Suffix]biçimindedir; burada bileşenler aşağıdaki anlamlara sahiptir:

  • Ana: Hataya neden olan değişiklikler
  • İkincil: Yeni özellikler, ancak geriye dönük uyumlu
  • Düzeltme Eki: Yalnızca geriye dönük uyumlu hata düzeltmeleri
  • -Suffix (isteğe bağlı): Kısa çizgi ve ardından yayın öncesi sürümü belirten bir dize (AnlamSal Sürüm Oluşturma veya SemVer kuralına göre).

Examples:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Important

nuget.org tam sürüm numarası olmayan tüm paket yüklemelerini reddeder. Sürüm, paketi oluşturmak için kullanılan .nuspec veya proje dosyasında belirtilmelidir.

Pre-release versions

Teknik olarak bakıldığında, NuGet sürüm öncesi gibi herhangi bir sürüme ön sürüm olarak davranıp başka yorum yapmaması nedeniyle paket oluşturucuları yayın öncesi sürümü belirtmek için herhangi bir dizeyi sonek olarak kullanabilir. Diğer bir deyişle, NuGet söz konusu kullanıcı arabiriminde tam sürüm dizesini görüntüler ve son ekin anlamını tüketiciye yorumlar.

Bu, paket geliştiricileri genellikle tanınan adlandırma kurallarını izler:

  • -alpha: Alfa sürümü, genellikle devam eden iş ve deneme için kullanılır.
  • -beta: Beta sürümü, genellikle bir sonraki planlı sürüm için özellik tamamlanmış ancak bilinen hatalar içerebilen bir sürümdür.
  • -rc: Önemli hatalar ortaya çıkmadığı sürece genellikle son (kararlı) olabilecek bir sürüm olan sürüm adayı.

NuGet, sürümleri önceliğe göre sıralarken SemVer standardını izler ve önce soneki olmayan bir sürüm seçer, ardından yayın öncesi sürümlere ters alfabetik sırada öncelik uygular ve noktalı gösterim sayılarını sayısal düzende ele alır.

Note

1.0.1-build.23 sürümünde olduğu gibi, noktalı ön sürüm sayıları SemVer 2.0.0 standardının bir parçası olarak kabul edilir ve bu nedenle yalnızca NuGet 4.3.0+ ile desteklenir.

1.0.1
1.0.1-zzz
1.0.1-rc.10
1.0.1-rc.2
1.0.1-open
1.0.1-beta
1.0.1-alpha2
1.0.1-alpha10
1.0.1-aaa

1.0.1-alfa10'un tamamen ters alfabetik düzende sıralandığını, 1.0.1-rc.10'un ise 1.0.1-rc.2'den daha öncelikli olduğunu unutmayın.

Version ranges

NuGet, paket bağımlılıklarına başvururken sürüm aralıklarını belirtmek için aralık gösteriminin kullanılmasını destekler ve aşağıdaki gibi özetlenir:

Notation Applied rule Description
1.0 x ≥ 1.0 En düşük sürüm, dahil
[1.0,) x ≥ 1.0 En düşük sürüm, dahil
(1.0,) x > 1.0 En düşük sürüm, özel
[1.0] x == 1,0 Tam sürüm eşleşmesi
(,1.0] x ≤ 1.0 En yüksek sürüm( dahil)
(,1.0) x < 1.0 En yüksek sürüm, özel
[1.0,2.0] 1,0 ≤ x ≤ 2,0 Tam aralık, dahil
(1.0,2.0) 1,0 < x < 2,0 Tam aralık, özel
[1.0,2.0) 1,0 ≤ x < 2,0 Karma kapsayıcı minimum ve özel maksimum sürüm
(1.0) invalid invalid

Best Practice

Proje dosyaları, packages.config dosyaları ve .nuspec dosyalarındaki paket bağımlılıkları için her zaman bir sürüm veya sürüm aralığı belirtin. Sürüm veya sürüm aralığı olmadan, bir bağımlılığı çözerken tutarlı geri yükleme sonuçları garanti edilmez. Bir uyumluluk sorunu bilmiyorsanız sahip olmadığınız paketler için sürüm aralıklarına üst sınır belirtmekten kaçının. Sürüm aralıklarının üst sınırları benimsemeye zarar verir, tüketicileri bağımlılıklara değerli güncelleştirmeler almaktan caydırabilir ve bazı durumlarda bağımlılıkların desteklenmeyen sürümlerini kullanmalarına neden olabilir.

Proje dosyalarındaki başvurular (PackageReference)

<!-- Accepts any version 6.1 and above.
     Will resolve to the smallest acceptable stable version.-->
<PackageReference Include="ExamplePackage" Version="6.1" />

<!-- Accepts any 6.x.y version.
     Will resolve to the highest acceptable stable version.-->
<PackageReference Include="ExamplePackage" Version="6.*" />

<!-- Accepts only version 6.1.0. -->
<PackageReference Include="ExamplePackage" Version="[6.1.0]" />

<!-- Accepts any version above, but not including 4.1.3. Could be
     used to guarantee a dependency with a specific bug fix. 
     Will resolve to the smallest acceptable stable version.-->
<PackageReference Include="ExamplePackage" Version="(4.1.3,)" />

<!-- Accepts any version up below 5.x, which might be used to prevent pulling in a later
     version of a dependency that changed its interface. However, this form is not
     recommended because it can be difficult to determine the lowest version. 
     Will resolve to the smallest acceptable stable version.
     -->
<PackageReference Include="ExamplePackage" Version="(,5.0)" />

<!-- Accepts any 1.x or 2.x version, but not 0.x or 3.x and higher.
     Will resolve to the smallest acceptable stable version.-->
<PackageReference Include="ExamplePackage" Version="[1,3)" />

<!-- Accepts 1.3.2 up to 1.4.x, but not 1.5 and higher.
     Will resolve to the smallest acceptable stable version. -->
<PackageReference Include="ExamplePackage" Version="[1.3.2,1.5)" />

packages.config Başvuruları:

packages.config'de her bağımlılık, paketleri geri yüklerken kullanılan tam bir version özniteliğiyle listelenir. allowedVersions özniteliği yalnızca güncelleştirme işlemleri sırasında paketin güncelleştirilebileceği sürümleri kısıtlamak için kullanılır.

<!-- Install/restore version 6.1.0, accept any version 6.1.0 and above on update. -->
<package id="ExamplePackage" version="6.1.0" allowedVersions="6.1.0" />

<!-- Install/restore version 6.1.0, and do not change during update. -->
<package id="ExamplePackage" version="6.1.0" allowedVersions="[6.1.0]" />

<!-- Install/restore version 6.1.0, accept any 6.x version during update. -->
<package id="ExamplePackage" version="6.1.0" allowedVersions="[6,7)" />

<!-- Install/restore version 4.1.4, accept any version above, but not including, 4.1.3.
     Could be used to guarantee a dependency with a specific bug fix. -->
<package id="ExamplePackage" version="4.1.4" allowedVersions="(4.1.3,)" />

<!-- Install/restore version 3.1.2, accept any version up below 5.x on update, which might be
     used to prevent pulling in a later version of a dependency that changed its interface.
     However, this form is not recommended because it can be difficult to determine the lowest version. -->
<package id="ExamplePackage" version="3.1.2" allowedVersions="(,5.0)" />

<!-- Install/restore version 1.1.4, accept any 1.x or 2.x version on update, but not
     0.x or 3.x and higher. -->
<package id="ExamplePackage" version="1.1.4" allowedVersions="[1,3)" />

<!-- Install/restore version 1.3.5, accepts 1.3.2 up to 1.4.x on update, but not 1.5 and higher. -->
<package id="ExamplePackage" version="1.3.5" allowedVersions="[1.3.2,1.5)" />

.nuspec dosyalarındaki Başvuruları

version öğesindeki <dependency> özniteliği, bağımlılık için kabul edilebilir aralık sürümlerini açıklar.

<!-- Accepts any version 6.1 and above. -->
<dependency id="ExamplePackage" version="6.1" />

<!-- Accepts any version above, but not including 4.1.3. Could be
     used to guarantee a dependency with a specific bug fix. -->
<dependency id="ExamplePackage" version="(4.1.3,)" />

<!-- Accepts any version up below 5.x, which might be used to prevent pulling in a later
     version of a dependency that changed its interface. However, this form is not
     recommended because it can be difficult to determine the lowest version. -->
<dependency id="ExamplePackage" version="(,5.0)" />

<!-- Accepts any 1.x or 2.x version, but not 0.x or 3.x and higher. -->
<dependency id="ExamplePackage" version="[1,3)" />

<!-- Accepts 1.3.2 up to 1.4.x, but not 1.5 and higher. -->
<dependency id="ExamplePackage" version="[1.3.2,1.5)" />

Normalleştirilmiş sürüm numaraları

Note

Bu, NuGet 3.4+ için hataya neden olan bir değişikliktir.

Yükleme, yeniden yükleme veya geri yükleme işlemleri sırasında bir depodan paket alırken NuGet 3.4+ sürüm numaralarını aşağıdaki gibi ele alır:

  • Baştaki sıfırlar sürüm numaralarından kaldırılır:

    • 1,00, 1,0 olarak değerlendirilir
    • 1.01.1, 1.1.1 olarak değerlendirilir
    • 1.00.0.1, 1.0.0.1 olarak değerlendirilir

  • Sürüm numarasının dördüncü bölümünde sıfır atlanır

    • 1.0.0.0, 1.0.0 olarak değerlendirilir
    • 1.0.01.0, 1.0.1 olarak değerlendirilir

  • SemVer 2.0.0 derleme meta verileri kaldırıldı

    • 1.0.7+r3456 1.0.7 olarak değerlendirilir

pack ve restore işlemleri, mümkün olduğunda sürümleri normalleştirir. Bu normalleştirme, önceden oluşturulmuş paketler için paketlerdeki sürüm numaralarını etkilemez; yalnızca bağımlılıkları çözerken NuGet'in sürümlerle nasıl eşleştiği etkiler.

Ancak NuGet paket depoları, paket sürümünün yinelenmesini önlemek için bu değerleri NuGet ile aynı şekilde ele almalıdır. Bu nedenle bir paketin sürüm 1.0 içeren bir depo, 1.0.0 sürümünü ayrı ve farklı bir paket olarak barındırmamalıdır.

Anlamsal Sürüm Oluşturma 2.0.0

Eski istemcilerde SemVer v2.0.0'ın belirli semantiği desteklenmez. NuGet, aşağıdaki deyimlerden biri doğruysa bir paket sürümünü SemVer v2.0.0'a özgü olarak değerlendirir:

  • Yayın öncesi etiketi noktayla ayrılmıştır, örneğin 1.0.0-alpha.1
  • Sürümde derleme meta verileri vardır, örneğin 1.0.0+githash

nuget.org için, aşağıdaki deyimlerden biri doğruysa bir paket SemVer v2.0.0 paketi olarak tanımlanır:

  • Paketin kendi sürümü, yukarıda açıklandığı gibi SemVer v2.0.0 uyumlu ancak SemVer v1.0.0 uyumlu değildir.
  • Paketin bağımlılık sürüm aralıklarından herhangi birinin, yukarıda tanımlanan SemVer v2.0.0 uyumlu ancak SemVer v1.0.0 uyumlu olmayan en düşük veya en yüksek sürümü vardır; örneğin, [1.0.0-alpha.1, ).

SemVer v2.0.0'a özgü bir paketi nuget.org yüklerseniz, paket eski istemciler tarafından görünmez ve yalnızca aşağıdaki NuGet istemcileri tarafından kullanılabilir:

  • NuGet 4.3.0+
  • Visual Studio 2017 sürüm 15.3+
  • NuGet VSIX v3.6.0 ile Visual Studio 2015
  • .NET SDK 2.0.0+

Third-party clients:

  • JetBrains Rider
  • Paket sürüm 5.0+

NuGetVersion'ın AnlamSal Sürüm Oluşturma'dan ayrıştığı yerler

NuGet paket sürümlerini programlı olarak kullanmak istiyorsanız, NuGet.Versioningpaketini kullanmanız kesinlikle önerilir. Statik yöntem NuGetVersion.Parse(string) sürüm dizelerini ayrıştırmak için kullanılabilir ve VersionComparerNuGetVersion örnekleri sıralamak için kullanılabilir.

NuGet işlevselliğini .NET üzerinde çalışmayan bir dilde uyguluyorsanız, NuGetVersion ile AnlamSal Sürüm Oluşturma arasındaki farkların bilinen listesi ve mevcut AnlamSal Sürüm Oluşturma kitaplığının nuget.org'da yayımlanmış paketler için çalışmama nedenleri aşağıdadır.

  1. NuGetVersion, ile uyumlu olması için Revision4. sürüm segmentini veya System.Versionüst kümesini destekler. Bu nedenle, ön sürüm ve meta veri etiketleri hariç, bir sürüm dizesi Major.Minor.Patch.Revision. Yukarıda açıklanan sürüm normalleştirmesine göre, Revision sıfırsa, normalleştirilmiş sürüm dizesinden atlanır.
  2. NuGetVersion yalnızca ana kesimin tanımlanmasını gerektirir. Diğerleri isteğe bağlıdır ve sıfıra eşdeğerdir. Bu, 1, 1.0, 1.0.0ve 1.0.0.0 kabul edildiği ve eşit olduğu anlamına gelir.
  3. NuGetVersion yayın öncesi bileşenler için büyük/küçük harfe duyarsız dize karşılaştırmaları kullanır. Bu, 1.0.0-alpha ve 1.0.0-Alpha eşit olduğu anlamına gelir.
  • Last updated on