Compartilhar via

Controle de versão do pacote

  • Artigo

Um pacote específico é sempre referenciado usando seu identificador de pacote e um número de versão exato. Por exemplo, Entity Framework no nuget.org tem várias dezenas de pacotes específicos disponíveis, desde a versão 4.1.10311 até a versão 6.1.3 (a versão estável mais recente) 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 Versão Semântica 2.0.0 padrão, com suporte do NuGet 4.3.0+ e do Visual Studio 2017 versão 15.3+. Certas semântica do SemVer v2.0.0 não têm suporte em clientes mais antigos.

Neste tópico:

Noções básicas de versão

Um número de versão específico está no formulário Major.Minor.Patch[-Sufixo], em que os componentes têm os seguintes significados:

  • principais: alterações interruptivas
  • minor: novos recursos, mas compatíveis com versões anteriores
  • patch: somente correções de bug compatíveis com versões anteriores
  • -Sufixo (opcional): um hífen seguido por uma cadeia de caracteres que indica uma versão de pré-lançamento (seguindo a convenção Controle de Versão Semântico ou SemVer).

exemplos de :

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Importante

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

Versões de pré-lançamento

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

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

  • -alpha: versão alfa, normalmente usada para trabalho em andamento e experimentação.
  • -beta: versão beta, normalmente um recurso concluído para a próxima versão planejada, mas pode conter bugs conhecidos.
  • -rc: Release candidate, normalmente uma versão potencialmente final (estável), a menos que bugs significativos surjam.

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

Nota

Os números de pré-lançamento com notação de ponto, como em 1.0.1-build.23, são considerados como parte do padrão de SemVer 2.0.0 e, como tal, têm suporte apenas com o 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

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

Intervalos de versão

Ao fazer referência a dependências de pacote, o NuGet dá suporte ao uso de notação de intervalo para especificar intervalos de versão, resumido da seguinte maneira:

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 Intervalo exato, inclusivo
(1.0,2.0) 1.0 < x < 2.0 Intervalo exato, exclusivo
[1.0,2.0) 1.0 ≤ x < 2.0 Versão mínima inclusiva mista e máxima exclusiva
(1.0) Inválido Inválido

Prática recomendada

Sempre especifique uma versão ou intervalo de versão para dependências de pacote em arquivos de projeto, arquivos packages.config e arquivos .nuspec. Sem uma versão ou intervalo de versão, ao resolver uma dependência, os resultados consistentes da restauração não são garantidos. Evite especificar um limite superior para intervalos de versão para pacotes que você não possui, a menos que você saiba de um problema de compatibilidade. Limites superiores a intervalos de versões prejudicam a adoção, desencorajam os consumidores a obter atualizações valiosas para dependências e, em alguns casos, podem levá-los a usar versões sem suporte 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 de no packages.config:

Em packages.config, cada dependência é listada com um atributo version exato usado ao restaurar pacotes. O atributo allowedVersions é usado somente durante operações de atualização para restringir as versões às 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 de 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

Nota

Essa é uma alteração significativa para o NuGet 3.4+.

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

  • 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 de versão será omitido

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

  • Metadados de build do SemVer 2.0.0 são removidos

    • 1.0.7+r3456 é tratado como 1.0.7

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

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

Versão semântica 2.0.0

Não há suporte para determinada semântica do SemVer v2.0.0 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 ponto, por exemplo, 1.0.0-alpha.1
  • A versão tem metadados de build, por exemplo, 1.0.0+githash

Para nuget.org, um pacote será 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 em conformidade 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 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 controle de versão semântico

Se você quiser usar programaticamente as versões do pacote NuGet, é altamente recomendável usar 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 do NuGet em um idioma que não é executado no .NET, aqui estão 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ântica existente pode não funcionar para pacotes já publicados no nuget.org.

  1. NuGetVersion dá suporte a um segmento de 4ª versão, Revision, para ser compatível ou com 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 de versão descrita acima, se Revision for zero, ela será omitida da cadeia de caracteres de versão normalizada.
  2. NuGetVersion requer apenas que o segmento principal seja definido. Todos os outros são opcionais e são equivalentes a zero. Isso significa que 1, 1.0, 1.0.0e 1.0.0.0 são todos 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. Isso significa que 1.0.0-alpha e 1.0.0-Alpha são iguais.