Partilhar via

Controle de versão do pacote

  • Artigo

Um pacote específico é sempre referido usando seu identificador de pacote e um número de versão exato. Por exemplo, Entity Framework no nuget.org tem várias dúzias de pacotes específicos disponíveis, variando da versão 4.1.10311 à versão 6.1.3 (a última versão estável) e uma variedade de versões de pré-lançamento como 6.2.0-beta1.

Ao criar um pacote, você atribui um número de versão específico com um sufixo de texto de pré-lançamento opcional. Ao consumir pacotes, por outro lado, você pode especificar um número de versão exato ou um intervalo de versões aceitáveis.

O documento a seguir segue o padrão Semantic Versioning 2.0.0, suportado pelo NuGet 4.3.0+ e pelo Visual Studio 2017 versão 15.3+. Certas semânticas do SemVer v2.0.0 não são suportadas em clientes mais antigos.

Neste tópico:

Noções básicas sobre a versão

Um número de versão específico está na forma Major.Minor.Patch[-Suffix], onde os componentes têm os seguintes significados:

  • Principais: Breaking changes
  • Minor: Novos recursos, mas retrocompatíveis
  • Patch: Apenas correções de bugs compatíveis com versões anteriores
  • -Sufixo (opcional): um hífen seguido de uma string denotando uma versão de pré-lançamento (seguindo a convenção Semantic Versioning ou SemVer).

Exemplos:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Importante

nuget.org rejeita qualquer carregamento de pacote que não tenha um número de versão exato. A versão deve ser especificada no arquivo de .nuspec ou projeto usado para criar o pacote.

Versões de pré-lançamento

Tecnicamente falando, os criadores de pacotes podem usar qualquer string como sufixo para denotar uma versão de pré-lançamento, já que o NuGet trata qualquer versão como pré-lançamento e não faz outra interpretação. Ou seja, o NuGet exibe a cadeia de caracteres da versão completa em qualquer interface do usuário envolvida, deixando qualquer interpretação do significado do sufixo para o consumidor.

Dito isso, os desenvolvedores de pacotes geralmente seguem convenções de nomenclatura reconhecidas:

  • -alpha: Libertação de alfa, normalmente utilizada para trabalhos em curso e experimentação.
  • -beta: Versão beta, normalmente uma que é recurso completo para a próxima versão planejada, mas pode conter bugs conhecidos.
  • -rc: Release candidate, normalmente uma versão que é potencialmente final (estável), a menos que surjam bugs significativos.

Ao ordenar versões por precedência, o NuGet segue o padrão SemVer e escolhe uma versão sem sufixo primeiro, depois aplica precedência às versões de pré-lançamento em ordem alfabética inversa e trata os números de notação de pontos com ordem numérica.

Observação

Os números de pré-lançamento com notação de pontos, como no1.0.1-build.23 , são considerados parte do padrão SemVer 2.0.0 e, como tal, são suportados apenas com o NuGet 4.3.0+.

  • de classificação SemVer 2.0
  • de classificação 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

Observe que 1.0.1-alpha10 é classificado estritamente em ordem alfabética inversa, enquanto 1.0.1-rc.10 é maior precedência do que 1.0.1-rc.2.

Intervalos de versões

Ao se referir a dependências de pacote, o NuGet oferece suporte ao uso de notação de intervalo para especificar intervalos de versão, resumidos da seguinte forma:

Notação Regra aplicada Descrição
1.0 x ≥ 1,0 Versão mínima, inclusive
[1.0,) x ≥ 1,0 Versão mínima, inclusive
(1.0,) x > 1,0 Versão mínima, exclusiva
[1.0] x == 1,0 Correspondência exata da versão
(,1.0] x ≤ 1,0 Versão máxima, inclusive
(,1.0) x < 1,0 Versão máxima, exclusiva
[1.0,2.0] 1,0 ≤ x ≤ 2,0 Alcance exato, inclusive
(1.0,2.0) 1,0 < x < 2,0 Alcance exato, exclusivo
[1.0,2.0) 1,0 ≤ x < 2,0 Versão mínima inclusiva mista e versão máxima exclusiva
(1.0) Inválido Inválido

Melhores Práticas

Sempre especifique uma versão ou intervalo de versões para dependências de pacotes em arquivos de projeto, arquivos de packages.config e arquivos de .nuspec. Sem uma versão ou intervalo de versões, ao resolver uma dependência, resultados de restauração consistentes não são garantidos. Evite especificar um limite superior para intervalos de versões para pacotes que você não possui, a menos que saiba de um problema de compatibilidade. Os limites superiores para intervalos de versões prejudicam a adoção, desencorajam os consumidores de obter atualizações valiosas para dependências e, em alguns casos, podem levá-los a usar versões não suportadas de dependências.

Referências em arquivos de projeto (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)" />

Referências em packages.config:

No packages.config, cada dependência é listada com um atributo version exato que é usado ao restaurar pacotes. O atributo allowedVersions é usado somente durante operações de atualização para restringir as versões para as quais o pacote pode ser atualizado.

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

Referências em arquivos .nuspec

O atributo version em um elemento <dependency> descreve as versões de intervalo aceitáveis para uma dependência.

<!-- 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 versão normalizados

Observação

Esta é uma mudança significativa para o NuGet 3.4+.

Ao obter pacotes de um repositório durante as operações de instalação, reinstalação ou restauração, o NuGet 3.4+ trata os números de versão da seguinte forma:

  • Os zeros à esquerda são removidos dos números de versão:

    • 1,00 é tratado como 1,0
    • 1.01.1 é tratado como 1.1.1
    • 1.00.0.1 é tratado como 1.0.0.1

  • Um zero na quarta parte do número da versão será omitido

    • 1.0.0.0 é tratado como 1.0.0
    • 1.0.01.0 é tratado como 1.0.1

  • Os metadados de compilação do SemVer 2.0.0 são removidos

    • 1.0.7+r3456 é tratado como 1.0.7

pack e restore operações normalizam versões sempre que possível. Para pacotes já construídos, essa normalização não afeta os números de versão nos próprios pacotes; afeta apenas a forma como o NuGet corresponde às versões ao resolver dependências.

No entanto, os repositórios de pacotes NuGet devem tratar esses valores da mesma maneira que o NuGet para evitar a duplicação da versão do pacote. Assim, um repositório que contém a versão 1.0 de um pacote não deve também hospedar a versão 1.0.0 como um pacote separado e diferente.

Versionamento semântico 2.0.0

Certas semânticas do SemVer v2.0.0 não são suportadas em clientes mais antigos. O NuGet considera uma versão do pacote específica do SemVer v2.0.0 se uma das seguintes instruções for verdadeira:

  • O rótulo de pré-lançamento é separado por pontos, por exemplo, 1.0.0-alpha.1
  • A versão tem metadados de compilação, por exemplo, 1.0.0+githash

Por nuget.org, um pacote é definido como um pacote SemVer v2.0.0 se uma das seguintes instruções for verdadeira:

  • A própria versão do pacote é compatível com SemVer v2.0.0, mas não compatível com SemVer v1.0.0, conforme definido acima.
  • Qualquer um dos intervalos de versão de dependência do pacote tem uma versão mínima ou máxima que é compatível com SemVer v2.0.0, mas não compatível com SemVer v1.0.0, definido acima; por exemplo, [1.0.0-alpha.1, ).

Se você carregar um pacote específico do SemVer v2.0.0 para nuget.org, o pacote será invisível para clientes mais antigos e estará disponível apenas para os seguintes clientes NuGet:

  • NuGet 4.3.0+
  • Visual Studio 2017 versão 15.3+
  • Visual Studio 2015 com NuGet VSIX v3.6.0
  • SDK do .NET 2.0.0+

Clientes de terceiros:

  • JetBrains Rider
  • Paket versão 5.0+

Onde NuGetVersion diverge do versionamento semântico

Se você quiser usar programaticamente as versões do pacote NuGet, é altamente recomendável usar o pacote NuGet.Versioning. O método estático NuGetVersion.Parse(string) pode ser usado para analisar as cadeias de caracteres de versão e VersionComparer pode ser usado para classificar NuGetVersion instâncias.

Se você estiver implementando a funcionalidade NuGet em um idioma que não é executado no .NET, aqui está a lista conhecida de diferenças entre o NuGetVersion e o Controle de Versão Semântico e os motivos pelos quais uma biblioteca de Controle de Versão Semântico existente pode não funcionar para pacotes já publicados no nuget.org.

  1. NuGetVersion suporta um segmento de 4ª versão, Revision, para ser compatível com, ou um superconjunto de, System.Version. Portanto, excluindo rótulos de pré-lançamento e metadados, uma cadeia de caracteres de versão é Major.Minor.Patch.Revision. De acordo com a normalização da versão descrita acima, se Revision for zero, ela será omitida da cadeia de caracteres da versão normalizada.
  2. NuGetVersion requer apenas que o segmento principal seja definido. Todos os outros são opcionais e equivalem a zero. Isso significa que 1, 1.0, 1.0.0e 1.0.0.0 são aceitos e iguais.
  3. NuGetVersion usa comparações de cadeia de caracteres que não diferenciam maiúsculas de minúsculas para componentes de pré-lançamento. Isto significa que 1.0.0-alpha e 1.0.0-Alpha são iguais.