Procurando e avaliando pacotes do NuGet para o seu projeto

Quando você inicia um projeto .NET ou identifica uma necessidade funcional em seu aplicativo ou serviço, muitas vezes você pode instalar pacotes NuGet existentes para economizar tempo e problemas decorrentes da criação de seus próprios pacotes. Esses pacotes podem vir da coleção pública em nuget.org ou de origens privadas fornecidas pela sua empresa ou por terceiros.

Procurar pacotes

Você pode procurar pacotes diretamente no https://nuget.org/packages, ou na interface do usuário do Gerenciador de Pacotes do Visual Studio ou no Console do Gerenciador de Pacotes com nuget.org como origem. Todos os pacotes em nuget.org são rotineiramente examinados em busca de vírus.

Em nuget.org/packages, você verá uma lista de pacotes NuGet com os pacotes mais populares em todos os projetos .NET listados primeiro. Alguns desses pacotes podem ser úteis para seus projetos.

Para procurar um pacote, insira o nome do pacote ou os termos de pesquisa na caixa de pesquisa na parte superior da página. Você pode usar a sintaxe de pesquisa avançada para filtrar sua pesquisa.

Filtragem e classificação avançadas

Em nuget.org/packages, você pode refinar seus resultados de pesquisa fazendo uso das opções avançadas de filtragem e classificação.

Use os filtros Estruturas para mostrar pacotes direcionados a estruturas .NET específicas (para saber mais, consulte Estruturas de destino):

• Marcar uma das caixas de seleção de geração do .NET Framework filtraria os resultados da pesquisa para pacotes compatíveis com qualquer uma das Estruturas de Destino individuais dentro dessa geração. Por exemplo, selecionar .NET retornará pacotes compatíveis com qualquer uma das estruturas .NET modernas, inclusive net5.0 por meio net8.0do .

  

• Expandir uma dessas gerações de estrutura com as setas à direita mostrará os Monikers da Estrutura de Destino (TFMs) individuais pelos quais você pode filtrar seus resultados. Por exemplo, selecionar net5.0 retornará pacotes compatíveis com a estrutura '.NET 5.0'.

• Por padrão, os pacotes são filtrados por sua lista expandida de estruturas compatíveis com cálculo. Se você quiser filtrar pacotes puramente pelas estruturas de ativos que eles visam explicitamente, desmarque a caixa de seleção Incluir estruturas compatíveis.

• A combinação de vários filtros de estrutura mostrará resultados de pesquisa que correspondem a todos os filtros selecionados, ou seja, pacotes que se enquadram na interseção de suas seleções. Por exemplo, selecionar netcoreapp3.1 e net45 juntos mostrará pacotes destinados a ".NET Core 3.1" e a ".NET Framework 4.5". Marcar a caixa de seleção de geração de estrutura .NET Core e a caixa de seleção net45 juntas retornará pacotes destinados a ".NET Framework 4.5" e a pelo menos um dos TFMs do ".NET Core" (netcoreapp1.0 até netcoreapp3.1).

  • Como alternativa, se você quiser ver pacotes correspondentes a qualquer um dos filtros da estrutura, selecione o botão de opção Qualquer na opção Modo de filtro da estrutura. Agora, selecione netcoreapp3.1 e net5.0 mostrará pacotes destinados a '.NET Core 3.1' ou '.NET 5.0'. Marcar a netcoreapp3.1 caixa de seleção e a caixa de seleção de .NET geração de estrutura juntas retornará pacotes destinados a '.NET Core 3.1' ou qualquer um dos '. NET' TFMs (net5.0 até net8.0).

• Você pode aprender mais sobre como avaliar as estruturas suportadas de um pacote e sua compatibilidade com seu projeto aqui.

Use o filtro Tipo de pacote para mostrar pacotes de um tipo específico:

• Todos os tipos é o padrão e mostra todos os pacotes, independentemente do tipo.
• Filtros de Dependência para pacotes NuGet regulares que você pode instalar em seu projeto.
• A ferramenta .NET filtra por pacotes de ferramentas .NET que contêm aplicativos de console.
• Filtros de Modelo para modelos .NET que você pode usar para criar novos projetos com o comando dotnet new.

Por padrão, o NuGet lista todas as versões dos pacotes, incluindo versões de pré-lançamento e beta. Na seção Opções, desmarque a caixa de seleção Incluir pré-lançamento para listar apenas versões estáveis de pacotes já lançados.

Para aplicar as alterações, escolha Aplicar. Para voltar aos padrões, selecione Redefinir.

Use a lista suspensa Classificar por no canto superior direito da página para classificar a lista por vários critérios:

• Relevância é o padrão e classifica os resultados de acordo com um algoritmo de pontuação interno.
• Downloads classifica os resultados da pesquisa pelo número total de downloads, em ordem decrescente.
• Atualizado recentemente classifica os resultados da pesquisa pela data de criação da versão mais recente do pacote em ordem cronológica decrescente.

Sintaxe de pesquisa

As consultas de pesquisa de pacote em nuget.org, na CLI do NuGet e no Visual Studio usam a mesma sintaxe. Outras origens de pacotes, como Azure Artifacts ou o Repositório de Pacotes do GitHub, podem usar sintaxe diferente ou podem não oferecer suporte a filtragem avançada.

• Você pode pesquisar as propriedades pacote id, packageid, version, title, tags, author, description, summary ou owner usando a sintaxe <property>:<term>.

• A pesquisa se aplica a palavras-chave e descrições e não diferencia maiúsculas de minúsculas. Por exemplo, todas as sequências a seguir pesquisam a string nuget.core na propriedade id:

  id:NuGet.Core
ID:nuget.core
Id:NUGET.CORE

• As pesquisas na propriedade id correspondem a subsequências, enquanto packageid e owner usam correspondências exatas que não diferenciam maiúsculas de minúsculas. Por exemplo:

  PackageId:jquery procura o ID do pacote jquery exato.
  Id:jquery procura todos os IDs de pacote que contêm a cadeia de caracteres jquery.

• É possível procurar vários valores ou propriedades ao mesmo tempo. Por exemplo:

  id:jquery id:ui procura vários termos na propriedade id.
  id:jquery tags:validation procura várias propriedades.

• A pesquisa ignora propriedades sem suporte, portanto invalid:jquery ui é o mesmo que procurar ui, e invalid:jquery retorna todos os pacotes.

Determinar estruturas compatíveis

O NuGet instala um pacote em um projeto somente se as estruturas .NET compatíveis do pacote incluem as estruturas de destino do projeto. Se o pacote não for compatível, o NuGet emitirá um erro.

Há várias maneiras de determinar as estruturas aceitas por um pacote:

• Na página de pesquisa, as estruturas suportadas de um pacote aparecerão como selos abaixo da ID do pacote. Esses selos mostram as versões de estrutura com suporte mais baixas das gerações .NET, .NET Core, .NET Standard e .NET Framework. O pacote será compatível com qualquer versão de estrutura que seja igual ou superior à versão do selo mostrada.

  Os emblemas 'azul escuro' representam estruturas explicitamente direcionadas, enquanto os emblemas 'azul claro' representam estruturas compatíveis com cálculos.

  Clicar em um selo redirecionará você para a página de detalhes do pacote em nuget.org. A guia Frameworks na página do pacote mostrará a lista completa de frameworks suportados.

  

• Na página do pacote em nuget.org, as estruturas compatíveis aparecem abaixo do ID do pacote e na guia Estruturas, mas nem todos os pacotes mostram estruturas compatíveis.

  

• Baixe o pacote manualmente selecionando Baixar pacote em Sobre. Altere a extensão de arquivo do pacote baixado de .nupkg para .zip, abra a pasta .zip e examine sua pasta lib. Há subpastas para cada estrutura compatível, cada uma noemada com um moniker da estrutura de destino (TFM). Para obter mais informações, consulte Estruturas de destino. Se não houver nenhuma subpasta em lib e houver apenas uma única DLL, tente instalar o pacote para descobrir sua compatibilidade.

• Tente instalar o pacote em um projeto usando Install-Package no Console do Gerenciador de Pacotes do Visual Studio. Se o pacote for incompatível, a saída do console mostrará as estruturas compatíveis com o pacote.

Pacotes de pré-lançamento

Muitos autores de pacote fornecem versões preview e betas à medida que continuam a implementar melhorias e buscar comentários sobre as revisões mais recentes. Por padrão, o nuget.org mostra pacotes de pré-lançamento em sua lista de pacotes e nos resultados da pesquisa.

Para listar e pesquisar apenas versões estáveis:

• Em nuget.org, desmarque a caixa de seleção Incluir pré-lançamento no painel de pesquisa avançada.
• Na interface do usuário do Gerenciador de Pacotes NuGet do Visual Studio, desmarque a caixa de seleção Incluir pré-lançamento ao lado da caixa de pesquisa.

As ferramentas Console do Gerenciador de Pacotes do Visual Studio, CLI do NuGet e CLI do dotnet não incluem versões de pré-lançamento por padrão. Para incluir versões de pré-lançamento.

• No Console do Gerenciador de Pacotes, use a opção -IncludePrerelease com os comandos Find-Package, Get-Package, Install-Package, Sync-Package e Update-Package. Para saber mais, consulte a Referência do PowerShell.

• Para a CLI do NuGet, use a opção -prerelease com os comandos install, update, delete e mirror. Para obter mais informações, consulte a Referência da CLI do NuGet.

• Para a CLI do dotnet, especifique uma versão de pré-lançamento com o argumento -v. Para obter mais informações, consulte a Referência do dotnet add package.

Pacotes C++ nativos

Projetos C++ do Visual Studio podem usar pacotes NuGet C++ nativos. A instalação desses pacotes habilita o comando de menu de contexto Gerenciar Pacotes NuGet, expõe uma estrutura de destino native e fornece integração com o MSBuild.

Para procurar pacotes nativos em nuget.org, pesquise usando tag:native. Esses pacotes normalmente fornecem arquivos .targets e .props que o NuGet importa automaticamente quando o pacote é adicionado a um projeto.

Avaliar pacotes

A melhor maneira de avaliar a utilidade de um pacote é experimentá-lo. Você assume uma dependência de um pacote quando o usa, portanto, deve certificar-se de que ele seja robusto e confiável. No entanto, instalar um pacote e testá-lo diretamente é demorado. Você pode aprender muito sobre a qualidade de um pacote usando as informações na página do pacote em nuget.org/packages.

• A marca de seleção Prefixo Reservado ao lado do ID do pacote na lista de pacotes e na página do pacote significa que os proprietários do pacote solicitaram e receberam um prefixo de ID de pacote reservado. Para atender aos critérios de reserva de prefixo de ID, os proprietários de pacotes devem identificar claramente a si mesmos e seus pacotes.

  

• Downloads na coluna da direita da página do pacote mostra o Total, a Versão atual e a Média por dia de downloads. Números grandes indicam que o pacote provou a si mesmo entre muitos desenvolvedores.

  

  Selecione Estatísticas completas ao lado de Downloads para ver uma página que mostra os downloads de pacotes das últimas seis semanas por número de versão. As versões que mais desenvolvedores estão usando normalmente são as melhores escolhas.

• A guia Usado por na página do pacote mostra os cinco pacotes de nuget.org mais populares e os repositórios do GitHub que dependem desse pacote. Os pacotes e repositórios que dependem desse pacote são chamados de dependentes. Pacotes dependentes e repositórios podem ser vistos como endossando este pacote porque eles escolheram confiar e depender dele.

  

  A versão estável mais recente de um pacote dependente deve depender de qualquer versão desse pacote. Essa definição garante que os pacotes dependentes listados sejam um reflexo atualizado das decisões dos autores de pacotes de confiar e depender do pacote. A lista de dependentes não mostra dependentes de pré-liberação, porque eles ainda não são considerados endossos "completos". Os exemplos a seguir mostram quais pacotes são aparecem como dependentes:

  Versão do pacote dependente	Pacote dependente listado como dependente?
  v1.0.0 v1.1.0 (última estável) depende deste pacote v1.2.0-preview	TRUE, a última versão estável depende deste pacote
  v1.0.0 depende deste pacote v1.1.0 (menos estável) v1.2.0-preview	FALSE, a última versão estável não depende deste pacote
  v1.0.0 depende deste pacote v1.1.0 (menos estável) v1.2.0-preview depende deste pacote	FALSE, a última versão estável não depende deste pacote

  O número de estrelas para um repositório do GitHub indica sua popularidade entre os usuários do GitHub. Para obter mais informações sobre o sistema de classificação de estrelas e o repositório do GitHub, consulte Sobre estrelas.

  Observação

  A seção Usado por é gerada automática e periodicamente, sem revisão humana e apenas para fins informativos.

• A guia Versões na página do pacote mostra as Versões, Downloads, datas de Última atualização e vulnerabilidades graves das versões do pacote. A versão instalada não deve ter vulnerabilidades de alta gravidade. Um pacote com boa manutenção tem atualizações recentes e um histórico de versões longo. Pacotes negligenciados têm atualizações em pouca quantidade e mais antigas.

  

A coluna da direita da página do pacote tem outros links informativos:

• Selecione Site do projeto, se disponível, para ver quais opções de suporte o autor fornece. Um projeto com um site dedicado geralmente tem um suporte melhor.

• Selecione Repositório de fontes para ir para o repositório de código-fonte do Git para o pacote. Muitos autores mantêm seus pacotes em repositórios de código aberto para que os usuários possam contribuir diretamente com correções de bugs e melhorias de recursos. O histórico de contribuição do pacote é um bom indicador de quantos desenvolvedores estão ativamente envolvidos.

• Selecione licença <tipo de licença> para ver o MIT do pacote ou outra licença. Se um pacote não especificar os termos de licença, entre em contato com o proprietário do pacote.

• Selecione qualquer um dos proprietários do pacote em Proprietários para ver os outros pacotes ele publicou. Proprietários com vários pacotes apresentam uma probabilidade maior de continuarem seu trabalho no futuro. Selecione Contatar proprietários ao lado de Proprietários para entrar em contato diretamente com os desenvolvedores do pacote.

Recuperar informações de licença.

Alguns clientes do NuGet e feeds NuGet podem não conseguir exibir informações de licenciamento. Para manter a compatibilidade com versões anteriores nesses casos, o URL da licença aponta para este documento que fala sobre como recuperar as informações da licença.

Se você for direcionado para esta página após selecionar o URL, isso significa que o pacote contém um arquivo de licença e:

• Você está conectado a um feed que ainda não sabe como interpretar e revelar as informações da licença para o cliente ou
• Você está usando um cliente que não sabe como interpretar e ler as novas informações de licença fornecidas pelo feed ou
• Uma combinação desses dois cenários.

Para ler as informações contidas no arquivo de licença dentro do pacote:

1. Baixe manualmente o pacote NuGet e descompacte seu conteúdo para uma pasta.
2. Abra o arquivo .nuspec na raiz da pasta.
3. Examine a marca <license>, como <license type="file">license\license.txt</license>. A tag de exemplo afirma que o arquivo de licença é chamado license.txt e está dentro de uma subpasta chamada license.
4. Navegue até o local especificado e abra o arquivo especificado.

Para obter informações sobre o MSBuild equivalente à configuração da licença no .nuspec, consulte Empacotando uma expressão de licença ou um arquivo de licença.

Próximas etapas

• Maneiras de instalar um pacote NuGet
• Instalar e gerenciar pacotes no Visual Studio usando o Gerenciador de Pacotes NuGet
• Instalar e gerenciar pacotes com o Console do Gerenciador de Pacotes no Visual Studio
• Instalar e gerenciar pacotes com a CLI do dotnet