Creare un pacchetto NuGet con l'interfaccia della riga di comando dotnet

  • Articolo

I pacchetti NuGet contengono codice che gli sviluppatori possono riutilizzare nei progetti. Indipendentemente da ciò che il codice esegue o contiene, si usa uno strumento da riga di comando, nuget.exe o dotnet.exe, per creare il pacchetto NuGet.

Questo articolo descrive come creare un pacchetto usando l'interfaccia della riga di comando dotnet. A partire da Visual Studio 2017, l'interfaccia della riga di comando dotnet è inclusa in tutti i carichi di lavoro .NET e .NET Core. Se è necessario installare l'interfaccia della riga di comando dotnet o altri strumenti client NuGet, vedere Installare gli strumenti client NuGet.

Questo argomento si applica solo a .NET e ad altri progetti che usano il formato sdk. Per questi progetti, NuGet usa le informazioni del file di progetto per creare un pacchetto. Per esercitazioni introduttive, vedere Creare pacchetti con l'interfaccia della riga di comando dotnet o Creare pacchetti con Visual Studio.

Il comando msbuild msbuild -t:pack è funzionalmente equivalente a dotnet pack. Per altre informazioni sulla creazione di un pacchetto con MSBuild, vedere Creare un pacchetto NuGet con MSBuild.

Nota

Impostare le proprietà

È possibile creare un progetto di libreria di classi di esempio usando il dotnet new classlib comando e creare un pacchetto del progetto usando dotnet pack. Il dotnet pack comando usa le proprietà seguenti. Se non si specificano valori nel file di progetto, il comando usa i valori predefiniti.

  • PackageId, l'identificatore del pacchetto deve essere univoco in nuget.org e in tutte le altre destinazioni che ospitano il pacchetto. Se non si specifica un valore, il comando usa .AssemblyName
  • Version è un numero di versione specifico nel formato Major.Minor.Patch[-Suffix], dove -Suffix identifica le versioni non definitive. Se non è specificato, il valore predefinito è 1.0.0.
  • Authors sono gli autori del pacchetto. Se non specificato, il valore predefinito è .AssemblyName
  • Company sono informazioni aziendali. Se non specificato, il valore predefinito è il Authors valore .
  • Product sono informazioni sul prodotto. Se non specificato, il valore predefinito è .AssemblyName

In Visual Studio è possibile impostare questi valori nelle proprietà del progetto. Fare clic con il pulsante destro del mouse sul progetto in Esplora soluzioni, scegliere Proprietà e quindi selezionare la sezione Pacchetto. È anche possibile aggiungere le proprietà direttamente al file con estensione csproj o ad altro file di progetto.

Nell'esempio seguente viene illustrato un file di progetto con proprietà del pacchetto aggiunte.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>UniqueID</PackageId>
    <Version>1.0.0</Version>
    <Authors>Author Name</Authors>
    <Company>Company Name</Company>
    <Product>Product Name</Product>
  </PropertyGroup>
</Project>

È possibile aggiungere altre proprietà facoltative, ad esempio Title, PackageDescriptione PackageTags.

Nota

Per i pacchetti compilati per l'utilizzo pubblico, prestare particolare attenzione alla PackageTags proprietà . I tag aiutano gli altri a trovare il pacchetto e a capire cosa fa.

Il dotnet pack comando converte PackageReferenceautomaticamente i file di progetto in dipendenze nel pacchetto creato. È possibile controllare quali asset includere tramite i IncludeAssetstag e ExcludeAssetsPrivateAssets . Per altre informazioni, vedere Controllo degli asset di dipendenza.

Per altre informazioni sulle dipendenze, sulle proprietà facoltative e sul controllo delle versioni, vedere:

Scegliere un identificatore univoco del pacchetto e impostare il numero di versione

L'identificatore del pacchetto e il numero di versione identificano in modo univoco il codice esatto contenuto nel pacchetto.

Seguire queste procedure consigliate per creare l'identificatore del pacchetto:

  • L'identificatore deve essere univoco tra nuget.org e tutte le altre posizioni che ospitano il pacchetto. Per evitare conflitti, un modello valido consiste nell'usare il nome della società come prima parte dell'identificatore.

  • Seguire una convenzione di denominazione simile allo spazio dei nomi .NET usando la notazione punto. Usare, ad esempio, Contoso.Utility.UsefulStuff invece di Contoso-Utility-UsefulStuff o Contoso_Utility_UsefulStuff. È anche utile per i consumer se si trova la corrispondenza tra l'identificatore del pacchetto e lo spazio dei nomi usato dal codice.

  • Se si produce un pacchetto di codice di esempio che illustra come usare un altro pacchetto, aggiungere .Sample all'identificatore, come in Contoso.Utility.UsefulStuff.Sample.

    Il pacchetto di esempio ha una dipendenza dal pacchetto originale. Quando si crea il pacchetto di esempio, aggiungere <IncludeAssets> con il contentFiles valore . Nella cartella del contenuto disporre il codice di esempio in una cartella denominata \Samples\<identifier>, ad esempio \Samples\Contoso.Utility.UsefulStuff.Sample.

Seguire queste procedure consigliate per impostare la versione del pacchetto:

  • In generale, impostare la versione del pacchetto in modo che corrisponda alla versione del progetto o dell'assembly, anche se non è strettamente necessaria. La corrispondenza della versione è semplice quando si limita un pacchetto a un singolo assembly. NuGet gestisce autonomamente le versioni dei pacchetti durante la risoluzione delle dipendenze, non le versioni degli assembly.

  • Se si usa uno schema di versione non standard, assicurarsi di prendere in considerazione le regole di controllo delle versioni di NuGet, come illustrato in Controllo delle versioni dei pacchetti. NuGet è principalmente conforme al controllo delle versioni semantiche 2.0.0.

Nota

Per altre informazioni sulla risoluzione delle dipendenze, vedere Risoluzione delle dipendenze con PackageReference. Per informazioni utili per comprendere il controllo delle versioni, vedere questa serie di post di blog:

Aggiungere un campo di descrizione facoltativo

La descrizione facoltativa del pacchetto viene visualizzata nella scheda LEGGIMI della pagina nuget.org del pacchetto. La descrizione estrae da <Description> nel file di progetto o $description nel file con estensione nuspec.

L'esempio seguente mostra un Description oggetto nel file con estensione csproj per un pacchetto .NET:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Azure.Storage.Blobs</PackageId>
    <Version>12.4.0</Version>
    <PackageTags>Microsoft Azure Storage Blobs;Microsoft;Azure;Blobs;Blob;Storage;StorageScalable</PackageTags>
    <Description>
      This client library enables working with the Microsoft Azure Storage Blob service for storing binary and text data.
      For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md and https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/CHANGELOG.md
      in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/BreakingChanges.txt
      Microsoft Azure Storage quickstarts and tutorials - https://learn.microsoft.com/azure/storage/
      Microsoft Azure Storage REST API Reference - https://learn.microsoft.com/rest/api/storageservices/
      REST API Reference for Blob Service - https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</Project>

Eseguire il comando pack

Per compilare il pacchetto NuGet o il file con estensione nupkg , eseguire il comando dotnet pack dalla cartella del progetto, che compila automaticamente anche il progetto.

dotnet pack

L'output mostra il percorso del file con estensione nupkg :

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj (in 97 ms).
  Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'.

Generare automaticamente il pacchetto in fase di compilazione

Per eseguire dotnet pack automaticamente ogni volta che si esegue dotnet build, aggiungere la riga seguente al file di <PropertyGroup> progetto nel tag :

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Nota

Quando si genera automaticamente il pacchetto, la compressione aumenta il tempo di compilazione per il progetto.

In esecuzione dotnet pack in una soluzione vengono inseriti tutti i progetti nella soluzione che possono essere inseriti in pacchetti, ovvero la IsPackable proprietà è impostata su true.

Testare l'installazione del pacchetto

Prima di pubblicare un pacchetto, è necessario testare l'installazione del pacchetto in un progetto. Il test garantisce che i file necessari finissi nelle posizioni corrette del progetto.

Testare l'installazione manualmente in Visual Studio o nella riga di comando usando il normale processo di installazione del pacchetto.

Importante

  • Non è possibile modificare i pacchetti dopo la creazione. Se si corregge un problema, modificare il contenuto del pacchetto e ricomprimere.

  • Dopo aver ricreato il pacchetto, la ricresting usa ancora la versione precedente del pacchetto fino a quando non si cancella la cartella dei pacchetti globali. La cancellazione della cartella è particolarmente importante per i pacchetti che non usano un'etichetta di versione preliminare univoca in ogni compilazione.

Passaggi successivi

Dopo aver creato il pacchetto, è possibile pubblicare il file con estensione nupkg nell'host preferito.

Pubblicare un pacchetto

Vedere gli articoli seguenti per informazioni su come estendere le funzionalità del pacchetto o supportare altri scenari: