Penerapan versi paket
Paket tertentu selalu disebut menggunakan pengidentifikasi paketnya dan nomor versi yang tepat. Misalnya, Kerangka Kerja Entitas
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, 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 termasuk akhiran pra-rilis.
- Rentang versi
- nomor versi yang dinormalisasi
- Versi Semantik 2.0.0
Dasar-dasar versi
Nomor versi tertentu dalam bentuk Major.Minor.Patch[-Suffix], di mana komponen memiliki arti berikut:
- Utama : Melanggar 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 .nuspec
atau proyek yang 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 fitur yang lengkap untuk rilis terencana berikutnya, tetapi mungkin berisi bug yang diketahui. -
-rc
: Kandidat rilis, 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.
Nota
Nomor prarilis dengan notasi titik, seperti dalam
-
pengurutan
SemVer 2.0 -
pengurutan
SemVer 1.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 maksimum minimum dan eksklusif campuran inklusif |
(1.0) | batal | batal |
Praktik Terbaik
Selalu tentukan rentang versi atau versi untuk dependensi paket dalam file proyek, file packages.config
, dan file .nuspec
. Tanpa versi atau rentang versi, saat menyelesaikan dependensi, hasil pemulihan yang konsisten tidak dijamin.
Hindari menentukan batas atas ke rentang versi ke paket yang tidak Anda miliki kecuali Anda mengetahui masalah kompatibilitas. Batas atas untuk versi merugikan adopsi, mencegah konsumen mendapatkan pembaruan berharga hingga dependensi, dan dalam beberapa kasus dapat menyebabkan mereka menggunakan versi dependensi yang tidak didukung.
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 di packages.config
:
Dalam packages.config
, setiap dependensi dicantumkan dengan atribut version
yang tepat 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 file .nuspec
Atribut version
dalam elemen <dependency>
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
Nota
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
operasi pack
dan restore
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 paket tidak boleh juga menghosting versi 1.0.0 sebagai paket terpisah dan berbeda.
Penerapan Versi Semantik 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 instans NuGetVersion
.
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.
-
NuGetVersion
mendukung segmen versi ke-4,Revision
, untuk kompatibel dengan, atau superset,System.Version
. Oleh karena itu, tidak termasuk label prarilis dan metadata, string versiMajor.Minor.Patch.Revision
. Sesuai normalisasi versi yang dijelaskan di atas, jikaRevision
adalah nol, itu dihilangkan dari string versi yang dinormalisasi. -
NuGetVersion
hanya memerlukan segmen utama untuk didefinisikan. Semua lainnya bersifat opsional, dan setara dengan nol. Ini berarti bahwa1
,1.0
,1.0.0
, dan1.0.0.0
semuanya diterima dan sama. -
NuGetVersion
menggunakan perbandingan string yang tidak sensitif huruf besar/kecil untuk komponen pra-rilis. Ini berarti bahwa1.0.0-alpha
dan1.0.0-Alpha
sama.