Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Em alguns casos, talvez você queira implementar seu próprio feed de pacotes NuGet. Existem muitas implementações existentes que permitem hospedar seu próprio feed de várias maneiras, mas o protocolo entre o software cliente do NuGet oficial e um feed de pacotes está documentado, permitindo que você crie sua própria implementação de feed do zero.
O protocolo evolui ao longo do tempo e este guia destina-se àqueles que desejam ou já implementaram um servidor de pacotes NuGet.
Desde a versão inicial do protocolo NuGet V3 em 2015, o NuGet evoluiu para fornecer aos desenvolvedores uma experiência mais avançada, e isso exige que os repositórios de pacotes façam trabalho adicional para fornecer o valor adicional aos consumidores de pacotes, além de simplesmente exigir metadados de pacotes hospedados e retornar os metadados de várias formas. Por exemplo, os pontos de extremidade de metadados de pesquisa e pacote contêm mais do que apenas metadados encontrados no arquivo nuspec do nupkg.
Observe que este guia está focado no protocolo NuGet V3, pois o protocolo V2 é essencialmente não documentado e, desde 2015, o protocolo recomendado para comunicação de cliente e servidor do NuGet é o protocolo V3. Para obter mais informações, leia sobre o controle de versão do protocolo.
Chronology
Para ajudar os autores de repositórios NuGet existentes a manterem-se atualizados com os recursos mais recentes do NuGet, aqui está a cronologia dos recursos relevantes mencionados no restante do documento.
| Year | Feature |
|---|---|
| 2013 |
Uma postagem no blog explicando como gerenciar proprietários de pacotes no nuget.org esclareceu que os proprietários mostrados no site são as contas que têm permissão para carregar novas versões e, portanto, os owners metadados no pacote são ignorados |
| 2017 |
verified adicionado às respostas SearchQueryService. |
| Suporte semântico do Versioning 2.0.0 | |
| 2018 | Licenças inseridas |
| 2019 | Ícones inseridos |
Depreciação do pacote em RegistrationBaseUrl (recurso de metadados do pacote) |
|
| 2020 |
Informações de vulnerabilidade do pacote no RegistrationsBaseUrl (recurso de metadados do pacote) |
Parâmetro de consulta adicionado packageTypes às SearchQueryService solicitações |
|
| 2021 | Readme integrado |
| 2023 |
Pré-autenticar solicitações já autenticadas VulnerabilityInfo recurso |
| 2025 | Habilitar downloads de README embutidos |
Campo de Propriedade
Considere dois dos campos do arquivo de manifesto do pacote (.nuspec): <authors> e <owners>.
Os autores de pacotes que estão empacotando conteúdo de terceiros geralmente colocam o nome de terceiros no <authors> campo.
O <owners> campo destinava-se a indicar quem publicou o pacote em um repositório e, portanto, quem deve ser contatado em caso de problemas ou perguntas de empacotamento.
Isso foi explicado em uma postagem no blog de 2013, de modo que o <owners> campo é considerado preterido no .nuspec arquivo.
Se o manifesto do pacote contiver esses metadados, ele deverá ser ignorado.
Não retorne o valor do campo .nuspec do arquivo <owners> na propriedade owners no recurso de pesquisa ou na resposta JSON do recurso de metadados do pacote.
Se o repositório tiver permissões por pacote, é recomendável relatar as contas que têm permissões para publicar novas versões nos metadados owner para respostas JSON de recursos de metadados de pesquisa e pacote.
Campo de resposta de pesquisa verified
A interface do usuário do Gerenciador de Pacotes do Visual Studio mostra uma marca de seleção azul ao lado de pacotes nos resultados do serviço de pesquisa , quando um novo campo verified é definido como true.
O NuGet.org usa isso com dados de prefixo de pacote (dados do lado do servidor, não parte da API do NuGet), para que essa marca de seleção só seja mostrada aos clientes quando a conta proprietária do pacote carregar o pacote.
Por exemplo, qualquer pacote com prefixo microsoft.* é verificado somente quando o pacote pertence à conta da Microsoft no nuget.org. Qualquer pessoa que tenha carregado um pacote com a ID do pacote começando microsoft. antes de os prefixos reservados serem implementados, não terá essa marca de seleção verificada.
O NuGet.org também permite que os prefixos não sejam exclusivos, para que qualquer pessoa possa carregar um pacote em Contoso.ToolWithPlugins.Community.*, mas não obtenha uma marca de seleção verificada.
Suporte ao Versionamento Semântico 2.0.0
O NuGet dá suporte a uma versão híbrida entre System.Version e Semântica, mas o suporte para a Versão Semântica 2.0.0 foi adicionado em 2017.
Portanto, os recursos da API do NuGet que retornam versões para versões de cliente inferiores à 3.6.0 não devem retornar pacotes que usam recursos semânticos 2.0.0 incompatíveis com o Controle de Versão Semântico 1.0.0.
As diferenças mais importantes entre as duas versões são os rótulos de pré-lançamento e a cadeia de metadados.
A especificação da Versão Semântica 1.0.0 fornece [0-9A-Za-z-] como um exemplo de cadeia de caracteres de expressão regular para os únicos caracteres permitidos como parte do rótulo de pré-lançamento e não dá suporte a cadeias de caracteres de metadados.
A especificação de Versão Semântica 2.0.0 permite que os identificadores de pré-lançamento sejam separados por . caracteres (e proíbe um identificador numérico de ter um zero à esquerda) e, além disso, permite que os metadados de build sejam adicionados após um +.
No recurso de metadados do pacote (RegistrationsBaseUrl), as versões do recurso abaixo da 3.6.0 só devem retornar pacotes que estejam em conformidade com o System.Version do .NET ou o Controle de versão semântico 1.0.0.
Isso significa que os pacotes cujas versões só estão em conformidade com o Controle de Versão Semântico 2.0.0 são invisíveis para essas versões do cliente.
Da mesma forma, o serviço de consulta de pesquisa (SearchQueryService) e o serviço de preenchimento automático (SearchAutocompleteService) adicionaram &semVerLevel={version} parâmetros de consulta.
Quando semVerLevel estiver ausente, suponha o valor 1.0.0.
Assim como o recurso de metadados do pacote, os pacotes cuja versão é compatível apenas com o Controle de Versão Semântico 2.0.0 não devem ser retornados quando o semVerLevel valor estiver abaixo de 2.0.0.
Arquivos incorporados
Os ícones do pacote, a licença e os arquivos readme podem ser (e são recomendados) inseridos no pacote.
Esses arquivos precisam de um ponto de extremidade de URL, extraído e colocado em um servidor de arquivos estático, ou uma URL que extraia dinamicamente os arquivos do .nupkg mediante solicitação, para que eles possam ser visualizados sem baixar o nupkg inteiro.
Se o seu repositório de pacotes fornecer navegação de pacotes e visualização dos detalhes do pacote, você poderá usar as URLs para mostrar aos clientes o conteúdo incorporado em seu site.
Por fim, o recurso de metadados do pacote e o recurso de pesquisa devem conter a URL hospedada nas iconUrlpropriedades , licenseUrle/ou readmeUrl da resposta JSON.
Pacotes (.nupkg arquivos) não devem ser modificados, pois os recursos do cliente (arquivos de bloqueio e pacotes assinados) detectarão modificações à medida que o pacote tiver sido adulterado.
Observe que a licença pode ser uma expressão SPDX ou um arquivo inserido (mas não ambos).
Os pacotes que usam uma expressão de licença, quando representados nos resultados de pesquisa e metadados do pacote, podem ter licenseUrl definido como a expressão de licença, codificada por URL e anexada ao final de https://licenses.nuget.org/.
Por exemplo, https://licenses.nuget.org/Apache-2.0.
A equipe do servidor NuGet.org tem documentação adicional sobre licenses.nuget.org.
Dados de vulnerabilidade e depreciação conhecidos
Recurso de metadados do pacote (RegistrationsBaseUrl)
O Recurso de Metadados do Pacote pode conter informações sobre depreciação e vulnerabilidade. Isso permite que os clientes que navegam em pacotes na Interface do Usuário do Gerenciador de Pacotes do Visual Studio ou equivalentes em outros IDEs sejam notificados sobre problemas importantes de segurança ou manutenção.
Se o repositório de pacotes for “up-sourcing” de outro repositório, para espelhar pacotes em seu próprio feed, recomendamos verificar periodicamente a fonte original para ver se há dados de depreciação ou vulnerabilidade e espelhar esses metadados em seu próprio repositório.
Se o repositório de pacotes estiver fazendo up-sourcing do nuget.org especificamente, mantendo o estado da última vez que você verificou (um “cursor”), você poderá usar o recurso Catalog para verificar com eficiência se há atualizações de pacotes para pacotes que você está espelhando, sem precisar baixar muitos arquivos JSON de metadados de pacote do feed de upstream.
Há um guia sobre como usar o recurso de catálogo com código de exemplo que pode ajudá-lo a começar.
Banco de dados de vulnerabilidades conhecido (VulnerabilityInfo)
Para fornecer verificação de vulnerabilidade de alto desempenho durante a restauração de pacotes, o NuGet baixa a lista completa de vulnerabilidades conhecidas do recurso VulnerabilityInfo.
Nuget.org fornece dados de vulnerabilidade para todos os avisos revisados do GitHub do banco de dados GitHub Advisories, que inclui pacotes que não estão hospedados no nuget.org.
Se o repositório de pacotes estiver hospedando pacotes de primeira parte e você quiser fornecer informações de vulnerabilidade aos clientes usando seu próprio feed, mas ainda não tiver nenhuma vulnerabilidade de pacote divulgada, você deverá fornecer um índice de vulnerabilidade com uma ou mais páginas de vulnerabilidade cujo conteúdo é uma matriz JSON vazia ([]).
Reutilizando dados de vulnerabilidade do nuget.org
O NuGet não exige que os recursos no índice de serviço ou no índice de vulnerabilidades estejam no mesmo servidor que o próprio índice de serviço. No entanto, há vários motivos pelos quais algumas empresas optam por bloquear nuget.org no firewall ou ter feeds no local em uma rede desconectada. Para evitar problemas de conectividade, recomendamos fornecer dados de vulnerabilidade de seu próprio aplicativo Web, para que os clientes Do NuGet façam apenas conexões HTTP com o host no qual o feed está instalado.
✔️ FAZER cache ou proxy das páginas de vulnerabilidade em seu próprio aplicativo Web
❌ NÃO anuncie api.nuget.org em seu índice de serviço ou índice de vulnerabilidade sem uma configuração para desativá-lo.
packageTypes consulta de pesquisa
A CLI do .NET permite pesquisar pacotes de ferramentas .NET com o dotnet tool search comando.
Isso é implementado adicionando um parâmetro de consulta &packageTypes={value} ao recurso de consulta de pesquisa, que lê valores do campo .nuspec de arquivo <packageTypes> do pacote.
Estrutura de URL para feeds autenticados
Conforme descrito na visão geral da API do NuGet, a URL inicial para toda a comunicação do servidor NuGet é o índice de serviço.
Este documento contém as URLs de todos os outros recursos que os clientes do NuGet consultarão.
A partir do NuGet 6.7 (Visual Studio &MSBuild 17.7 e .NET SDK 7.0.400), o NuGet usa . NET's HttpClientHandler.PreAuthenticate, que só evita solicitações HTTP anônimas quando as URLs subsequentes estão no mesmo diretório virtual ou em um subdiretório, de uma URL que foi autenticada anteriormente.
Isso reduzirá drasticamente o número de solicitações HTTP não autenticadas enviadas ao servidor e, portanto, reduzirá a carga de trabalho do servidor.
Aqui estão alguns exemplos:
| URL | O PreAuthenticate será? |
|---|---|
| https://pkgs.contoso.com/nuget/v3/feed/index.json | N/A, esse é o índice de serviço. |
| https://pkgs.contoso.com/nuget/v3/search | Não, não no mesmo ou no subdiretório do índice de serviço. |
| https://search.pkgs.contoso.com/nuget/v3/feed/ | Não, não no mesmo nome do host que o índice de serviço. |
| https://pkgs.contoso.com/nuget/v3/feed/search | Sim, no mesmo diretório que o índice de serviço. |
| https://pkgs.contoso.com/nuget/v3/registration/ | Não, não em um subdiretório do índice de serviço. |
| https://pkgs.contoso.com/nuget/v3/feed/registration/ | Sim, em um subdiretório do índice de serviço. |
| https://pkgs.contoso.com/nuget/v3/{guid}/registration/ | Veja abaixo |
No último exemplo, o servidor pode ter um nome canônico (neste exemplo, um guid) e ter um ou mais aliases.
Se a solicitação de índice de serviço foi autenticada em uma URL não canônica (o nome "amigável", no nosso exemplo feed), então não, qualquer solicitação aos recursos na URL canônica não corresponderá às regras de HttpClientHandler para PreAuthenticate.
No entanto, se a URL não canônica for um redirecionamento HTTP para a URL canônica, https://pkgs.contoso.com/nuget/v3/{guid}/index.jsonessa URL será usada no HttpClientHandlercache de credenciais.
Nesse caso, cada solicitação para o índice de serviço terá latência adicional devido ao redirecionamento.
Embora a API V3 do NuGet tenha sido projetada para funcionar em um servidor de arquivos estático, o recurso de pesquisa é a exceção que sempre requer um serviço Web dinâmico para processar solicitações.
Se você deseja hospedar a pesquisa, ou mesmo qualquer outro recurso da API do NuGet, em servidores diferentes, a fim de se beneficiar da HttpClientHandlerdo PreAuthenticate, você precisará usar um proxy reverso para garantir que todas as URLs voltadas para o cliente no índice de serviço atendam à regra “no mesmo ou no subdiretório”.
Habilitar downloads de README embutidos
Um novo recurso foi documentado para construir uma URL que pode ser usada para baixar um README para um determinado pacote. Isso permitirá que o cliente, como a interface do usuário de Gerenciamento de Pacotes no VS, exiba o README inserido para pacotes que não foram instalados anteriormente pelo usuário. O cliente construirá essa URL e tentará baixar o README, usando a resposta à solicitação para determinar se um README está disponível. Isso significa que os servidores devem estar preparados para receber várias solicitações para o ponto de extremidade construído à medida que os usuários navegam na interface de usuário do Gerenciamento de Projetos.