Partilhar via

Preterir pacotes

  • Artigo

Você pode preterir um pacote se não mantiver mais um pacote ou se quiser incentivar os consumidores do pacote a migrar para outro pacote.

A substituição do pacote é diferente da deslistagem do pacote, conforme explicado abaixo:

  • A não lista de um pacote impede sua descoberta porque ele está oculto nos resultados da pesquisa.
  • A substituição de um pacote permite que os consumidores existentes do pacote descubram se eles o instalaram ou usaram em seus projetos. Ele também permite que eles saibam o motivo da substituição e um pacote recomendado alternativo, conforme especificado por você (o editor de pacotes). A substituição de um pacote não cancela a lista do pacote.

Como publicador, você pode optar por não listar, bem como preterir pacotes.

Fluxo de trabalho de substituição

  1. Para preterir um pacote, vá para Gerenciar pacotes e selecione Preterir:

    Go to deprecate package option

  2. Selecione a versão que você gostaria de preterir. Se você quiser preterir todas as versões, escolha Selecionar todas as versões .

    Select package versions to deprecate

  3. Escolha um motivo para a substituição. Se o pacote não for mais mantido, escolha a opção Herdado . Se a versão específica tiver um bug crítico, escolha a opção de bugs críticos . Por qualquer outro motivo, selecione Outro. Você sempre pode especificar um pacote recomendado alternativo (e versão) e uma mensagem personalizada para os proprietários.

    Select reasons alternate package recommendation and custom message

Observação

A mensagem personalizada é mostrada apenas em nuget.org, mas não nos clientes. Atualmente, clientes como dotnet.exe e o NuGet Gerenciador de Pacotes não mostram a mensagem personalizada.

Experiência do cliente para pacotes preteridos

Depois que um pacote for preterido, seus consumidores serão notificados sobre ele das seguintes maneiras (dependendo do cliente usado).

Visual Studio

Disponível a partir do Visual Studio 2019 versão 16.3

Visual Studio alerta sobre o uso de um pacote preterido na Installed guia. Ele mostrará um aviso para o pacote e suas informações de substituição (incluindo o motivo pelo qual ele foi preterido e o pacote alternativo a ser usado, se presente).

Deprecated packages on Visual Studio installed tab of package manager

dotnet.exe

Disponível a partir do SDK do .NET 3.0

Se você usar dotnet.exe, poderá executar o comando dotnet list package --deprecated na pasta de solução ou projeto para obter uma lista de pacotes preteridos junto com as informações de substituição:

> dotnet list package --deprecated

The following sources were used:
   https://api.nuget.org/v3/index.json

Project `My.Test.Project` has the following deprecated packages
   [netcoreapp3.0]:
   Top-level Package      Resolved   Reason(s)   Alternative
   > My.Sample.Lib        6.0.0      Legacy      My.Awesome.Package

Transferir popularidade para um pacote mais recente

Autores de pacotes que preteriram um pacote herdado podem optar por transferir sua "popularidade" para um pacote mais recente para aumentar o ranking de pesquisa do pacote mais recente. Isso ajuda os clientes a descobrir o pacote mais recente em vez do pacote preterido.

Por exemplo, digamos que eu tenha dois pacotes:

  • Meu pacote herdado preterido, Contoso.Legacy com 3 milhões de downloads
  • Meu pacote mais recente, Contoso.Latest com 5 downloads

NuGet.org prefere resultados de pesquisa com downloads/popularidade mais altos. Dada a consulta de pesquisa "Contoso", meu pacote Contoso.Legacy preterido provavelmente ficaria acima do meu pacote Contoso.Latest mais recente nos resultados da pesquisa.

Para resolver esse problema, posso me candidatar para transferir a popularidade do meu pacote herdado preterido para o meu pacote mais recente. Isso faria Contoso.Latest com que a classificação fosse maior nos resultados da pesquisa, ao mesmo tempo Contoso.Legacy em que classificaria-se mais baixo. Somente as pontuações de popularidade interna para os pacotes são afetadas, a contagem real de download para cada pacote não será afetada.

Observação

As transferências de popularidade podem dificultar significativamente a localização do pacote herdado pelos consumidores.

Confira a tabela abaixo para ter uma ideia concreta de como uma transferência de popularidade pode afetar os rankings de pesquisa da consulta "Contoso":

Classificação de pesquisa Antes da transferência de popularidade Após a transferência de popularidade
1 Contoso.Legacy, downloads de 3M Contoso.Latest, 5 downloads
2 Contoso.Scanner, downloads de 2M Contoso.Scanner, downloads de 2M
3 Contoso.Core, downloads de 1,5M Contoso.Core, downloads de 1,5M
4 Contoso.UI, downloads de 1M Contoso.UI, downloads de 1M
... ... ...
20 Contoso.Latest, 5 downloads Contoso.Legacy, downloads de 3M

Processo de aplicativo de transferência de popularidade

  1. Examine os requisitos de transferência de popularidade.
  2. Envie um email account@nuget.org com o pacote preterido cuja popularidade deve ser transferida e a lista de pacotes estáveis que devem receber a transferência de popularidade.

Depois que o aplicativo for enviado, notificaremos você sobre a aceitação ou rejeição do aplicativo (com os critérios que causaram rejeição). Talvez seja necessário fazer outras perguntas de identificação para confirmar a identidade do proprietário.

Requisitos de transferência de popularidade

  • Os pacotes herdados e novos pacotes devem compartilhar todos os proprietários.
  • Os novos pacotes devem estar claramente relacionados aos pacotes herdados na nomenclatura e função (ou seja, uma evolução ou próxima geração).
  • Todas as versões dos pacotes herdados devem ser preteridas e apontar para os novos pacotes que recebem a transferência.
  • A transferência de popularidade não deve causar confusão para NuGet usuários ou piorar a experiência de pesquisa NuGet.
  • Os novos pacotes devem ter uma versão estável.
  • O pacote herdado não deve receber transferências de popularidade de outro pacote preterido.

Cenários avançados de transferência de popularidade

Consolidações de pacote

Posso transferir a popularidade de vários pacotes preteridos em favor de um único novo pacote. Por exemplo, digamos que eu tenha três pacotes:

  • Meu primeiro pacote herdado preterido, Contoso.Legacy1
  • Meu segundo pacote herdado preterido, Contoso.Legacy2
  • Meu novo pacote consolidado, Contoso.Latest

Depois que eu preterir Contoso.Legacy1 e Contoso.Legacy2, posso me candidatar para transferir sua popularidade para Contoso.Latest.

Divisões de pacote

A popularidade de um pacote preterido pode ser transferida e dividida entre até cinco pacotes mais recentes. Isso será útil se a funcionalidade de um pacote preterido tiver sido dividida entre vários novos pacotes. Por exemplo, digamos que eu tenha três pacotes:

  • Meu pacote herdado preterido, Contoso.Legacy
  • Meu primeiro novo pacote, Contoso.Web
  • Meu segundo novo pacote, Contoso.Cloud

Contoso.Legacy inclui a funcionalidade da Web e da nuvem, mas decidi separar essa funcionalidade em pacotes diferentes para a próxima geração. Depois de preterir Contoso.Legacy, posso me candidatar para transferir sua popularidade para ambos Contoso.Web e Contoso.Cloud.

Aviso

A popularidade transferida será dividida uniformemente entre todos os novos pacotes. Como resultado, recomendamos transferir a popularidade do pacote preterido para o menor número possível de pacotes.

Cadeias de transferência de popularidade

Um pacote preterido não poderá transferir sua popularidade se já estiver recebendo popularidade de outro pacote preterido. Por exemplo, digamos que eu tenha três pacotes:

  • Meu pacote herdado preterido, Contoso.First
  • Meu pacote herdado preterido, Contoso.Second
  • Meu novo pacote, Contoso.Latest

Se Contoso.First transferir sua popularidade para Contoso.Second, então Contoso.Second não poderá transferir sua popularidade para Contoso.Latest. Em vez disso, recomendamos transferir a popularidade de ambos Contoso.First e Contoso.Second para Contoso.Latest, de acordo com o cenário de consolidações de pacotes .