Creare un pacchetto usando l'interfaccia della riga di comando di nuget.exe

Indipendentemente dalle operazioni del pacchetto o dal codice che contiene, è possibile usare uno degli strumenti dell'interfaccia della riga di comando, nuget.exe o dotnet.exe, per creare un pacchetto di tale funzionalità in un componente che può essere condiviso e usato da un numero qualsiasi di altri sviluppatori. Per installare gli strumenti dell'interfaccia della riga di comando di NuGet, vedere Installare gli strumenti client NuGet. Si noti che Visual Studio non include automaticamente uno strumento dell'interfaccia della riga di comando.

• Per i progetti non in stile SDK, in genere progetti .NET Framework, seguire la procedura descritta in questo articolo per creare un pacchetto. Per istruzioni dettagliate sull'uso di Visual Studio e dell'interfaccia della nuget.exe riga di comando, vedere Creare e pubblicare un pacchetto .NET Framework.

• Per i progetti .NET Core e .NET Standard che usano il formato in stile SDK e per tutti gli altri progetti in stile SDK, vedere Creare un pacchetto NuGet usando l'interfaccia della riga di comando dotnet.

• Per i progetti migrati da packages.config a PackageReference, usare msbuild -t:pack.

Tecnicamente, un pacchetto NuGet è solo un file ZIP rinominato con l'estensione e il .nupkg cui contenuto corrisponde a determinate convenzioni. In questo argomento viene descritto il processo dettagliato di creazione di un pacchetto che soddisfi tali convenzioni.

La creazione di pacchetti inizia con il codice compilato (assembly), i simboli e/o altri file che si desidera recapitare come pacchetto (vedere Panoramica e flusso di lavoro). Questo processo è indipendente dalla compilazione o dalla generazione di file che vengono inseriti nel pacchetto, anche se è possibile ricavare informazioni in un file di progetto per mantenere sincronizzati gli assembly e i pacchetti compilati.

Decidere quali assembly includere nel pacchetto

La maggior parte dei pacchetti per utilizzo generico contiene uno o più assembly che altri sviluppatori possono usare nei propri progetti.

• In generale, è consigliabile avere un assembly per ogni pacchetto NuGet, purché ogni assembly sia utile in modo indipendente. Ad esempio, se si dispone di un oggetto Utilities.dll che dipende da Parser.dll, e Parser.dll è utile da sola, creare un pacchetto per ognuno di essi. In questo modo gli sviluppatori possono usare Parser.dll indipendentemente da Utilities.dll.

• Se la libreria è costituita da più assembly che non sono utili in modo indipendente, è consigliabile combinarli in un unico pacchetto. Usando l'esempio precedente, se Parser.dll contiene codice usato solo da Utilities.dll, è consigliabile conservarlo Parser.dll nello stesso pacchetto.

• Analogamente, se Utilities.dll dipende da Utilities.resources.dll, dove di nuovo quest'ultimo non è utile da solo, quindi inserire entrambi nello stesso pacchetto.

Le risorse sono, infatti, un caso speciale. Quando un pacchetto viene installato in un progetto, NuGet aggiunge automaticamente i riferimenti all'assembly alle DLL del pacchetto, escluse quelle denominate .resources.dll perché si presuppone che siano assembly satellite localizzati (vedere Creazione di pacchetti localizzati). Per questo motivo, evitare di usare .resources.dll per i file che altrimenti contengono codice di pacchetto essenziale.

Se la libreria contiene assembly di interoperabilità COM, seguire le linee guida aggiuntive in Creare pacchetti con assembly di interoperabilità COM.

Ruolo e struttura del file .nuspec

Dopo aver appreso quali file si desidera creare un pacchetto, il passaggio successivo consiste nel creare un manifesto del pacchetto in un .nuspec file XML.

Il manifesto:

1. Descrive il contenuto del pacchetto ed è incluso nel pacchetto.
2. Determina sia la creazione del pacchetto che indica a NuGet come installare il pacchetto in un progetto. Ad esempio, il manifesto identifica altre dipendenze del pacchetto, in modo che NuGet possa anche installare tali dipendenze quando viene installato il pacchetto principale.
3. Contiene proprietà obbligatorie e facoltative, come descritto di seguito. Per informazioni esatte, incluse altre proprietà non menzionate qui, vedere le informazioni di riferimento su .nuspec.

Proprietà obbligatorie:

• Identificatore del pacchetto, che deve essere univoco nella raccolta che ospita il pacchetto.
• Numero di versione specifico nel formato Major.Minor.Patch[-Suffix] dove -Suffix identifica le versioni non definitive
• Il titolo del pacchetto come dovrebbe apparire nell'host (ad esempio nuget.org)
• Informazioni sull'autore e sul proprietario.
• Descrizione lunga del pacchetto.

Proprietà opzionali comuni:

• Note di rilascio
• Informazioni sul copyright
• Breve descrizione per l'interfaccia utente di Gestione pacchetti in Visual Studio
• ID locale
• URL progetto
• Licenza come espressione o file (licenseUrl è deprecato, usare invece l'elementolicense di metadati nuspec)
• Un file icona (iconUrl è deprecato, usare invece l'elemento di metadati icon nuspec)
• Elenchi di dipendenze e riferimenti
• Tag utili per le ricerche nella galleria

Di seguito è riportato un file tipico (ma fittizio), .nuspec con commenti che descrivono le proprietà:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Identifier that must be unique within the hosting gallery -->
        <id>Contoso.Utility.UsefulStuff</id>

        <!-- Package version number that is used when resolving dependencies -->
        <version>1.8.3</version>

        <!-- Authors contain text that appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- 
            Owners are typically nuget.org identities that allow gallery
            users to easily find other packages by the same owners.  
        -->
        <owners>dejanatc, rjdey</owners>
        
         <!-- Project URL provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

         <!-- License information is displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        

        <!-- Icon is used in Visual Studio's package manager UI -->
        <icon>icon.png</icon>

        <!-- 
            If true, this value prompts the user to accept the license when
            installing the package. 
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Any details about this particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

        <!-- 
            The description can be used in package manager UI. Note that the
            nuget.org gallery uses information you add in the portal. 
        -->
        <description>Core utility functions for web applications</description>

        <!-- Copyright information -->
        <copyright>Copyright ©2016 Contoso Corporation</copyright>

        <!-- Tags appear in the gallery and can be used for tag searches -->
        <tags>web utility http json url parsing</tags>

        <!-- Dependencies are automatically installed when the package is installed -->
        <dependencies>
            <dependency id="Newtonsoft.Json" version="9.0" />
        </dependencies>
    </metadata>

    <!-- A readme.txt to display when the package is installed -->
    <files>
        <file src="readme.txt" target="" />
        <file src="icon.png" target="" />
    </files>
</package>

Per informazioni dettagliate sulla dichiarazione delle dipendenze e sulla specifica dei numeri di versione, vedere packages.config e Controllo delle versioni dei pacchetti. È anche possibile visualizzare gli asset dalle dipendenze direttamente nel pacchetto usando gli attributi include e exclude sull'elemento dependency. Vedere .nuspec Reference - Dependencies (Informazioni di riferimento su .nuspec - Dipendenze).

Poiché il manifesto è incluso nel pacchetto creato da esso, è possibile trovare un numero qualsiasi di esempi aggiuntivi esaminando i pacchetti esistenti. Una buona origine è la cartella global-packages nel computer, il cui percorso viene restituito dal comando seguente:

nuget locals -list global-packages

Passare a qualsiasi cartella package\version , copiare il .nupkg file in un .zip file, quindi aprire il .zip.nuspec file ed esaminarlo al suo interno.

Creare il file con estensione nuspec

La creazione di un manifesto completo inizia in genere con un file di base .nuspec generato tramite uno dei metodi seguenti:

• Directory di lavoro basata su convenzioni
• DLL di assemblaggio
• Un progetto di Visual Studio
• Nuovo file con valori predefiniti

Si modifica quindi il file a mano in modo che descriva il contenuto esatto desiderato nel pacchetto finale.

Da una directory di lavoro basata su convenzioni

Poiché un pacchetto NuGet è solo un file ZIP rinominato con l'estensione .nupkg , spesso è più semplice creare la struttura di cartelle desiderata nel file system locale, quindi creare il .nuspec file direttamente da tale struttura. Il nuget pack comando aggiunge quindi automaticamente tutti i file nella struttura di cartelle , escluse le cartelle che iniziano con ., consentendo di mantenere i file privati nella stessa struttura.

Il vantaggio di questo approccio è che non è necessario specificare nel manifesto quali file si desidera includere nel pacchetto (come illustrato più avanti in questo argomento). È sufficiente che il processo di compilazione producano la struttura di cartelle esatta che viene inserita nel pacchetto ed è possibile includere facilmente altri file che potrebbero non far parte di un progetto altrimenti:

• Contenuto e codice sorgente da inserire nel progetto di destinazione.
• Script di PowerShell
• Trasformazioni in file di codice sorgente e di configurazione esistenti in un progetto.

Le convenzioni di cartella sono le seguenti:

Poiché la struttura di cartelle può contenere un numero qualsiasi di assembly per un numero qualsiasi di framework di destinazione, questo metodo è necessario quando si creano pacchetti che supportano più framework.

In ogni caso, dopo aver creato la struttura di cartelle desiderata, eseguire il comando seguente in tale cartella per creare il .nuspec file:

nuget spec

Anche in questo caso, l'oggetto generato .nuspec non contiene riferimenti espliciti ai file nella struttura di cartelle. NuGet include automaticamente tutti i file quando viene creato il pacchetto. È comunque necessario modificare i valori segnaposto in altre parti del manifesto.

Da una DLL di assembly

Nel semplice caso di creazione di un pacchetto da un assembly, è possibile generare un .nuspec file dai metadati nell'assembly usando il comando seguente:

nuget spec <assembly-name>.dll

L'utilizzo di questo formulario sostituisce alcuni segnaposto nel manifest con valori specifici provenienti dall'assembly. Ad esempio, la <id> proprietà viene impostata sul nome dell'assembly e <version> viene impostata sulla versione dell'assembly. Altre proprietà nel manifest, tuttavia, non hanno valori corrispondenti nell'assembly e pertanto contengono ancora segnaposti.

Da un progetto di Visual Studio

La creazione di un .nuspec da un .csproj o da un .vbproj è conveniente perché i pacchetti installati in questi progetti possono essere automaticamente indicati come dipendenze. Usare semplicemente il comando seguente nella stessa cartella del file di progetto:

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget spec

Il file risultante <project-name>.nuspec contiene token che vengono sostituiti in fase di creazione del pacchetto con valori del progetto, inclusi i riferimenti a tutti gli altri pacchetti già installati.

Se si hanno dipendenze del pacchetto da includere in .nuspec, usare nuget pack al suo posto e recuperare il file con estensione .nuspec dall'interno del file con estensione .nupkg generato. Ad esempio, usare il comando seguente.

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget pack myproject.csproj

Un token è delimitato da $ simboli su entrambi i lati della proprietà del progetto. Ad esempio, il <id> valore in un manifesto generato in questo modo viene in genere visualizzato come segue:

<id>$id$</id>

Questo token viene sostituito con il AssemblyName valore del file di progetto in fase di compressione. Per il mapping esatto dei valori del progetto ai .nuspec token, vedere le informazioni di riferimento sui token di sostituzione.

I token evitano la necessità di aggiornare valori cruciali come il numero di versione in .nuspec durante l'aggiornamento del progetto. È sempre possibile sostituire i token con valori letterali, se necessario.

Si noti che sono disponibili diverse opzioni aggiuntive per la creazione di pacchetti quando si lavora da un progetto di Visual Studio, come descritto in Esecuzione del pacchetto nuget per generare il file con estensione nupkg in un secondo momento.

Pacchetti a livello di soluzione

Solo per NuGet 2.x. Non disponibile in NuGet 3.0+.

NuGet 2.x supportava la nozione di pacchetto a livello di soluzione che installa strumenti o comandi aggiuntivi per la console di Gestione pacchetti (il contenuto della tools cartella), ma non aggiunge riferimenti, contenuto o personalizzazioni di compilazione a qualsiasi progetto nella soluzione. Tali pacchetti non contengono file nelle cartelle dirette lib, contento build e nessuna delle relative dipendenze include file nelle rispettive libcartelle , contento build .

NuGet tiene traccia dei pacchetti a livello di soluzione installati in un packages.config file nella .nuget cartella, anziché nel file del packages.config progetto.

Nuovo file con valori predefiniti

Il comando seguente crea un manifesto predefinito con segnaposto, che garantisce l'avvio con la struttura di file corretta:

nuget spec [<package-name>]

Se si omette <package-name>, il file risultante è Package.nuspec. Se si specifica un nome, ad Contoso.Utility.UsefulStuffesempio , il file è Contoso.Utility.UsefulStuff.nuspec.

L'oggetto risultante .nuspec contiene segnaposto per valori come il projectUrl. Assicurarsi di modificare il file prima di usarlo per creare il file finale .nupkg .

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

L'identificatore del pacchetto (<id> elemento) e il numero di versione (<version> elemento ) sono i due valori più importanti nel manifesto perché identificano in modo univoco il codice esatto contenuto nel pacchetto.

Procedure consigliate per l'identificatore del pacchetto:

• Univocità: l'identificatore deve essere univoco tra nuget.org o qualsiasi raccolta che ospita il pacchetto. Prima di decidere su un identificatore, cercare nella galleria pertinente per verificare se è già in uso. Per evitare conflitti, un modello valido consiste nell'usare il nome della società come prima parte dell'identificatore, ad esempio Contoso..
• Nomi simili a namespace: seguire un modello simile ai namespace in .NET, usando la notazione a punti anziché i trattini. Ad esempio, usare Contoso.Utility.UsefulStuff anziché Contoso-Utility-UsefulStuff o Contoso_Utility_UsefulStuff. I consumatori trovano inoltre utile quando l'identificatore del pacchetto corrisponde ai namespace usati nel codice.
• Pacchetti di esempio: se si produce un pacchetto di codice di esempio che illustra come usare un altro pacchetto, aggiungere .Sample come suffisso all'identificatore, come in Contoso.Utility.UsefulStuff.Sample. Il pacchetto di esempio avrà naturalmente una dipendenza dall'altro pacchetto. Quando si crea un pacchetto di esempio, usare il metodo della directory di lavoro basato su convenzioni descritto in precedenza. Nella cartella content, organizzare il codice di esempio in una cartella chiamata \Samples\<identifier> come in \Samples\Contoso.Utility.UsefulStuff.Sample.

Procedure consigliate per la versione del pacchetto:

• In generale, impostare la versione del pacchetto in modo che corrisponda alla libreria, anche se questa operazione non è strettamente necessaria. Si tratta di una questione semplice quando si limita un pacchetto a un singolo assembly, come descritto in precedenza in Decidere quali assembly includere nel pacchetto. In generale, tenere presente che NuGet gestisce le versioni dei pacchetti durante la risoluzione delle dipendenze, non le versioni degli assembly.
• Quando 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.

La serie seguente di brevi post di blog è utile anche per comprendere il controllo delle versioni:

• Parte 1: Affrontare il problema del DLL Hell
• Parte 2: Algoritmo principale
• Parte 3: Unificazione tramite reindirizzamenti di binding

Aggiungere il file README e altri file

Per specificare direttamente i file da includere nel pacchetto, usare il <files> nodo nel .nuspec file , che segue il <metadata> tag :

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
    <!-- ... -->
    </metadata>
    <files>
        <!-- Add a readme -->
        <file src="readme.txt" target="" />

        <!-- Add files from an arbitrary folder that's not necessarily in the project -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

Quando si include un file denominato readme.txt nella radice del pacchetto, Visual Studio visualizza il contenuto del file come testo normale immediatamente dopo l'installazione diretta del pacchetto. I file di lettura non vengono visualizzati per i pacchetti installati come dipendenze. Ad esempio, ecco come viene visualizzato il file leggimi per il pacchetto HtmlAgilityPack:

Includere i props e le destinazioni di MSBuild in un pacchetto

In alcuni casi, potrebbe essere necessario aggiungere destinazioni o proprietà di compilazione personalizzate nei progetti che utilizzano il pacchetto, ad esempio l'esecuzione di uno strumento personalizzato o un processo durante la compilazione. Puoi ottenere ulteriori informazioni su proprietà e destinazioni di MSBuild nei pacchetti NuGet

Creare <package_id>.targets o <package_id>.props ,ad esempio Contoso.Utility.UsefulStuff.targets, all'interno delle cartelle di compilazione del progetto.

Quindi, nel .nuspec file, assicurarsi di fare riferimento a questi file all'interno del nodo <files>:

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- Include everything in \build -->
        <file src="build\**" target="build" />

        <!-- Other files -->
        <!-- ... -->
    </files>
</package>

Quando i pacchetti vengono aggiunti a un progetto, NuGet includerà automaticamente questi props e target.

Eseguire nuget pack per generare il file con estensione nupkg

Quando si usa un assembly o la directory di lavoro basata su convenzioni, creare un pacchetto eseguendo nuget pack con il file .nuspec, sostituendo <project-name> con il nome del file specifico.

nuget pack <project-name>.nuspec

Quando si usa un progetto di Visual Studio, eseguire nuget pack con il file di progetto, che carica automaticamente il file del progetto e sostituisce tutti i token all'interno di esso usando i valori nel file di .nuspec progetto:

nuget pack <project-name>.csproj

In tutti i casi, nuget pack esclude le cartelle che iniziano con un punto, ad esempio .git o .hg.

NuGet indica se sono presenti errori nel .nuspec file che richiedono la correzione, ad esempio dimenticando di modificare i valori segnaposto nel manifesto.

Al momento in cui nuget pack riesce, hai un file .nupkg che puoi pubblicare in una galleria appropriata, come descritto in Pubblicazione di un pacchetto.

Opzioni aggiuntive

È possibile usare varie opzioni della riga di comando con nuget pack per escludere i file, ignorare il numero di versione nel manifesto e modificare la cartella di output, tra le altre funzionalità. Per un elenco completo, fare riferimento al riferimento al comando pack.

Le opzioni seguenti sono alcune comuni ai progetti di Visual Studio:

• Progetti a cui si fa riferimento: se il progetto fa riferimento ad altri progetti, è possibile aggiungere i progetti a cui si fa riferimento come parte del pacchetto o come dipendenze usando l'opzione -IncludeReferencedProjects :

  nuget pack MyProject.csproj -IncludeReferencedProjects
  

  Questo processo di inclusione è ricorsivo, quindi se MyProject.csproj fa riferimento ai progetti B e C e tali progetti fanno riferimento a D, E e F, i file da B, C, D, E e F sono inclusi nel pacchetto.

  Se un progetto a cui si fa riferimento include un .nuspec file autonomo, NuGet aggiunge invece il progetto a cui si fa riferimento come dipendenza. È necessario creare un pacchetto e pubblicare il progetto separatamente.

• Configurazione della compilazione: Per impostazione predefinita, NuGet usa il set di configurazione di compilazione predefinito nel file di progetto, in genere Debug. Per comprimere i file da una configurazione di compilazione diversa, ad esempio Release, usare l'opzione -properties con la configurazione:

  nuget pack MyProject.csproj -properties Configuration=Release
  

• Simboli: per includere simboli che consentono ai consumer di scorrere il codice del pacchetto nel debugger, usare l'opzione -Symbols :

  nuget pack MyProject.csproj -symbols
  

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.

Per i test automatizzati, il processo di base è il seguente:

1. Copiare il .nupkg file in una cartella locale.
2. Aggiungere la cartella alle fonti del pacchetto usando il comando nuget sources add -name <name> -source <path> (vedere nuget fonti). Si noti che è necessario impostare questa origine locale una sola volta in un determinato computer.
3. Installare il pacchetto da tale origine usando nuget install <packageID> -source <name> dove <name> corrisponde al nome dell'origine come indicato in nuget sources. Se si specifica l'origine, il pacchetto viene installato solo da tale origine.
4. Esaminare il file system per verificare che i file siano installati correttamente.

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:

• Controllo delle versioni dei pacchetti
• Supporto per più framework di destinazione
• Trasformazioni dei file di origine e di configurazione
• Localizzazione
• Versioni preliminari
• Impostare il tipo di pacchetto
• Creare pacchetti con assembly di interoperabilità COM

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

• Pacchetti nativi
• Pacchetti di simboli