Penerapan versi paket

  • Artikel
  • 8 menit untuk membaca

Paket tertentu selalu disebut menggunakan pengidentifikasi paket dan nomor versi yang tepat. Misalnya, Entity Framework di nuget.org memiliki beberapa lusin paket tertentu yang tersedia, mulai dari versi 4.1.10311 hingga versi 6.1.3 (rilis stabil terbaru) dan berbagai versi pra-rilis seperti 6.2.0-beta1.

Saat membuat paket, Anda menetapkan nomor versi tertentu dengan akhiran teks pra-rilis opsional. Saat menggunakan paket, di sisi lain, Anda dapat menentukan nomor versi yang tepat atau rentang versi yang dapat diterima.

Dalam topik ini:

Dasar-dasar versi

Nomor versi tertentu dalam bentuk Major.Minor.Patch[-Suffix], di mana komponen memiliki arti berikut:

  • Utama: Memutus perubahan
  • Minor: Fitur baru, tetapi kompatibel mundur
  • Patch: Perbaikan bug kompatibel mundur saja
  • -Akhiran (opsional): tanda hubung diikuti dengan string yang menunjukkan versi pra-rilis (mengikuti konvensi Penerapan Versi Semantik atau SemVer 1.0).

Contoh:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta1

Penting

nuget.org menolak unggahan paket apa pun yang tidak memiliki nomor versi yang tepat. Versi harus ditentukan dalam file proyek atau yang .nuspec digunakan untuk membuat paket.

Versi pra-rilis

Secara teknis, pembuat paket dapat menggunakan string apa pun sebagai akhiran untuk menunjukkan versi pra-rilis, karena NuGet memperlakukan versi seperti pra-rilis dan tidak membuat interpretasi lain. Artinya, NuGet menampilkan string versi lengkap dalam UI apa pun yang terlibat, meninggalkan interpretasi arti akhiran kepada konsumen.

Meskipun demikian, pengembang paket umumnya mengikuti konvensi penamaan yang diakui:

  • -alpha: Rilis alfa, biasanya digunakan untuk pekerjaan yang sedang berlangsung dan eksperimen.
  • -beta: Rilis beta, biasanya fitur yang lengkap untuk rilis yang direncanakan berikutnya, tetapi mungkin berisi bug yang diketahui.
  • -rc: Merilis kandidat, biasanya rilis yang berpotensi final (stabil) kecuali muncul bug yang signifikan.

Catatan

NuGet 4.3.0+ mendukung SemVer 2.0.0, yang mendukung nomor pra-rilis dengan notasi titik, seperti dalam 1.0.1-build.23. Notasi titik tidak didukung dengan versi NuGet sebelum 4.3.0. Anda dapat menggunakan formulir seperti 1.0.1-build23.

Saat menyelesaikan referensi paket dan beberapa versi paket hanya berbeda dengan akhiran, NuGet memilih versi tanpa akhiran terlebih dahulu, lalu menerapkan prioritas untuk versi pra-rilis dalam urutan alfabet terbalik. Misalnya, versi berikut akan dipilih dalam urutan yang tepat yang ditunjukkan:

1.0.1
1.0.1-zzz
1.0.1-rc
1.0.1-open
1.0.1-beta
1.0.1-alpha2
1.0.1-alpha
1.0.1-aaa

Semantic Versioning 2.0.0

Dengan NuGet 4.3.0+ dan Visual Studio 2017 versi 15.3+, NuGet mendukung Semantic Versioning 2.0.0.

Semantik tertentu dari SemVer v2.0.0 tidak didukung di klien yang lebih lama. NuGet menganggap versi paket sebagai SemVer v2.0.0 spesifik jika salah satu pernyataan berikut ini benar:

  • Label pra-rilis dipisahkan titik, misalnya, 1.0.0-alpha.1
  • Versi ini memiliki build-metadata, misalnya, 1.0.0+githash

Untuk nuget.org, paket didefinisikan sebagai paket SemVer v2.0.0 jika salah satu pernyataan berikut ini benar:

  • Versi paket sendiri sesuai dengan SemVer v2.0.0 tetapi tidak sesuai dengan SemVer v1.0.0, seperti yang didefinisikan di atas.
  • Salah satu rentang versi dependensi paket memiliki versi minimum atau maksimum yang sesuai dengan SemVer v2.0.0 tetapi tidak sesuai dengan SemVer v1.0.0, yang ditentukan di atas; misalnya, [1.0.0-alpha.1, ).

Jika Anda mengunggah paket khusus SemVer v2.0.0 ke nuget.org, paket tidak terlihat oleh klien yang lebih lama dan hanya tersedia untuk klien NuGet berikut:

  • NuGet 4.3.0+
  • Visual Studio 2017 versi 15.3+
  • Visual Studio 2015 dengan NuGet VSIX v3.6.0
  • dotnet
    • dotnetcore.exe (.NET SDK 2.0.0+)

Klien pihak ketiga:

  • Pengendara JetBrains
  • Paket versi 5.0+

Rentang versi

Saat merujuk ke dependensi paket, NuGet mendukung penggunaan notasi interval untuk menentukan rentang versi, diringkas sebagai berikut:

Notasi Aturan yang diterapkan Deskripsi
1,0 x ≥ 1.0 Versi minimum, inklusif
(1.0,) x > 1.0 Versi minimum, eksklusif
[1.0] x == 1.0 Kecocokan versi yang tepat
(,1.0] x ≤ 1.0 Versi maksimum, inklusif
(,1.0) x < 1.0 Versi maksimum, eksklusif
[1.0,2.0] 1.0 ≤ x ≤ 2.0 Rentang yang tepat, inklusif
(1.0,2.0) 1.0 < x < 2.0 Rentang yang tepat, eksklusif
[1.0,2.0) 1.0 ≤ x < 2.0 Versi campuran minimum inklusif dan maksimum eksklusif
(1.0) invalid invalid

Saat menggunakan format PackageReference, NuGet juga mendukung penggunaan notasi mengambang, *, untuk bagian akhiran Mayor, Minor, Patch, dan pra-rilis dari angka tersebut. Versi mengambang tidak didukung dengan packages.config format . Saat versi mengambang ditentukan, aturannya adalah menyelesaikan ke versi tertinggi yang ada yang cocok dengan deskripsi versi. Contoh versi mengambang dan resolusinya ada di bawah ini.

Catatan

Rentang versi dalam PackageReference menyertakan versi pra-rilis. Secara desain, versi mengambang tidak menyelesaikan versi prarilis kecuali diikutsertakan. Untuk status permintaan fitur terkait, lihat masalah 6434.

Contoh

Selalu tentukan rentang versi atau versi untuk dependensi paket dalam file proyek, packages.config file, dan .nuspec file. Tanpa rentang versi atau versi, NuGet 2.8.x dan yang lebih lama memilih versi paket terbaru yang tersedia saat menyelesaikan dependensi, sedangkan NuGet 3.x dan yang lebih baru memilih versi paket terendah. Menentukan versi atau rentang versi menghindari ketidakpastian ini.

Referensi dalam file proyek (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 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)" />

Resolusi versi mengambang

Versi Versi yang ada di server Resolusi Alasan Catatan
* 1.1.0
1.1.1
1.2.0
1.3.0-alpha		 1.2.0 Versi stabil tertinggi.
1.1.* 1.1.0
1.1.1
1.1.2-alpha
1.2.0-alpha		 1.1.1 Versi stabil tertinggi yang menghormati pola yang ditentukan.
*-* 1.1.0
1.1.1
1.1.2-alpha
1.3.0-beta		 1.3.0-beta Versi tertinggi termasuk versi yang tidak stabil. Tersedia dalam versi Visual Studio 16.6, NuGet versi 5.6, .NET Core SDK versi 3.1.300
1.1.*-* 1.1.0
1.1.1
1.1.2-alpha
1.1.2-beta
1.3.0-beta		 1.1.2-beta Versi tertinggi yang menghormati pola dan menyertakan versi yang tidak stabil. Tersedia dalam versi Visual Studio 16.6, NuGet versi 5.6, .NET Core SDK versi 3.1.300

Catatan

Resolusi versi mengambang tidak mempertimbangkan apakah paket terdaftar atau tidak. Resolusi versi mengambang akan diselesaikan secara lokal jika kondisi dapat dipenuhi dengan paket di Folder Paket Global.

Referensi dalam packages.config:

Dalam packages.config, setiap dependensi dicantumkan dengan atribut persis version yang digunakan saat memulihkan paket. Atribut allowedVersions hanya digunakan selama operasi pembaruan untuk membatasi versi yang mungkin diperbarui paket.

<!-- 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)" />

Referensi dalam .nuspec file

Atribut version dalam <dependency> elemen menjelaskan versi rentang yang dapat diterima untuk dependensi.

<!-- 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)" />

Nomor versi yang dinormalisasi

Catatan

Ini adalah perubahan yang melanggar untuk NuGet 3.4 dan yang lebih baru.

Saat mendapatkan paket dari repositori selama operasi penginstalan, penginstalan ulang, atau pemulihan, NuGet 3.4+ memperlakukan nomor versi sebagai berikut:

  • Nol di depan dihapus dari nomor versi:

    1.00 diperlakukan sebagai 1.0 1.01.1 diperlakukan sebagai 1.1.1 1.00.0.1 diperlakukan sebagai 1.0.0.1

  • Nol di bagian keempat dari nomor versi akan dihilangkan

    1.0.0.0 diperlakukan sebagai 1.0.0 1.0.01.0 diperlakukan sebagai 1.0.1

  • Metadata build SemVer 2.0.0 dihapus

    1.0.7+r3456 diperlakukan sebagai 1.0.7

pack dan restore operasi menormalkan versi jika memungkinkan. Untuk paket yang sudah dibuat, normalisasi ini tidak memengaruhi nomor versi dalam paket itu sendiri; ini hanya memengaruhi bagaimana NuGet cocok dengan versi saat menyelesaikan dependensi.

Namun, repositori paket NuGet harus memperlakukan nilai-nilai ini dengan cara yang sama seperti NuGet untuk mencegah duplikasi versi paket. Dengan demikian repositori yang berisi versi 1.0 dari paket tidak boleh juga menghosting versi 1.0.0 sebagai paket terpisah dan berbeda.

Di mana NuGetVersion berbeda dari Penerapan Versi Semantik

Jika Anda ingin menggunakan versi paket NuGet secara terprogram, sangat disarankan untuk menggunakan paket NuGet.Versioning. Metode statis NuGetVersion.Parse(string) dapat digunakan untuk mengurai string versi, dan VersionComparer dapat digunakan untuk mengurutkan NuGetVersion instans.

Jika Anda menerapkan fungsionalitas NuGet dalam bahasa yang tidak berjalan di .NET, berikut adalah daftar perbedaan yang diketahui antara NuGetVersion dan Penerapan Versi Semantik, dan alasan mengapa pustaka Penerapan Versi Semantik yang ada mungkin tidak berfungsi untuk paket yang sudah diterbitkan di nuget.org.

  1. NuGetVersion mendukung segmen versi ke-4, , Revisionagar kompatibel dengan, atau superset, System.Version. Oleh karena itu, tidak termasuk label prarilis dan metadata, string versi adalah Major.Minor.Patch.Revision. Sesuai normalisasi versi yang dijelaskan di atas, jika Revision nol, itu dihilangkan dari string versi yang dinormalisasi.
  2. NuGetVersion hanya mengharuskan segmen utama didefinisikan. Semua lainnya bersifat opsional, dan setara dengan nol. Ini berarti bahwa 1, 1.0, 1.0.0, dan 1.0.0.0 semuanya diterima dan sama.
  3. NuGetVersion menggunakan perbandingan string insenstif kasus untuk komponen pra-rilis. Ini berarti bahwa 1.0.0-alpha dan 1.0.0-Alpha sama.