Penerapan versi paket

  • Artikel

Paket tertentu selalu disebut menggunakan pengidentifikasi paketnya 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.

Dokumen berikut mengikuti standar Semantic Versioning 2.0.0 , yang didukung oleh NuGet 4.3.0+ dan Visual Studio 2017 versi 15.3+. Semantik tertentu dari SemVer v2.0.0 tidak didukung di klien yang lebih lama.

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 yang kompatibel mundur saja
  • -Akhiran (opsional): tanda hubung diikuti dengan string yang menunjukkan versi pra-rilis (mengikuti konvensi Penerapan Versi Semantik atau SemVer ).

Contoh:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

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 apa pun dari 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 yang merupakan fitur lengkap untuk rilis terencana berikutnya, tetapi mungkin berisi bug yang diketahui.
  • -rc: Merilis kandidat, biasanya rilis yang berpotensi final (stabil) kecuali muncul bug yang signifikan.

Saat mengurutkan versi berdasarkan prioritas, NuGet mengikuti standar SemVer dan memilih versi tanpa akhiran terlebih dahulu, lalu menerapkan prioritas untuk versi pra-rilis dalam urutan alfabet terbalik dan memperlakukan nomor notasi titik dengan urutan numerik.

Catatan

Nomor prarilis dengan notasi titik, seperti dalam 1.0.1-build.23, dianggap sebagai bagian dari standar SemVer 2.0.0, dan dengan demikian hanya didukung dengan NuGet 4.3.0+.

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

Perhatikan bahwa 1.0.1-alpha10 diurutkan secara ketat dalam urutan alfabet terbalik, sedangkan 1.0.1-rc.10 lebih diutamakan daripada 1.0.1-rc.2.

Rentang versi

Saat mengacu pada dependensi paket, NuGet mendukung penggunaan notasi interval untuk menentukan rentang versi, dirangkum sebagai berikut:

Notasi Aturan yang diterapkan Deskripsi
1.0 x ≥ 1.0 Versi minimum, inklusif
[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

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

Referensi dalam packages.config:

Dalam packages.config, setiap dependensi dicantumkan dengan atribut yang tepat 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+.

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.

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 metadata build, 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 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
  • .NET SDK 2.0.0+

Klien pihak ketiga:

  • Pengendara JetBrains
  • Paket versi 5.0+

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, Revision, agar 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 yang tidak peka huruf besar/kecil untuk komponen pra-rilis. Ini berarti bahwa 1.0.0-alpha dan 1.0.0-Alpha sama.