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 e ela é armazenada 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.

Vamos nos concentrar nas dependências de pacote. Um projeto .NET pode ter outros tipos de dependências, incluindo estruturas, analisadores, referências de projetos e dependências de projetos compartilhados, bem como dependências de pacotes.

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 conforme surgirem. Use essas bibliotecas em vez de criar as suas. Não é provável que você vá escrever o código por conta própria porque há muitos casos extremos a serem considerados.
  • 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 o resultado seja comparável ao que já está disponível, não é um bom uso do seu tempo replicar o trabalho de escrever esse código quando você não precisa fazer isso.
  • 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: pode ser um problema se seu pacote depender de uma dependência que foi preterida ou que não foi atualizada por um longo 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, usaremos a CLI do .NET Core interna 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.

Screenshot of NuGet.org showing a list of popular packages.

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 a partir de um pacote é comum quando você está tentando desenvolver suas próprias bibliotecas .NET e deseja testar o pacote localmente ou, por algum motivo, não deseja utilizar um registro.

Diagram that illustrates the relationship between package creators, package hosts, and package consumers.

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 NuGet.org e procura o código a ser baixado. Ela está localizada em https://nuget.org. Você também pode navegar por essa página em busca de pacotes se a visitar utilizando um navegador. Cada pacote tem um site dedicado que você pode acessar.

Screenshot of the landing page for a NuGet package.

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.

Screenshot of information and metrics on a NuGet package.

Comandos .NET

Até agora, você viu que é possível 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. Conforme expandir o uso do .NET, você passará a empregar cada vez mais comandos de diversas 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 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 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. Isso é bom para uma visualização 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 ver 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, bem como ferramentas específicas do projeto que são especificadas no arquivo de 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

Mais cedo ou mais tarde, é provável que você perceba que não precisa mais de um pacote ou que o pacote instalado não é o que você precisa. Talvez você encontre outro pacote que realizará 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.