Localizar e avaliar pacotes NuGet para 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 de criação de seus próprios pacotes. Os pacotes existentes podem vir da coleção pública nuget.org ou de fontes privadas que sua organização ou outra parte fornece.

Localizar pacotes

Você pode encontrar pacotes diretamente em 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 fonte. Todos os pacotes de nuget.org são verificados rotineiramente em busca de vírus.

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

Para pesquisar um pacote, insira o nome do pacote ou os termos de pesquisa na caixa Pesquisar 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

No nuget.org/packages, você pode refinar os resultados da pesquisa usando as opções avançadas de filtragem e classificação.

Use os filtros de Frameworks para mostrar pacotes direcionados a frameworks específicos do .NET (para saber mais, consulte Frameworks de Destino):

• Selecionar uma das caixas de seleção das gerações do framework do .NET filtraria os resultados da pesquisa para pacotes compatíveis com qualquer um dos Frameworks de Destino individuais dessa geração. Por exemplo, a seleção .NET retornará pacotes compatíveis com qualquer um dos frameworks modernos do .NET, inclusive de net5.0 até net8.0.

  

• A expansão de uma dessas gerações de frameworks usando as setas à direita mostrará a você identificadores individuais da Estrutura de Destino (TFMs) pelos quais você pode filtrar seus resultados. Por exemplo, a seleção 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 computadas. Se você quiser filtrar pacotes puramente pelos frameworks de ativos aos quais eles são explicitamente direcionados, desmarque a opção Incluir frameworks compatíveis.

• A combinação de vários filtros de estrutura mostrará os resultados da 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 ao '.NET Core 3.1' e ao '.NET Framework 4.5'. Selecionar a .NET Core caixa de seleção de geração do framework e a net45 caixa de seleção juntas retornará pacotes destinados ao '.NET Framework 4.5' e pelo menos um dos TFMs '.NET Core' (netcoreapp1.0 até netcoreapp3.1).

  • Como alternativa, se você quiser ver pacotes que correspondam a qualquer um dos filtros do framework, selecione o botão de Qualquer na opção Modo de Filtro do Framework. Agora, selecione netcoreapp3.1 e net5.0 mostrará pacotes destinados ao '.NET Core 3.1' ou ao '.NET 5.0'. Selecionar a caixa de seleção netcoreapp3.1 e a caixa de seleção .NET de geração do framework em conjunto retornará pacotes destinados ao '.NET Core 3.1' ou a qualquer um dos TFMs do '.NET' (entre net5.0 e net8.0).

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

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

• Todos os tipos são o padrão e mostram todos os pacotes independentemente do tipo.
• Filtros de dependência para pacotes NuGet regulares que você pode instalar em seu projeto.
• Filtros de ferramenta .NET para pacotes de ferramentas do .NET que contêm aplicativos de console.
• Filtros de modelo para modelos do .NET que você pode usar para criar novos projetos com o novo comando dotnet .

Por padrão, o NuGet lista todas as versões de 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 de pacote estáveis e lançadas.

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

Use o menu suspenso 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.
• Os downloads classificam os resultados da pesquisa pelo número total de downloads, em ordem decrescente.
• Recentemente, a atualização 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, da CLI do NuGet e de dentro do Visual Studio usam a mesma sintaxe. Outras fontes de pacote, como o Azure Artifacts ou o Repositório de Pacotes do GitHub, podem usar sintaxe diferente ou podem não dar suporte à filtragem avançada.

• Você pode pesquisar o pacoteid, packageid, , version, titletags, , author, descriptionsummaryou owner propriedades 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 cadeias de caracteres a seguir pesquisam a id propriedade para a cadeia de caracteres nuget.core:

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

• Busca na propriedade id coincidências com subcadeias de caracteres, enquanto packageid e owner usam coincidências exatas, sem diferenciar maiúsculas de minúsculas. Por exemplo:

  PackageId:jquery pesquisa a ID jqueryexata do pacote.
  Id:jquery pesquisa todas as IDs de pacote que contêm a cadeia de caracteres jquery.

• Você pode pesquisar vários valores ou propriedades ao mesmo tempo. Por exemplo:

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

• A pesquisa ignora propriedades sem suporte, ou seja, invalid:jquery ui é a mesma que pesquisar ui e invalid:jquery retorna todos os pacotes.

Determinar estruturas com suporte

O NuGet instala um pacote em um projeto somente se as estruturas do .NET com suporte do pacote incluirem 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 compatíveis com um pacote:

• Na página de pesquisa, as estruturas com suporte 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 do framework igual ou superior à versão do indicador mostrada.

  Os selos "azul escuro" representam estruturas explicitamente direcionadas, enquanto os selos "azul claro" representam estruturas compatíveis computadas.

  Clicar em um selo redirecionará você para a página de detalhes do pacote no nuget.org. A guia Estruturas na página do pacote mostrará a lista completa de estruturas com suporte.

  

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

  

• Baixe o pacote manualmente selecionando Baixar pacote sob 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 com suporte, cada uma nomeada com um identificador de estrutura de destino (TFM). Para obter mais informações, consulte Estruturas de Destino. Se não houver subpastas 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 com suporte do pacote.

Pacotes de pré-lançamento

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

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

• No nuget.org, desmarque a caixa de seleção Incluir pré-lançamento no painel de pesquisa avançado.
• 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 Pesquisar.

O Console do Gerenciador de Pacotes do Visual Studio, a CLI do NuGet e as ferramentas da 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 obter mais informações, consulte a Referência do PowerShell.

• Para a CLI do NuGet, use o switch -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 .NET, especifique uma versão de pré-lançamento com o argumento -v. Para obter mais informações, consulte a dotnet add package referência.

Pacotes C++ nativos

Os 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 native estrutura de destino e fornece integração do MSBuild.

Para encontrar pacotes nativos em nuget.org/packages, pesquise usando tag:native. Esses pacotes normalmente fornecem arquivos .targets e .props , que o NuGet importa automaticamente ao adicionar os pacotes.

Avaliar pacotes

A melhor maneira de avaliar a utilidade de um pacote é experimentá-lo. Você usa uma dependência de um pacote ao usá-lo, portanto, deve garantir 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.

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

  

• Downloads na coluna direita da página do pacote mostram Total, Versão atual e Média por dia de downloads. Números grandes indicam que o pacote provou-se 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 melhores opções.

• A guia Usado por na página do pacote mostra os cinco pacotes mais populares do nuget.org e os repositórios do GitHub que dependem desse pacote. Pacotes e repositórios que dependem desse pacote são chamados de dependentes. Pacotes e repositórios dependentes podem ser vistos como endossando esse pacote, pois eles optaram por 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 reflitam uma representação atualizada das decisões dos autores do pacote em confiar e depender dele. A lista de dependentes não mostra dependentes de pré-lançamento, porque eles ainda não são considerados endossamentos sinceros. Os exemplos a seguir mostram quais pacotes são mostrados como dependentes:

  Versão de pacote dependente	Pacote dependente listado como dependente?
  v1.0.0 v1.1.0 (estável mais recente) depende desse pacote v1.2.0-preview	TRUE, a versão estável mais recente depende desse pacote
  A v1.0.0 depende desse pacote v1.1.0 (estável mais recente) v1.2.0-preview	FALSE, a versão estável mais recente não depende desse pacote
  A v1.0.0 depende desse pacote v1.1.0 (estável mais recente) v1.2.0-preview depende desse pacote	FALSE, a versão estável mais recente não depende desse pacote

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

  Observação

  A seção Usado por é gerada automaticamente periodicamente, sem revisão humana e exclusivamente para fins informativos.

• A guia Versões na página do pacote mostra as versões, as downloads, as datas da última atualização e as vulnerabilidades graves das versões do pacote. A versão instalada não deve ter nenhuma vulnerabilidade de alta gravidade. Um pacote bem mantido tem atualizações recentes e um longo histórico de versões. Pacotes negligenciados têm poucas atualizações e há muito tempo.

  

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

• Selecione o site do Project, se disponível, para ver quais opções de suporte o autor fornece. Geralmente, há suporte para um projeto com um site dedicado.

• Selecione o repositório de origem 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 software livre, para que os usuários possam contribuir diretamente com correções de bugs e aprimoramentos de recursos. O histórico de contribuição do pacote é um bom indicador de quantos desenvolvedores estão ativamente envolvidos.

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

• Selecione qualquer um dos proprietários do pacote em Proprietários para ver outros pacotes que eles publicaram. Proprietários com vários pacotes são mais propensos a continuar dando suporte ao seu trabalho. 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 NuGet e feeds do NuGet podem não ser capazes de exibir informações de licenciamento. Para manter a compatibilidade com versões anteriores nesses casos, a URL de licença aponta para este documento sobre como recuperar as informações de licença.

Se a seleção da URL de licença de um pacote o levar para esta página, isso implicará que o pacote contém um arquivo de licença e:

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

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

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

Para obter informações sobre o MSBuild equivalente a definir a 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