Partilhar via

Melhores práticas de criação de pacotes

  • Artigo

Esta orientação destina-se a fornecer aos autores de pacotes NuGet uma referência leve para criar e publicar pacotes de alta qualidade. Ele se concentrará principalmente em práticas recomendadas específicas do pacote, como metadados e empacotamento. Para obter sugestões mais detalhadas para a criação de bibliotecas de alta qualidade, consulte as diretrizes de biblioteca de código aberto do .NET.

Tipos de recomendações

Cada artigo apresenta quatro tipos de recomendação: Fazer, Considerar, Evitar e Não fazer. O tipo de recomendação indica o quanto de perto ela deve ser seguida.

Procure quase sempre seguir a recomendação Fazer. Por exemplo:

✔️ INCLUA uma breve descrição para o seu pacote que descreva sua finalidade.

Por outro lado, as recomendações Considerar geralmente devem ser seguidas, mas há exceções à regra legítimas:

✔️ CONSIDERE escolher um nome de pacote do NuGet com um prefixo que cumpra os critérios de reserva de prefixo do NuGet.

As recomendações Evitar mencionam coisas que em geral não são ideais, mas há casos em que, às vezes, quebrar a regra faz sentido:

❌ EVITAR referências do pacote NuGet que demandam uma versão exata.

Por fim, as recomendações Não fazer indicam algo que você quase nunca deve fazer:

❌ NÃO use a propriedade de metadados LicenseUrl.

Criar um pacote NuGet

A maneira recomendada mais recente de criar um pacote NuGet é a partir de um projeto estilo SDK. As propriedades do projeto estilo SDK, incluindo a estrutura de destino e os metadados do pacote, são definidas no arquivo de projeto.

Crie um pacote do seu projeto no estilo SDK, definindo as propriedades necessárias e empacotando no Visual Studio ou na CLI do dotnet.

✔️ CRIE um projeto estilo SDK e crie (empacote) seu pacote usando o Visual Studio ou a CLI do dotnet.

Para obter orientações mais detalhadas sobre a criação de pacotes, incluindo ferramentas de cliente necessárias, exemplo de arquivo de projeto e comandos, consulte Criar um pacote NuGet usando a CLI do dotnet.

Para ajudar a decidir quais estruturas .NET segmentar, consulte nossas diretrizes mais recentes para segmentação entre plataformas.

Metadados de pacote

Os metadados são um componente fundamental de qualquer pacote NuGet. A qualidade dos seus metadados pode influenciar enormemente a descoberta, usabilidade e confiabilidade do seu pacote.

No Visual Studio, a maneira recomendada de especificar metadados do pacote é ir para Projeto > Propriedades de [Nome do projeto] > Pacote.

Os elementos de metadados do pacote também podem ser especificados diretamente no arquivo de projeto.

Abaixo está uma tabela que mapeia e desenvolve os elementos de metadados do pacote disponíveis:

Nome da propriedade do Visual Studio Arquivo de projeto/nome da propriedade MSBuild Nome da propriedade Nuspec Descrição
Package id PackageId id O nome do pacote do identificador.
Package version PackageVersion version Versão do pacote NuGet.
Authors Authors authors Uma lista separada por vírgulas de autores de pacotes, geralmente usando o "nome atraente" do indivíduo ou de uma organização.
Description Description description Uma descrição longa do pacote.
Copyright Copyright copyright Detalhes sobre direitos autorais do pacote.
Project URL PackageProjectUrl projectUrl O URL da home page do projeto.
Icon File PackageIcon icon O caminho para o arquivo de imagem de ícone de um pacote.
README PackageReadmeFile readme O caminho para o arquivo markdown LEIAME do pacote.
Repository URL RepositoryUrl repository url URL para o repositório do qual o pacote foi criado.
Repository type RepositoryType repository type Tipo de repositório para o qual o URL do repositório está apontando (ou seja, "git").
Tags PackageTags tags Uma lista delimitada por espaço de marcas e palavras-chave que descrevem o pacote. Marcas são usadas ao pesquisar pacotes.
Release notes PackageReleaseNotes releaseNotes Uma descrição das alterações feitas nesta versão do pacote.
Licensing - Expression PackageLicenseExpression license type="expression" Uma expressão de licença SPDX.
Licensing - File PackageLicenseFile license type="file" Caminho para um arquivo de licença personalizado.

ID do Pacote

Se você estiver publicando um pacote completamente novo:

✔️ ESCOLHA um ID de pacote que seja exclusivo e claramente diferenciado dos pacotes existentes em NuGet.org.

Você pode verificar se um ID de pacote é único e diferenciável pesquisando o ID em NuGet.org ou verificando se o seguinte link existe: https://www.nuget.org/packages/<nome do pacote>.

✔️ CONSIDERE escolher um nome de pacote do NuGet com um prefixo que cumpra os critérios de reserva de prefixo do NuGet.

Reservar o ID de prefixo para seu pacote permitirá que você obtenha a marca de seleção verificada: image

Consulte os documentos de reserva de prefixo de ID do pacote para saber mais.

Versão do pacote

✔️ CONSIDE usar o SemVer para criar a versão do seu pacote NuGet.

Essencialmente, isso significa usar o formato Major.Minor.Patch[-prerelease].

✔️ PUBLIQUE um pacote como um pacote de pré-lançamento se ele não estiver estável ou for um preview.

Consulte o Guia de controle de versão da biblioteca .NET para obter orientações mais avançadas.

Autores

✔️ USE o campo de autor para o seu "nome atraente" ou o "nome atraente" da sua organização.

Por exemplo, se meu nome de usuário NuGet.org for "jdoe", usar "Jane Doe" para o campo de autor pode ajudar os consumidores a me reconhecerem como autora. Se o nome de usuário NuGet.org da minha organização for "ContosoToolkit", usar "Contoso Corporation" pode ser mais reconhecível e inspirar mais confiança do consumidor.

Descrição

✔️ INCLUA uma breve descrição (até 4000 caracteres) para descrever seu pacote.

As descrições de pacotes são um dos campos mais proeminentes que aparecem na pesquisa do NuGet e provavelmente serão a primeira coisa que os consumidores em potencial analisarão para determinar se um pacote é adequado para eles.

✔️ ADICIONE um aviso de direitos autorais ao seu pacote com "Direitos autorais (c) <nome/empresa><ano>".

Um aviso de direitos autorais indica essencialmente que seu trabalho não pode ser copiado sem sua permissão. Incluir um aviso de direitos autorais em seu pacote é fácil e não fará mal algum!

Exemplo: Direitos autorais (c) Contoso 2020

URL do projeto

✔️ INCLUA um link para um projeto, repositório ou site da empresa associado.

Seu site de projeto deve ter tudo o que os usuários precisam saber sobre seu pacote e provavelmente será onde eles procurarão documentação.

Ícone

✔️ CONSIDERE incluir um ícone com seu pacote para ajudar a diferenciá-lo visualmente. É uma adição relativamente pequena que pode melhorar a percepção da qualidade do pacote.

Os ícones podem ser específicos para pacotes individuais ou ser um logotipo de marca.

✔️ USE uma imagem com 128 x 128 e tela de fundo transparente (PNG) para proporcionar os melhores resultados de visualização.

O NuGet dimensionará automaticamente sua imagem para o cliente em que ela está sendo exibida.

❌ NÃO use a propriedade de metadados preterida IconUrl.

README

✔️ ADICIONE um arquivo markdown LEIAME que fornece uma visão geral do que seu pacote faz e como começar a usá-lo.

Um pacote LEIAME irá melhorar significativamente a percepção de qualidade do seu pacote, bem como a integração de novos usuários. Considere também visualizar seu LEIAME antes de carregá-lo! Veja como incluir um arquivo LEIAME no pacote NuGet para obter mais detalhes.

Tipo de repositório e URL

✔️ CONSIDERE configurar o Link de origem para adicionar automaticamente metadados de controle do código-fonte ao pacote NuGet e fazer com que seja mais fácil depurar sua biblioteca.

O Link de origem adiciona automaticamente Repository URL e Repository Type aos metadados do pacote. Ele também adiciona a confirmação específica associada à versão do pacote.

Tags

✔️ INCLUA várias tags com termos-chave relacionados ao seu pacote para melhorar a capacidade de descoberta.

As tags são levadas em conta no algoritmo de pesquisa do NuGet.org e são especialmente úteis para termos que não estão no ID do pacote, mas são relevantes.

Por exemplo, se eu publicasse um pacote para registrar sequências no console, incluiria: "logging, log, console, string, output"

Notas de versão

✔️ INCLUA notas de versão com cada atualização descrevendo quais alterações foram feitas.

Embora não seja necessário um formato específico para as notas de versão, recomendamos incluir:

  1. Alterações da falha
  2. Novos recursos
  3. Correções de bug

Se você já guarda notas de versão ou um log de mudanças em seu repositório, também poderá incluir um link para o arquivo relevante.

Licenciamento

✔️ INCLUA uma expressão de licença ou arquivo de licença em seu pacote.

Importante

Um projeto sem uma licença adota por padrão direitos autorais exclusivos, o que significa que você não concedeu permissão a ninguém para usar seu projeto.

❌ NÃO use a propriedade de metadados preterida LicenseUrl.

Isso representa uma ambiguidade legal, pois as alterações de licença no URL alterarão retroativamente a licença exibida para versões anteriores do pacote.

Se o seu pacote for de código aberto

✔️ ESCOLHA uma licença de código aberto para tornar seu pacote de código aberto.

"As licenças de código aberto são licenças que estão em conformidade com a Open Source Definition — em resumo, elas permitem que o software seja livremente usado, modificado e compartilhado." – Open Source Initiative. Para saber mais sobre software de código aberto e a Open Source Initiative, consulte https://opensource.org/.

✔️ CONSIDERE incluir uma expressão de licença em seu pacote.

As expressões de licença são apresentadas de forma mais clara e tornam mais óbvio para os consumidores se eles podem usar seu pacote ou se a licença foi alterada.

Observação

O NuGet.org só aceita expressões de licença para licenças aprovadas pela Open Source Initiative ou pela Free Software Foundation.

Se o seu pacote não for de código aberto

✔️ INCLUA um arquivo de licença em seu pacote.

Qualquer arquivo de licença (.txt ou .md) pode ser adicionado ao seu pacote, incluindo licenças não padrão.