Compartilhar via

Controle de versão

  • Artigo

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

Alterações da falha

Para obter informações sobre como lidar com quebras de compatibilidade entre versões, consulte Quebras de compatibilidade.

Números de versão

Uma biblioteca .NET tem várias maneiras de especificar uma versão. Essas versões são as mais importantes:

Versão do pacote NuGet

A Versão do pacote NuGet é exibida em NuGet.org e o gerenciador de pacotes do 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 se referirão a ela 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 nenhum efeito sobre o comportamento do runtime.

<PackageVersion>1.0.0-alpha1</PackageVersion>

O identificador do 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 teste. Para obter mais informações, veja pacotes 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 SemVer (Controle de Versão Semântico). O SemVer indica o significado das alterações entre versões e ajuda os desenvolvedores a tomar uma decisão informada ao escolher qual versão usar. Por exemplo, ir de 1.0 para 2.0 indica que potencialmente há alterações interruptivas.

✔️ CONSIDERAR o uso do SemVer 2.0.0 para criar a versão do seu pacote NuGet.

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

✔️ FAÇA a inclusão de um sufixo de pré-lançamento ao liberar um pacote não estável. (Para obter mais informações sobre como marcar APIs como versão prévia 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á concluído.

Versão do assembly

A versão do assembly é o que o CLR usa em tempo de execução para selecionar qual versão de um assembly carregar. Selecionar um assembly usando o controle de versão só se aplica aos assemblies com um nome forte.

<AssemblyVersion>1.0.0.0</AssemblyVersion>

O .NET Framework CLR exige 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 associação deve ser adicionado ao arquivo de configuração do aplicativo .NET.

Nomenclatura forte combinada com a versão do assembly habilita carregamento de versão do assembly estrita. Embora a atribuição de um nome forte a uma biblioteca tenha uma série de benefícios, frequentemente resulta em exceções de tempo de execução em que não é possível encontrar um assembly e exigem redirecionamentos de associações em app.config ou web.config. No .NET (Core), o carregamento de assembly é mais flexível. O runtime do .NET (Core) carrega automaticamente assemblies com uma versão mais alta em tempo de execução.

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

Por exemplo, Biblioteca 1.0 e Biblioteca 1.0.1 têm ambas uma AssemblyVersion de 1.0.0.0, enquanto a Biblioteca 2.0 tem uma AssemblyVersion de 2.0.0.0. Quando a versão do assembly é alterada com menos frequência, ela reduz os redirecionamentos de associação.

✔️ CONSIDERE manter o número de versão principal do AssemblyVersion e a versão do pacote NuGet em sincronia.

A versão do AssemblyVersion é incluída em algumas mensagens informativas exibidas ao usuário, por exemplo, o nome do assembly e os nomes de tipo 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 uma AssemblyVersion fixa.

Embora um AssemblyVersion inalterável evite a necessidade de redirecionamentos de associação, isso significa que apenas uma única versão do assembly pode ser instalada no GAC (Cache de Assembly Global). Além disso, os aplicativos que fazem referência ao assembly no GAC serão interrompidos se outro aplicativo atualizar o assembly do GAC com alterações interruptivas.

Versão do arquivo do assembly

A versão do arquivo de assembly é usada para exibir uma versão de arquivo no Windows e não tem efeito sobre o comportamento em tempo de execução. Definir essa versão é opcional. Ela fica visível na caixa de diálogo Propriedades do Arquivo no Windows Explorer:

<FileVersion>11.0.2.21924</FileVersion>

Windows Explorer Windows Explorer

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

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

✔️ Use o formato Major.Minor.Build.Revision para a versão de arquivo.

Embora a versão do arquivo nunca seja usada pelo .NET, 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 do assembly

A versão informativa do assembly é usada para registrar informações adicionais de versão e não tem nenhum efeito sobre o comportamento do runtime. Definir essa versão é opcional. Se você estiver usando o Source Link, essa versão será definida no build com a versão do pacote NuGet, além de uma versão de controle do código-fonte. Por exemplo, 1.0.0-beta1+204ff0a inclui o hash de commit do código-fonte do qual a assemblagem foi criada. Para obter mais informações, confira Source Link.

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

Nota

Versões mais antigas do Visual Studio geram um aviso de build se essa 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.

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

AnteriorPróximo