Compartir a través de

Control de versiones de paquetes

  • Artículo

Siempre se hace referencia a un paquete específico mediante su identificador de paquete y un número de versión exacto. Por ejemplo, Entity Framework en nuget.org tiene disponibles varias docenas de paquetes específicos, que van desde la versión 4.1.10311 hasta la versión 6.1.3 (la versión estable más reciente) y una variedad de versiones preliminares, como 6.2.0-beta1.

Al crear un paquete, asigne un número de versión específico con un sufijo de texto de versión preliminar opcional. Por otro lado, al consumir paquetes, puede especificar un número de versión exacto o un intervalo de versiones aceptables.

El siguiente documento sigue el estándar semántica versioning 2.0.0, compatible con NuGet 4.3.0+ y Visual Studio 2017 versión 15.3+. Algunas semántica de semVer v2.0.0 no se admiten en clientes anteriores.

En este tema:

Conceptos básicos de la versión

Un número de versión específico tiene el formato Major.Minor.Patch[-Suffix], donde los componentes tienen los siguientes significados:

  • principal: Cambios importantes
  • minor: nuevas características, pero compatibles con versiones anteriores
  • patch: correcciones de errores compatibles con versiones anteriores solo
  • -Sufijo (opcional): un guión seguido de una cadena que indica una versión preliminar (siguiendo la convención de versiones semánticas o SemVer).

Ejemplos de :

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Importante

nuget.org rechaza cualquier carga de paquetes que no tenga un número de versión exacto. La versión debe especificarse en el archivo de .nuspec o proyecto que se usa para crear el paquete.

Versiones preliminares

Técnicamente, los creadores de paquetes pueden usar cualquier cadena como sufijo para indicar una versión preliminar, ya que NuGet trata cualquier versión como versión preliminar y no realiza ninguna otra interpretación. Es decir, NuGet muestra la cadena de versión completa en cualquier interfaz de usuario implicada, dejando cualquier interpretación del significado del sufijo al consumidor.

Dicho esto, los desarrolladores de paquetes suelen seguir las convenciones de nomenclatura reconocidas:

  • -alpha: versión alfa, que normalmente se usa para la experimentación y el trabajo en curso.
  • -beta: versión beta, normalmente una que es una característica completa para la próxima versión planeada, pero puede contener errores conocidos.
  • -rc: versión candidata para lanzamiento, normalmente una versión que puede ser final (estable) a menos que surjan errores significativos.

Al ordenar las versiones por precedencia, NuGet sigue el estándar SemVer y elige primero una versión sin un sufijo, luego aplica prioridad a las versiones preliminares en orden alfabético inverso y trata los números de notación de puntos con orden numérico.

Nota

Los números de versión preliminar con notación de puntos, como en 1.0.1-build.23, se consideran parte del estándar SemVer 2.0.0 y, por tanto, solo se admite n con NuGet 4.3.0+.

  • de ordenación de SemVer 2.0
  • de ordenación de 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

Tenga en cuenta que 1.0.1-alpha10 se ordena estrictamente en orden alfabético inverso, mientras que 1.0.1-rc.10 es mayor que 1.0.1-rc.2.

Intervalos de versiones

Al hacer referencia a las dependencias del paquete, NuGet admite el uso de notación de intervalos para especificar intervalos de versión, resumidos de la manera siguiente:

Notación Regla aplicada Descripción
1.0 x ≥ 1.0 Versión mínima, inclusiva
[1.0,) x ≥ 1.0 Versión mínima, inclusiva
(1.0,) x > 1.0 Versión mínima, exclusiva
[1.0] x == 1,0 Coincidencia de versión exacta
(,1.0] x ≤ 1.0 Versión máxima, inclusiva
(,1.0) x < 1.0 Versión máxima, exclusiva
[1.0,2.0] 1.0 ≤ x ≤ 2.0 Intervalo exacto, inclusivo
(1.0,2.0) 1.0 < x < 2.0 Rango exacto, exclusivo
[1.0,2.0) 1.0 ≤ x < 2.0 Versión máxima mínima y exclusiva mixta inclusiva
(1.0) No válido No válido

Procedimiento recomendado

Especifique siempre una versión o un intervalo de versiones para las dependencias de paquetes en archivos de proyecto, archivos packages.config y archivos .nuspec. Sin una versión o intervalo de versiones, al resolver una dependencia, no se garantizan resultados de restauración coherentes. Evite especificar un límite superior a los intervalos de versiones para los paquetes que no posee a menos que sepa un problema de compatibilidad. Los límites superiores a los intervalos de versiones dañan la adopción, desalienten a los consumidores de obtener actualizaciones valiosas a las dependencias y, en algunos casos, pueden provocar que usen versiones no admitidas de dependencias.

Referencias en archivos de proyecto (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)" />

referencias de en packages.config:

En packages.config, todas las dependencias se muestran con un atributo version exacto que se usa al restaurar paquetes. El atributo allowedVersions solo se usa durante las operaciones de actualización para restringir las versiones a las que se puede actualizar el paquete.

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

referencias de en archivos .nuspec

El atributo version de un elemento <dependency> describe las versiones de intervalo que son aceptables para una dependencia.

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

Números de versión normalizados

Nota

Se trata de un cambio importante para NuGet 3.4 y versiones posteriores.

Al obtener paquetes de un repositorio durante las operaciones de instalación, reinstalación o restauración, NuGet 3.4+ trata los números de versión de la siguiente manera:

  • Los ceros iniciales se quitan de los números de versión:

    • 1.00 se trata como 1.0
    • 1.01.1 se trata como 1.1.1
    • 1.00.0.1 se trata como 1.0.0.1

  • Se omitirá un cero en la cuarta parte del número de versión.

    • 1.0.0.0 se trata como 1.0.0
    • 1.0.01.0 se trata como 1.0.1

  • Se quitan los metadatos de compilación de SemVer 2.0.0

    • 1.0.7+r3456 se trata como 1.0.7

pack y restore operaciones normalizan las versiones siempre que sea posible. En el caso de los paquetes ya creados, esta normalización no afecta a los números de versión de los propios paquetes; afecta solo a cómo NuGet coincide con las versiones al resolver las dependencias.

Sin embargo, los repositorios de paquetes NuGet deben tratar estos valores de la misma manera que NuGet para evitar la duplicación de versiones del paquete. Por lo tanto, un repositorio que contiene la versión 1.0 de un paquete no debe hospedar la versión 1.0.0 como un paquete independiente y diferente.

Control de versiones semántico 2.0.0

No se admite cierta semántica de SemVer v2.0.0 en clientes anteriores. NuGet considera que una versión del paquete es semVer v2.0.0 específica si alguna de las siguientes instrucciones es cierta:

  • La etiqueta de versión preliminar está separada por puntos, por ejemplo, 1.0.0-alpha.1
  • La versión tiene metadatos de compilación, por ejemplo, 1.0.0+githash

Para nuget.org, un paquete se define como un paquete SemVer v2.0.0 si se cumple alguna de las siguientes instrucciones:

  • La propia versión del paquete es compatible con SemVer v2.0.0, pero no compatible con SemVer v1.0.0, como se definió anteriormente.
  • Cualquiera de los intervalos de versiones de dependencia del paquete tiene una versión mínima o máxima compatible con SemVer v2.0.0, pero no compatible con SemVer v1.0.0, definida anteriormente; por ejemplo, [1.0.0-alpha.1, ).

Si carga un paquete específico de SemVer v2.0.0 para nuget.org, el paquete es invisible para los clientes más antiguos y solo está disponible para los siguientes clientes NuGet:

  • NuGet 4.3.0+
  • Visual Studio 2017, versión 15.3+
  • Visual Studio 2015 con de VSIX de NuGet v3.6.0
  • SDK de .NET 2.0.0+

Clientes de terceros:

  • JetBrains Rider
  • Paket versión 5.0+

Donde NuGetVersion difiere del control de versiones semánticos

Si desea usar mediante programación las versiones del paquete NuGet, se recomienda encarecidamente usar el paquete NuGet.Versioning. El método estático NuGetVersion.Parse(string) se puede usar para analizar las cadenas de versión y VersionComparer se puede usar para ordenar NuGetVersion instancias.

Si va a implementar la funcionalidad de NuGet en un lenguaje que no se ejecuta en .NET, esta es la lista conocida de diferencias entre las NuGetVersion y el control de versiones semántico, y los motivos por los que una biblioteca de control de versiones semántica existente podría no funcionar para los paquetes ya publicados en nuget.org.

  1. NuGetVersion admite un segmento de versión 4, Revision, para que sea compatible con o un superconjunto de System.Version. Por lo tanto, excluyendo las etiquetas de metadatos y de versión preliminar, una cadena de versión es Major.Minor.Patch.Revision. Según la normalización de versiones descrita anteriormente, si Revision es cero, se omite de la cadena de versión normalizada.
  2. NuGetVersion solo requiere que se defina el segmento principal. Todos los demás son opcionales y son equivalentes a cero. Esto significa que 1, 1.0, 1.0.0y 1.0.0.0 se aceptan y son iguales.
  3. NuGetVersion usa comparaciones de cadenas que no distinguen mayúsculas de minúsculas para los componentes de versión preliminar. Esto significa que 1.0.0-alpha y 1.0.0-Alpha son iguales.