NuGet

Artigo
03/13/2024

O NuGet é um gerenciador de pacotes para o ecossistema .NET e é a principal maneira pela qual os desenvolvedores descobrem e adquirem bibliotecas de código aberto .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 MyGet e 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 adicionados automaticamente ao pacote e os metadados restantes são adicionados ao arquivo MSBuild, como nome do pacote e número da versão. A compilação com o dotnet pack comando gera um *.nupkg arquivo 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 *.nuspec arquivo e a nuget.exe ferramenta de linha de comando. Um arquivo nuspec oferece grande controle, mas você deve especificar cuidadosamente quais assemblies e destinos devem ser incluídos 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 suportam um arquivo de projeto no estilo SDK.

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

Dependências do pacote

As dependências do pacote NuGet são abordadas em detalhes no artigo Dependências .

Metadados importantes do pacote NuGet

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

Nome da propriedade MSBuild	Nome Nuspec	Description
`PackageId`	`id`	O identificador do pacote. Um prefixo do identificador pode ser reservado se atender aos critérios.
`PackageVersion`	`version`	Versão do pacote NuGet. Para obter mais informações, consulte Versão do pacote NuGet.
`Title`	`title`	Um título do pacote amigo do ser humano. O padrão é o `PackageId`.
`Description`	`description`	Uma longa descrição do pacote exibido na interface do usuário.
`Authors`	`authors`	Uma lista separada por vírgulas de autores de pacotes, correspondentes aos nomes de perfil em nuget.org.
`PackageTags`	`tags`	Uma lista delimitada por ponto e vírgula ou ponto e vírgula de tags e palavras-chave que descrevem o pacote. As tags são usadas ao pesquisar pacotes.
`PackageIcon`	`icon`	Um caminho para uma imagem no pacote para usar como um ícone de pacote. Leia mais sobre `icon` metadados.
`PackageProjectUrl`	`projectUrl`	Um URL para a página inicial do projeto ou repositório de origem.
`PackageLicenseExpression`	`license`	O identificador SPDX da licença do projeto. Somente licenças aprovadas pela OSI e FSF podem usar um identificador. Outras licenças devem usar `PackageLicenseFile`o . Leia mais sobre `license` metadados.

Importante

Um projeto sem uma licença tem direitos autorais exclusivos, tornando legalmente impossível para outras pessoas usarem.

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

✔️ USE um HTTPS href para o ícone do pacote.

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

✔️ USE uma imagem de ícone de pacote que seja 64x64 e tenha um fundo transparente para melhores resultados de visualização.

✔️ CONSIDERE configurar o Link de origem para adicionar metadados de controle de origem aos seus assemblies e ao pacote NuGet.

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

Pacotes de pré-lançamento

Os pacotes 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 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>

Nota

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

NuGet pre-release package dependency

✔️ PUBLIQUE 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 fazer referência a ele.

Pacotes de símbolos

Os arquivos de símbolo (*.pdb) são produzidos pelo compilador .NET junto com assemblies. Os arquivos de símbolo mapeiam locais de execução para o código-fonte original para que você possa percorrer o código-fonte enquanto ele está sendo executado usando um depurador. O NuGet oferece suporte à geração de um pacote de símbolos separado (*.snupkg) contendo arquivos de símbolos ao lado do pacote principal que contém assemblies .NET. A ideia dos pacotes de símbolos é que eles são hospedados em um servidor de símbolos e só são baixados por uma ferramenta como o Visual Studio on demand.

NuGet.org hospeda seu próprio repositório de servidores 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 suas fontes de símbolos no Visual Studio.

Importante

O servidor de símbolos NuGet.org suporta apenas os novos arquivos de símbolos portáteis (*.pdb) criados por projetos no estilo SDK.

Para usar o servidor de símbolos NuGet.org ao depurar uma biblioteca .NET, os desenvolvedores devem ter o Visual Studio 2017 versão 15.9 ou posterior.

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

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

A desvantagem de incorporar 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 for um problema, você deve publicar símbolos em um pacote de símbolos.

✔️ CONSIDERE a publicação de símbolos como um pacote de símbolos (*.snupkg) para NuGet.org

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

A ressalva é que os usuários podem precisar 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.

Anterior Seguinte

Partilhar via