Partager via

Contrôle de version du package

  • Article

Un package spécifique est toujours référencé à l’aide de son identificateur de package et d’un numéro de version exact. Par exemple, Entity Framework sur nuget.org dispose de plusieurs dizaines de packages spécifiques disponibles, allant de la version 4.1.10311 à la version 6.1.3 (la dernière version stable) et d’une variété de versions préliminaires telles que 6.2.0-beta1.

Lors de la création d’un package, vous affectez un numéro de version spécifique avec un suffixe de texte de préversion facultatif. En revanche, lorsque vous consommez des packages, vous pouvez spécifier un numéro de version exact ou une plage de versions acceptables.

Le document suivant suit la version sémantique version 2.0.0 standard, prise en charge par NuGet 4.3.0+ et Visual Studio 2017 version 15.3+. Certaines sémantiques de SemVer v2.0.0 ne sont pas prises en charge dans les clients plus anciens.

Dans cette rubrique :

Principes de base de la version

Un numéro de version spécifique se trouve sous la forme Major.Minor.Patch[-Suffix], où les composants ont les significations suivantes :

  • majeur : changements cassants
  • mineure : nouvelles fonctionnalités, mais rétrocompatibles
  • Correctif: correctifs de bogues compatibles vers l’arrière uniquement
  • -Suffixe (facultatif) : trait d’union suivi d’une chaîne indiquant une version préliminaire (après la convention de version sémantique ou SemVer).

exemples :

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Important

nuget.org rejette tout chargement de package qui n’a pas de numéro de version exact. La version doit être spécifiée dans le fichier .nuspec ou projet utilisé pour créer le package.

Versions préliminaires

Techniquement, les créateurs de packages peuvent utiliser n’importe quelle chaîne comme suffixe pour désigner une version préliminaire, car NuGet traite n’importe quelle version telle que la préversion et n’effectue aucune autre interprétation. Autrement dit, NuGet affiche la chaîne de version complète dans l’interface utilisateur impliquée, en laissant toute interprétation de la signification du suffixe au consommateur.

Cela dit, les développeurs de packages suivent généralement les conventions d’affectation de noms reconnues :

  • -alpha: version alpha, généralement utilisée pour le travail en cours et l’expérimentation.
  • -beta: version bêta, généralement une fonctionnalité terminée pour la prochaine version planifiée, mais peut contenir des bogues connus.
  • -rc: candidat à la mise en production, généralement une version potentiellement finale (stable), sauf si des bogues significatifs apparaissent.

Lors de l’ordre des versions par précédence, NuGet suit la norme SemVer et choisit d’abord une version sans suffixe, puis applique la priorité aux versions de préversion dans l’ordre alphabétique inverse et traite les numéros de notation par points avec l’ordre numérique.

Note

Les nombres de préversion avec notation par points, comme dans 1.0.1-build.23, sont considérés comme faisant partie de la SemVer 2.0.0 standard, et, par conséquent, sont uniquement pris en charge avec 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

Notez que 1.0.1-alpha10 est trié strictement dans l’ordre alphabétique inverse, tandis que 1.0.1-rc.10 est plus prioritaire que 1.0.1-rc.2.

Plages de versions

Lorsque vous faites référence aux dépendances de package, NuGet prend en charge l’utilisation de la notation d’intervalle pour spécifier des plages de versions, résumé comme suit :

Notation Règle appliquée Description
1.0 x ≥ 1.0 Version minimale, inclusive
[1.0,) x ≥ 1.0 Version minimale, inclusive
(1.0,) x > 1.0 Version minimale, exclusive
[1.0] x == 1.0 Correspondance exacte de version
(,1.0] x ≤ 1.0 Version maximale, inclusive
(,1.0) x < 1.0 Version maximale, exclusive
[1.0,2.0] 1.0 ≤ x ≤ 2.0 Plage exacte, inclusive
(1.0,2.0) 1.0 < x < 2.0 Plage exacte, exclusive
[1.0,2.0) 1.0 ≤ x < 2.0 Version minimale inclusive mixte et maximale exclusive
(1.0) Non valide Non valide

Bonne pratique

Spécifiez toujours une version ou une plage de versions pour les dépendances de package dans les fichiers projet, les fichiers packages.config et les fichiers .nuspec. Sans version ou plage de versions, lors de la résolution d’une dépendance, les résultats de restauration cohérents ne sont pas garantis. Évitez de spécifier une limite supérieure aux plages de versions aux packages que vous ne possédez pas, sauf si vous connaissez un problème de compatibilité. Les limites supérieures aux plages de versions nuisent à l’adoption, découragent les consommateurs d’obtenir des mises à jour précieuses aux dépendances et, dans certains cas, peuvent les conduire à utiliser des versions non prises en charge des dépendances.

Références dans les fichiers projet (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)" />

références dans packages.config:

Dans packages.config, chaque dépendance est répertoriée avec un attribut version exact utilisé lors de la restauration des packages. L’attribut allowedVersions est utilisé uniquement pendant les opérations de mise à jour pour limiter les versions auxquelles le package peut être mis à jour.

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

références dans les fichiers .nuspec

L’attribut version dans un élément <dependency> décrit les versions de plage acceptables pour une dépendance.

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

Numéros de version normalisés

Note

Il s’agit d’un changement cassant pour NuGet 3.4+.

Lorsque vous obtenez des packages à partir d’un référentiel pendant les opérations d’installation, de réinstallation ou de restauration, NuGet 3.4+ traite les numéros de version comme suit :

  • Les zéros non significatifs sont supprimés des numéros de version :

    • 1.00 est traité comme 1.0
    • 1.01.1 est traité comme 1.1.1
    • 1.00.0.1 est traité comme 1.0.0.1

  • Un zéro dans la quatrième partie du numéro de version est omis

    • 1.0.0.0 est traité comme 1.0.0
    • 1.0.01.0 est traité comme 1.0.1

  • Les métadonnées de build SemVer 2.0.0 sont supprimées

    • 1.0.7+r3456 est traité comme 1.0.7

pack et les opérations de restore normalisent les versions dans la mesure du possible. Pour les packages déjà générés, cette normalisation n’affecte pas les numéros de version dans les packages eux-mêmes ; cela affecte uniquement la façon dont NuGet correspond aux versions lors de la résolution des dépendances.

Toutefois, les référentiels de package NuGet doivent traiter ces valeurs de la même façon que NuGet pour empêcher la duplication de version du package. Ainsi, un référentiel qui contient la version 1.0 d’un package ne doit pas non plus héberger la version 1.0.0 comme un package distinct et différent.

Gestion sémantique de version 2.0.0

Certaines sémantiques de SemVer v2.0.0 ne sont pas prises en charge dans les clients plus anciens. NuGet considère qu’une version de package est spécifique à SemVer v2.0.0 si l’une des instructions suivantes est vraie :

  • L’étiquette de préversion est séparée par des points, par exemple, 1.0.0-alpha.1
  • La version a des métadonnées de build, par exemple, 1.0.0+githash

Pour nuget.org, un package est défini comme un package SemVer v2.0.0 si l’une des instructions suivantes est vraie :

  • La propre version du package est conforme à SemVer v2.0.0, mais pas conforme à SemVer v1.0.0, comme défini ci-dessus.
  • Toutes les plages de versions de dépendance du package ont une version minimale ou maximale conforme à SemVer v2.0.0, mais pas semVer v1.0.0, définie ci-dessus ; par exemple, [1.0.0-alpha.1, ).

Si vous chargez un package spécifique à SemVer v2.0.0 sur nuget.org, le package est invisible pour les clients plus anciens et disponible uniquement pour les clients NuGet suivants :

  • NuGet 4.3.0+
  • Visual Studio 2017 version 15.3+
  • Visual Studio 2015 avec nuGet VSIX v3.6.0
  • KIT SDK .NET 2.0.0+

Clients tiers :

  • JetBrains Rider
  • Paket version 5.0+

Où NuGetVersion diffère du contrôle de version sémantique

Si vous souhaitez utiliser programmatiquement des versions de package NuGet, il est vivement recommandé d’utiliser le package NuGet.Versioning. La méthode statique NuGetVersion.Parse(string) peut être utilisée pour analyser les chaînes de version, et VersionComparer pouvez être utilisée pour trier NuGetVersion instances.

Si vous implémentez des fonctionnalités NuGet dans un langage qui ne s’exécute pas sur .NET, voici la liste connue des différences entre NuGetVersion et le contrôle de version sémantique, et les raisons pour lesquelles une bibliothèque de gestion des versions sémantiques existante peut ne pas fonctionner pour les packages déjà publiés sur nuget.org.

  1. NuGetVersion prend en charge un segment de version 4e, Revision, pour être compatible avec, ou un super-ensemble de System.Version. Par conséquent, à l’exclusion des étiquettes de préversion et de métadonnées, une chaîne de version est Major.Minor.Patch.Revision. Comme pour la normalisation de version décrite ci-dessus, si Revision est égal à zéro, elle est omise à partir de la chaîne de version normalisée.
  2. NuGetVersion nécessite uniquement que le segment principal soit défini. Tous les autres sont facultatifs et sont équivalents à zéro. Cela signifie que 1, 1.0, 1.0.0et 1.0.0.0 sont tous acceptés et égaux.
  3. NuGetVersion utilise des comparaisons de chaînes non sensibles à la casse pour les composants en préversion. Cela signifie que 1.0.0-alpha et 1.0.0-Alpha sont égaux.