NuGet

NuGet è uno strumento di gestione pacchetti per l'ecosistema .NET e rappresenta il modo principale in cui gli sviluppatori individuano e acquisiscono librerie open source .NET. NuGet.org, un servizio gratuito fornito da Microsoft per l'hosting dei pacchetti NuGet, è l'host primario per i pacchetti NuGet pubblici, ma è possibile eseguire la pubblicazione in servizi NuGet personalizzati, come MyGet e Azure Artifacts.

Creare un pacchetto NuGet

Un pacchetto NuGet (*.nupkg) è un file ZIP che contiene gli assembly .NET e i metadati associati.

Ci sono due modi principali per creare un pacchetto NuGet. Il modo più recente e consigliato consiste nel creare un pacchetto da un progetto in stile SDK (file di progetto il cui contenuto inizia con <Project Sdk="Microsoft.NET.Sdk">). Destinazioni e assembly vengono aggiunti automaticamente al pacchetto e i metadati rimanenti vengono aggiunti al file MSBuild, ad esempio numero di versione e nome del pacchetto. La compilazione con il comando dotnet pack genera un file *.nupkg invece di assembly.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <AssemblyName>Contoso.Api</AssemblyName>
    <PackageVersion>1.1.0</PackageVersion>
    <Authors>John Doe</Authors>
  </PropertyGroup>
</Project>

Il modo meno recente per creare un pacchetto NuGet consiste nell'usare un file *.nuspec e lo strumento da riga di comando nuget.exe. Un file nuspec offre uno straordinario controllo, ma è necessario specificare attentamente quali assembly e destinazioni includere nel pacchetto NuGet finale. È facile commette un errore o dimenticarsi di aggiornare il file nuspec quando si apportano modifiche. Il vantaggio di un file nuspec è la possibilità di usarlo per creare pacchetti NuGet per framework che ancora non supportano un file di progetto in stile SDK.

✔️ VALUTARE l'uso di un file di progetto in stile SDK per creare il pacchetto NuGet.

Dipendenze dei pacchetti

Le dipendenze dei pacchetti NuGet sono illustrate in dettaglio nell'articolo Dipendenze.

Metadati importanti dei pacchetti NuGet

Un pacchetto NuGet supporta numerose proprietà dei metadati. La tabella seguente contiene i principali metadati che deve offrire ogni pacchetto in NuGet.org:

Nome proprietà MSBuild	Nome nuspec	Descrizione
PackageId	id	Identificatore di pacchetto. Un prefisso dell'identificatore può essere riservato se soddisfa i criteri.
PackageVersion	version	Versione del pacchetto NuGet. Per altre informazioni, vedere Versione dei pacchetti NuGet.
Title	title	Titolo descrittivo del pacchetto. Il valore predefinito è PackageId.
Description	description	Descrizione lunga del pacchetto visualizzata nell'interfaccia utente.
Authors	authors	Elenco di autori del pacchetto delimitati da virgole, corrispondenti ai nomi dei profili in nuget.org.
PackageTags	tags	Elenco di tag e parole chiave delimitati da spazi o punti e virgola che descrivono il pacchetto. I tag vengono usati per la ricerca di pacchetti.
PackageIcon	icon	Percorso di un'immagine nel pacchetto da usare come icona del pacchetto. Altre informazioni sui metadati icon.
PackageProjectUrl	projectUrl	URL della home page del progetto o del repository di origine.
PackageLicenseExpression	license	Identificatore SPDX della licenza del progetto. Solo le licenze con approvazione OSI e FSF possono usare un identificatore. Le altre licenze devono usare PackageLicenseFile. Altre informazioni sui metadati license.

Importante

Per un progetto senza una licenza viene applicato per impostazione predefinita il copyright esclusivo, che ne impedisce a livello legale l'uso da parte di altre persone.

✔️ VALUTARE la scelta di un nome di pacchetto NuGet con un prefisso che soddisfi i criteri per prenotare il prefisso NuGet.

✔️ USARE un attributo href HTTPS per l'icona del pacchetto.

I siti come NuGet.org vengono eseguiti con il protocollo HTTPS abilitato e la visualizzazione di un'immagine non HTTPS comporta la generazione di un avviso di contenuto misto.

✔️ USARE un'immagine di icona del pacchetto con dimensioni di 64x64 e con uno sfondo trasparente per ottenere una migliore visualizzazione.

✔️ VALUTARE la configurazione di Source Link per aggiungere metadati di controllo del codice sorgente agli assembly e al pacchetto NuGet.

Il collegamento all'origine aggiunge automaticamente metadati RepositoryUrl e RepositoryType al pacchetto NuGet. Il collegamento all'origine aggiunge anche informazioni sul codice sorgente esatto da cui è stato compilato il pacchetto. Ad esempio, a un pacchetto creato da un repository Git verrà aggiunto l'hash commit come metadati.

Pacchetti in versione non definitiva

I pacchetti NuGet con un suffisso di versione sono considerati versioni non definitive. Per impostazione predefinita, l'interfaccia utente di Gestione pacchetti NuGet mostra le versioni stabili, a meno che un utente non scelga esplicitamente pacchetti in versione non definitiva, ideali per test utente limitati.

<PackageVersion>1.0.1-beta1</PackageVersion>

Nota

Una pacchetto stabile non può dipendere da un pacchetto in versione non definitiva. È necessario impostare un pacchetto come versione non definitiva oppure fare in modo che dipenda da una versione stabile precedente.

✔️ PUBBLICARE un pacchetto in versione non definitiva a scopi di test, anteprima o sperimentazione.

✔️ PUBBLICARE un pacchetto stabile quando è pronto, in modo che altri pacchetti stabili possano farvi riferimento.

Pacchetti di simboli

I file di simboli (*.pdb) vengono prodotti dal compilatore .NET insieme agli assembly. I file di simboli mappano le posizioni di esecuzione al codice sorgente originale, in modo che sia possibile esaminare il codice sorgente mentre è in esecuzione usando un debugger. NuGet supporta la generazione di un pacchetto di simboli separato (*.snupkg) contenente i file di simboli insieme al pacchetto principale che contiene gli assembly .NET. L'idea dei pacchetti di simboli è che siano ospitati in un server di simboli e scaricati solo da uno strumento come Visual Studio su richiesta.

NuGet.org ospita il proprio repository del server dei simboli. Gli sviluppatori possono usare i simboli pubblicati nel server dei simboli di NuGet.org aggiungendo https://symbols.nuget.org/download/symbols alle loro origini di simboli in Visual Studio.

Importante

Il server dei simboli di NuGet.org supporta solo i nuovi file di simboli portatili (*.pdb) creati da progetti in stile SDK.

Per usare il server dei simboli di NuGet.org per il debug di una libreria .NET, gli sviluppatori devono avere Visual Studio 2017 15.9 o versioni successive.

Un'alternativa alla creazione di un pacchetto di simboli è incorporare i file di simboli nel pacchetto NuGet principale. Il pacchetto NuGet principale è di dimensioni maggiori, tuttavia, grazie ai file di simboli incorporati gli sviluppatori non devono configurare il server di simboli NuGet.org. Se si sta creando un pacchetto NuGet usando un progetto in stile SDK, è possibile incorporare i file di simboli impostando la proprietà AllowedOutputExtensionsInPackageBuildOutputFolder:

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
    <!-- Include symbol files (*.pdb) in the built .nupkg -->
    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
  </PropertyGroup>
</Project>

Lo svantaggio dell'incorporamento di file di simboli è che aumentano le dimensioni del pacchetto di circa il 30% per le librerie .NET compilate con i progetti di tipo SDK. Se le dimensioni del pacchetto costituiscono un problema, i simboli dovranno essere pubblicati in un pacchetto di simboli.

✔️ VALUTARE la punnlicazione di simboli come un pacchetto di simboli (*.snupkg) in NuGet.org

I pacchetti di simboli (*.snupkg) rappresentano una buona esperienza di debug on demand per gli sviluppatori perché non fanno aumentare le dimensioni del pacchetto principale né interferiscono con le prestazioni del ripristino per gli utenti che non intendono eseguire il debug del pacchetto NuGet.

L'unico inconveniente è costituito dal fatto che gli utenti potrebbero dover individuare e configurare, una sola volta, il server di simboli NuGet nel proprio IDE per acquisire i file di simboli. Visual Studio 2019 versione 16.1 ha aggiunto il server dei simboli di NuGet.org all'elenco dei server di simboli predefiniti.

PrecedenteSuccessivo