NuGet

O NuGet é um gerenciador de pacotes para o ecossistema do .NET e é a principal maneira como os desenvolvedores descobrem e adquirem bibliotecas de código-fonte aberto do .NET. O NuGet.org, um serviço gratuito fornecido pela Microsoft para hospedar pacotes do NuGet, é o host primário para os pacotes públicos do NuGet, mas você pode publicar em serviços personalizados do NuGet, como MyGet e Azure Artifacts.

Criar um pacote NuGet

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

Há duas maneiras principais de criar um pacote do NuGet. A maneira recomendada e mais recente é criar um pacote de um projeto no estilo do 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 do NuGet é com um arquivo *.nuspec e a ferramenta de linha de comando nuget.exe. Um arquivo nuspec dá excelente controle, mas você deve especificar com cuidado quais assemblies e destinos incluir no pacote final do NuGet. É fácil cometer um erro ou alguém se esquecer de atualizar o nuspec ao fazer alterações. A vantagem de um nuspec é que você pode usá-lo criar pacotes do NuGet para estruturas que ainda não dão suporte a um arquivo de projeto de estilo do SDK.

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

Dependências do pacote

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

Metadados de pacote do NuGet importantes

Um pacote do NuGet dá suporte a muitas propriedades de metadados. A seguinte tabela contém os principais metadados que todo projeto do NuGet.org deve fornecer:

Nome da Propriedade do MSBuild	Nome Nuspec	Descrição
PackageId	id	O identificador de pacote. Um prefixo do identificador poderá ser reservado se ele cumprir os critérios.
PackageVersion	version	Versão do pacote NuGet. Para obter mais informações, veja Controle de versão de pacote do NuGet.
Title	title	Um título amigável a humanos do pacote. Usa como padrão PackageId.
Description	description	Uma descrição longa do pacote exibida na interface do usuário.
Authors	authors	Uma lista separada por vírgulas de autores de pacote que correspondem aos nomes de perfil em nuget.org.
PackageTags	tags	Uma lista delimitada por espaço ou ponto e vírgula de marcas e palavras-chave que descrevem o pacote. Marcas são usadas ao pesquisar pacotes.
PackageIcon	icon	Um caminho para uma imagem no pacote a ser usado como um ícone de pacote. Leia mais sobre icon metadados.
PackageProjectUrl	projectUrl	Uma URL para o repositório de origem ou página inicial do projeto.
PackageLicenseExpression	license	O identificador SPDX da licença de projeto. Somente licenças aprovadas por OSI e FSF podem usar um identificador. Outras licenças devem usar PackageLicenseFile. Leia mais sobre license metadados.

Importante

Um projeto sem uma licença usa como padrão direitos autorais exclusivos, tornando legalmente impossível seu uso por outras pessoas.

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

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

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

✔️ FAÇA uso de uma imagem de ícone do pacote de 64 x 64 e com um segundo plano transparente para melhor visualização dos resultados.

✔️ 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 os metadados RepositoryUrl e RepositoryType ao pacote NuGet. O Source Link também adiciona informações sobre o código-fonte exato do qual o pacote foi criado. Por exemplo, um pacote criado 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 do NuGet mostra versões estáveis, a menos que um usuário aceite pacotes de pré-lançamento, tornando os pacotes de pré-lançamento ideais para testes de usuários limitados.

<PackageVersion>1.0.1-beta1</PackageVersion>

Observação

Um pacote estável não pode depender de um pacote de pré-lançamento. Você deve criar seu próprio pacote de pré-lançamento ou depender de uma versão estável mais antiga.

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

✔️ FAÇA a publicação de um pacote estável quando ele estiver pronto para que outros pacotes estáveis possam fazer referência a ele.

Pacotes de símbolo

Arquivos de símbolo (*.pdb) são produzidos pelo compilador do .NET junto com assemblies. Arquivos de símbolo mapeiam locais de execução para o código-fonte original para que você possa percorrer o código-fonte conforme ele é executado usando 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 de pacotes de símbolos é que eles estão hospedados em um servidor de símbolos e são baixados somente 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 do NuGet.org adicionando https://symbols.nuget.org/download/symbols às suas fontes de símbolos no Visual Studio.

Importante

O servidor de símbolos do NuGet.org é compatível apenas com novos arquivos de símbolo portátil (*.pdb) criados por projetos no estilo de SDK.

Para usar o servidor de símbolos do NuGet.org durante a depuração de uma biblioteca do .NET, os desenvolvedores precisam ter o Visual Studio 2017 versão 15.9 ou posterior.

Uma alternativa para criar um pacote de símbolos é inserir arquivos de símbolo no pacote do NuGet principal. O pacote do NuGet principal será maior, mas os arquivos de símbolos inseridos significam que os desenvolvedores não precisam configurar o servidor de símbolos do NuGet.org. Se você estiver criando seu pacote do NuGet usando um projeto de estilo do SDK, 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 de 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 a possibilidade de publicar símbolos como um pacote de símbolos (*.snupkg) em NuGet.org

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

A limitação é que os usuários podem precisar encontrar e configurar o servidor de símbolos do NuGet no 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ímbolo padrão.

AnteriorAvançar