Informazioni di riferimento sul file .nuspec

Un file .nuspec è un manifesto XML che contiene i metadati del pacchetto. Questo manifesto viene usato per compilare il pacchetto e per fornire informazioni ai consumer. Il manifesto viene sempre incluso in un pacchetto.

Contenuto dell'argomento:

• Formato generale e schema
• Token di sostituzione (usati con un progetto di Visual Studio)
• Dipendenze
• Riferimenti espliciti agli assembly
• Riferimenti agli assembly del framework
• Inclusione di file di assembly
• Inclusione di file di contenuto
• File nuspec di esempio

Compatibilità dei tipi di progetto

• Usare .nuspec con nuget.exe pack per i progetti non in stile SDK che usano packages.config.

• Non .nuspec è necessario un file per creare pacchetti per progetti in stile SDK (in genere progetti .NET Core e .NET Standard che usano l'attributo SDK). Si noti che un .nuspec oggetto viene generato quando si crea il pacchetto.

  Se si sta creando un pacchetto usando dotnet.exe pack o msbuild pack target, è consigliabile includere tutte le proprietà in genere presenti nel .nuspec file di progetto. Tuttavia, è possibile scegliere di usare un .nuspec file per comprimere usando dotnet.exe o msbuild pack target.

• Per i progetti migrati da packages.config a PackageReference, non è necessario un .nuspec file per creare il pacchetto. Usare invece msbuild -t:pack.

Formato generale e schema

Un nuspec.xsd file di schema è disponibile nel repository GitHub NuGet. Si noti che questo file rappresenta solo lo schema più recente per un .nuspec file. Non esistono versioni ufficialmente pubblicate e nessuna versione del file corrisponde a una versione specifica di NuGet.

All'interno di questo schema, un file .nuspec ha il formato generale seguente:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Required elements-->
        <id></id>
        <version></version>
        <description></description>
        <authors></authors>

        <!-- Optional elements -->
        <!-- ... -->
    </metadata>
    <!-- Optional 'files' node -->
</package>

Per una rappresentazione visiva chiara dello schema, aprire il file di schema in Visual Studio in modalità progettazione e fare clic sul collegamento XML Schema Explorer. In alternativa, aprire il file come codice, fare clic con il pulsante destro del mouse nell'editor e scegliere Mostra in XML Schema Explorer. In entrambi i casi si ottiene una visualizzazione simile alla seguente (quando è per la maggior parte espansa):

Tutti i nomi degli elementi XML nel file con estensione nuspec fanno distinzione tra maiuscole e minuscole, come avviene per XML in generale. Ad esempio, l'uso dell'elemento <description> di metadati è corretto e <Description> non è corretto. Di seguito è illustrata la combinazione di maiuscole e minuscole appropriate per ogni nome di elemento.

Importante

Mentre il .nuspec file contiene un riferimento a uno schema (xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"), NuGet-Team non ha mai pubblicato un file di schema che potrebbe essere usato per la convalida automatica dello schema.

Elementi dei metadati obbligatori

Anche se gli elementi seguenti sono i requisiti minimi per un pacchetto, è consigliabile aggiungere gli elementi dei metadati facoltativi per migliorare l'esperienza complessiva degli sviluppatori con il pacchetto.

Questi elementi devono essere visualizzati all'interno di un elemento <metadata>.

id

Identificatore del pacchetto senza distinzione tra maiuscole e minuscole che deve essere univoco in nuget.org o in qualsiasi raccolta in cui risiede il pacchetto. L'ID non può contenere spazi o caratteri non validi per un URL e in genere segue le regole dello spazio dei nomi .NET. Vedere Choosing a unique package identifier and setting the version number (Scelta di un identificatore univoco del pacchetto e impostazione del numero di versione) per altre indicazioni.

Quando si carica un pacchetto in nuget.org, il id campo è limitato a 128 caratteri.

versione

La versione del pacchetto secondo il criterio principale.secondaria.patch. I numeri di versione possono includere un suffisso di versione non definitiva, come descritto in Controllo delle versioni dei pacchetti.

Quando si carica un pacchetto in nuget.org, il version campo è limitato a 64 caratteri.

description

Descrizione del pacchetto per la visualizzazione dell'interfaccia utente.

Quando si carica un pacchetto in nuget.org, il description campo è limitato a 4000 caratteri.

authors

Elenco delimitato da virgole di autori di pacchetti. E authors da owners nuspec vengono ignorati durante il caricamento del pacchetto in nuget.org. Per impostare la proprietà del pacchetto su nuget.org, vedere Gestione dei proprietari di pacchetti in nuget.org.

Elementi dei metadati facoltativi

owners

Importante

i proprietari sono deprecati. Usare invece gli autori.

Elenco delimitato da virgole dei proprietari di pacchetti. L'oggetto owners da nuspec viene ignorato durante il caricamento del pacchetto in nuget.org. Per impostare la proprietà del pacchetto su nuget.org, vedere Gestione dei proprietari di pacchetti in nuget.org.

projectUrl

URL della pagina iniziale del pacchetto, spesso visualizzato nell'interfaccia utente e in nuget.org.

Quando si carica un pacchetto in nuget.org, il projectUrl campo è limitato a 4000 caratteri.

licenseUrl

Importante

licenseUrl è deprecato. Usare invece la licenza.

URL per la licenza del pacchetto, spesso visualizzato in interfacce utente come nuget.org.

Quando si carica un pacchetto in nuget.org, il licenseUrl campo è limitato a 4000 caratteri.

Licenza

Supportato con NuGet 4.9.0 e versioni successive

Espressione di licenza SPDX o percorso di un file di licenza all'interno del pacchetto, spesso visualizzato in interfacce utente come nuget.org. Se si ha la licenza del pacchetto con una licenza comune, ad esempio MIT o BSD-2-Clause, usare l'identificatore di licenza SPDX associato. Ad esempio:

<license type="expression">MIT</license>

Nota

NuGet.org accetta solo espressioni di licenza approvate dall'iniziativa Open Source o Free Software Foundation.

Se il pacchetto è concesso in licenza con più licenze comuni, è possibile specificare una licenza composita usando la sintassi delle espressioni SPDX versione 2.0. Ad esempio:

<license type="expression">BSD-2-Clause OR MIT</license>

Se si usa una licenza personalizzata non supportata dalle espressioni di licenza, è possibile creare un pacchetto di un .txt file o .md con il testo della licenza. Ad esempio:

<package>
  <metadata>
    ...
    <license type="file">LICENSE.txt</license>
    ...
  </metadata>
  <files>
    ...
    <file src="licenses\LICENSE.txt" target="" />
    ...
  </files>
</package>

Per l'equivalente di MSBuild, vedere Creazione di un'espressione di licenza o di un file di licenza.

La sintassi esatta delle espressioni di licenza di NuGet è descritta di seguito in ABNF.

license-id            = <short form license identifier from https://spdx.org/spdx-specification-21-web-version#h.luq9dgcle9mo>

license-exception-id  = <short form license exception identifier from https://spdx.org/spdx-specification-21-web-version#h.ruv3yl8g6czd>

simple-expression = license-id / license-id”+”

compound-expression =  1*1(simple-expression /
                simple-expression "WITH" license-exception-id /
                compound-expression "AND" compound-expression /
                compound-expression "OR" compound-expression ) /                
                "(" compound-expression ")" )

license-expression =  1*1(simple-expression / compound-expression / UNLICENSED)

iconUrl

Importante

iconUrl è deprecato. Usare invece l'icona.

URL di un'immagine 128x128 con sfondo trasparente da usare come icona per il pacchetto nella visualizzazione dell'interfaccia utente. Assicurarsi che questo elemento contenga l'URL diretto dell'immagine e non l'URL di una pagina Web contenente l'immagine. Ad esempio, per usare un'immagine da GitHub, usare l'URL del file non elaborato, ad esempio username>/<repository>/raw/<branch>/<logo.png>.https://github.com/<

Quando si carica un pacchetto in nuget.org, il iconUrl campo è limitato a 4000 caratteri.

icona

Supportato con NuGet 5.3.0 e versioni successive

Si tratta di un percorso di un file di immagine all'interno del pacchetto, spesso visualizzato in interfacce utente come nuget.org come icona del pacchetto. Le dimensioni del file di immagine sono limitate a 1 MB. I formati di file supportati includono JPEG e PNG. È consigliabile una risoluzione dell'immagine di 128x128.

Ad esempio, è necessario aggiungere quanto segue a nuspec durante la creazione di un pacchetto usando nuget.exe:

<package>
  <metadata>
    ...
    <icon>images\icon.png</icon>
    ...
  </metadata>
  <files>
    ...
    <file src="..\icon.png" target="images\" />
    ...
  </files>
</package>

Esempio di icona pacchetto nuspec.

Per l'equivalente di MSBuild, vedere Compressione di un file di immagine icona.

Suggerimento

Per mantenere la compatibilità con le versioni precedenti con client e origini che non supportano iconancora , specificare sia icon che iconUrl. Visual Studio supporta icon i pacchetti provenienti da un'origine basata su cartelle.

readme

Supportato con NuGet 5.10.0 preview 2 e versioni successive

Quando si crea il pacchetto di un file readme, è necessario usare l'elemento readme per specificare il percorso del pacchetto, relativo alla radice del pacchetto. Oltre a questo, è necessario assicurarsi che il file sia incluso nel pacchetto. I formati di file supportati includono solo Markdown (.md).

Ad esempio, è necessario aggiungere quanto segue al file nuspec per comprimere un file leggimi con il progetto:

<package>
  <metadata>
    ...
    <readme>docs\readme.md</readme>
    ...
  </metadata>
  <files>
    ...
    <file src="..\readme.md" target="docs\" />
    ...
  </files>
</package>

Per l'equivalente di MSBuild, vedere Compressione di un file leggimi.

requireLicenseAcceptance

Valore booleano che specifica se il client deve richiedere al consumer di accettare la licenza del pacchetto prima di installarlo.

developmentDependency

(2.8 +) Valore booleano che specifica se il pacchetto deve essere contrassegnato come dipendenza solo per lo sviluppo, in modo che il pacchetto non possa essere incluso come dipendenza in altri pacchetti. Con PackageReference (NuGet 4.8 +), questo flag indica anche che gli asset in fase di compilazione verranno esclusi dalla compilazione. Vedere DevelopmentDependency support for PackageReference (Supporto di DevelopmentDependency per PackageReference)

riepilogo

Importante

summary è deprecato. Utilizzare invece description.

Descrizione breve del pacchetto per la visualizzazione dell'interfaccia utente. Se omesso, viene usata una versione troncata di description.

Quando si carica un pacchetto in nuget.org, il summary campo è limitato a 4000 caratteri.

releaseNotes

(1.5+) Descrizione delle modifiche apportate in questa versione del pacchetto, spesso usata nell'interfaccia utente, come la scheda Aggiornamenti di Gestione pacchetti di Visual Studio, in sostituzione della descrizione del pacchetto.

Quando si carica un pacchetto in nuget.org, il releaseNotes campo è limitato a 35.000 caratteri.

copyright

(1.5+) Informazioni sul copyright per il pacchetto.

Quando si carica un pacchetto in nuget.org, il copyright campo è limitato a 4000 caratteri.

lingua

ID delle impostazioni locali per il pacchetto. Vedere Creazione di pacchetti localizzati.

tag

Elenco di tag e parole chiave delimitati da spazi che descrivono il pacchetto e facilitano l'individuabilità dei pacchetti tramite meccanismi di ricerca e filtro.

Quando si carica un pacchetto in nuget.org, il tags campo è limitato a 4000 caratteri.

serviceable

(3.3+) Solo per uso interno in NuGet.

repository

Metadati del repository, costituiti da quattro attributi facoltativi: type e url (4.0+) e branch commit (4.6+). Questi attributi consentono di eseguire il mapping dell'oggetto .nupkg al repository che lo ha compilato, con il potenziale per ottenere informazioni dettagliate come il nome del singolo ramo e/o eseguire il commit dell'hash SHA-1 che ha compilato il pacchetto. Deve trattarsi di un URL disponibile pubblicamente che può essere richiamato direttamente da un software di controllo della versione. Non deve essere una pagina HTML perché questo è destinato al computer. Per il collegamento alla pagina del progetto, usare invece il projectUrl campo .

Ad esempio:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        ...
        <repository type="git" url="https://github.com/NuGet/NuGet.Client.git" branch="dev" commit="e1c65e4524cd70ee6e22abe33e6cb6ec73938cb3" />
        ...
    </metadata>
</package>

Quando si carica un pacchetto in nuget.org, l'attributo type è limitato a 100 caratteri e l'attributo url è limitato a 4000 caratteri.

title

Titolo descrittivo del pacchetto che può essere usato in alcuni schermi dell'interfaccia utente. (nuget.org e il Gestione pacchetti in Visual Studio non mostrano il titolo)

Quando si carica un pacchetto in nuget.org, il title campo è limitato a 256 caratteri, ma non viene usato per scopi di visualizzazione.

Elementi di raccolta

packageTypes

(3.5 +) Raccolta di zero o più elementi <packageType> che specificano il tipo del pacchetto se diverso da un pacchetto di dipendenza tradizionale. Ogni packageType include gli attributi di name e version. Vedere Setting a package type (Impostazione di un tipo di pacchetto).

dipendenze

Raccolta di zero o più elementi <dependency> che specificano le dipendenze per il pacchetto. Ogni dipendenza include gli attributi id, version, include (3.x+) ed exclude (3.x+). Vedere Dipendenze di seguito.

frameworkAssemblies

(1.2 +) Raccolta di zero o più elementi <frameworkAssembly> che identificano i riferimenti ad assembly .NET Framework richiesti dal pacchetto. Ciò assicura che i riferimenti vengano aggiunti ai progetti che utilizzano il pacchetto. Ogni frameworkAssembly include gli attributi assemblyName e targetFramework. Vedere Riferimenti agli assembly del framework più avanti.

references

(1.5 +) Raccolta di zero o più elementi <reference> per la denominazione degli assembly nella cartella lib del pacchetto, aggiunti come riferimenti al progetto. Ogni riferimento include un attributo file. <references> può anche contenere un elemento <group> con un attributo targetFramework, che contiene a sua volta elementi <reference>. Se omesso, vengono inclusi tutti i riferimenti in lib. Vedere Riferimenti espliciti agli assembly più avanti.

contentFiles

(3.3 +) Raccolta di elementi <files> che identificano i file di contenuto da includere nel progetto che utilizza il pacchetto. Questi file sono specificati con un set di attributi che descrivono come devono essere usati all'interno del sistema del progetto. Vedere Inclusione di file di assembly più avanti.

files

Il <package> nodo può contenere un <files> nodo come elemento di pari livello a <metadata>e un <contentFiles> elemento figlio in <metadata>per specificare quali file di assembly e contenuto includere nel pacchetto. Vedere Inclusione di file di assembly e Inclusione di file di contenuto più avanti in questo argomento per ulteriori dettagli.

attributi di metadati

minClientVersion

Specifica la versione minima del client NuGet, imposta da nuget.exe e da Gestione pacchetti di Visual Studio, che può installare questo pacchetto. Questo attributo viene usato ogni volta che il pacchetto dipende da funzionalità specifiche del file .nuspec aggiunte in una particolare versione del client NuGet. Ad esempio, un pacchetto che usa l'attributo developmentDependency deve specificare "2.8" per minClientVersion. Analogamente, un pacchetto che usa l'elemento contentFiles (vedere la sezione successiva) deve impostare minClientVersion su "3.3". Si noti che poiché i client NuGet prima della versione 2.5 non riconoscono questo flag, essi rifiutano sempre di installare il pacchetto indipendentemente dal contenuto di minClientVersion.

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata minClientVersion="100.0.0.1">
        <id>dasdas</id>
        <version>2.0.0</version>
        <title />
        <authors>dsadas</authors>
        <owners />
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>My package description.</description>
    </metadata>
    <files>
        <file src="content\one.txt" target="content\one.txt" />
    </files>
</package>

Token di sostituzione

Quando si crea un pacchetto, il nuget pack comando sostituisce i token delimitati da $nei nodi e <files> del <metadata> .nuspec file con valori provenienti da un file di progetto o dall'opzione pack del -properties comando.

Nella riga di comando, i valori dei token vengono specificati con nuget pack -properties <name>=<value>;<name>=<value>. Ad esempio, è possibile usare un token come $owners$ e $desc$ nel file .nuspec e specificare i valori al momento della creazione del pacchetto come indicato di seguito:

nuget pack MyProject.csproj -properties
    owners=janedoe,harikm,kimo,xiaop;desc="Awesome app logger utility"

Per usare valori da un progetto, specificare il token descritto nella tabella riportata di seguito (AssemblyInfo fa riferimento al file in Properties, ad esempio AssemblyInfo.cs o AssemblyInfo.vb).

Per usare questi token, eseguire nuget pack con il file di progetto anziché semplicemente il file .nuspec. Ad esempio, quando si usa il comando seguente, i token $id$ e $version$ in un file .nuspec vengono sostituiti con i valori AssemblyName e AssemblyVersion del progetto:

nuget pack MyProject.csproj

In genere, quando si dispone di un progetto, si crea inizialmente il file .nuspec con nuget spec MyProject.csproj, che include automaticamente alcuni di questi token standard. Tuttavia, se un progetto non include i valori per elementi .nuspec obbligatori, nuget pack ha esito negativo. Inoltre, se si modificano i valori del progetto, assicurarsi di ricompilare prima di creare il pacchetto. Questa operazione può essere eseguita facilmente con l'opzione build del comando pack.

Ad eccezione di $configuration$, i valori nel progetto vengono usati preferenzialmente rispetto a qualsiasi altro valore assegnato allo stesso token nella riga di comando.

Token	Origine del valore	Valore
$id$	File di progetto	AssemblyName (titolo) dal file di progetto
$version$	AssemblyInfo	AssemblyInformationalVersion se presente, in caso contrario AssemblyVersion
$author$	AssemblyInfo	AssemblyCompany
$title$	AssemblyInfo	AssemblyTitle
$description$	AssemblyInfo	AssemblyDescription
$copyright$	AssemblyInfo	AssemblyCopyright
$configuration$	DLL dell'assembly	Configurazione usata per compilare l'assembly, con impostazione predefinita Debug. Si noti che per creare un pacchetto con la configurazione Rilascio, è sempre necessario usare -properties Configuration=Release nella riga di comando.

I token possono essere usati anche per risolvere i percorsi quando si includono file di assembly e file di contenuto. I token hanno gli stessi nomi delle proprietà di MSBuild e ciò consente di selezionare i file da includere a seconda della configurazione di compilazione corrente. Ad esempio, se si usano i token seguenti nel file .nuspec:

<files>
    <file src="bin\$configuration$\$id$.pdb" target="lib\net40" />
</files>

E si compila un assembly il cui AssemblyName è LoggingLibrary con la configurazione Release in MSBuild, le righe risultanti nel file .nuspec nel pacchetto sono le seguenti:

<files>
    <file src="bin\Release\LoggingLibrary.pdb" target="lib\net40" />
</files>

Elemento Dependencies

L'elemento <dependencies> all'interno di <metadata> contiene qualsiasi numero di elementi <dependency> che identificano altri pacchetti da cui dipende il pacchetto di livello superiore. Gli attributi per ogni <dependency> sono i seguenti:

Attributo	Descrizione
id	(Obbligatorio) ID pacchetto della dipendenza, ad esempio "EntityFramework" e "NUnit", ovvero il nome di pacchetto che nuget.org mostra nella pagina di un pacchetto.
version	(Obbligatorio) Intervallo di versioni accettabili come dipendenza. Per la sintassi esatta, vedere Controllo delle versioni dei pacchetti. Le versioni mobili non sono supportate.
includere	Elenco delimitato da virgole di tag di inclusione/esclusione (vedere di seguito) che indicano la dipendenza da includere nel pacchetto finale. Il valore predefinito è all.
escludere	Elenco delimitato da virgole di tag di inclusione/esclusione (vedere di seguito) che indicano la dipendenza da escludere nel pacchetto finale. Il valore predefinito è build,analyzers che può essere sovrascritto. Ma content/ ContentFiles anche esclusi in modo implicito nel pacchetto finale che non può essere sovrascritto. I tag specificati con exclude hanno la precedenza rispetto a quelli specificati con include. Ad esempio, include="runtime, compile" exclude="compile" è identico a include="runtime".

Quando si carica un pacchetto in nuget.org, l'attributo di id ogni dipendenza è limitato a 128 caratteri e l'attributo version è limitato a 256 caratteri.

Tag di inclusione/esclusione	Cartelle di destinazione interessate
contentFiles	Contenuto
runtime	Runtime, Resources e FrameworkAssemblies
compile	lib
build	build (proprietà e destinazioni MSBuild)
native	native
Nessuno	Nessuna cartella
tutto	Tutte le cartelle

Ad esempio, le righe seguenti indicano dipendenze da PackageA versione 1.1.0 o successive e da PackageB versione 1.x.

<dependencies>
    <dependency id="PackageA" version="1.1.0" />
    <dependency id="PackageB" version="[1,2)" />
</dependencies>

Le righe seguenti indicano dipendenze dagli stessi pacchetti, ma specificano di includere le cartelle contentFiles e build di PackageA e tutte le cartelle tranne native e compile di PackageB.

<dependencies>
    <dependency id="PackageA" version="1.1.0" include="contentFiles, build" />
    <dependency id="PackageB" version="[1,2)" exclude="native, compile" />
</dependencies>

Importante

Quando si crea un oggetto .nuspec da un progetto usando nuget spec, le dipendenze presenti in tale progetto non vengono incluse automaticamente nel file risultante .nuspec . Usare invece nuget pack myproject.csproje ottenere il file con estensione nuspec dall'interno del file nupkg generato. Questo file con estensione nuspec contiene le dipendenze.

Gruppi di dipendenze

Versione 2.0+

In alternativa a un unico elenco semplice, è possibile specificare le dipendenze in base al profilo del framework del progetto di destinazione usando elementi <group> all'interno di <dependencies>.

Ogni gruppo ha un attributo denominato targetFramework e contiene zero o più elementi <dependency>. Tali dipendenze vengono installate insieme quando il framework di destinazione è compatibile con il profilo di framework del progetto.

L'elemento <group> senza un attributo targetFramework viene usato come elenco predefinito o di fallback delle dipendenze. Vedere Framework di destinazione per gli identificatori di framework esatti.

Importante

Il formato di gruppo non può essere usato in combinazione con un elenco semplice.

Nota

Il formato del moniker del framework di destinazione (TFM) usato nella lib/ref cartella è diverso rispetto al TFM usato in dependency groups. Se i framework di destinazione dichiarati nella dependencies group lib/ref cartella del .nuspec file non hanno corrispondenze esatte, pack il comando genererà l'avviso NuGet NU5128.

L'esempio seguente mostra variazioni diverse dell'elemento <group>:

<dependencies>
    <group>
        <dependency id="RouteMagic" version="1.1.0" />
    </group>

    <group targetFramework=".NETFramework4.7.2">
        <dependency id="jQuery" version="1.6.2" />
        <dependency id="WebActivator" version="1.4.4" />
    </group>

    <group targetFramework="netcoreapp3.1">
    </group>
</dependencies>

Riferimenti espliciti agli assembly

L'elemento <references> viene utilizzato dai progetti utilizzando packages.config per specificare in modo esplicito gli assembly a cui deve fare riferimento il progetto di destinazione quando si usa il pacchetto. I riferimenti espliciti vengono generalmente usati per gli assembly solo della fase di progettazione. Per altre informazioni, vedere la pagina relativa alla selezione di assembly a cui fanno riferimento i progetti .

Ad esempio, l'elemento <references> seguente indica a NuGet di aggiungere riferimenti solo a xunit.dll e a xunit.extensions.dll anche se sono presenti altri assembly nel pacchetto:

<references>
    <reference file="xunit.dll" />
    <reference file="xunit.extensions.dll" />
</references>

Gruppi di riferimenti

In alternativa a un unico elenco semplice, è possibile specificare i riferimenti in base al profilo del framework del progetto di destinazione usando elementi <group> all'interno di <references>.

Ogni gruppo ha un attributo denominato targetFramework e contiene zero o più elementi <reference>. Tali riferimenti vengono aggiunti a un progetto quando il framework di destinazione è compatibile con il profilo di framework del progetto.

L'elemento <group> senza un attributo targetFramework viene usato come elenco predefinito o di fallback dei riferimenti. Vedere Framework di destinazione per gli identificatori di framework esatti.

Importante

Il formato di gruppo non può essere usato in combinazione con un elenco semplice.

L'esempio seguente mostra variazioni diverse dell'elemento <group>:

<references>
    <group>
        <reference file="a.dll" />
    </group>

    <group targetFramework="net45">
        <reference file="b45.dll" />
    </group>

    <group targetFramework="netcore45">
        <reference file="bcore45.dll" />
    </group>
</references>

Riferimenti agli assembly del framework

Gli assembly del framework sono quelli che fanno parte di .NET Framework e devono essere già presenti nella Global Assembly Cache (GAC) per qualsiasi computer. Grazie all'identificazione di tali assembly all'interno dell'elemento <frameworkAssemblies>, un pacchetto può garantire che i riferimenti necessari vengano aggiunti a un progetto nel caso in cui il progetto non includa già tali riferimenti. Tali assembly, ovviamente, non vengono inclusi in un pacchetto direttamente.

L'elemento <frameworkAssemblies> contiene zero o più elementi <frameworkAssembly>, ognuno dei quali specifica gli attributi seguenti:

Attributo	Descrizione
assemblyName	(Obbligatorio) Nome completo dell'assembly.
targetFramework	(Facoltativo) Specifica il framework di destinazione a cui si applica questo riferimento. Se omesso, indica che il riferimento si applica a tutti i framework. Vedere Framework di destinazione per gli identificatori di framework esatti.

L'esempio seguente mostra un riferimento a System.Net per tutti i framework di destinazione e un riferimento a System.ServiceModel solo per .NET Framework 4.0:

<frameworkAssemblies>
    <frameworkAssembly assemblyName="System.Net"  />

    <frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
</frameworkAssemblies>

Inclusione di file di assembly

Se si seguono le convenzioni descritte in Creazione di un pacchetto, non è necessario specificare in modo esplicito un elenco di file nel file .nuspec. Il comando nuget pack rileva automaticamente i file necessari.

Importante

Quando un pacchetto viene installato in un progetto, NuGet aggiunge automaticamente i riferimenti agli assembly alle DLL del pacchetto, escludendo quelli denominati .resources.dll perché si presuppone che siano assembly satellite localizzati. Per questo motivo, evitare di usare .resources.dll per i file che contengono invece codice essenziale per il pacchetto.

Per evitare questo comportamento automatico e controllare in modo esplicito quali file vengono inclusi in un pacchetto, posizionare un elemento <files> come elemento figlio di <package> (ed elemento di pari livello di <metadata>), identificando ogni file con un elemento <file> separato. Ad esempio:

<files>
    <file src="bin\Debug\*.dll" target="lib" />
    <file src="bin\Debug\*.pdb" target="lib" />
    <file src="tools\**\*.*" exclude="**\*.log" />
</files>

Con NuGet 2.x e versioni precedenti e i progetti che usano packages.config, l'elemento <files> viene usato anche per includere file di contenuto non modificabili quando viene installato un pacchetto. Con NuGet 3.3 + e PackageReference per i progetti, viene invece usato l'elemento <contentFiles>. Vedere Inclusione di file di contenuto di seguito per informazioni dettagliate.

Attributi dell'elemento file

Ogni elemento <file> specifica gli attributi seguenti:

Attributo	Descrizione
src	Percorso del file o dei file da includere, soggetto alle esclusioni specificate dall'attributo exclude. Il percorso è relativo al file .nuspec, a meno che non venga specificato un percorso assoluto. Il carattere jolly * è consentito e il carattere jolly doppio ** implica una ricerca ricorsiva nelle cartelle.
target	Percorso relativo della cartella all'interno del pacchetto in cui vengono collocati i file di origine, che deve iniziare con lib, content, build o tools. Vedere Creazione di un file .nuspec da una directory di lavoro basata su convenzioni.
exclude	Elenco delimitato da punti e virgola dei file o dei modelli di file da escludere dal percorso src. Il carattere jolly * è consentito e il carattere jolly doppio ** implica una ricerca ricorsiva nelle cartelle.

Esempi

Singolo assembly

Source file:
    library.dll

.nuspec entry:
    <file src="library.dll" target="lib" />

Packaged result:
    lib\library.dll

Singolo assembly specifico di un framework di destinazione

Source file:
    library.dll

.nuspec entry:
    <file src="assemblies\net40\library.dll" target="lib\net40" />

Packaged result:
    lib\net40\library.dll

Set di DLL con un carattere jolly

Source files:
    bin\release\libraryA.dll
    bin\release\libraryB.dll

.nuspec entry:
    <file src="bin\release\*.dll" target="lib" />

Packaged result:
    lib\libraryA.dll
    lib\libraryB.dll

DLL per framework diversi

Source files:
    lib\net40\library.dll
    lib\net20\library.dll

.nuspec entry (using ** recursive search):
    <file src="lib\**" target="lib" />

Packaged result:
    lib\net40\library.dll
    lib\net20\library.dll

Esclusione di file

Source files:
    \tools\fileA.bak
    \tools\fileB.bak
    \tools\fileA.log
    \tools\build\fileB.log

.nuspec entries:
    <file src="tools\*.*" target="tools" exclude="tools\*.bak" />
    <file src="tools\**\*.*" target="tools" exclude="**\*.log" />

Package result:
    (no files)

Inclusione di file di contenuto

I file di contenuto sono file non modificabili che un pacchetto deve includere in un progetto. Essendo non modificabili, non sono progettati per essere modificati dal progetto che li utilizza. Alcuni esempi di file di contenuto includono:

• Immagini incorporate come risorse
• File di origine già compilati
• Script che devono essere inclusi con l'output di compilazione del progetto
• File di configurazione per il pacchetto che devono essere inclusi nel progetto ma non richiedono modifiche specifiche del progetto

I file di contenuto vengono inclusi in un pacchetto con l'elemento <files>, specificando la cartella content nell'attributo target. Questi file vengono tuttavia ignorati quando il pacchetto viene installato in un progetto usando PackageReference, che usa invece l'elemento <contentFiles>.

Per ottenere la massima compatibilità con i progetti in cui viene utilizzato, un pacchetto specifica idealmente i file di contenuto in entrambi gli elementi.

Uso dell'elemento files per i file di contenuto

Per i file di contenuto, usare semplicemente lo stesso formato usato per i file di assembly, ma specificare content come cartella di base nell'attributo target, come illustrato negli esempi seguenti.

File di contenuto semplici

Source files:
    css\mobile\style1.css
    css\mobile\style2.css

.nuspec entry:
    <file src="css\mobile\*.css" target="content\css\mobile" />

Packaged result:
    content\css\mobile\style1.css
    content\css\mobile\style2.css

File di contenuto con struttura di directory

Source files:
    css\mobile\style.css
    css\mobile\wp7\style.css
    css\browser\style.css

.nuspec entry:
    <file src="css\**\*.css" target="content\css" />

Packaged result:
    content\css\mobile\style.css
    content\css\mobile\wp7\style.css
    content\css\browser\style.css

File di contenuto specifico di un framework di destinazione

Source file:
    css\cool\style.css

.nuspec entry
    <file src="css\cool\style.css" target="Content" />

Packaged result:
    content\style.css

File di contenuto copiato in una cartella con un punto nel nome

In questo caso, NuGet rileva che l'estensione in target non corrisponde all'estensione in src, quindi interpreta la parte del nome in target come cartella:

Source file:
    images\picture.png

.nuspec entry:
    <file src="images\picture.png" target="Content\images\package.icons" />

Packaged result:
    content\images\package.icons\picture.png

File di contenuto senza estensione

Per includere i file senza estensione, usare i caratteri jolly * o **:

Source file:
    flags\installed

.nuspec entry:
    <file src="flags\**" target="flags" />

Packaged result:
    flags\installed

File di contenuto con percorso completo e destinazione completa

In questo caso, dato che le estensioni dei file di origine e di destinazione corrispondono, NuGet presuppone che la destinazione sia un nome di file e non una cartella:

Source file:
    css\cool\style.css

.nuspec entry:
    <file src="css\cool\style.css" target="Content\css\cool" />
    or:
    <file src="css\cool\style.css" target="Content\css\cool\style.css" />

Packaged result:
    content\css\cool\style.css

Ridenominazione di un file di contenuto nel pacchetto

Source file:
    ie\css\style.css

.nuspec entry:
    <file src="ie\css\style.css" target="Content\css\ie.css" />

Packaged result:
    content\css\ie.css

Esclusione di file

Source file:
    docs\*.txt (multiple files)

.nuspec entry:
    <file src="docs\*.txt" target="content\docs" exclude="docs\admin.txt" />
    or
    <file src="*.txt" target="content\docs" exclude="admin.txt;log.txt" />

Packaged result:
    All .txt files from docs except admin.txt (first example)
    All .txt files from docs except admin.txt and log.txt (second example)

Uso dell'elemento contentFiles per i file di contenuto

NuGet 4.0 + con PackageReference

Per impostazione predefinita, un pacchetto inserisce il contenuto in una cartella contentFiles (vedere di seguito) e nuget pack include tutti i file nella cartella usando gli attributi predefiniti. In questo caso non è affatto necessario includere un nodo contentFiles nel file .nuspec.

Per controllare quali file sono inclusi, l'elemento <contentFiles> specifica una raccolta di elementi <files> che identificano i file esatti inclusi.

Questi file sono specificati con un set di attributi che descrivono come devono essere usati all'interno del sistema del progetto:

Attributo	Descrizione
include	(Obbligatorio) Percorso del file o dei file da includere, soggetto alle esclusioni specificate dall'attributo exclude. Il percorso è relativo alla contentFiles cartella a meno che non venga specificato un percorso assoluto. Il carattere jolly * è consentito e il carattere jolly doppio ** implica una ricerca ricorsiva nelle cartelle.
exclude	Elenco delimitato da punti e virgola dei file o dei modelli di file da escludere dal percorso src. Il carattere jolly * è consentito e il carattere jolly doppio ** implica una ricerca ricorsiva nelle cartelle.
buildAction	Azione di compilazione da assegnare all'elemento di contenuto per MSBuild, ad esempio Content, None, Embedded Resource, Compilee così via. Il valore predefinito è Compile.
copyToOutput	Valore booleano che indica se copiare gli elementi di contenuto nella cartella di output di compilazione (o pubblicazione). L'impostazione predefinita è false.
flatten	Valore booleano che indica se copiare gli elementi di contenuto di una singola cartella nell'output di compilazione (true) o se mantenere la struttura di cartelle nel pacchetto (false). Questo flag funziona solo quando il flag copyToOutput è impostato su true. L'impostazione predefinita è false.

Quando si installa un pacchetto, NuGet applica gli elementi figlio di <contentFiles> dall'alto verso il basso. Se più voci corrispondono allo stesso file, vengono applicate tutte le voci. La voce di livello superiore sostituisce le voci inferiori in presenza di un conflitto per lo stesso attributo.

Struttura delle cartelle del pacchetto

Il progetto del pacchetto deve strutturare il contenuto in base al modello seguente:

/contentFiles/{codeLanguage}/{TxM}/{any?}

• codeLanguages può essere cs, vb, fs, any o l'equivalente in caratteri minuscoli di uno specifico $(ProjectLanguage)
• TxM è qualsiasi moniker di framework di destinazione valido supportato da NuGet (vedere Framework di destinazione).
• Qualsiasi struttura di cartelle può essere aggiunta alla fine di questa sintassi.

Ad esempio:

Language- and framework-agnostic:
    /contentFiles/any/any/config.xml

net45 content for all languages
    /contentFiles/any/net45/config.xml

C#-specific content for net45 and up
    /contentFiles/cs/net45/sample.cs

Le cartelle vuote possono usare _._ per rifiutare esplicitamente di fornire contenuti per determinate combinazioni di linguaggio e TxM, ad esempio:

/contentFiles/vb/any/code.vb
/contentFiles/cs/any/_._

Sezione di esempio contentFiles

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        ...
        <contentFiles>
            <!-- Embed image resources -->
            <files include="any/any/images/dnf.png" buildAction="EmbeddedResource" />
            <files include="any/any/images/ui.png" buildAction="EmbeddedResource" />

            <!-- Embed all image resources under contentFiles/cs/ -->
            <files include="cs/**/*.png" buildAction="EmbeddedResource" />

            <!-- Copy config.xml to the root of the output folder -->
            <files include="cs/uap/config/config.xml" buildAction="None" copyToOutput="true" flatten="true" />

            <!-- Copy run.cmd to the output folder and keep the directory structure -->
            <files include="cs/commands/run.cmd" buildAction="None" copyToOutput="true" flatten="false" />

            <!-- Include everything in the scripts folder except exe files -->
            <files include="cs/net45/scripts/*" exclude="**/*.exe"  buildAction="None" copyToOutput="true" />
        </contentFiles>
        </metadata>
</package>

Gruppi di riferimento del framework

Solo PackageReference versione 5.1+ wih

I riferimenti al framework sono un concetto di .NET Core che rappresenta framework condivisi, ad esempio WPF o Windows Form. Specificando un framework condiviso, il pacchetto garantisce che tutte le relative dipendenze del framework siano incluse nel progetto di riferimento.

Ogni <group> elemento richiede un targetFramework attributo e zero o più <frameworkReference> elementi.

L'esempio seguente mostra un nuspec generato per un progetto WPF .NET Core. Si noti che la creazione manuale di nuspec che contengono riferimenti al framework non è consigliata. Prendere invece in considerazione l'uso del pacchetto di destinazioni , che li dedurrà automaticamente dal progetto.

<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
  <metadata>
    <dependencies>
      <group targetFramework=".NETCoreApp3.1" />
    </dependencies>
    <frameworkReferences>
      <group targetFramework=".NETCoreApp3.1">
        <frameworkReference name="Microsoft.WindowsDesktop.App.WPF" />
      </group>
    </frameworkReferences>
  </metadata>
</package>

File nuspec di esempio

File .nuspec semplice che non specifica dipendenze o file

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.2.3</version>
        <authors>Kim Abercrombie, Franck Halmaert</authors>
        <description>Sample exists only to show a sample .nuspec file.</description>
        <language>en-US</language>
        <projectUrl>http://xunit.codeplex.com/</projectUrl>
        <license type="expression">MIT</license>
    </metadata>
</package>

File .nuspec con dipendenze

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.0.0</version>
        <authors>Microsoft</authors>
        <dependencies>
            <dependency id="another-package" version="3.0.0" />
            <dependency id="yet-another-package" version="1.0.0" />
        </dependencies>
    </metadata>
</package>

File .nuspec con file

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>routedebugger</id>
        <version>1.0.0</version>
        <authors>Jay Hamlin</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>Route Debugger is a little utility I wrote...</description>
    </metadata>
    <files>
        <file src="bin\Debug\*.dll" target="lib" />
    </files>
</package>

File .nuspec con assembly di framework

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>PackageWithGacReferences</id>
        <version>1.0</version>
        <authors>Author here</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>
            A package that has framework assemblyReferences depending
            on the target framework.
        </description>
        <frameworkAssemblies>
            <frameworkAssembly assemblyName="System.Web" targetFramework="net40" />
            <frameworkAssembly assemblyName="System.Net" targetFramework="net40-client, net40" />
            <frameworkAssembly assemblyName="Microsoft.Devices.Sensors" targetFramework="sl4-wp" />
            <frameworkAssembly assemblyName="System.Json" targetFramework="sl3" />
        </frameworkAssemblies>
    </metadata>
</package>

In questo esempio vengono installati i componenti seguenti per destinazioni di progetto specifiche:

• . NET4 ->System.Web, System.Net
• . Profilo client NET4 ->System.Net
• Silverlight 3 ->System.Json
• WindowsPhone ->Microsoft.Devices.Sensors