Uma introdução ao NuGet

Uma ferramenta essencial para qualquer plataforma de desenvolvimento moderna é um mecanismo através do qual os desenvolvedores podem criar, compartilhar e consumir código útil. Muitas vezes, esse código é empacotado em "pacotes" que contêm código compilado (como DLLs) juntamente com outro conteúdo necessário nos projetos que consomem esses pacotes.

Para o .NET (incluindo o .NET Core), o mecanismo suportado pela Microsoft para compartilhar código é NuGet, que define como os pacotes para .NET são criados, hospedados e consumidos, e fornece as ferramentas para cada uma dessas funções.

Simplificando, um pacote NuGet é um único arquivo ZIP com a extensão .nupkg que contém código compilado (DLLs), outros arquivos relacionados a esse código e um manifesto descritivo que inclui informações como o número da versão do pacote. Desenvolvedores com código para compartilhar criam pacotes e os publicam em um host público ou privado. Os utilizadores de pacotes obtêm esses pacotes de hosts adequados, adicionam-nos aos seus projetos e, em seguida, chamam a funcionalidade de um pacote no seu código de projeto. O próprio NuGet lida com todos os detalhes intermediários.

Como o NuGet oferece suporte a hosts privados ao lado do host nuget.org público, você pode usar pacotes NuGet para compartilhar código exclusivo de uma organização ou grupo de trabalho. Você também pode usar pacotes NuGet como uma maneira conveniente de estruturar o seu próprio código para uso apenas nos seus próprios projetos. Em resumo, um pacote NuGet é uma unidade de código compartilhável, mas não requer nem implica nenhum meio específico de compartilhamento.

O fluxo de pacotes entre criadores, anfitriões e consumidores

Em seu papel como um host público, o próprio NuGet mantém o repositório central de mais de 100.000 pacotes exclusivos em nuget.org. Esses pacotes são empregados por milhões de desenvolvedores do .NET/.NET Core todos os dias. O NuGet também permite que você hospede pacotes de forma privada na nuvem (como no Azure DevOps), em uma rede privada ou até mesmo apenas em seu sistema de arquivos local. Ao fazer isso, esses pacotes estão disponíveis apenas para os desenvolvedores que têm acesso ao host, dando-lhe a capacidade de disponibilizar pacotes para um grupo específico de consumidores. As opções são explicadas em Hospedar seus próprios feeds NuGet. Através de opções de configuração, você também pode controlar exatamente quais hosts podem ser acessados por qualquer computador, garantindo assim que os pacotes sejam obtidos de fontes específicas, em vez de um repositório público como nuget.org.

Seja qual for a sua natureza, um host serve como ponto de conexão entre os criadores de pacotes e os consumidores de pacotes . Os criadores criam pacotes NuGet úteis e os publicam em um host. Em seguida, os consumidores procuram pacotes úteis e compatíveis em anfitriões acessíveis, descarregando e incluindo esses pacotes nos seus projetos. Uma vez instalado em um projeto, as APIs dos pacotes ficam disponíveis para o restante do código do projeto.

Compatibilidade de direcionamento de pacotes

Um pacote "compatível" significa que contém assemblies criados para pelo menos um .NET Framework de destino que seja compatível com o .NET Framework alvo do projeto consumidor. Os desenvolvedores podem criar pacotes específicos para uma estrutura, como com controles UWP, ou podem oferecer suporte a uma gama mais ampla de destinos. Para maximizar a compatibilidade de um pacote, os desenvolvedores visam o .NET Standard , que todos os projetos .NET e .NET Core podem consumir. Este é o meio mais eficiente para criadores e consumidores, pois um único pacote (geralmente contendo uma única montagem) funciona para todos os projetos que consomem.

Os desenvolvedores de pacotes que exigem APIs fora do .NET Standard, por outro lado, criam assemblies separados para as diferentes estruturas de destino que desejam suportar e incluem todos esses assemblies no mesmo pacote (que é chamado de "multi-targeting"). Quando um consumidor instala esse pacote, o NuGet extrai apenas os assemblies necessários para o projeto. Isso minimiza o impacto do pacote na aplicação final e/ou nos componentes produzidos por esse projeto. Um pacote multialvo é, naturalmente, mais difícil de manter para o seu criador.

Observação

Para obter orientação sobre componentes de aplicativo versus bibliotecas reutilizáveis, consulte a documentação do .NET Standard no tópico.

Ferramentas NuGet

Além do suporte à hospedagem, o NuGet também fornece uma variedade de ferramentas usadas por criadores e consumidores. Consulte Instalando ferramentas de cliente NuGet para obter ferramentas específicas.

Ferramenta	Plataformas	Cenários aplicáveis	Descrição
da CLI dotnet	Tudo	Criação, Consumo	Ferramenta CLI para bibliotecas .NET Core e .NET Standard e para projetos no estilo SDK destinados ao .NET Framework (consulte atributo SDK). Fornece determinados recursos da CLI do NuGet diretamente na cadeia de ferramentas do .NET Core. Como com a CLI nuget.exe, a CLI dotnet não interage com projetos do Visual Studio.
nuget.exe CLI	Tudo	Criação, Consumo	Ferramenta CLI para bibliotecas do .NET Framework e projetos não no estilo SDK destinados a bibliotecas .NET Standard. Fornece todos os recursos do NuGet, com alguns comandos se aplicando especificamente aos criadores de pacotes, alguns se aplicando apenas aos consumidores e outros se aplicando a ambos. Por exemplo, os criadores de pacotes usam o comando nuget pack para criar um pacote a partir de vários assemblies e arquivos relacionados, os consumidores de pacotes usam nuget install para incluir pacotes em uma pasta de projeto e todos usam nuget config para definir variáveis de configuração do NuGet. Como uma ferramenta independente de plataforma, a CLI do NuGet não interage com projetos do Visual Studio.
Consola do Gestor de Pacotes	Visual Studio para Windows	Consumo	Fornece comandos PowerShell para instalar e gerenciar pacotes em projetos do Visual Studio.
da interface do usuário do Gerenciador de Pacotes	Visual Studio em Windows	Consumo	Fornece uma interface do usuário fácil de usar para instalar e gerenciar pacotes em projetos do Visual Studio.
Gerir a Interface de Utilizador do NuGet	Visual Studio para Mac	Consumo	Forneça uma interface do usuário fácil de usar para instalar e gerenciar pacotes em projetos do Visual Studio para Mac.
MSBuild	Windows	Criação, Consumo	Fornece a capacidade de criar pacotes e restaurar pacotes usados em um projeto diretamente através da cadeia de ferramentas MSBuild.

Como você pode ver, as ferramentas do NuGet com as quais você trabalha dependem muito se você está criando, consumindo ou publicando pacotes e da plataforma na qual está trabalhando. Normalmente, os criadores de pacotes também são consumidores, pois se baseiam na funcionalidade existente em outros pacotes NuGet. E esses pacotes, é claro, podem, por sua vez, depender de outros ainda.

Para obter mais informações, comece com os artigos fluxo de trabalho de criação de pacotes e fluxo de trabalho de consumo de pacotes.

Gerenciando dependências

A capacidade de construir facilmente sobre o trabalho de outros é um dos recursos mais poderosos de um sistema de gerenciamento de pacotes. Assim, muito do que o NuGet faz é gerenciar essa árvore de dependência ou "gráfico" em nome de um projeto. Simplesmente dito, você só precisa se preocupar com os pacotes que você está usando diretamente em um projeto. Se qualquer um desses pacotes consumir outros pacotes (que, por sua vez, podem consumir ainda outros), o NuGet cuidará de todas essas dependências de nível inferior.

A imagem a seguir mostra um projeto que depende de cinco pacotes, que por sua vez dependem de vários outros.

Observe que alguns pacotes aparecem várias vezes no gráfico de dependência. Por exemplo, existem três consumidores diferentes do pacote B, e cada consumidor também pode especificar uma versão diferente para esse pacote (não mostrada). Esta é uma ocorrência comum, especialmente para embalagens amplamente utilizadas. O NuGet, felizmente, faz todo o trabalho duro para determinar exatamente qual versão do pacote B satisfaz todos os consumidores. Em seguida, o NuGet faz o mesmo para todos os outros pacotes, independentemente da profundidade do gráfico de dependência.

Para obter mais detalhes sobre como o NuGet executa esse serviço, consulte Resolução de dependência.

Rastreando referências e restaurando pacotes

Como os projetos podem mover-se facilmente entre computadores de programadores, repositórios de controlo de versão, servidores de compilação e assim por diante, é altamente impraticável manter os assemblies binários de pacotes NuGet diretamente vinculados a um projeto. Isso tornaria cada cópia do projeto desnecessariamente inchada (e, portanto, desperdiçaria espaço nos repositórios de controle do código-fonte). Isso também tornaria muito difícil atualizar binários de pacote para versões mais recentes, pois as atualizações teriam que ser aplicadas em todas as cópias do projeto.

Em vez disso, o NuGet mantém uma lista de referência simples dos pacotes dos quais um projeto depende, incluindo dependências de nível superior e inferior. Ou seja, sempre que você instala um pacote de algum host em um projeto, o NuGet registra o identificador do pacote e o número da versão na lista de referência. (A desinstalação de um pacote, é claro, o remove da lista.) Em seguida, o NuGet fornece um meio de restaurar todos os pacotes referenciados mediante solicitação, conforme descrito em de restauração de pacotes.

Com apenas a lista de referência, o NuGet pode reinstalar, ou seja, restaurar , todos esses pacotes de hosts públicos e/ou privados a qualquer momento. Ao submeter um projeto para controlo de código fonte ou compartilhá-lo de outra forma, incluis apenas a lista de referências e excluis quaisquer binários do pacote (ver Pacotes e controlo de código fonte).

O computador que recebe um projeto, como um servidor de compilação que obtém uma cópia do projeto como parte de um sistema de implantação automatizado, simplesmente solicita ao NuGet para restaurar dependências sempre que necessário. Sistemas de compilação como o Azure DevOps fornecem etapas de "restauração do NuGet" para essa finalidade exata. Da mesma forma, quando os desenvolvedores obtêm uma cópia de um projeto (como ao clonar um repositório), eles podem invocar comandos como nuget restore (NuGet CLI), dotnet restore (dotnet CLI) ou Install-Package (Console do Gerenciador de Pacotes) para obter todos os pacotes necessários. O Visual Studio, por sua vez, restaura automaticamente os pacotes ao criar um projeto (desde que a restauração automática esteja ativada, conforme descrito em de restauração de pacotes).

Claramente, então, a principal função do NuGet no que diz respeito aos desenvolvedores é manter essa lista de referência em nome do seu projeto e fornecer os meios para restaurar (e atualizar) eficientemente esses pacotes referenciados. Essa lista é mantida num dos dois formatos de gestão de pacotes, como são chamados:

• PackageReference (ou "referências de pacote em arquivos de projeto") | (NuGet 4.0+) Mantém uma lista das dependências de nível superior de um projeto diretamente no arquivo de projeto, portanto, nenhum arquivo separado é necessário. Um arquivo associado, obj/project.assets.json, é gerado dinamicamente para gerenciar o gráfico de dependência geral dos pacotes que um projeto usa junto com todas as dependências de nível inferior. PackageReference é sempre usado por projetos .NET Core.

• packages.config: (NuGet 1.0+) Um arquivo XML que mantém uma lista simples de todas as dependências no projeto, incluindo as dependências de outros pacotes instalados. Os pacotes instalados ou restaurados são armazenados em uma pasta packages.

O formato de gerenciamento de pacotes empregado em qualquer projeto depende do tipo de projeto e da versão disponível do NuGet (e/ou Visual Studio). Para verificar qual formato está sendo usado, basta procurar packages.config na raiz do projeto depois de instalar seu primeiro pacote. Se não tiver esse ficheiro, procure diretamente no ficheiro de projeto por um elemento <PackageReference>.

Quando você tiver uma escolha, recomendamos o uso de PackageReference. packages.config é mantido para fins de legado e não está mais em desenvolvimento ativo.

Dica

Vários comandos nuget.exe da CLI, como nuget install, não adicionam automaticamente o pacote à lista de referência. A lista é atualizada ao instalar um pacote com o Gerenciador de Pacotes do Visual Studio (UI ou Console) e com dotnet.exe CLI.

O que mais o NuGet faz?

Até agora você aprendeu as seguintes características do NuGet:

• O NuGet fornece ao repositório nuget.org central suporte para hospedagem privada.
• O NuGet fornece as ferramentas que os desenvolvedores precisam para criar, publicar e consumir pacotes.
• Mais importante ainda, o NuGet mantém uma lista de referência de pacotes usados em um projeto e a capacidade de restaurar e atualizar esses pacotes a partir dessa lista.

Para que esses processos funcionem de forma eficiente, o NuGet faz algumas otimizações nos bastidores. Mais notavelmente, o NuGet gerencia um cache de pacotes e uma pasta de pacotes globais para atalho de instalação e reinstalação. O cache evita o download de um pacote que já foi instalado na máquina. A pasta de pacotes globais permite que vários projetos compartilhem o mesmo pacote instalado, reduzindo assim a pegada geral do NuGet no computador. O cache e a pasta de pacotes globais também são muito úteis quando você está frequentemente restaurando um número maior de pacotes, como em um servidor de compilação. Para obter mais detalhes sobre esses mecanismos, consulte Gerenciando os pacotes globais e as pastas de cache.

Dentro de um projeto individual, o NuGet gerencia o gráfico de dependência geral, que novamente inclui a resolução de várias referências a diferentes versões do mesmo pacote. É bastante comum que um projeto dependa de um ou mais pacotes que tenham as mesmas dependências. Alguns dos pacotes de utilitários mais úteis no nuget.org são empregados por muitos outros pacotes. Em todo o gráfico de dependência, então, você poderia facilmente ter dez referências diferentes para diferentes versões do mesmo pacote. Para evitar trazer várias versões desse pacote para o próprio aplicativo, o NuGet classifica qual versão única pode ser usada por todos os consumidores. (Para obter mais informações, consulte Resolução de dependência.)

Além disso, o NuGet mantém todas as especificações relacionadas a como os pacotes são estruturados (incluindo de localização e símbolos de depuração) e como eles são referenciados (incluindo intervalos de versões e versões de pré-lançamento.) O NuGet também fornece várias APIs para trabalhar com seus serviços programaticamente e fornece suporte para desenvolvedores que escrevem extensões do Visual Studio e modelos de projeto.

Reserve um momento para navegar pelo sumário desta documentação e você verá todos esses recursos representados lá, juntamente com notas de versão que remontam aos primórdios do NuGet.

Vídeo relacionado

Encontre vídeos do NuGet no Canal 9 e YouTube.

Comentários, contribuições e questões

Finalmente, agradecemos muito os comentários e contribuições para esta documentação — basta selecionar as opções Feedback e Editar no topo de qualquer página, ou visitar o repositório de documentação e a lista de problemas da documentação no GitHub.

Também aceitamos contribuições para o próprio NuGet através dos seus vários repositórios GitHub; os problemas do NuGet podem ser encontrados em https://github.com/NuGet/home/issues.

Aproveite a sua experiência NuGet!