Versionamento

Uma biblioteca de software raramente está completa na versão 1.0. Boas bibliotecas evoluem com o tempo, adicionando recursos, corrigindo bugs e melhorando o desempenho. É importante que você possa lançar novas versões de uma biblioteca .NET sem interromper os usuários existentes.

Mudanças significativas

Para obter informações sobre como lidar com mudanças de ruptura entre versões, consulte Mudanças de Ruptura.

Números de versão

Uma biblioteca .NET tem muitas maneiras de especificar uma versão. Estas versões são as mais importantes:

• versão do pacote NuGet
• Versão de Assembly
• Versão do arquivo de montagem
• Versão informativa do Assembly

Versão do pacote NuGet

A versão do pacote NuGet é exibida no NuGet.org e no gestor de pacotes NuGet do Visual Studio, e adicionada ao código-fonte quando o pacote é usado. A versão do pacote NuGet é o número de versão que os usuários normalmente verão e eles se referirão a ele quando falarem sobre a versão de uma biblioteca que estão usando. A versão do pacote NuGet é usada pelo NuGet e não tem efeito no comportamento do tempo de execução.

<PackageVersion>1.0.0-alpha1</PackageVersion>

O identificador de pacote NuGet combinado com a versão do pacote NuGet é usado para identificar um pacote no NuGet. Por exemplo, Newtonsoft.Json + 11.0.2. Um pacote com um sufixo é um pacote de pré-lançamento e tem um comportamento especial que o torna ideal para testes. Para obter mais informações, consulte os pacotes de pré-lançamento .

Como a versão do pacote NuGet é a versão mais visível para os desenvolvedores, é uma boa ideia atualizá-la usando Semantic Versioning (SemVer). O SemVer indica a importância das alterações entre versões e ajuda os desenvolvedores a tomar uma decisão informada ao escolher qual versão usar. Por exemplo, passar de 1.0 para 2.0 indica que há alterações potencialmente revolucionárias.

✔️ CONSIDERE usar SemVer 2.0.0 para versionar o seu pacote NuGet.

✔️ USE a versão do pacote NuGet na documentação pública, pois é o número da versão que os usuários normalmente verão.

✔️ DO inclua um sufixo de pré-lançamento ao liberar um pacote não estável. (Para obter mais informações sobre como marcar APIs como visualização ou experimental, consulte APIs de visualização.)

Os usuários devem optar por obter pacotes de pré-lançamento, para que entendam que o pacote não está completo.

Versão do Assembly

A versão do assembly é o que o CLR, em tempo de execução, usa para selecionar qual versão de um assembly deve carregar. A seleção de um assembly usando versionamento só se aplica a assemblies com um nome forte.

<AssemblyVersion>1.0.0.0</AssemblyVersion>

O CLR do .NET Framework exige uma correspondência exata para carregar um assembly de nome forte. Por exemplo, Library1, Version=1.0.0.0 foi compilado com uma referência a Newtonsoft.Json, Version=11.0.0.0. O .NET Framework só carregará essa versão exata 11.0.0.0. Para carregar uma versão diferente em tempo de execução, um redirecionamento de vinculação deve ser adicionado ao arquivo de configuração do aplicativo .NET.

A nomenclatura forte combinada com a versão de montagem permite carregamento rigoroso da versão de montagem. Embora atribuir um nome forte a uma biblioteca tenha vários benefícios, normalmente resulta em exceções em tempo de execução que ocorrem quando um assembly não pode ser encontrado, exigindo que os redirecionamentos de vinculação em, app.config ou web.config sejam corrigidos. No .NET (Core), o carregamento do assembly é mais relaxado. Durante a execução, o runtime do .NET (Core) carrega automaticamente assemblies com uma versão superior.

✔️ CONSIDERE incluir apenas uma versão principal no AssemblyVersion.

Por exemplo, a Biblioteca 1.0 e a Biblioteca 1.0.1 têm AssemblyVersion de 1.0.0.0, enquanto a Biblioteca 2.0 tem AssemblyVersion de 2.0.0.0. Quando a versão de montagem muda com menos frequência, isso diminui os redirecionamentos de vinculação.

✔️ CONSIDERE manter o número da versão principal do AssemblyVersion e a versão do pacote NuGet sincronizados.

O AssemblyVersion é incluído em algumas mensagens informativas exibidas para o utilizador, por exemplo, o nome do assembly e os nomes de tipos qualificados do assembly em mensagens de exceção. Manter uma relação entre as versões fornece mais informações aos desenvolvedores sobre qual versão eles estão usando.

❌ NÃO tem um AssemblyVersion fixo.

Embora uma "AssemblyVersion" inalterável evite a necessidade de redirecionamentos de ligações, isso significa que apenas uma única versão do assembly pode ser instalada na Cache de Assemblagem Global (GAC). Além disso, as aplicações que fazem referência ao assembly no GAC serão interrompidas se outra aplicação atualizar o assembly no GAC com alterações que causam problemas.

Versão do arquivo de montagem

A versão do arquivo assembly é usada para exibir uma versão do arquivo no Windows e não tem efeito sobre o comportamento em tempo de execução. A configuração desta versão é opcional. É visível na caixa de diálogo Propriedades do ficheiro no Explorador do Windows:

<FileVersion>11.0.2.21924</FileVersion>

✔️ Considere incluir um número de compilação de integração contínua como a revisão do AssemblyFileVersion.

Por exemplo, você está criando a versão 1.0.0 do seu projeto e o número de compilação de integração contínua é 99, portanto, seu AssemblyFileVersion é 1.0.0.99.

✔️ USE o formato Major.Minor.Build.Revision para a versão do arquivo.

Embora a versão do arquivo nunca seja usada pelo .NET, o Windows espera que a versão do arquivo esteja no formato Major.Minor.Build.Revision. Um aviso será gerado se a versão não seguir esse formato.

Versão informativa da montagem

A versão informativa do assembly é usada para registrar informações de versão adicionais e não tem efeito sobre o comportamento do tempo de execução. A configuração desta versão é opcional. Se você estiver usando o Link de origem, essa versão será definida na compilação com a versão do pacote NuGet mais uma versão de controle do código-fonte. Por exemplo, 1.0.0-beta1+204ff0a inclui o hash commit do código-fonte a partir do qual o assembly foi criado. Para obter mais informações, consulte Link de origem.

<InformationalVersion>The quick brown fox jumped over the lazy dog.</InformationalVersion>

Observação

Versões mais antigas do Visual Studio geram um aviso de compilação se esta versão não seguir o formato Major.Minor.Build.Revision. O aviso pode ser ignorado com segurança.

❌ EVITE definir você mesmo a versão informativa do assembly.

Permita que o SourceLink gere automaticamente a versão que contém o NuGet e os metadados de controle do código-fonte.

AnteriorPróximo