Adicionar pacotes ao projeto do .NET

  • 2 minutos

O .NET tem muitas bibliotecas principais que cuidam de tudo, desde o gerenciamento de arquivos até o HTTP e a compactação de arquivos. Também há um enorme ecossistema com bibliotecas de terceiros. É possível usar o NuGet, o Gerenciador de Pacotes do .NET, para instalar essas bibliotecas e usá-las no aplicativo.

O .NET e seu ecossistema usam muito a palavra dependência. Uma dependência de pacote é uma biblioteca de terceiros. É uma parte do código reutilizável que realiza algo e que você deve adicionar ao seu aplicativo. A biblioteca de terceiros é algo de que seu aplicativo depende para funcionar, por isso o uso da palavra dependência.

Você pode pensar na biblioteca de terceiros como um pacote armazenado em um repositório. Um pacote é composto por uma ou mais bibliotecas que podem ser adicionadas ao aplicativo para que você possa aproveitar os recursos delas.

Aqui, vamos nos concentrar nas dependências do pacote. No entanto, um projeto do .NET pode ter outros tipos de dependências além das dependências do pacote. Incluindo frameworks, analisadores, referências do projeto e dependências de projeto compartilhadas.

Determinar se você precisa de um pacote

Como você sabe se precisa de um pacote para seu projeto? Trata-se de uma pergunta complicada que envolve alguns fatores:

  • Como aprimorar o código: considere se você está lidando com uma tarefa como garantir a segurança, por exemplo, e está tentando implementar a autenticação e a autorização. Trata-se de uma tarefa em que você precisa acertar para proteger seus dados e os dados de seus clientes. Há padrões e bibliotecas disponíveis que são usados por vários desenvolvedores. Essas bibliotecas implementam recursos que provavelmente serão sempre necessários, e os problemas serão corrigidos à medida que surgirem. Use essas bibliotecas em vez de criar as suas. Tampouco é provável que você escreva código por conta própria, porque existem tantos casos extremos que você precisa levar em conta.
  • Economizar tempo: você poderia criar por conta própria a maioria das coisas, como bibliotecas de utilitários ou bibliotecas de componentes da interface do usuário, mas isso exige tempo. Mesmo que seus resultados sejam comparáveis ao que está disponível, replicar o trabalho não é um bom uso do seu tempo.
  • Manutenção: todas as bibliotecas e aplicativos precisam de manutenção mais cedo ou mais tarde. Essa manutenção envolve adicionar novos recursos e corrigir bugs. É um bom uso do seu tempo ou do tempo da sua equipe manter uma biblioteca ou é melhor deixar que uma equipe de software de código aberto cuide disso?

Avaliar um pacote

Antes de instalar uma biblioteca, é uma boa ideia verificar em quais dependências ela se baseia. Essas dependências podem encorajar o uso do pacote ou podem deter você. Estes são alguns fatores a considerar ao selecionar uma dependência para seu projeto:

  • Tamanho: o número de dependências pode criar um grande volume. Se você tiver largura de banda limitada ou outras limitações de hardware, esse fato poderá ser uma preocupação.
  • Licenciamento: você precisa verificar se a licença concedida à biblioteca abrange o uso pretendido, seja comercial, pessoal ou acadêmico.
  • Manutenção ativa: Poderá ser um problema se o seu pacote depender de uma dependência que não tenha manutenção ativa. A dependência poderá estar preterida ou não ter sido atualizada há muito tempo.

Saiba mais sobre um pacote antes de instalá-lo acessando https://www.nuget.org/packages/<package name>. Essa URL levará você a uma página detalhada do pacote. Selecione a lista suspensa Dependências para ver de quais pacotes ela depende para funcionar.

O número de dependências listadas pode não revelar toda a verdade. Se baixar um pacote, você poderá se deparar com uma dependência de dezenas de pacotes. Por quê? Cada pacote tem uma lista de dependências. Para garantir que você possa usar um pacote, todas as dependências são rastreadas e baixadas quando você executa o comando dotnet add package <package name>.

Instalar um pacote

Há várias maneiras de instalar pacotes. Há uma linha de comando interna e uma interface gráfica do usuário para o gerenciador de pacotes no Visual Studio e no Visual Studio para Mac. Você pode adicionar manualmente referências de pacote ao arquivo de projeto ou instalá-las por meio de uma ferramenta de CLI (interface de linha de comando), como Paket ou a CLI do .NET Core.

Para este módulo, vamos usar a CLI integrada do .NET Core para instalar pacotes. Você pode adicionar um pacote ao projeto do .NET invocando um comando no terminal. Um comando de instalação típico tem a seguinte aparência: dotnet add package <name of package>. Quando você executa o comando add package, a ferramenta de linha de comando se conecta a um registro global, busca o pacote e o armazena em um local de pasta em cache que todos os projetos podem usar.

Após a instalação e a criação do projeto, as referências são adicionadas às suas pastas de depuração ou de versão. Seu diretório de projeto tem a seguinte aparência:

-| bin/
---| Debug/
------| net3.1
--------| <files included in the dependency>

Localizar um pacote

Os desenvolvedores individuais podem usar o registro global do NuGet.org para localizar e baixar os pacotes necessários para os aplicativos. Uma empresa pode ter uma estratégia em vigor com relação a quais pacotes podem ser usados e onde encontrá-los.

Captura de tela do NuGet.org mostrando uma lista de pacotes populares.

Os pacotes podem estar localizados em muitos lugares diferentes. Algumas dessas fontes podem estar disponíveis publicamente e outras podem ser restritas, disponíveis somente aos funcionários de uma empresa específica. Estes são alguns dos lugares onde os pacotes podem residir:

  • Registros: um exemplo pode ser um registro global, como o registro do NuGet.org. Você pode hospedar seus próprios registros, que podem ser privados ou públicos. Serviços como o GitHub e o Azure DevOps disponibilizam registros privados.
  • Arquivos: você pode instalar um pacote por meio de uma pasta local. A instalação de um pacote é comum quando você está tentando desenvolver suas próprias bibliotecas do .NET e quer testar o pacote localmente. Ou se, por algum motivo, você não quer usar um registro.

Diagrama que ilustra a relação entre criadores de pacote, hosts de pacote e consumidores de pacote.

Registro do NuGet e a ferramenta dotnet

Quando você executa dotnet add package <name of dependency>, o .NET vai para um registro global chamado registro do NuGet.org, localizado em https://nuget.org, e procura o código a ser baixado. Você também poderá procurar pacotes nesta página se visitá-la usando um navegador. Cada pacote tem um site dedicado que você pode acessar.

Captura de tela da página de aterrissagem para um pacote do NuGet.

Nesses sites, é possível saber mais sobre onde reside o código-fonte. Você também pode encontrar informações sobre manutenção e métricas de downloads.

Captura de tela de informações e métricas em um pacote do NuGet.

Comandos .NET

Até o momento, você aprendeu como pode instalar dependências usando a CLI do .NET Core. Mas essa ferramenta pode fazer muito mais que isso.

A CLI do .NET tem uma quantidade razoável de comandos. Os comandos ajudam você com tarefas como instalar pacotes, criar pacotes e inicializar projetos do .NET. Não é necessário conhecer todos os comandos em detalhes. Quando você começa a usar o .NET, é provável que use somente um subconjunto dos comandos. À medida que expandir seu uso do .NET, você poderá usar mais comandos de várias categorias.

Para se lembrar do que os comandos fazem, é útil considerar que eles se dividem em categorias:

  • Gerenciar dependências: os comandos nesta categoria abrangem instalação, remoção, limpeza após a instalação de pacotes, bem como atualização de pacotes.
  • Executar programas: a ferramenta .NET Core pode ajudar você a gerenciar os fluxos no desenvolvimento do aplicativo. Exemplos de fluxos de aplicativo são a execução de testes, a compilação de código e a execução de comandos de migração para atualizar projetos.
  • Criar e publicar pacotes: diversos comandos podem ajudar em tarefas, como criar um pacote compactado e enviá-lo por push a um registro.

Para ver uma lista detalhada com todos os comandos, insira dotnet --help no terminal.

Como instalar um pacote

Use o comando dotnet add package <dependency name> para instalar uma dependência normal destinada a ser usada como parte do seu aplicativo.

Observação

Você pode instalar alguns pacotes globalmente. Esses pacotes não são destinados a serem importados para o projeto. Por esse motivo, muitos pacotes globais são modelos ou ferramentas da CLI. Também é possível instalar essas ferramentas globais por meio de um repositório de pacotes. Instale as ferramentas usando o comando dotnet tool install <name of package>. Instale modelos usando o comando dotnet new -i <name of package>.

Após a instalação

Os pacotes instalados são listados na seção dependencies do seu arquivo .csproj. Para ver exatamente quais pacotes estão na pasta, digite dotnet list package.

Project 'DotNetDependencies' has the following package references
   [net8.0]:
   Top-level Package      Requested   Resolved
   > Humanizer            2.7.9       2.7.9

Este comando lista apenas os pacotes de nível superior e não as dependências deles, que chamamos de pacotes transitivos. Esse comando é bom para dar uma olhada rápida. Se você deseja uma exibição mais detalhada, pode listar todos os pacotes transitivos. Quando você faz isso, o comando list tem a seguinte aparência:

dotnet list package --include-transitive

A inclusão de transitivos permite que você veja as dependências junto com todos os pacotes que você instalou. Se executar dotnet list package --include-transitive, você poderá obter esta saída:

Project 'DotNetDependencies' has the following package references
   [net8.0]:
   Top-level Package      Requested   Resolved
   > Humanizer            2.7.9       2.7.9

   Transitive Package               Resolved
   > Humanizer.Core                 2.7.9
   > Humanizer.Core.af              2.7.9
   > Humanizer.Core.ar              2.7.9
   > Humanizer.Core.bg              2.7.9
   > Humanizer.Core.bn-BD           2.7.9
   > Humanizer.Core.cs              2.7.9
   ...

Restaurar dependências

Quando você cria ou clona um projeto, as dependências incluídas não são baixadas ou instaladas até que você crie o projeto. Você pode restaurar manualmente as dependências, e as ferramentas específicas do projeto que estão especificadas no arquivo do projeto, executando o comando dotnet restore. Na maioria dos casos, não é preciso usar o comando explicitamente. A restauração do NuGet é executada implicitamente, se necessário, quando você executa comandos como new, build e run.

Limpar dependências

É provável que, cedo ou tarde, você se dê conta de que não precisa mais de um pacote. Ou poderá perceber que o pacote que você instalou não é o que você precisa. Talvez você encontre outro pacote que realize melhor uma determinada tarefa. Qualquer que seja o motivo, você deve remover as dependências que não está usando. Fazer isso mantém tudo limpo. Além disso, as dependências ocupam espaço.

Para remover um pacote do seu projeto, utilize o comando remove, da seguinte forma: dotnet remove package <name of dependency>. Esse comando remove o pacote do arquivo .csproj do seu projeto.