Como adicionar Source Link num pacote NuGet
Neste artigo, exploro em detalhes como adicionar suporte ao Source Link em uma biblioteca publicada no NuGet.
Como pudemos ver no artigo anterior, o Source Link é uma tecnologia que visa prover uma grande experiência de depuração para binários .NET e que facilita muito a vida dos desenvolvedores na hora de resolver problemas.
Neste artigo, veremos como adicionar suporte ao Source Link nas nossas bibliotecas.
#Como adicionar Source Link num assembly
O primeiro passo para adicionar suporte ao Source Link nos nossos assemblies é instalar o pacote Source Link do provedor de controle de versão que você utiliza no seu projeto.
Para fins de exemplo neste artigo, vou utilizar a minha biblioteca ForeverFactory, que está hospedada no GitHub. Para uma lista completa dos provedores suportados, consulte o repositório do Source Link.
Assim, você pode instalar o SourceLink adicionando a seguinte referência no seu projeto:
É de suma importância que a propriedade PrivateAssets seja definida como all para o Source Link funcionar.
Feito isso, precisamos configurar no arquivo do projeto como será feita a geração dos pacotes de símbolos.
- Define a URL do repositório que será incluída nos metadados do pacote de símbolos
- Instrui o o sistema de build a embarcar arquivos que participaram do build, mas não são rastreados pelo controle de versão
- Instrui o sistema de build a gerar um pacote de símbolos, além do pacote com os binários
- Define o formato do pacote de símbolos como
snupkg
Com essas configurações feitas, podemos gerar um pacote localmente com os seguintes comandos:
Com este comando dotnet pack, geramos nosso pacote NuGet no diretório nuget-package, como podemos ver na imagem a seguir:
#Como validar pacotes NuGet usando NGPE
Antes de publicar nosso pacote, podemos validá-lo com a ferramenta NuGet Package Explorer (NGPE).
Com o NGPE, podemos confirmar que os metadados necessários foram embarcados no pacote:
- O conteúdo do pacote, com os binários, ícone do projeto e XMLs de documentação
- Na seção Repository, encontramos a URL do repositório, e o commit atual
- Na seção Health, a ferramenta nos indica dois problemas:
- O pacote foi gerado a partir de um build não-determístico
- Há flags do compilador faltando
Voltaremos a tratar desses dois pontos mais adiante no artigo. Vamos agora verificar o que contém o pacote de símbolos gerado:
Como podemos verificar no arquivo, o pacote de símbolos contém os arquivos PDB para depuração, além dos metadados associando repositório e commit ao pacote.
#Configurando builds determinísticos
Por padrão, os builds do .NET são indeterminísticos. Isso significa que cada build gera binários e símbolos ligeiramente diferentes de builds anteriores.
Eles são diferentes porque incluem metadados acerca da máquina que executou o build, timestamp, entre outros, localização dos arquivos na máquina e muito mais. Essas informações servem principalmente para facilitar a depuração local desses binários.
Isso é um problema para um pacote NuGet publicado porque não é possível garantir que este pacote é o que diz ser.
A recomendação nesse caso, é fazer com que o build que publica o pacote nos servidores do NuGet, executado num pipeline de CI, execute builds determinísticos.
Esta configuração é feita através da
- Instrui o sisema de build a utilizar builds determinísticos sempre que possível
- Determina que o build foi realizado num pipeline de integração contínua. Note que esta propriedade só é definida como
truese o build for executado num workflow do GitHub Actions, conforme definido pela variável de ambienteGITHUB_ACTIONSestiver definida comotrue
Conforme explicado neste repositório, builds determinísticos só acontecem em builds de integração contínua.
Podemos simular um build de CI localmente com o seguinte comando:
Abrindo este novo build no NGPE, podemos verificar que este novo pacote foi gerado com um build determinístico.
A próxima etapa, é realizar a publicação do pacote. Para fins de exemplo, compartilho a seguir o pipeline de release do meu projeto ForeverFactory:
- Quando publicamos os arquivos
.nupkg, o CLI do NuGet identifica a presença dos pacotes de símbolos.snpkge publica eles também
A primeira coisa que precisamos confirmar, é se os símbolos estão sendo publicados corretamente no feed do projeto no NuGet.org:
Por fim, podemos validar o pacote publicado usando o NGPE. Para isso, basta abrir o pacote a partir do feed usando a opção File -> Open from Feed...:
#Conclusão
Seguindo estes passos, habilitamos o Source Link na nossa biblioteca, tornando-a muito mais fácil de depurar, e tornando mais fácil a vida dos usuários.