NuGet

Articolo
01/29/2025

NuGet è uno strumento di gestione pacchetti per l'ecosistema .NET ed è 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 di pacchetti NuGet, è l'host principale per i pacchetti NuGet pubblici, ma è possibile pubblicare in servizi NuGet personalizzati, ad esempio MyGet e Azure Artifacts.

Creare un pacchetto NuGet

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

Esistono due modi principali per creare un pacchetto NuGet. Il modo più recente e consigliato consiste nel creare un pacchetto da un progetto di tipo SDK (file di progetto il cui contenuto inizia con <Project Sdk="Microsoft.NET.Sdk">). Gli assembly e le destinazioni vengono aggiunti automaticamente al pacchetto e i metadati rimanenti vengono aggiunti al file MSBuild, ad esempio il nome del pacchetto e il numero di versione. La compilazione con il comando dotnet pack restituisce un file *.nupkg anziché gli 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 precedente per creare un pacchetto NuGet è costituito da un file *.nuspec e dallo strumento da riga di comando nuget.exe. Un file nuspec offre un ottimo controllo, ma è necessario specificare attentamente quali assembly e destinazioni includere nel pacchetto NuGet finale. È facile fare un errore o per qualcuno dimenticare di aggiornare il nuspec quando si apportano modifiche. Il vantaggio di un nuspec è che è possibile usarlo per creare pacchetti NuGet per framework che non supportano ancora un file di progetto in stile SDK.

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

Dipendenze dei pacchetti

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

Metadati importanti del pacchetto NuGet

Un pacchetto NuGet supporta molte proprietà dei metadati . La tabella seguente contiene i metadati di base che ogni pacchetto in NuGet.org deve fornire:

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

Importante

Un progetto privo di licenza è, per impostazione predefinita, protetto da copyright esclusivo, rendendo legalmente impossibile l'uso da parte di altre persone.

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

✔️ Usa un href https per l'icona del pacchetto.

I siti come NuGet.org sono eseguiti con HTTPS abilitato e la visualizzazione di un'immagine non HTTPS creerà un avviso di contenuto misto.

✔️ DO utilizza un'immagine dell'icona del pacchetto che sia 64x64 e abbia uno sfondo trasparente per una visualizzazione ottimale.

✔️ È consigliabile impostare Source Link per aggiungere metadati del controllo del codice sorgente agli assembly e al pacchetto NuGet.

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

Pacchetti prerelease

I pacchetti NuGet con un suffisso di versione vengono considerati versione preliminare. Per impostazione predefinita, l'interfaccia utente di Gestione pacchetti NuGet mostra le versioni stabili a meno che un utente non acconsenta esplicitamente ai pacchetti non definitive, rendendo i pacchetti non definitive ideali per i test utente limitati.

<PackageVersion>1.0.1-beta1</PackageVersion>

Nota

Un pacchetto stabile non può dipendere da un pacchetto prerelease. Devi rendere il tuo pacchetto una versione prerelease o dipendere da una versione stabile precedente.

dipendenza del pacchetto NuGet pre-rilascio

✔️ Pubblicare un pacchetto non definitivo per testare, visualizzare in anteprima o sperimentare.

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

Pacchetti di simboli

I file di simboli (*.pdb) vengono generati dal compilatore .NET insieme agli assembly. I file di simboli mappano i percorsi di esecuzione al codice sorgente originale, in modo da poter passare attraverso il codice sorgente mentre è in esecuzione usando un debugger. NuGet supporta la generazione di un pacchetto di simboli separato (*.snupkg) contenente file di simboli oltre al pacchetto principale contenente assembly .NET. L'idea dei pacchetti di simboli è ospitata in un server di simboli e viene scaricata 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 NuGet.org aggiungendo https://symbols.nuget.org/download/symbols alle origini dei simboli in Visual Studio.

Importante

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

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

Un'alternativa alla creazione di un pacchetto di simboli consiste nell'incorporare file di simboli nel pacchetto NuGet principale. Il pacchetto NuGet principale sarà più grande, ma i file di simboli incorporati indicano che gli sviluppatori non devono configurare il server dei simboli NuGet.org. Se si compila il pacchetto NuGet usando un progetto di tipo SDK, è possibile incorporare 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 dei file di simboli è che aumentano le dimensioni del pacchetto di circa 30% per le librerie .NET compilate usando progetti in stile SDK. Se le dimensioni del pacchetto sono un problema, è consigliabile pubblicare i simboli in un pacchetto di simboli.

✔️ CONSIDERARE la pubblicazione di simboli come pacchetto di simboli (*.snupkg) su NuGet.org

I pacchetti di simboli (*.snupkg) offrono agli sviluppatori un'esperienza di debug su richiesta senza gonfiare le dimensioni principali del pacchetto e influire sulle prestazioni di ripristino per coloro che non intendono eseguire il debug del pacchetto NuGet.

L'avvertenza è che gli utenti potrebbero dover trovare e configurare il server dei simboli NuGet nell'IDE (come configurazione una tantum) per ottenere 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.

Condividi tramite