NuGet

O NuGet é um gerenciador de pacotes para o ecossistema do .NET e é a principal maneira de os desenvolvedores descobrirem e adquirirem bibliotecas de software livre do .NET. NuGet.org, um serviço gratuito fornecido pela Microsoft para hospedar pacotes NuGet, é o host principal para pacotes NuGet públicos, mas você pode publicar em serviços NuGet personalizados, como Do MyGet e do Azure Artifacts.

Criar um pacote NuGet

Um pacote NuGet (*.nupkg) é um arquivo zip que contém assemblies .NET e metadados associados.

Há duas maneiras principais de criar um pacote NuGet. A maneira mais recente e recomendada é criar um pacote a partir de um projeto no estilo SDK (arquivo de projeto cujo conteúdo começa com <Project Sdk="Microsoft.NET.Sdk">). Assemblies e destinos são automaticamente adicionados ao pacote e o restante dos metadados é adicionado ao arquivo MSBuild, como o número de versão e o nome do pacote. Compilar com o comando dotnet pack gera um arquivo *.nupkg em vez de assemblies.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <AssemblyName>Contoso.Api</AssemblyName>
    <PackageVersion>1.1.0</PackageVersion>
    <Authors>John Doe</Authors>
  </PropertyGroup>
</Project>

A maneira mais antiga de criar um pacote NuGet é com um arquivo *.nuspec e a ferramenta de linha de comando nuget.exe. Um arquivo nuspec oferece um ótimo controle, mas você deve especificar cuidadosamente quais assemblies e alvos incluir no pacote NuGet final. É fácil cometer um erro ou alguém esquecer de atualizar o nuspec ao fazer alterações. A vantagem de um nuspec é que você pode usá-lo para criar pacotes NuGet para estruturas que ainda não dão suporte a um arquivo de projeto no estilo SDK.

✔️ CONSIDERE o uso de um arquivo de projeto no estilo SDK para criar o pacote NuGet.

Dependências do pacote

Dependências de pacotes NuGet são abordadas detalhadamente no artigo Dependências.

Metadados importantes do pacote NuGet

Um pacote NuGet dá suporte a muitas propriedades de metadados . A tabela a seguir contém os metadados principais que cada pacote no NuGet.org deve fornecer:

✔️ CONSIDERE escolher um nome de pacote NuGet com um prefixo que atenda aos critérios de reserva de prefixo do NuGet .

✔️ FAÇA uso de um href HTTPS com o ícone do pacote.

Sites como NuGet.org executados com HTTPS habilitado e exibindo uma imagem não HTTPS criarão um aviso de conteúdo misto.

✔️ Use uma imagem de ícone de pacote que seja 64x64 e tenha uma tela de fundo transparente para obter melhores resultados de exibição.

✔️ CONSIDERE a configuração do Source Link para adicionar metadados de controle do código-fonte aos assemblies e ao pacote NuGet.

O Source Link adiciona automaticamente as metadados RepositoryUrl e RepositoryType ao pacote NuGet. O Link de Origem também adiciona informações sobre o código-fonte exato do qual o pacote foi criado. Por exemplo, um pacote criado a partir de um repositório Git terá o hash de confirmação adicionado como metadados.

Pacotes de pré-lançamento

Pacotes do NuGet com um sufixo de versão são considerados pré-lançamento. Por padrão, a interface do usuário do Gerenciador de Pacotes NuGet mostra versões estáveis, a menos que um usuário opte por pré-lançamento de pacotes, tornando os pacotes de pré-lançamento ideais para testes de usuário limitados.

<PackageVersion>1.0.1-beta1</PackageVersion>

✔️ FAÇA a publicação de um pacote de pré-lançamento ao testar, visualizar ou experimentar.

✔️ Publique um pacote estável quando estiver pronto para que outros pacotes estáveis possam referenciá-lo.

Pacotes de símbolos

Arquivos de símbolo (*.pdb) são produzidos pelo compilador do .NET junto com assemblies. Os arquivos de símbolo mapeiam os locais de execução para o código-fonte original, permitindo que você navegue pelo código-fonte enquanto ele está em execução com a ajuda de um depurador. O NuGet é compatível com a geração de um pacote de símbolos separado (*.snupkg) contendo arquivos de símbolo junto com o pacote principal contendo assemblies do .NET. A ideia dos pacotes de símbolos é que eles são hospedados em um servidor de símbolos e são baixados apenas por uma ferramenta como o Visual Studio sob demanda.

O NuGet.org hospeda seu próprio repositório do servidor de símbolos. Os desenvolvedores podem usar os símbolos publicados no servidor de símbolos NuGet.org adicionando https://symbols.nuget.org/download/symbols às fontes de símbolo no Visual Studio.

Uma alternativa para criar um pacote de símbolos é inserir arquivos de símbolo no pacote NuGet principal. O pacote NuGet principal será maior, mas os arquivos de símbolo inseridos significam que os desenvolvedores não precisam configurar o servidor de símbolos NuGet.org. Se estiver criando seu pacote NuGet usando um projeto no estilo SDK, você poderá inserir arquivos de símbolo definindo a propriedade AllowedOutputExtensionsInPackageBuildOutputFolder:

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
    <!-- Include symbol files (*.pdb) in the built .nupkg -->
    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
  </PropertyGroup>
</Project>

A desvantagem de inserir arquivos de símbolo é que eles aumentam o tamanho do pacote em cerca de 30% para bibliotecas .NET compiladas usando projetos no estilo SDK. Se o tamanho do pacote é uma preocupação, você deve publicar símbolos em um pacote de símbolos em vez disso.

✔️ CONSIDERE publicar símbolos como um pacote de símbolos (*.snupkg) no NuGet.org

Os pacotes de símbolos (*.snupkg) fornecem aos desenvolvedores uma boa experiência de depuração sob demanda sem aumentar o tamanho do pacote principal e impactar o desempenho de restauração para aqueles que não pretendem depurar o pacote NuGet.

A ressalva é que os usuários talvez precisem localizar e configurar o servidor de símbolos NuGet em seu IDE (como uma configuração única) para obter arquivos de símbolo. O Visual Studio 2019 versão 16.1 adicionou o servidor de símbolos do NuGet.org à lista de servidores de símbolos padrão.