Condividi tramite

Procedure consigliate per la creazione di pacchetti

  • Articolo

Queste linee guida consentono agli autori di pacchetti NuGet di fornire agli autori di pacchetti NuGet un riferimento leggero per creare e pubblicare pacchetti di alta qualità. Si concentrerà principalmente sulle procedure consigliate specifiche del pacchetto, ad esempio metadati e compressione. Per suggerimenti più approfonditi per la creazione di librerie di alta qualità, vedere le linee guida per la libreria open source .NET.

Tipi di suggerimenti

Ogni articolo presenta quattro tipi di suggerimenti: Da fare, Da considerare, Da evitare e Da non fare. Il tipo di raccomandazione indica quanto deve essere seguito da vicino.

È opportuno seguire quasi sempre un suggerimento di tipo Da fare. Ad esempio:

✔️ DO include una breve descrizione per il pacchetto che descrive il relativo scopo.

D'altra parte, è consigliabile seguire le raccomandazioni in genere, ma esistono eccezioni legittime alla regola:

✔️ VALUTARE la possibilità di scegliere un nome di pacchetto NuGet con un prefisso che soddisfi i criteri di prenotazione del prefisso di NuGet.

I suggerimenti di tipo Da evitare si riferiscono a operazioni in genere non consigliabili, ma che talvolta possono avere un'utilità:

❌ EVITARE riferimenti al pacchetto NuGet che richiedono una versione esatta.

E infine, i suggerimenti di tipo Da non fare indicano operazioni che quasi sempre è necessario evitare:

❌ NON usare la LicenseUrl proprietà dei metadati.

Creare un pacchetto NuGet

Il modo consigliato più recente per creare un pacchetto NuGet è da un progetto in stile SDK. Le proprietà del progetto in stile SDK, inclusi i metadati del framework di destinazione e del pacchetto, vengono definite nel file di progetto.

Creare un pacchetto dal progetto di tipo SDK definendo le proprietà necessarie e la compressione in Visual Studio o nell'interfaccia della riga di comando dotnet.

✔️ CREARE un progetto in stile SDK e creare (pack) il pacchetto usando Visual Studio o l'interfaccia della riga di comando dotnet.

Per indicazioni più dettagliate sulla creazione di pacchetti, inclusi gli strumenti client necessari, l'esempio di file di progetto e i comandi, vedere Creare un pacchetto NuGet usando l'interfaccia della riga di comando dotnet.

Per decidere quali framework .NET usare come destinazione, vedere le linee guida più recenti per la destinazione multipiattaforma.

Metadati dei pacchetti

I metadati sono un componente fondamentale di qualsiasi pacchetto NuGet. La qualità dei metadati può influenzare notevolmente l'individuabilità, l'usabilità e l'affidabilità del pacchetto.

In Visual Studio, il modo consigliato per specificare i metadati del pacchetto consiste nel passare a Project > [Project Name] Properties > Package.

Gli elementi dei metadati del pacchetto possono anche essere specificati direttamente nel file di progetto.

Di seguito è riportato un mapping di tabella e la descrizione degli elementi dei metadati del pacchetto disponibili:

Nome proprietà di Visual Studio File di progetto/Nome proprietà MSBuild Nome proprietà Nuspec Descrizione
Package id PackageId id Nome o identificatore del pacchetto.
Package version PackageVersion version Versione del pacchetto NuGet.
Authors Authors authors Un elenco delimitato da virgole di autori di pacchetti, spesso usando il nome "piuttosto" dell'utente o di un'organizzazione.
Description Description description Descrizione del pacchetto.
Copyright Copyright copyright Informazioni sul copyright per il pacchetto.
Project URL PackageProjectUrl projectUrl URL della home page del progetto.
Icon File PackageIcon icon Percorso del file di immagine dell'icona del pacchetto.
README PackageReadmeFile readme Percorso del file markdown README del pacchetto.
Repository URL RepositoryUrl repository url URL del repository da cui è stato compilato il pacchetto.
Repository type RepositoryType repository type Il tipo di repository a cui punta l'URL del repository ,ad esempio "git".
Tags PackageTags tags Elenco di tag e parole chiave delimitati da spazi che descrivono il pacchetto. I tag vengono usati per la ricerca di pacchetti.
Release notes PackageReleaseNotes releaseNotes Descrizione delle modifiche apportate in questa versione del pacchetto.
Licensing - Expression PackageLicenseExpression license type="expression" Espressione di licenza SPDX.
Licensing - File PackageLicenseFile license type="file" Percorso di un file di licenza personalizzato.

ID pacchetto

Se si pubblica un pacchetto completamente nuovo:

✔️ DO scegliere un ID pacchetto univoco e chiaramente differenziato rispetto ai pacchetti esistenti in NuGet.org.

È possibile verificare se un ID pacchetto è univoco e differenziabile cercando l'ID in NuGet.org o verificando se il collegamento seguente esiste: https://www.nuget.org/packages/<nome> del pacchetto.

✔️ VALUTARE la possibilità di scegliere un nome di pacchetto NuGet con un prefisso che soddisfi i criteri di prenotazione del prefisso di NuGet.

La prenotazione dell'ID prefisso per il pacchetto consentirà di ottenere il segno di spunta verificato: image

Per altre informazioni, vedere la documentazione sulla prenotazione del prefisso ID pacchetto.

Versione pacchetto

✔️ Prendere in considerazione l'uso di SemVer per la versione del pacchetto NuGet.

In pratica, questo significa usare il formato Major.Minor.Patch[-prerelease].

✔️ Pubblicare un pacchetto come pacchetto non definitive se non è stabile o un'anteprima.

Per indicazioni più avanzate, vedere la guida al controllo delle versioni della libreria .NET.

Autori

✔️ Usare il campo autore per il nome "piuttosto" dell'organizzazione o dell'organizzazione.

Ad esempio, se il nome utente NuGet.org è "jdoe", l'uso di "Jane Doe" per il campo autore può aiutare i consumatori a riconoscermi come autore. Se l'NuGet.org nome utente dell'organizzazione è "ContosoToolkit", l'uso di "Contoso Corporation" potrebbe essere più riconoscibile e ispirare maggiore fiducia dei consumatori.

Descrizione

✔️ DO include una breve descrizione (fino a 4000 caratteri) per descrivere il pacchetto.

Le descrizioni dei pacchetti sono uno dei campi più importanti visualizzati nella ricerca NuGet e probabilmente sarà la prima cosa che i potenziali consumer esaminano per determinare se un pacchetto è adatto per loro.

✔️ DO aggiungere una nota sul copyright al pacchetto con "Copyright (c) <name/company><year>".

Una nota sul copyright indica essenzialmente che il lavoro non può essere copiato senza l'autorizzazione dell'utente. L'inclusione di un avviso sul copyright nel pacchetto è facile e non farà alcun danno!

Esempio: Copyright (c) Contoso 2020

URL progetto

✔️ DO include un collegamento a un progetto, un repository o un sito Web aziendale associato.

Il sito del progetto deve avere tutti gli utenti che devono conoscere il pacchetto e probabilmente sarà la posizione in cui gli utenti cercano la documentazione.

Icon

✔️ PRENDERE IN CONSIDERAZIONE l'inclusione di un'icona con il pacchetto per facilitarne la differenziazione visiva. Si tratta di un'aggiunta relativamente piccola che può migliorare la percezione della qualità del pacchetto.

Le icone possono essere specifiche dei singoli pacchetti o essere un logo del marchio.

✔️ DO usa un'immagine 128x128 e ha uno sfondo trasparente (PNG) per ottenere risultati di visualizzazione ottimali.

NuGet ridimensiona automaticamente l'immagine nel client in cui viene visualizzata.

❌ NON usare la proprietà dei metadati deprecata IconUrl .

README

✔️ DO aggiungere un file markdown README che fornisce una panoramica delle operazioni eseguite dal pacchetto e di come iniziare.

Un pacchetto README migliorerà significativamente la percezione della qualità del pacchetto e l'onboarding di nuovi utenti. Valutare anche la possibilità di visualizzare in anteprima il file README prima di caricarlo. Per altri dettagli, vedere come includere un file README nel pacchetto NuGet.

Tipo di repository e URL

✔️ VALUTARE la possibilità di configurare il collegamento di origine per aggiungere automaticamente i metadati del controllo del codice sorgente al pacchetto NuGet e semplificare il debug della libreria.

Il collegamento di origine aggiunge Repository URL automaticamente e Repository Type ai metadati del pacchetto. Aggiunge anche il commit specifico associato alla versione del pacchetto.

Tag

✔️ DO include diversi tag con termini chiave correlati al pacchetto per migliorare l'individuabilità.

I tag vengono presi in considerazione nell'algoritmo di ricerca di NuGet.org e sono particolarmente utili per i termini che non sono nell'ID pacchetto, ma sono rilevanti.

Ad esempio, se è stato pubblicato un pacchetto per registrare le stringhe nella console, includerei: "logging, log, console, string, output"

Note sulla versione

✔️ Do include note sulla versione con ogni aggiornamento che descrive le modifiche apportate.

Anche se non è necessario alcun formato specifico per le note sulla versione, è consigliabile includere:

  1. Modifiche di rilievo
  2. Nuove funzionalità
  3. Correzioni di bug

Se si tengono già traccia delle note sulla versione o di un log delle modifiche nel repository, è anche possibile includere un collegamento al file pertinente.

Licenze

✔️ DO include un'espressione di licenza o un file di licenza nel pacchetto.

Importante

Un progetto senza una licenza prevede per impostazione predefinita copyright esclusivo, vale a dire che non si è concesso a nessuno l'autorizzazione per l'uso del progetto.

❌ NON usare la proprietà dei metadati deprecata LicenseUrl .

Ciò presenta ambiguità legale perché le modifiche alle licenze nell'URL cambieranno retroattivamente la licenza visualizzata per le versioni precedenti del pacchetto.

Se il pacchetto è open source

✔️ SCEGLIERE una licenza open source per rendere il pacchetto open source.

"Le licenze open source sono licenze conformi alla definizione open source, in breve consentono l'uso libero, la modifica e la condivisione del software". - Iniziativa open source. Per altre informazioni sul software open source e sull'iniziativa Open Source, vedere https://opensource.org/.

✔️ PRENDERE IN CONSIDERAZIONE l'inclusione di un'espressione di licenza nel pacchetto.

Le espressioni di licenza vengono visualizzate più chiaramente e rendono più ovvio agli utenti se possono usare il pacchetto o se la licenza è cambiata.

Nota

NuGet.org accetta solo espressioni di licenza per le licenze approvate dall'iniziativa Open Source o dalla Free Software Foundation.

Se il pacchetto non è open source

✔️ Do include un file di licenza nel pacchetto.

Qualsiasi file di licenza (.txt o md) può essere aggiunto al pacchetto, incluse le licenze non standard.