Creare un pacchetto usando l'interfaccia della riga di comando di nuget.exeCreate a package using the nuget.exe CLI

Indipendentemente dalle operazioni eseguite dal pacchetto o dal tipo di codice contenuto, è possibile usare uno degli strumenti dell'interfaccia della riga di comando, ovvero nuget.exe o dotnet.exe. per rendere disponibili tali funzionalità in un componente condivisibile e utilizzabile da altri sviluppatori.No matter what your package does or what code it contains, you use one of the CLI tools, either nuget.exe or dotnet.exe, to package that functionality into a component that can be shared with and used by any number of other developers. Per installare gli strumenti dell'interfaccia della riga di comando di NuGet, vedere Installare gli strumenti client di NuGet.To install NuGet CLI tools, see Install NuGet client tools. Si noti che Visual Studio non include automaticamente uno strumento dell'interfaccia della riga di comando.Note that Visual Studio does not automatically include a CLI tool.

Da un punto di vista tecnico, un pacchetto NuGet è solo un file ZIP rinominato con l'estensione .nupkg e i cui contenuti rispettano determinate convenzioni.Technically speaking, a NuGet package is just a ZIP file that's been renamed with the .nupkg extension and whose contents match certain conventions. Questo argomento descrive il processo dettagliato di creazione di un pacchetto che soddisfa tali convenzioni.This topic describes the detailed process of creating a package that meets those conventions.

La creazione di un pacchetto inizia con il codice compilato (assembly), i simboli e/o altri file che si vuole distribuire come pacchetto. Vedere Panoramica e flusso di lavoro.Packaging begins with the compiled code (assemblies), symbols, and/or other files that you want to deliver as a package (see Overview and workflow). Questo processo è indipendente dalla compilazione o comunque dalla generazione dei file inseriti nel pacchetto, anche se è possibile usare le informazioni contenute in un file di progetto per mantenere sincronizzati i pacchetti e gli assembly compilati.This process is independent from compiling or otherwise generating the files that go into the package, although you can draw from information in a project file to keep the compiled assemblies and packages in sync.

Importante

Questo argomento si applica ai progetti non in stile SDK, in genere progetti diversi dai progetti .NET Core e .NET Standard che usano Visual Studio 2017 e versioni successive e NuGet 4.0+.This topic applies to non-SDK-style projects, typically projects other than .NET Core and .NET Standard projects using Visual Studio 2017 and higher versions and NuGet 4.0+.

Scegliere gli assembly per cui creare un pacchettoDecide which assemblies to package

La maggior parte dei pacchetti per utilizzo generico contiene uno o più assembly che gli altri sviluppatori possono usare nei propri progetti.Most general-purpose packages contain one or more assemblies that other developers can use in their own projects.

  • In generale, l'ideale è avere un assembly per ogni pacchetto NuGet, purché ogni assembly abbia una propria utilità.In general, it's best to have one assembly per NuGet package, provided that each assembly is independently useful. Se ad esempio è presente un file Utilities.dll che dipende da Parser.dll e Parser.dll è utile di per sé, creare un pacchetto per ognuno.For example, if you have a Utilities.dll that depends on Parser.dll, and Parser.dll is useful on its own, then create one package for each. In questo modo gli sviluppatori possono usare Parser.dll indipendentemente da Utilities.dll.Doing so allows developers to use Parser.dll independently of Utilities.dll.

  • Se la libreria è costituita da più assembly che non hanno una propria utilità, è consigliabile combinarli in un solo pacchetto.If your library is composed of multiple assemblies that aren't independently useful, then it's fine to combine them into one package. Usando l'esempio precedente, se Parser.dll contiene codice che viene usato solo da Utilities.dll, è consigliabile tenere Parser.dll nello stesso pacchetto.Using the previous example, if Parser.dll contains code that's used only by Utilities.dll, then it's fine to keep Parser.dll in the same package.

  • Analogamente, se Utilities.dll dipende da Utilities.resources.dll e quest'ultimo non è utile di per sé, inserirli entrambi nello stesso pacchetto.Similarly, if Utilities.dll depends on Utilities.resources.dll, where again the latter is not useful on its own, then put both in the same package.

Le risorse sono di fatto un caso particolare.Resources are, in fact, a special case. Quando un pacchetto viene installato in un progetto, NuGet aggiunge automaticamente alle DLL del pacchetto i riferimenti agli assembly, escludendo quelli denominati .resources.dll perché si presuppone che siano assembly satellite localizzati. Vedere Creazione di pacchetti localizzati.When a package is installed into a project, NuGet automatically adds assembly references to the package's DLLs, excluding those that are named .resources.dll because they are assumed to be localized satellite assemblies (see Creating localized packages). Per questo motivo, evitare di usare .resources.dll per i file che contengono invece codice essenziale per il pacchetto.For this reason, avoid using .resources.dll for files that otherwise contain essential package code.

Se la libreria contiene assembly di interoperabilità COM, seguire le linee guida aggiuntive in Creare pacchetti con assembly di interoperabilità COM.If your library contains COM interop assemblies, follow additional the guidelines in Create packages with COM interop assemblies.

Ruolo e struttura del file con estensione nuspecThe role and structure of the .nuspec file

Dopo avere deciso per quali file si vuole creare un pacchetto, il passaggio successivo prevede la creazione di un manifesto del pacchetto in un file XML .nuspec.Once you know what files you want to package, the next step is creating a package manifest in a .nuspec XML file.

Il manifesto:The manifest:

  1. Descrive i contenuti del pacchetto e viene incluso nel pacchetto.Describes the package's contents and is itself included in the package.
  2. Gestisce la creazione del pacchetto e indica a NuGet come installare il pacchetto in un progetto.Drives both the creation of the package and instructs NuGet on how to install the package into a project. Il manifesto, ad esempio, identifica le altre dipendenze del pacchetto in modo che NuGet possa installare anche tali dipendenze quando viene installato il pacchetto principale.For example, the manifest identifies other package dependencies such that NuGet can also install those dependencies when the main package is installed.
  3. Contiene le proprietà sia obbligatorie che facoltative, come descritto di seguito.Contains both required and optional properties as described below. Per informazioni dettagliate, incluse le altre proprietà non citate qui, vedere Informazioni di riferimento sul file .nuspec.For exact details, including other properties not mentioned here, see the .nuspec reference.

Proprietà obbligatorie:Required properties:

  • Identificatore del pacchetto, che deve essere univoco nella raccolta che ospita il pacchetto.The package identifier, which must be unique across the gallery that hosts the package.
  • Numero di versione specifico nel formato Major.Minor.Patch[-Suffix] dove -Suffix identifica le versioni preliminariA specific version number in the form Major.Minor.Patch[-Suffix] where -Suffix identifies pre-release versions
  • Titolo del pacchetto come deve essere visualizzato nell'host (ad esempio, nuget.org)The package title as it should appear on the host (like nuget.org)
  • Informazioni sull'autore e sul proprietario.Author and owner information.
  • Descrizione estesa del pacchetto.A long description of the package.

Proprietà facoltative comuni:Common optional properties:

Di seguito è riportato un file .nuspec tipico (ma fittizio), con commenti che descrivono le proprietà:The following is a typical (but fictitious) .nuspec file, with comments describing the properties:

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

        <!-- The package version number that is used when resolving dependencies -->
        <version>1.8.3-beta</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>
        

        <!-- The icon is used in Visual Studio's package manager UI -->
        <iconUrl>http://github.com/contoso/UsefulStuff/nuget_icon.png</iconUrl>

        <!-- 
            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="" />
    </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.For details on declaring dependencies and specifying version numbers, see packages.config and Package versioning. È anche possibile esporre gli asset dalle dipendenze direttamente nel pacchetto usando gli attributi include ed exclude nell'elemento dependency.It is also possible to surface assets from dependencies directly in the package by using the include and exclude attributes on the dependency element. Vedere la sezione Dipendenze delle informazioni di riferimento sul file .nuspec.See .nuspec Reference - Dependencies.

Poiché il manifesto è incluso nel pacchetto creato, per trovare altri esempi, esaminare i pacchetti esistenti.Because the manifest is included in the package created from it, you can find any number of additional examples by examining existing packages. Una valida fonte è la cartella global-packages nel computer, la posizione della quale viene restituita dal comando seguente:A good source is the global-packages folder on your computer, the location of which is returned by the following command:

nuget locals -list global-packages

Andare a qualsiasi cartella pacchetto\versione, copiare il file .nupkg in un file .zip, quindi aprire il file .zip ed esaminare il file .nuspec.Go into any package\version folder, copy the .nupkg file to a .zip file, then open that .zip file and examine the .nuspec within it.

Nota

Quando si crea un file .nuspec da un progetto di Visual Studio, il manifesto contiene token che vengono sostituiti con le informazioni provenienti dal progetto quando il pacchetto viene compilato.When creating a .nuspec from a Visual Studio project, the manifest contains tokens that are replaced with information from the project when the package is built. Vedere Creazione del file con estensione nuspec da un progetto di Visual Studio.See Creating the .nuspec from a Visual Studio project.

Creare il file con estensione nuspecCreate the .nuspec file

La creazione di un manifesto completo inizia in genere con un file .nuspec di base generato con uno dei metodi seguenti:Creating a complete manifest typically begins with a basic .nuspec file generated through one of the following methods:

Si modifica quindi il file manualmente in modo che descriva il contenuto esatto che dovrà essere incluso nel pacchetto finale.You then edit the file by hand so that it describes the exact content you want in the final package.

Importante

I file .nuspec generati contengono segnaposto che devono essere modificati prima di creare il pacchetto con il comando nuget pack,Generated .nuspec files contain placeholders that must be modified before creating the package with the nuget pack command. che ha esito negativo se il file .nuspec contiene segnaposto.That command fails if the .nuspec contains any placeholders.

Da una directory di lavoro basata sulle convenzioniFrom a convention-based working directory

Dato che un pacchetto NuGet è solo un file ZIP rinominato con l'estensione .nupkg, spesso è più semplice creare la struttura di cartelle necessaria nel file system locale e quindi creare il file .nuspec direttamente da tale struttura.Because a NuGet package is just a ZIP file that's been renamed with the .nupkg extension, it's often easiest to create the folder structure you want on your local file system, then create the .nuspec file directly from that structure. Il comando nuget pack aggiunge quindi automaticamente tutti i file in tale struttura di cartelle, escluse le cartelle che iniziano con ., per poter mantenere i file privati nella stessa struttura.The nuget pack command then automatically adds all files in that folder structure (excluding any folders that begin with ., allowing you to keep private files in the same structure).

Il vantaggio di questo approccio è che non è necessario specificare nel manifesto i file che si vuole includere nel pacchetto, come illustrato più avanti in questo argomento.The advantage to this approach is that you don't need to specify in the manifest which files you want to include in the package (as explained later in this topic). È sufficiente fare in modo che il processo di compilazione generi l'esatta struttura di cartelle da inserire nel pacchetto, per poter facilmente includere altri file che altrimenti potrebbero non fare parte di un progetto:You can simply have your build process produce the exact folder structure that goes into the package, and you can easily include other files that might not be part of a project otherwise:

  • Contenuto e codice sorgente da inserire nel progetto di destinazione.Content and source code that should be injected into the target project.
  • Script PowerShellPowerShell scripts
  • Trasformazioni della configurazione esistente e dei file del codice sorgente di un progetto.Transformations to existing configuration and source code files in a project.

Le convenzioni delle cartelle sono le seguenti:The folder conventions are as follows:

CartellaFolder DESCRIZIONEDescription Azione durante l'installazione del pacchettoAction upon package install
(radice)(root) Percorso del file readme.txtLocation for readme.txt Visual Studio visualizza un file readme.txt nella radice del pacchetto quando il pacchetto viene installato.Visual Studio displays a readme.txt file in the package root when the package is installed.
lib/{tfm}lib/{tfm} File di assembly (.dll), di documentazione (.xml) e di simboli (.pdb) per il moniker del framework di destinazione (TFM, Target Framework Moniker) specificatoAssembly (.dll), documentation (.xml), and symbol (.pdb) files for the given Target Framework Moniker (TFM) Gli assembly vengono aggiunti come riferimenti per la compilazione, oltre che per il runtime. .xml e .pdb vengono copiati nelle cartelle di progetto.Assemblies are added as references for compile as well as runtime; .xml and .pdb copied into project folders. Per la creazione di sottocartelle specifiche del framework di destinazione, vedere Supporto di più framework di destinazione.See Supporting multiple target frameworks for creating framework target-specific sub-folders.
ref/{tfm}ref/{tfm} File di assembly (.dll) e di simboli (.pdb) per il moniker del framework di destinazione (TFM, Target Framework Moniker) specificatoAssembly (.dll), and symbol (.pdb) files for the given Target Framework Moniker (TFM) Gli assembly vengono aggiunti come riferimenti solo per la fase di compilazione. Non verrà quindi copiato nulla nella cartella bin del progetto.Assemblies are added as references only for compile time; So nothing will be copied into project bin folder.
runtimesruntimes File di assembly (.dll), di simboli (.pdb) e di risorse native (.pri) specifici dell'architetturaArchitecture-specific assembly (.dll), symbol (.pdb), and native resource (.pri) files Gli assembly vengono aggiunti come riferimenti solo per il runtime. Gli altri file vengono copiati nelle cartelle di progetto.Assemblies are added as references only for runtime; other files are copied into project folders. Deve esistere sempre un assembly specifico AnyCPU corrispondente (TFM) sotto la cartella /ref/{tfm} per fornire l'assembly della fase di compilazione corrispondente.There should always be a corresponding (TFM) AnyCPU specific assembly under /ref/{tfm} folder to provide corresponding compile time assembly. Vedere Supporto di più framework di destinazione.See Supporting multiple target frameworks.
contenutocontent File arbitrariArbitrary files I contenuti vengono copiati nella radice del progetto.Contents are copied to the project root. La cartella content può essere considerata come la radice dell'applicazione di destinazione che in definitiva utilizza il pacchetto.Think of the content folder as the root of the target application that ultimately consumes the package. Per fare in modo che il pacchetto aggiunga un'immagine nella cartella /images dell'applicazione, inserirla nella cartella content/images del pacchetto.To have the package add an image in the application's /images folder, place it in the package's content/images folder.
buildbuild File .targets e .props MSBuildMSBuild .targets and .props files Vengono automaticamente inseriti nel progetto (NuGet 3.x+).Automatically inserted into the project (NuGet 3.x+).
buildMultiTargetingbuildMultiTargeting File .targets e .props di MSBuild per l'assegnazione di più framework di destinazioneMSBuild .targets and .props files for cross-framework targeting Vengono automaticamente inseriti nel progetto.Automatically inserted into the project.
buildTransitivebuildTransitive (5.0 +) File .targets e .props di MSBuild che si propagano in modo transitivo a qualsiasi progetto che gli utilizza.(5.0+) MSBuild .targets and .props files that flow transitively to any consuming project. Vedere la pagina delle funzionalità.See the feature page. Vengono automaticamente inseriti nel progetto.Automatically inserted into the project.
toolstools Script di PowerShell e programmi accessibili dalla console di Gestione pacchettiPowershell scripts and programs accessible from the Package Manager Console La cartella tools viene aggiunta alla variabile di ambiente PATH solo per la console di Gestione pacchetti, in particolare non alla variabile PATH impostata per MSBuild durante la compilazione del progetto.The tools folder is added to the PATH environment variable for the Package Manager Console only (Specifically, not to the PATH as set for MSBuild when building the project).

Poiché la struttura di cartelle può contenere un numero indeterminato di assembly per un numero indeterminato di framework di destinazione, questo metodo è necessario quando si creano pacchetti che supportano più framework.Because your folder structure can contain any number of assemblies for any number of target frameworks, this method is necessary when creating packages that support multiple frameworks.

In ogni caso, dopo avere creato la struttura di cartelle desiderata, eseguire il comando seguente in tale cartella per creare il file .nuspec:In any case, once you have the desired folder structure in place, run the following command in that folder to create the .nuspec file:

nuget spec

Anche in questo caso, il file .nuspec generato non contiene riferimenti espliciti ai file nella struttura di cartelle.Again, the generated .nuspec contains no explicit references to files in the folder structure. NuGet include tutti i file automaticamente quando viene creato il pacchetto.NuGet automatically includes all files when the package is created. È tuttavia necessario modificare i valori dei segnaposto nelle altre parti del manifesto.You still need to edit placeholder values in other parts of the manifest, however.

Da una DLL dell'assemblyFrom an assembly DLL

Nel semplice caso della creazione di un pacchetto da un assembly, è possibile generare un file .nuspec dai metadati nell'assembly usando il comando seguente:In the simple case of creating a package from an assembly, you can generate a .nuspec file from the metadata in the assembly using the following command:

nuget spec <assembly-name>.dll

Usando questo formato, alcuni segnaposto nel manifesto vengono sostituiti con i valori specifici dell'assembly.Using this form replaces a few placeholders in the manifest with specific values from the assembly. La proprietà <id>, ad esempio, viene impostata sul nome dell'assembly e <version> viene impostata sulla versione dell'assembly.For example, the <id> property is set to the assembly name, and <version> is set to the assembly version. Le altre proprietà del manifesto non hanno tuttavia valori corrispondenti nell'assembly e perciò contengono ancora i segnaposto.Other properties in the manifest, however, don't have matching values in the assembly and thus still contain placeholders.

Da un progetto di Visual StudioFrom a Visual Studio project

La creazione di un file .nuspec da un file .csproj o .vbproj è utile perché viene fatto automaticamente riferimento agli altri pacchetti che sono stati installati in tale progetto come a dipendenze.Creating a .nuspec from a .csproj or .vbproj file is convenient because other packages that have been installed into those project are automatically referenced as dependencies. È sufficiente usare il comando seguente nella stessa cartella del file di progetto:Simply use the following command in the same folder as the project file:

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

Il file <project-name>.nuspec risultante contiene token che in fase di creazione del pacchetto vengono sostituiti con i valori del progetto, inclusi i riferimenti agli altri pacchetti già installati.The resulting <project-name>.nuspec file contains tokens that are replaced at packaging time with values from the project, including references to any other packages that have already been installed.

In presenza di dipendenze del pacchetto da includere nel file con estensione nuspec, usare invece nuget pack e ottenere il file con estensione nuspec dall'interno del file con estensione nupkg generato.If you have package dependencies to include in the .nuspec, instead use nuget pack, and get the .nuspec file from within the generated .nupkg file. Ad esempio, usare il comando seguente.For example, use the following command.

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

A token is delimited by `$` symbols on both sides of the project property. For example, the `<id>` value in a manifest generated in this way typically appears as follows:

```xml
<id>$id$</id>

Questo token viene sostituito con il valore AssemblyName del file di progetto in fase di creazione del pacchetto.This token is replaced with the AssemblyName value from the project file at packing time. Per il mapping esatto dei valori del progetto ai token di .nuspec, vedere le informazioni di riferimento in Token di sostituzione.For the exact mapping of project values to .nuspec tokens, see the Replacement Tokens reference.

I token evitano di dover aggiornare i valori fondamentali, ad esempio il numero di versione, nel file .nuspec quando si aggiorna il progetto.Tokens relieve you from needing to update crucial values like the version number in the .nuspec as you update the project. È sempre possibile sostituire i token con valori letterali, se necessario.(You can always replace the tokens with literal values, if desired).

Tenere presente che sono disponibili diverse altre opzioni di creazione del pacchetto quando si usa un progetto di Visual Studio, come illustrato più avanti in Esecuzione di nuget pack per generare il file con estensione nupkg.Note that there are several additional packaging options available when working from a Visual Studio project, as described in Running nuget pack to generate the .nupkg file later on.

Pacchetti a livello di soluzioneSolution-level packages

Solo NuGet 2.x. Non disponibile in NuGet 3.0+.NuGet 2.x only. Not available 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 (contenuti della cartella tools), ma non aggiunge riferimenti, contenuto o personalizzazioni delle compilazioni ai progetti della soluzione.NuGet 2.x supported the notion of a solution-level package that installs tools or additional commands for the Package Manager Console (the contents of the tools folder), but does not add references, content, or build customizations to any projects in the solution. Tali pacchetti non contengono file nelle cartelle lib, content o build dirette e nessuna dipendenza ha file nelle rispettive cartelle lib, content o build.Such packages contain no files in its direct lib, content, or build folders, and none of its dependencies have files in their respective lib, content, or build folders.

NuGet tiene traccia dei pacchetti a livello di soluzione installati in un file packages.config nella cartella .nuget, invece che nel file packages.config del progetto.NuGet tracks installed solution-level packages in a packages.config file in the .nuget folder, rather than the project's packages.config file.

Nuovo file con valori predefinitiNew file with default values

Il comando seguente crea un manifesto predefinito con segnaposto, che assicura di iniziare con la struttura di file corretta:The following command creates a default manifest with placeholders, which ensures you start with the proper file structure:

nuget spec [<package-name>]

Se si omette <package-name>, il file risultante è Package.nuspec.If you omit <package-name>, the resulting file is Package.nuspec. Se come nome si specifica ad esempio Contoso.Utility.UsefulStuff, il file è Contoso.Utility.UsefulStuff.nuspec.If you provide a name such as Contoso.Utility.UsefulStuff, the file is Contoso.Utility.UsefulStuff.nuspec.

Il file .nuspec risultante contiene segnaposto per i valori come projectUrl.The resulting .nuspec contains placeholders for values like the projectUrl. Assicurarsi di modificare il file prima di usarlo per creare il file .nupkg finale.Be sure to edit the file before using it to create the final .nupkg file.

Scegliere un identificatore univoco del pacchetto e impostare il numero di versioneChoose a unique package identifier and setting the version number

L'identificatore del pacchetto (elemento <id>) e il numero di versione (elemento <version>) sono i due valori più importanti del manifesto perché identificano in modo univoco il codice esatto contenuto nel pacchetto.The package identifier (<id> element) and the version number (<version> element) are the two most important values in the manifest because they uniquely identify the exact code that's contained in the package.

Procedure consigliate per l'identificatore del pacchetto:Best practices for the package identifier:

  • Univocità: l'identificatore deve essere univoco in nuget.org o in qualsiasi raccolta che ospita il pacchetto.Uniqueness: The identifier must be unique across nuget.org or whatever gallery hosts the package. Prima di scegliere un identificatore, eseguire una ricerca nella raccolta applicabile per controllare se il nome è già in uso.Before deciding on an identifier, search the applicable gallery to check if the name is already in use. Per evitare conflitti, è consigliabile usare il nome della società come prima parte dell'identificatore, ad esempio Contoso..To avoid conflicts, a good pattern is to use your company name as the first part of the identifier, such as Contoso..
  • Nomi simili a spazi dei nomi: seguono un modello simile a quello degli spazi dei nomi in .NET, usando la notazione con punto invece dei trattini.Namespace-like names: Follow a pattern similar to namespaces in .NET, using dot notation instead of hyphens. Usare, ad esempio, Contoso.Utility.UsefulStuff invece di Contoso-Utility-UsefulStuff o Contoso_Utility_UsefulStuff.For example, use Contoso.Utility.UsefulStuff rather than Contoso-Utility-UsefulStuff or Contoso_Utility_UsefulStuff. Per gli utenti è anche utile che l'identificatore del pacchetto corrisponda agli spazi dei nomi usati nel codice.Consumers also find it helpful when the package identifier matches the namespaces used in the code.
  • 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.Sample Packages: If you produce a package of sample code that demonstrates how to use another package, attach .Sample as a suffix to the identifier, as 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 basata sulle convenzioni descritto in precedenza.(The sample package would of course have a dependency on the other package.) When creating a sample package, use the convention-based working directory method described earlier. Nella cartella content inserire il codice di esempio in una cartella denominata \Samples\<identifier> come in \Samples\Contoso.Utility.UsefulStuff.Sample.In the content folder, arrange the sample code in a folder called \Samples\<identifier> as in \Samples\Contoso.Utility.UsefulStuff.Sample.

Procedure consigliate per la versione del pacchetto:Best practices for the package version:

  • In generale, impostare la versione del pacchetto in modo che corrisponda alla libreria, anche se non è strettamente necessario.In general, set the version of the package to match the library, though this is not strictly required. È davvero semplicissimo quando si limita un pacchetto a un singolo assembly, come descritto precedentemente in Scelta degli assembly per cui creare un pacchetto.This is a simple matter when you limit a package to a single assembly, as described earlier in Deciding which assemblies to package. In generale, tenere presente che, durante la risoluzione delle dipendenze, di per sé NuGet gestisce le versioni dei pacchetti, non le versioni degli assembly.Overall, remember that NuGet itself deals with package versions when resolving dependencies, not assembly versions.
  • Quando si usa uno schema della versione non standard, tenere in considerazione le regole di controllo delle versioni di NuGet, come illustrato in Controllo delle versioni dei pacchetti.When using a non-standard version scheme, be sure to consider the NuGet versioning rules as explained in Package versioning.

Per informazioni sul controllo delle versioni, vedere anche la serie seguente di brevi post di blog:The following series of brief blog posts are also helpful to understand versioning:

Aggiungere un file leggimi e altri fileAdd a readme and other files

Per specificare direttamente i file da includere nel pacchetto, usare il nodo <files> nel file .nuspec, che segue il tag <metadata>:To directly specify files to include in the package, use the <files> node in the .nuspec file, which follows the <metadata> tag:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/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>

Suggerimento

Quando si usa l'approccio della directory di lavoro basata sulle convenzioni, è possibile inserire il file readme.txt nella radice del pacchetto e gli altri contenuti nella cartella content.When using the convention-based working directory approach, you can place the readme.txt in the package root and other content in the content folder. Non sono necessari elementi <file> nel manifesto.No <file> elements are necessary in the manifest.

Quando si include un file denominato readme.txt nella radice del pacchetto, Visual Studio visualizza i contenuti del file come testo normale subito dopo avere installato direttamente il pacchetto.When you include a file named readme.txt in the package root, Visual Studio displays the contents of that file as plain text immediately after installing the package directly. I file leggimi non vengono visualizzati per i pacchetti installati come dipendenze.(Readme files are not displayed for packages installed as dependencies). Ecco ad esempio come viene visualizzato il file leggimi per il pacchetto HtmlAgilityPack:For example, here's how the readme for the HtmlAgilityPack package appears:

Visualizzazione di un file leggimi per un pacchetto NuGet durante l'installazione

Nota

Se si include un nodo <files> vuoto nel file .nuspec, NuGet non include nel pacchetto altri contenuti diversi dal contenuto della cartella lib.If you include an empty <files> node in the .nuspec file, NuGet doesn't include any other content in the package other than what's in the lib folder.

Includere proprietà e destinazioni MSBuild in un pacchettoInclude MSBuild props and targets in a package

In alcuni casi, potrebbe essere necessario aggiungere destinazioni o proprietà di compilazione personalizzata nei progetti che utilizzano il pacchetto, ad esempio l'esecuzione di uno strumento o processo personalizzato durante la compilazione.In some cases, you might want to add custom build targets or properties in projects that consume your package, such as running a custom tool or process during build. A tale scopo, inserire i file nel formato <package_id>.targets o <package_id>.props (ad esempio Contoso.Utility.UsefulStuff.targets) nella cartella \build del progetto.You do this by placing files in the form <package_id>.targets or <package_id>.props (such as Contoso.Utility.UsefulStuff.targets) within the \build folder of the project.

I file nella cartella radice \build sono considerati adatti a tutti i framework di destinazione.Files in the root \build folder are considered suitable for all target frameworks. Per indicare file specifici del framework, inserirli prima nelle sottocartelle appropriate, come di seguito:To provide framework-specific files, first place them within appropriate subfolders, such as the following:

\build
    \netstandard1.4
        \Contoso.Utility.UsefulStuff.props
        \Contoso.Utility.UsefulStuff.targets
    \net462
        \Contoso.Utility.UsefulStuff.props
        \Contoso.Utility.UsefulStuff.targets

Nel file .nuspec assicurarsi quindi di fare riferimento a questi file nel nodo <files>:Then in the .nuspec file, be sure to refer to these files in the <files> node:

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

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

La possibilità di includere file props e targets di MSBuild in un pacchetto è stata introdotta con NuGet 2.5, pertanto è consigliabile aggiungere l'attributo minClientVersion="2.5" all'elemento metadata per indicare la versione client NuGet minima richiesta per utilizzare il pacchetto.Including MSBuild props and targets in a package was introduced with NuGet 2.5, therefore it is recommended to add the minClientVersion="2.5" attribute to the metadata element, to indicate the minimum NuGet client version required to consume the package.

Quando installa un pacchetto con i file \build, NuGet aggiunge elementi <Import> di MSBuild nel file di progetto che puntano ai file .targets e .props.When NuGet installs a package with \build files, it adds MSBuild <Import> elements in the project file pointing to the .targets and .props files. .props viene aggiunto all'inizio del file di progetto, .targets viene aggiunto alla fine. Viene aggiunto un elemento <Import> di MSBuild condizionale separato per ogni framework di destinazione.(.props is added at the top of the project file; .targets is added at the bottom.) A separate conditional MSBuild <Import> element is added for each target framework.

I file .props e .targets di MSBuild per l'assegnazione di più framework di destinazione possono essere posizionati nella cartella \buildMultiTargeting.MSBuild .props and .targets files for cross-framework targeting can be placed in the \buildMultiTargeting folder. Durante l'installazione del pacchetto, NuGet aggiunge elementi <Import> corrispondenti al file di progetto, a condizione che il framework di destinazione non sia impostato (la proprietà MSBuild $(TargetFramework) deve essere vuota).During package installation, NuGet adds the corresponding <Import> elements to the project file with the condition, that the target framework is not set (the MSBuild property $(TargetFramework) must be empty).

Con NuGet 3.x, le destinazioni non vengono aggiunte al progetto, ma vengono rese disponibili tramite {projectName}.nuget.g.targets e {projectName}.nuget.g.props.With NuGet 3.x, targets are not added to the project but are instead made available through {projectName}.nuget.g.targets and {projectName}.nuget.g.props.

Eseguire nuget pack per generare il file con estensione nupkgRun nuget pack to generate the .nupkg file

Quando si usa un assembly o la directory di lavoro basata sulle convenzioni, creare un pacchetto eseguendo nuget pack con il file .nuspec, sostituendo <project-name> con il nome file specifico:When using an assembly or the convention-based working directory, create a package by running nuget pack with your .nuspec file, replacing <project-name> with your specific filename:

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 .nuspec del progetto e sostituisce il token usando i valori del file di progetto:When using a Visual Studio project, run nuget pack with your project file, which automatically loads the project's .nuspec file and replaces any tokens within it using values in the project file:

nuget pack <project-name>.csproj

Nota

L'uso diretto del file di progetto è necessario per la sostituzione dei token perché il progetto è l'origine dei valori dei token.Using the project file directly is necessary for token replacement because the project is the source of the token values. La sostituzione dei token non avviene se si usa nuget pack con un file .nuspec.Token replacement does not happen if you use nuget pack with a .nuspec file.

In tutti i casi, nuget pack esclude le cartelle che iniziano con un punto, ad esempio .git o .hg.In all cases, nuget pack excludes folders that start with a period, such as .git or .hg.

NuGet indica se sono presenti errori nel file .nuspec che richiedono una correzione, ad esempio se si dimentica di modificare i valori dei segnaposto nel manifesto.NuGet indicates if there are any errors in the .nuspec file that need correcting, such as forgetting to change placeholder values in the manifest.

Dopo la corretta esecuzione di nuget pack, è disponibile un file .nupkg che è possibile pubblicare in una raccolta appropriata, come illustrato in Pubblicazione di un pacchetto.Once nuget pack succeeds, you have a .nupkg file that you can publish to a suitable gallery as described in Publishing a Package.

Suggerimento

Per esaminare un pacchetto dopo averlo creato, è possibile aprirlo nello strumento Package Explorer,A helpful way to examine a package after creating it is to open it in the Package Explorer tool. che offre una visualizzazione grafica dei contenuti del pacchetto e del manifesto.This gives you a graphical view of the package contents and its manifest. È anche possibile rinominare il file .nupkg risultante in un file .zip ed esplorarne il contenuto direttamente.You can also rename the resulting .nupkg file to a .zip file and explore its contents directly.

Opzioni aggiuntiveAdditional options

Tra le altre funzionalità, è possibile usare diverse opzioni della riga di comando con nuget pack per escludere i file, eseguire l'override del numero di versione nel manifesto e modificare la cartella di output.You can use various command-line switches with nuget pack to exclude files, override the version number in the manifest, and change the output folder, among other features. Per un elenco completo, vedere le informazioni di riferimento sul comando pack.For a complete list, refer to the pack command reference.

Le seguenti sono alcune opzioni comuni ai progetti di Visual Studio:The following options are a few that are common with Visual Studio projects:

  • Progetti di 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:Referenced projects: If the project references other projects, you can add the referenced projects as part of the package, or as dependencies, by using the -IncludeReferencedProjects option:

    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 di B, C, D, E e F vengono inclusi nel pacchetto.This inclusion process is recursive, so if MyProject.csproj references projects B and C, and those projects reference D, E, and F, then files from B, C, D, E, and F are included in the package.

    Se un progetto a cui si fa riferimento include un proprio file .nuspec, NuGet aggiunge invece tale progetto a cui si fa riferimento come dipendenza.If a referenced project includes a .nuspec file of its own, then NuGet adds that referenced project as a dependency instead. È necessario creare un pacchetto per il progetto e pubblicarlo separatamente.You need to package and publish that project separately.

  • Configurazione della build: per impostazione predefinita, NuGet usa la configurazione della build predefinita impostata nel file di progetto, in genere Debug.Build configuration: By default, NuGet uses the default build configuration set in the project file, typically Debug. Per creare un pacchetto per i file da una configurazione della build differente, ad esempio Release, usare l'opzione -properties con la configurazione:To pack files from a different build configuration, such as Release, use the -properties option with the configuration:

    nuget pack MyProject.csproj -properties Configuration=Release
    
  • Simboli: per includere i simboli che consentono agli utenti di eseguire il codice del pacchetto un'istruzione alla volta nel debugger, usare l'opzione -Symbols:Symbols: to include symbols that allow consumers to step through your package code in the debugger, use the -Symbols option:

    nuget pack MyProject.csproj -symbols
    

Testare l'installazione del pacchettoTest package installation

Prima di pubblicare un pacchetto, in genere si preferisce testarne il processo di installazione in un progetto.Before publishing a package, you typically want to test the process of installing a package into a project. I test assicurano che i file necessari vengano inseriti nei percorsi corretti all'interno del progetto.The tests make sure that the necessarily files all end up in their correct places in the project.

È possibile testare manualmente le installazioni in Visual Studio o dalla riga di comando seguendo i normali passaggi di installazione del pacchetto.You can test installations manually in Visual Studio or on the command line using the normal package installation steps.

Per i test automatizzati, il processo di base è il seguente:For automated testing, the basic process is as follows:

  1. Copiare il file .nupkg in una cartella locale.Copy the .nupkg file to a local folder.
  2. Aggiungere la cartella alle origini del pacchetto usando il comando nuget sources add -name <name> -source <path>. Vedere nuget sources.Add the folder to your package sources using the nuget sources add -name <name> -source <path> command (see nuget sources). Si noti che è necessario impostare l'origine locale solo una volta in ogni computer.Note that you need only set this local source once on any given computer.
  3. Installare il pacchetto da tale origine usando nuget install <packageID> -source <name> dove <name> corrisponde al nome dell'origine specificata in nuget sources.Install the package from that source using nuget install <packageID> -source <name> where <name> matches the name of your source as given to nuget sources. Specificando l'origine, il pacchetto viene con certezza installato solo da tale origine.Specifying the source ensures that the package is installed from that source alone.
  4. Esaminare il file system per controllare che i file siano installati correttamente.Examine your file system to check that files are installed correctly.

Passaggi successiviNext Steps

Dopo aver creato un pacchetto, ovvero un file .nupkg, è possibile pubblicarlo nella raccolta di propria scelta, come descritto in Pubblicazione di un pacchetto.Once you've created a package, which is a .nupkg file, you can publish it to the gallery of your choice as described on Publishing a Package.

Potrebbe anche essere necessario estendere le funzionalità del pacchetto o supportare altri scenari, come descritto negli argomenti seguenti:You might also want to extend the capabilities of your package or otherwise support other scenarios as described in the following topics:

Sono infine disponibili altri tipi di pacchetti da tenere presenti:Finally, there are additional package types to be aware of: