Guia de implementação do NuGet Server

Em alguns casos, talvez você queira implementar seu próprio feed de pacotes NuGet. Existem muitas implementações existentes que permitem que você hospede seu próprio feed de várias maneiras, mas o protocolo entre o software cliente NuGet oficial e um feed de pacote está documentado, permitindo que você crie sua própria implementação de feed do zero.

O protocolo evolui com o tempo e este guia é destinado àqueles que desejam ou já implementaram um servidor de pacotes NuGet.

Desde o lançamento inicial do protocolo NuGet V3 em 2015, o NuGet evoluiu para fornecer aos desenvolvedores uma experiência mais rica, 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 endereços de metadados de pesquisa e do pacote contêm mais do que apenas os metadados encontrados no ficheiro nuspec do nupkg.

Observe que este guia é focado no protocolo NuGet V3, uma vez que o protocolo V2 é essencialmente não documentado e, desde 2015, o protocolo recomendado para a comunicação entre cliente e servidor NuGet é o protocolo V3. Para obter mais informações, leia sobre o controle de versão de protocolo.

Chronology

Para ajudar os autores dos repositórios NuGet existentes a se manterem atualizados com os recursos mais recentes do NuGet, aqui está a cronologia dos recursos relevantes mencionados no restante do documento.

Campo do proprietário

Considere dois 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 campo <authors>. 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 embalagem.

Isso foi explicado em uma postagem de blog de 2013, então o <owners> campo é considerado preterido no .nuspec arquivo. Se o manifesto do pacote contiver esses metadados, ele deve ser ignorado. Não retorne o valor do campo .nuspec do arquivo <owners> na propriedade owners na resposta JSON do recurso de pesquisa ou do recurso de metadados do pacote.

Se o repositório tiver permissões por pacote, é recomendável indicar as contas que têm permissões para publicar novas versões nos metadados owner das respostas JSON de metadados de pesquisa e de pacote.

verified campo de resposta da pesquisa

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.

NuGet.org utiliza isso com os dados de prefixo de pacote (dados do lado do servidor, não fazem parte da API do NuGet), para que a marca de seleção seja mostrada apenas aos clientes quando a conta que possui o pacote tenha carregado o pacote. Por exemplo, qualquer pacote com prefixo microsoft.* é verificado somente quando o pacote pertence à conta da Microsoft no nuget.org. Qualquer pessoa que carregou um pacote com ID de pacote começando com microsoft. antes dos prefixos reservados serem implementados, não terá essa marca de seleção verificada. 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 receberá uma marca de verificação verificada.

Suporte a versionamento semântico 2.0.0

O NuGet suporta um híbrido entre System.Version e a Versão 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 a 3.6.0 não devem retornar pacotes que usam recursos do Semantic 2.0.0 que são incompatíveis com o Semantic Versioning 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 Semantic Versioning 1.0.0 fornece [0-9A-Za-z-] como uma cadeia de caracteres de Expressão Regular de exemplo para os únicos caracteres permitidos como parte do rótulo de pré-lançamento e não oferece suporte a cadeias de caracteres de metadados. A especificação do Semantic Versioning 2.0.0 permite que identificadores de pré-lançamento sejam separados por . caracteres (e proíbe que um identificador numérico tenha um zero à esquerda) e, adicionalmente, permite que metadados de compilação sejam adicionados após um +.

No recurso de metadados do pacote (RegistrationsBaseUrl), as versões de recursos abaixo da 3.6.0 só devem retornar pacotes que estejam em conformidade com o . NET's System.Version ou Versionamento Semântico 1.0.0. Isso significa que os pacotes cujas versões são compatíveis apenas com o Semantic Versioning 2.0.0 são invisíveis para essas versões de 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 faltando, assuma o valor 1.0.0. Como o recurso de metadados do pacote, os pacotes cuja versão é compatível apenas com o Versionamento Semântico 2.0.0 não devem ser retornados quando o valor estiver abaixo de semVerLevel 2.0.0.

Arquivos incorporados

Ícones de pacote, licença e arquivos readme podem ser (e são recomendados ser) incorporados no pacote. Esses ficheiros precisam de um ponto final URL, extraído e colocado num servidor de ficheiros estático, ou um URL que extrai dinamicamente os ficheiros do .nupkg mediante solicitação, para que possam ser acessados sem descarregar o nupkg por completo. Se o repositório de pacotes fornecer detalhes de navegação e visualização de pacotes, você poderá usar as URLs para mostrar aos clientes o conteúdo incorporado em seu site.

Finalmente, o recurso de metadados do pacote e o recurso de pesquisa devem conter a URL hospedada nas propriedades iconUrl, licenseUrl e/ou readmeUrl da resposta JSON. Os pacotes (.nupkg ficheiros) não devem ser modificados, pois os recursos do cliente (ficheiros de bloqueio e pacotes assinados) detetarão modificações se o pacote for adulterado.

Observe que a licença pode ser uma expressão SPDX ou um arquivo incorporado (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 definido o licenseUrl para a expressão de licença, codificado em URL e anexado ao final do 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 conhecidos de vulnerabilidade e depreciação

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 equivalente em outros IDEs, sejam notificados sobre problemas importantes de segurança ou manutenção.

Se o repositório de pacotes estiver importando pacotes de outro repositório para replicar pacotes no seu próprio feed, recomendamos verificar periodicamente a fonte original para identificar dados de descontinuação ou vulnerabilidade e replicar esses metadados no seu próprio repositório. Se o seu repositório de pacotes estiver a buscar diretamente de nuget.org, ao manter um registo do estado da última verificação (um "cursor"), poderá utilizar o recurso Catalog para verificar eficazmente se existem atualizações para os pacotes que está a espelhar, sem necessitar de descarregar um grande número de ficheiros JSON de metadados de pacotes do feed upstream. Há um guia sobre como usar o recurso de catálogo com código de exemplo que pode ajudá-lo a começar.

Base de dados de vulnerabilidades conhecidas (VulnerabilityInfo)

Para fornecer análise de vulnerabilidades de alto desempenho durante a restauração do pacote, o NuGet baixa a lista completa de vulnerabilidades conhecidas do VulnerabilityInfo recurso. 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 primários 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, forneça um índice de vulnerabilidade com uma ou mais páginas de vulnerabilidade cujo conteúdo seja uma matriz JSON vazia ().[]

Reutilizando os dados de vulnerabilidade do nuget.org

O NuGet não exige que os recursos no índice de serviço, ou o índice de vulnerabilidade, estejam no mesmo servidor que o próprio índice de serviço. No entanto, há várias razões pelas quais algumas empresas optam por bloquear nuget.org no firewall ou ter feeds locais em uma rede desconectada. Para evitar problemas de conectividade, recomendamos fornecer dados de vulnerabilidade do seu próprio aplicativo Web, para que os clientes NuGet façam conexões HTTP apenas com o host no qual o feed está instalado.

✔️ Armazene em cache ou faça proxy das páginas de vulnerabilidade no seu próprio aplicativo Web

❌ NÃO anuncie api.nuget.org no 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 do .NET com o dotnet tool search comando. Isso é implementado adicionando um &packageTypes={value} parâmetro de consulta ao recurso de consulta de pesquisa, que lê valores do campo de arquivo .nuspec do <packageTypes> 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 NuGet consultarão. A partir do NuGet 6.7 (Visual Studio & MSBuild 17.7 e .NET SDK 7.0.400), o NuGet utiliza a funcionalidade do .NET, que evita solicitações HTTP anónimas apenas quando URLs subsequentes estão no mesmo diretório virtual, ou em um subdiretório, de uma URL que já 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.

Eis alguns exemplos:

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 num URL não canónico (o nome "amigável", no nosso exemplo feed), então não, todas as solicitações para recursos sob a URL canónica não corresponderão às regras de HttpClientHandlerPreAuthenticate. No entanto, se a URL não canônica for um redirecionamento HTTP para a URL canônica, então essa URL será usada no cache de credenciais de https://pkgs.contoso.com/nuget/v3/{guid}/index.json. Nesse caso, cada solicitação para o índice de serviço terá latência adicional, devido ao redirecionamento.

Enquanto a API V3 do NuGet foi 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 desejar hospedar a pesquisa, ou qualquer outro recurso da API do NuGet, em servidores diferentes, para se beneficiar do HttpClientHandler e do PreAuthenticate, precisará usar um proxy reverso para garantir que todas as URLs orientadas para o cliente no índice de serviço cumpram a regra de "mesmo ou subdiretório".

Ativar o download de README incorporado

Um novo recurso foi documentado para construir uma URL que pode ser usada para baixar um LEIA-ME para um determinado pacote. Isso permitirá que o cliente, como a interface do usuário de gerenciamento de pacotes no VS, exiba o LEIA-ME incorporado para pacotes que não foram instalados anteriormente pelo usuário. O cliente construirá esse URL e tentará baixar o LEIA-ME, usando a resposta à solicitação para determinar se um LEIA-ME está disponível. Isso significa que os servidores devem esperar múltiplas solicitações para o ponto de extremidade construído, à medida que os utilizadores navegam pela interface de utilizador do PM.