Contrôle de version des packagesPackage versioning

Un package spécifique est toujours appelé à l’aide de son identificateur de package et un numéro de version exact.A specific package is always referred to using its package identifier and an exact version number. Par exemple, Entity Framework sur nuget.org a plusieurs dizaines des packages spécifiques disponibles, allant de version 4.1.10311 vers la version 6.1.3 (la dernière stable mise en production) et une variété de versions préliminaires comme 6.2.0-beta1.For example, Entity Framework on nuget.org has several dozen specific packages available, ranging from version 4.1.10311 to version 6.1.3 (the latest stable release) and a variety of pre-release versions like 6.2.0-beta1.

Lorsque vous créez un package, vous affectez un numéro de version spécifique avec un suffixe facultatif en version préliminaire.When creating a package, you assign a specific version number with an optional pre-release text suffix. En revanche, lors de l’utilisation des packages, vous pouvez spécifier un numéro de version exact ou une plage de versions acceptables.When consuming packages, on the other hand, you can specify either an exact version number or a range of acceptable versions.

Dans cette rubrique :In this topic:

Principes fondamentaux de versionVersion basics

Un numéro de version spécifique se présente sous la forme version_principale.version_secondaire.version_corrective [-suffixe], où les composants ont les significations suivantes :A specific version number is in the form Major.Minor.Patch[-Suffix], where the components have the following meanings:

  • Principales: Modifications avec ruptureMajor: Breaking changes
  • Mineure: Nouvelles fonctionnalités, offrant néanmoins une compatibilité descendanteMinor: New features, but backwards compatible
  • Correctif: Correctifs de bogues à compatibilité descendante uniquementPatch: Backwards compatible bug fixes only
  • -Suffixe (facultatif) : un trait d’union suivie d’une chaîne qui dénote une version préliminaire (suivant la convention Semver ou SemVer 1.0).-Suffix (optional): a hyphen followed by a string denoting a pre-release version (following the Semantic Versioning or SemVer 1.0 convention).

Exemples :Examples:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta1

Important

NuGet.org rejette tout chargement du package qui ne dispose pas d’un numéro de version exact.nuget.org rejects any package upload that lacks an exact version number. La version doit être spécifiée dans le .nuspec ou le fichier projet utilisé pour créer le package.The version must be specified in the .nuspec or project file used to create the package.

Versions préliminairesPre-release versions

Techniquement parlant, créateurs de package peuvent utiliser n’importe quelle chaîne comme suffixe pour désigner une version préliminaire, que NuGet traite n’importe quelle version de ce type en tant que version préliminaire et aucune autre interprétation a fait.Technically speaking, package creators can use any string as a suffix to denote a pre-release version, as NuGet treats any such version as pre-release and makes no other interpretation. Autrement dit, NuGet les affiche la version complète de chaîne dans toute l’interface utilisateur est impliquée, en laissant toute interprétation du sens du suffixe au consommateur.That is, NuGet displays the full version string in whatever UI is involved, leaving any interpretation of the suffix's meaning to the consumer.

Ceci dit, les développeurs de packages suivent généralement les conventions de nommage reconnues :That said, package developers generally follow recognized naming conventions:

  • -alpha: Version alpha, généralement utilisée pour les travaux en cours et l’expérimentation.-alpha: Alpha release, typically used for work-in-progress and experimentation.
  • -beta: Version bêta, comprenant généralement toutes les fonctionnalités de la prochaine version planifiée, mais pouvant contenir des bogues connus.-beta: Beta release, typically one that is feature complete for the next planned release, but may contain known bugs.
  • -rc: Version Release Candidate, généralement une version potentiellement finale (stable), sauf si des bogues importants apparaissent.-rc: Release candidate, typically a release that's potentially final (stable) unless significant bugs emerge.

Notes

Prend en charge de NuGet 4.3.0 SemVer 2.0.0, qui prend en charge les numéros de version préliminaire avec la notation à points, comme dans 1.0.1-build.23.NuGet 4.3.0+ supports SemVer 2.0.0, which supports pre-release numbers with dot notation, as in 1.0.1-build.23. La notation à points n’est pas prise en charge avec les versions de NuGet antérieures à 4.3.0.Dot notation is not supported with NuGet versions before 4.3.0. Vous pouvez utiliser un format similaire à 1.0.1-build23.You can use a form like 1.0.1-build23.

Lors de la résolution des références de package et de plusieurs versions de package diffèrent uniquement par le suffixe, NuGet choisit une version sans suffixe tout d’abord, puis applique la priorité pour les versions préliminaires dans l’ordre alphabétique inverse.When resolving package references and multiple package versions differ only by suffix, NuGet chooses a version without a suffix first, then applies precedence to pre-release versions in reverse alphabetical order. Par exemple, les versions suivantes seraient choisies dans l’ordre exact indiqué :For example, the following versions would be chosen in the exact order shown:

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

Semver 2.0.0Semantic Versioning 2.0.0

Avec NuGet 4.3.0 et Visual Studio 2017 version 15.3 +, NuGet prend en charge Semver 2.0.0.With NuGet 4.3.0+ and Visual Studio 2017 version 15.3+, NuGet supports Semantic Versioning 2.0.0.

Les clients plus anciens ne prend pas en charge certaine sémantique de version de SemVer 2.0.0.Certain semantics of SemVer v2.0.0 are not supported in older clients. NuGet prend en compte une version de package à être SemVer v2.0.0 spécifique si une des affirmations suivantes est vraie :NuGet considers a package version to be SemVer v2.0.0 specific if either of the following statements is true:

  • L’étiquette de version préliminaire est séparé par un point, par exemple, 1.0.0-alpha.1The pre-release label is dot-separated, for example, 1.0.0-alpha.1
  • La version a des métadonnées de la build, par exemple, 1.0.0+githashThe version has build-metadata, for example, 1.0.0+githash

Pour nuget.org, un package est défini comme un package de version 2.0.0 SemVer si une des affirmations suivantes est vraie :For nuget.org, a package is defined as a SemVer v2.0.0 package if either of the following statements is true:

  • La version du package est v2.0.0 SemVer conforme mais pas SemVer v1.0.0 conforme, tel que défini ci-dessus.The package's own version is SemVer v2.0.0 compliant but not SemVer v1.0.0 compliant, as defined above.
  • Une des plages de versions de dépendance du package a une version minimale ou maximale est SemVer v2.0.0 conforme mais pas SemVer v1.0.0 conforme, défini ci-dessus ; par exemple, [1.0.0-alpha.1,).Any of the package's dependency version ranges has a minimum or maximum version that is SemVer v2.0.0 compliant but not SemVer v1.0.0 compliant, defined above; for example, [1.0.0-alpha.1, ).

Si vous téléchargez un package spécifique à la version 2.0.0 de SemVer sur nuget.org, le package est invisible aux clients plus anciens et disponible pour seulement les clients NuGet suivants :If you upload a SemVer v2.0.0-specific package to nuget.org, the package is invisible to older clients and available to only the following NuGet clients:

  • NuGet 4.3.0NuGet 4.3.0+
  • Visual Studio 2017 version 15.3 +Visual Studio 2017 version 15.3+
  • Visual Studio 2015 avec v3.6.0 d’extension VSIX NuGetVisual Studio 2015 with NuGet VSIX v3.6.0
  • dotnetdotnet
    • dotnetcore.exe (Kit de développement logiciel .NET 2.0.0+)dotnetcore.exe (.NET SDK 2.0.0+)

Les clients tiers :Third-party clients:

  • Avenant de JetBrainsJetBrains Rider
  • Paket version 5.0 et versions ultérieuresPaket version 5.0+

Caractères génériques et les plages de versionsVersion ranges and wildcards

Lorsque vous faites référence aux dépendances de package, NuGet prend en charge à l’aide de la notation de l’intervalle pour la spécification de plages de versions, résumées comme suit :When referring to package dependencies, NuGet supports using interval notation for specifying version ranges, summarized as follows:

NotationNotation Règle appliquéeApplied rule DescriptionDescription
1.01.0 x ≥ 1.0x ≥ 1.0 Version minimale, inclusiveMinimum version, inclusive
(1.0,)(1.0,) x > 1.0x > 1.0 Version minimale, exclusiveMinimum version, exclusive
[1.0][1.0] x == 1.0x == 1.0 Correspondance de la version exacteExact version match
(,1.0](,1.0] x ≤ 1.0x ≤ 1.0 Version maximale, inclusiveMaximum version, inclusive
(,1.0)(,1.0) x < 1.0x < 1.0 Version maximale, exclusiveMaximum version, exclusive
[1.0,2.0][1.0,2.0] 1.0 ≤ x ≤ 2.01.0 ≤ x ≤ 2.0 Plage exacte, inclusifExact range, inclusive
(1.0,2.0)(1.0,2.0) 1.0 < x < 2.01.0 < x < 2.0 Plage exacte, exclusifExact range, exclusive
[1.0,2.0)[1.0,2.0) 1.0 ≤ x < 2.01.0 ≤ x < 2.0 Mixte inclusive minimale et exclusive version maximaleMixed inclusive minimum and exclusive maximum version
(1.0)(1.0) non valideinvalid non valideinvalid

Lorsque vous utilisez le format PackageReference, NuGet prend également en charge à l’aide d’une notation de caractère générique, *, pour majeure, mineure, correctifs et des parties de suffixe de version préliminaire du nombre.When using the PackageReference format, NuGet also supports using a wildcard notation, *, for Major, Minor, Patch, and pre-release suffix parts of the number. Les caractères génériques ne sont pas pris en charge avec le packages.config format.Wildcards are not supported with the packages.config format.

Notes

Versions préliminaires ne sont pas incluses lors de la résolution des plages de versions.Pre-release versions are not included when resolving version ranges. Versions préliminaires sont inclus lorsque vous utilisez un caractère générique (*).Pre-release versions are included when using a wildcard (*). La plage de versions [1.0,2.0], par exemple, n’inclut pas 2.0 bêta, mais la notation de caractère générique 2.0-* est.The version range [1.0,2.0], for example, does not include 2.0-beta, but the wildcard notation 2.0-* does. Consultez émettre 912 pour obtenir des informations sur les caractères génériques en version préliminaire.See issue 912 for further discussion on pre-release wildcards.

ExemplesExamples

Spécifiez toujours une version ou une plage de versions de dépendances de package dans les fichiers de projet, packages.config fichiers, et .nuspec fichiers.Always specify a version or version range for package dependencies in project files, packages.config files, and .nuspec files. Sans une version ou une plage de versions, NuGet 2.8.x et précédemment choisit la dernière version de package disponibles lors de la résolution d’une dépendance, tandis que NuGet 3.x et versions ultérieures choisit la plus ancienne version de package.Without a version or version range, NuGet 2.8.x and earlier chooses the latest available package version when resolving a dependency, whereas NuGet 3.x and later chooses the lowest package version. Spécification d’une version ou plage évite cette incertitude.Specifying a version or version range avoids this uncertainty.

Références dans les fichiers de projet (PackageReference)References in project files (PackageReference)

<!-- Accepts any version 6.1 and above. -->
<PackageReference Include="ExamplePackage" Version="6.1" />

<!-- Accepts any 6.x.y version. -->
<PackageReference Include="ExamplePackage" Version="6.*" />
<PackageReference Include="ExamplePackage" Version="[6,7)" />

<!-- Accepts any version above, but not including 4.1.3. Could be
     used to guarantee a dependency with a specific bug fix. -->
<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. -->
<PackageReference Include="ExamplePackage" Version="(,5.0)" />

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

<!-- Accepts 1.3.2 up to 1.4.x, but not 1.5 and higher. -->
<PackageReference Include="ExamplePackage" Version="[1.3.2,1.5)" />

Les références dans packages.config:References in packages.config:

Dans packages.config, chaque dépendance est répertorié avec un exacte version attribut qui est utilisé lors de la restauration des packages.In packages.config, every dependency is listed with an exact version attribute that's used when restoring packages. Le allowedVersions attribut est utilisé uniquement pendant les opérations de mise à jour pour limiter les versions à laquelle le package peut être mis à jour.The allowedVersions attribute is used only during update operations to constrain the versions to which the package might be updated.

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

Les références dans .nuspec fichiersReferences in .nuspec files

Le version d’attribut dans un <dependency> élément décrit les versions de plage qui sont acceptables pour une dépendance.The version attribute in a <dependency> element describes the range versions that are acceptable for a dependency.

<!-- 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éeNormalized version numbers

Notes

Il s’agit d’une modification avec rupture pour NuGet 3.4 et versions ultérieures.This is a breaking change for NuGet 3.4 and later.

Lors de l’obtention des packages à partir d’un référentiel lors de l’installation, réinstaller, opérations ou de restauration, NuGet 3.4 + traite les numéros de version comme suit :When obtaining packages from a repository during install, reinstall, or restore operations, NuGet 3.4+ treats version numbers as follows:

  • Les zéros non significatifs sont supprimés de numéros de version :Leading zeroes are removed from version numbers:

      1.00 is treated as 1.0
      1.01.1 is treated as 1.1.1
      1.00.0.1 is treated as 1.0.0.1
    
  • Un zéro dans la quatrième partie du numéro de version sera omisA zero in the fourth part of the version number will be omitted

      1.0.0.0 is treated as 1.0.0
      1.0.01.0 is treated as 1.0.1
    

Cette normalisation n’affecte pas les numéros de version dans les packages eux-mêmes ; elle affecte uniquement comment NuGet correspond aux versions lors de la résolution des dépendances.This normalization does not affect the version numbers in the packages themselves; it affects only how NuGet matches versions when resolving dependencies.

Toutefois, les référentiels de packages NuGet doivent traiter ces valeurs dans la même façon que NuGet pour éviter la duplication de version de package.However, NuGet package repositories must treat these values in the same way as NuGet to prevent package version duplication. Par conséquent, un référentiel qui contient la version 1.0 d’un package ne doit également héberger version 1.0.0 sous forme de package distincte et différente.Thus a repository that contains version 1.0 of a package should not also host version 1.0.0 as a separate and different package.