Condividi tramite

Creare un pacchetto NuGet con MSBuild

Quando si crea un pacchetto NuGet dal codice, si inserisce tale funzionalità in un componente che può essere condiviso e usato da un numero qualsiasi di altri sviluppatori. Questo articolo descrive come creare un pacchetto usando MSBuild. MSBuild è preinstallato con ogni carico di lavoro di Visual Studio che contiene NuGet. È anche possibile usare MSBuild tramite l'interfaccia della riga di comando dotnet con dotnet msbuild.

Per i progetti .NET Core e .NET Standard che usano il formato SDK e qualsiasi altro progetto in stile SDK, NuGet usa le informazioni nel file di progetto direttamente per creare un pacchetto. Per un progetto non in stile SDK che usa <PackageReference>, NuGet usa anche il file di progetto per creare un pacchetto.

I progetti in stile SDK hanno la funzionalità pack disponibile per impostazione predefinita. Per i progetti PackageReference non in stile SDK, è disponibile anche per impostazione predefinita a partire da Visual Studio 2026. Nelle versioni precedenti di Visual Studio è necessario aggiungere il pacchetto NuGet.Build.Tasks.Pack alle dipendenze del progetto ed è consigliabile rimuovere questo riferimento al pacchetto durante l'aggiornamento a Visual Studio 2026. Per informazioni dettagliate sugli obiettivi del pacchetto MSBuild, consultare Pacchetto NuGet e ripristino come obiettivi MSBuild.

Per i progetti in stile SDK, msbuild -t:pack è funzionalmente equivalente a dotnet pack.

Importante

Questo argomento si applica ai progetti in stile SDK , in genere progetti .NET Core e .NET Standard e a progetti non in stile SDK che usano PackageReference.

Impostare le proprietà

Per creare un pacchetto sono necessarie le proprietà seguenti.

  • PackageId, l'identificatore del pacchetto, che deve essere univoco nella raccolta che ospita il pacchetto. Se non è specificato, il valore predefinito è 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.
  • Il titolo del pacchetto come dovrebbe apparire nell'host (ad esempio nuget.org)
  • Authors, informazioni sull'autore e sul proprietario. Se non è specificato, il valore predefinito è AssemblyName.
  • Company, il nome dell'azienda. Se non è specificato, il valore predefinito è AssemblyName.

Inoltre, se si esegue l'impacchettamento di progetti in stile non-SDK che usano PackageReference, è necessario quanto segue:

  • PackageOutputPath, la cartella di output per il pacchetto generato quando si chiama il comando pack.

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 selezionare la scheda Pacchetto ). È anche possibile impostare queste proprietà direttamente nei file di progetto (con estensione csproj).

<PropertyGroup>
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>your_name</Authors>
  <Company>your_company</Company>
</PropertyGroup>

Importante

Assegnare al pacchetto un identificatore univoco in nuget.org o nell'origine del pacchetto in uso.

L'esempio seguente mostra un file di progetto semplice e completo con queste proprietà incluse.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>ClassLibDotNetStandard</PackageId>
    <Version>1.0.0</Version>
    <Authors>your_name</Authors>
    <Company>your_company</Company>
  </PropertyGroup>
</Project>

È anche possibile impostare le proprietà facoltative, ad esempio Title, PackageDescriptione PackageTags, come descritto in Destinazioni del pacchetto MSBuild, Controllo degli asset di dipendenza e proprietà dei metadati NuGet.

Annotazioni

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

Per informazioni dettagliate sulla dichiarazione delle dipendenze e sulla specifica dei numeri di versione, vedere Riferimenti ai pacchetti nei file di progetto e controllo delle versioni dei pacchetti. È anche possibile visualizzare gli asset dalle dipendenze direttamente nel pacchetto usando gli <IncludeAssets> attributi e <ExcludeAssets> . Per altre informazioni, vedere Controllare gli asset di dipendenza.

Aggiungere un campo di descrizione facoltativo

La descrizione facoltativa del pacchetto viene visualizzata nella scheda README della pagina nuget.org del pacchetto. La descrizione viene estratta dal <Description> nel file di progetto o dal $description nel file .nuspec.

L'esempio seguente mostra un Description nel file .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>

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 in nuget.org e in 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, utilizzando la notazione a punto. Ad esempio, usare Contoso.Utility.UsefulStuff anziché Contoso-Utility-UsefulStuff o Contoso_Utility_UsefulStuff. È anche utile per i consumatori se si abbina l'identificatore del pacchetto allo 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 valore contentFiles. 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.

Annotazioni

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:

Configurare il progetto per il pacchetto

I progetti in stile SDK non richiedono alcuna configurazione aggiuntiva.

I progetti non in stile SDK richiedono almeno un pacchetto installato (tramite PackageReference, non packages.config) o il progetto deve indicare esplicitamente a NuGet di considerare il progetto come progetto PackageReference tramite la RestoreProjectStyle proprietà .

Visual Studio 2022 e versioni precedenti non dispone del pacchetto incorporato, quindi è anche necessario installare il pacchetto NuGet.Build.Tasks.Pack. Quando si esegue l'aggiornamento a Visual Studio 2026 o versione successiva, è consigliabile disinstallare il pacchetto in modo da trarre vantaggio da nuove funzionalità e correzioni di bug.

  1. Modificare il file di progetto.

    Se si vuole indicare in modo esplicito a NuGet di considerare il progetto come PackageReference (il progetto non dispone di pacchetti installati), trovare o aggiungere un oggetto <PropertyGroup> che non dispone di alcuna Condition istruzione e aggiungere:

    <PropertyGroup>
  <!-- other properties -->
  <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
  <!-- more properties are allowed -->
</PropertyGroup>

    Se si usa Visual Studio 2022 o versioni precedenti, aggiungere quanto segue dopo l'elemento <PropertyGroup> :

    <ItemGroup>
  <!-- ... -->
  <PackageReference Include="NuGet.Build.Tasks.Pack" Version="6.14.0" PrivateAssets="all" />
  <!-- ... -->
</ItemGroup>

    Annotazioni

    Prendere in considerazione l'uso della versione più recente di questo pacchetto disponibile.

  2. Aprire un prompt dei comandi per gli sviluppatori (nella casella Cerca digitare Prompt dei comandi per sviluppatori).

    In genere si vuole avviare il prompt dei comandi per gli sviluppatori per Visual Studio dal menu Start , perché verrà configurato con tutti i percorsi necessari per MSBuild.

  3. Passare alla cartella contenente il file di progetto e digitare il comando seguente per ripristinare il pacchetto NuGet.Build.Tasks.Pack.

    # Uses the project file in the current folder by default
msbuild -t:restore

    Assicurarsi che l'output di MSBuild indichi che la compilazione è stata completata correttamente.

Eseguire il comando msbuild -t:pack

Per compilare un pacchetto NuGet (un .nupkg file) dal progetto, eseguire il msbuild -t:pack comando , che compila automaticamente anche il progetto:

Nel prompt dei comandi per gli sviluppatori per Visual Studio digitare il comando seguente:

# Uses the project file in the current folder by default
msbuild -t:pack

L'output mostra il percorso del .nupkg file.

Microsoft (R) Build Engine version 16.1.76+g14b0a930a7 for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.

Build started 8/5/2019 3:09:15 PM.
Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" on node 1 (pack target(s)).
GenerateTargetFrameworkMonikerAttribute:
Skipping target "GenerateTargetFrameworkMonikerAttribute" because all output files are up-to-date with respect to the input files.
CoreCompile:
  ...
CopyFilesToOutputDirectory:
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.dll" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll".
  ClassLib_DotNetStandard -> C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb".
GenerateNuspec:
  Successfully created package 'C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\AppLogger.1.0.0.nupkg'.
Done Building Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" (pack target(s)).

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:01.21

Generare automaticamente il pacchetto alla compilazione

Per eseguire msbuild -t:pack automaticamente quando si compila o si ripristina il progetto, aggiungere la riga seguente al file di progetto all'interno di <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Quando si esegue msbuild -t:pack in una soluzione, vengono inseriti tutti i progetti nella soluzione che sono comprimibili (<IsPackable> la proprietà è impostata su true).

Annotazioni

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

Installazione del pacchetto di test

Prima di pubblicare un pacchetto, in genere si vuole testare il processo di installazione di un pacchetto in un progetto. I test assicurano che tutti i file necessari vengano inseriti nei loro posti corretti nel progetto.

È possibile testare le installazioni manualmente in Visual Studio o nella riga di comando usando i normali passaggi di installazione del pacchetto.

Importante

I pacchetti non sono modificabili. Se si corregge un problema, modificare il contenuto del pacchetto e impacchettare di nuovo, quando si esegui nuovamente il test si utilizza ancora la vecchia versione del pacchetto fino a quando non si cancella la cartella dei pacchetti globali. Ciò è particolarmente rilevante quando si testano pacchetti che non usano un'etichetta di versione preliminare univoca in ogni compilazione.

Passaggi successivi

Dopo aver creato un pacchetto, ovvero un .nupkg file, è possibile pubblicarlo nella raccolta di propria scelta, come descritto in Pubblicazione di un pacchetto.

È anche possibile estendere le funzionalità del pacchetto o supportare altri scenari, come descritto negli argomenti seguenti:

Infine, sono disponibili altri tipi di pacchetto da tenere presenti:

  • Last updated on