NUSPEC-Referenz

Bei einer .nuspec-Datei handelt es sich um eine XML-Manifestdatei, die Paketmetadaten enthält. Diese Manifestdatei wird sowohl für die Erstellung des Pakets als auch zur Bereitstellung von Informationen für die Benutzer verwendet. Manifestdateien sind in allen Paketen enthalten.

In diesem Thema:

• Allgemeine Form und Schema
• Ersetzungstokens (bei der Verwendung in einem Visual Studio-Projekt)
• Abhängigkeiten
• Explizite Assemblyverweise
• Verweise auf Frameworkassemblys
• Einfügen von Assemblydateien
• Einfügen von Inhaltsdateien
• Beispiel: nuspec-Dateien

Projekttyp-Kompatibilität

• Verwenden Sie .nuspec mit nuget.exe pack für nicht-SDK-artige Projekte, die packages.config nutzen.

• Eine .nuspec Datei ist nicht erforderlich, um Pakete für PROJEKTE im SDK-Stil zu erstellen (in der Regel .NET Core- und .NET Standard-Projekte, die das SDK-Attribut verwenden). (Beachten Sie, dass beim Erstellen des Pakets ein .nuspec generiert wird.)

  Wenn Sie ein Paket mit dotnet.exe pack oder msbuild pack target erstellen, empfehlen wir Ihnen, stattdessen alle Eigenschaften, die normalerweise in der .nuspec Datei enthalten sind, in die Projektdatei aufzunehmen. Sie können jedoch stattdessen eine .nuspec Datei zum Packen verwenden mit dotnet.exe oder msbuild pack target.

• Für Projekte, die von packages.config PackageReference migriert wurden, ist zum .nuspec Erstellen des Pakets keine Datei erforderlich. Verwenden Sie stattdessen msbuild -t:pack.

Allgemeine Form und Schema

Eine nuspec.xsd-Schemadatei finden Sie im NuGet GitHub-Repository. Beachten Sie, dass diese Datei nur das neueste Schema für eine .nuspec Datei repräsentiert. Es sind keine offiziell veröffentlichten Versionen vorhanden und keine Version dieser Datei entspricht einer bestimmten NuGet-Version.

Für dieses Schema gilt die im Folgenden dargestellte allgemeine Form für die .nuspec-Datei:

<?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>

Für eine übersichtliche Darstellung des Schemas öffnen Sie die Schemadatei im Entwurfsmodus in Visual Studio, und klicken Sie auf den Link XML-Schema-Explorer. Alternativ können Sie auch die Datei als Code öffnen, mit der rechten Maustaste in den Editor klicken und Show XML Schema Explorer (XML-Schema-Explorer anzeigen) auswählen. In beiden Fällen wird eine Ansicht zurückgegeben, die der in der folgenden Abbildung ähnlich ist, wenn Sie größtenteils erweitert ist:

Bei allen XML-Elementnamen in der .nuspec-Datei wird die Groß-/Kleinschreibung beachtet, wie bei XML im Allgemeinen. Die Verwendung des Metadatenelements <description> ist beispielsweise korrekt und <Description> nicht korrekt. Die richtige Groß-/Kleinschreibung für jeden Elementnamen ist unten dokumentiert.

Wichtig

Die .nuspec-Datei enthält zwar einen Verweis auf ein Schema (xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"), jedoch hat das NuGet-Team nie eine Schemadatei veröffentlicht, die für die automatische Schemaüberprüfung verwendet werden kann.

Erforderliche Metadatenelemente

Obwohl es sich bei den folgenden Elementen um die Mindestanforderungen für ein Paket handelt, sollten Sie in Erwägung ziehen, die optionalen Metadatenelemente hinzuzufügen, damit Entwicklern die Arbeit mit Ihren Paketen erleichtert wird.

Diese Elemente müssen in einem <metadata>-Element angezeigt werden.

id

Der Paketbezeichner, der die Groß- und Kleinschreibung nicht berücksichtigt und auf nuget.org oder im für das Paket verwendeten Katalog eindeutig sein muss. IDs dürfen keine Leerzeichen oder für eine URL unzulässige Zeichen enthalten. Sie müssen den Regeln für .NET-Namespaces entsprechen. Informationen finden Sie unter Choosing a unique package identifier (Auswählen eines eindeutigen Paketbezeichners).

Beim Hochladen eines Pakets auf nuget.org ist das id Feld auf 128 Zeichen beschränkt.

version

Die Version des Pakets, die dem Muster Hauptversion.Nebenversion.Patch folgt. Versionsnummern enthalten möglicherweise, wie unter Paketversionsverwaltung beschrieben, ein Suffix der Vorabversion.

Beim Hochladen eines Pakets auf nuget.org ist das version Feld auf 64 Zeichen beschränkt.

Beschreibung

Eine Beschreibung des Pakets für die Anzeige der Benutzeroberfläche.

Beim Hochladen eines Pakets in nuget.org ist das description Feld auf 4000 Zeichen beschränkt.

authors

Eine durch Kommata getrennte Liste von Paketautoren. Die authors und die owners von der Nuspec-Datei werden beim Hochladen des Pakets auf nuget.org ignoriert. Informationen zum Festlegen des Paketbesitzes für nuget.org finden Sie unter Verwalten von Paketbesitzern auf nuget.org.

Optionale Metadatenelemente

Besitzer

Wichtig

Besitzer sind veraltet. Verwenden Sie stattdessen Autor.

Eine durch Komma getrennte Liste der Paketbesitzer. Die owners von der Nuspec-Datei wird beim Hochladen des Pakets auf nuget.org ignoriert. Informationen zum Festlegen des Paketbesitzes für nuget.org finden Sie unter Verwalten von Paketbesitzern auf nuget.org.

projectUrl

Eine URL für die Paket-Homepage, häufig auf der Benutzeroberfläche sowie auf nuget.org angezeigt.

Beim Hochladen eines Pakets in nuget.org ist das projectUrl Feld auf 4000 Zeichen beschränkt.

licenseUrl

Wichtig

licenseUrl ist veraltet. Verwenden Sie stattdessen Lizenz.

Eine URL für die Paketlizenz, häufig auf der Benutzeroberfläche sowie auf nuget.org angezeigt.

Beim Hochladen eines Pakets in nuget.org ist das licenseUrl Feld auf 4000 Zeichen beschränkt.

license

Unterstützt mit NuGet 4.9.0 und höher

Ein SPDX-Lizenzausdruck oder Pfad zu einer Lizenzdatei innerhalb des Pakets, häufig in Benutzeroberflächen wie nuget.org angezeigt. Wenn Sie das Paket unter einer gemeinsamen Lizenz wie MIT oder BSD-2-Klausel lizenzieren, verwenden Sie den zugehörigen SPDX-Lizenzbezeichner. Zum Beispiel:

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

Hinweis

NuGet.org akzeptiert nur Lizenzausdrücke, die von der Open-Source-Initiative oder der Free Software Foundation genehmigt wurden.

Wenn Ihr Paket unter mehreren allgemeinen Lizenzen lizenziert ist, können Sie eine zusammengesetzte Lizenz mit der SPDX-Ausdruckssyntax Version 2.0 angeben. Zum Beispiel:

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

Wenn Sie eine benutzerdefinierte Lizenz verwenden, die von Lizenzausdrücken nicht unterstützt wird, können Sie eine .txt oder .md Datei mit dem Text der Lizenz verpacken. Zum Beispiel:

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

Das MSBuild-Äquivalent finden Sie unter Packen eines Lizenzausdrucks oder einer Lizenzdatei

Die genaue Syntax für die NuGet Lizenzausdrücke wird unten in ABNF beschrieben.

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

Wichtig

iconUrl ist veraltet. Verwenden Sie stattdessen Symbol.

Eine URL für ein 128x128-Bild mit transparentem Hintergrund, das als Symbol für das Paket in der Benutzeroberfläche verwendet wird. Stellen Sie sicher, dass dieses Element die direkte Bild-URL und nicht nur die URL einer Webseite enthält, die das Bild enthält. Wenn Sie z. B. ein Bild von GitHub verwenden möchten, verwenden Sie die URL der rohen Datei wie https://github.com/<username>/<repository>/raw/<branch>/<logo.png>.

Beim Hochladen eines Pakets in nuget.org ist das iconUrl Feld auf 4000 Zeichen beschränkt.

Symbol

Unterstützt mit NuGet 5.3.0 und höher

Es handelt sich um einen Pfad zu einer Bilddatei innerhalb des Pakets, die häufig in Benutzeroberflächen wie nuget.org als Paketsymbol angezeigt wird. Die Größe der Bilddatei ist auf 1 MB begrenzt. Unterstützte Dateiformate: JPEG und PNG. Wir empfehlen eine Bildauflösung von 128 x 128.

Sie würden z. B. Folgendes zu Ihrer Nuspec hinzufügen, wenn Sie ein Paket mit nuget.exe erstellen:

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

Beispiel für paketsymbol nuspec.

Sehen Sie sich für das MSBuild-Äquivalent eine Symbolbilddatei an.

Tipp

Um die Abwärtskompatibilität mit Clients und Quellen zu wahren, die noch keine icon Unterstützung bieten, spezifizieren Sie sowohl icon als auch iconUrl. Visual Studio unterstützt icon Pakete, die aus einer ordnerbasierten Quelle stammen.

readme

Unterstützt mit NuGet 5.10.0 Preview 2 und höher

Beim Packen einer Readme-Datei müssen Sie das readme Element verwenden, um den Paketpfad relativ zum Stammverzeichnis des Pakets anzugeben. Darüber hinaus müssen Sie sicherstellen, dass die Datei im Paket enthalten ist. Unterstützte Dateiformate umfassen nur Markdown (.md).

Sie würden beispielsweise Folgendes zu Ihrer nuspec hinzufügen, um eine Infodatei mit Ihrem Projekt zu packen:

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

Sehen Sie sich das MSBuild-Äquivalent an, um eine Readme-Datei zu packen.

requireLicenseAcceptance

Ein boolescher Wert, der angibt, ob der Client den Benutzer dazu auffordern muss, die Paketlizenz vor der Installation des Pakets zu akzeptieren.

developmentDependency

(2.8 und höher) Ein boolescher Wert, der angibt, ob das Paket mit einer Abhängigkeit markiert werden soll, die nur für die Entwicklung gilt, wodurch vermieden wird, dass das Paket als Abhängigkeit in andere Pakete eingefügt wird. Bei PackageReference (NuGet 4.8+) bedeutet dieses Flag auch, dass Objekte zur Kompilierzeit von der Kompilierung ausgeschlossen werden. Weitere Informationen finden Sie unter DevelopmentDependency-Stütze für PackageReference

Zusammenfassung

Wichtig

summary ist veraltet. Verwenden Sie stattdessen description.

Eine kurze Beschreibung des Pakets für die Anzeige der Benutzeroberfläche. Wenn diese nicht angegeben wird, wird eine gekürzte Version von description verwendet.

Beim Hochladen eines Pakets in nuget.org ist das summary Feld auf 4000 Zeichen beschränkt.

releaseNotes

(1.5 und höher) Eine Beschreibung der in diesem Release des Pakets enthaltenen Änderungen, die häufig in Benutzeroberflächen wie der Registerkarte Updates des Visual Studio-Paket-Managers anstelle von Paketbeschreibungen verwendet wird.

Beim Hochladen eines Pakets auf nuget.org ist das releaseNotes Feld auf 35.000 Zeichen beschränkt.

copyright

(1.5 und höher) Copyright-Informationen zum Paket.

Beim Hochladen eines Pakets in nuget.org ist das copyright Feld auf 4000 Zeichen beschränkt.

language

Die Gebietsschema-ID des Pakets. Informationen dazu finden Sie unter Creating localized packages (Erstellen von lokalisierten Paketen).

tags

Eine durch Leerzeichen getrennte Liste mit Tags und Schlüsselwörtern, die das Paket beschreiben und zum Ermitteln von Paketen über Suchvorgänge und Filter beitragen.

Beim Hochladen eines Pakets in nuget.org ist das tags Feld auf 4000 Zeichen beschränkt.

serviceable

(3.3 und höher) Nur für die interne Verwendung von NuGet.

repository

Repositorymetadaten, bestehend aus vier optionalen Attributen: type und url (4.0+) sowie branch und commit (4.6+). Mit diesen Attributen können Sie das .nupkg Repository zuordnen, das es erstellt hat, mit dem Potenzial, so detailliert wie der Name der einzelnen Verzweigung und /oder commit SHA-1-Hash abzurufen, das das Paket erstellt hat. Dies sollte eine öffentlich verfügbare URL sein, die direkt von einer Versionskontrollsoftware aufgerufen werden kann. Es sollte keine HTML-Seite sein, da dies für den Computer vorgesehen ist. Verwenden Sie zum Verknüpfen mit der Projektseite stattdessen das projectUrl Feld.

Zum Beispiel:

<?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>

Beim Hochladen eines Pakets auf nuget.org ist das type Attribut auf 100 Zeichen beschränkt, und das url Attribut ist auf 4000 Zeichen beschränkt.

title

Ein benutzerfreundlicher Titel des Pakets, das in einigen Benutzeroberflächen-Displays verwendet werden kann. (nuget.org und die Paket-Manager in Visual Studio zeigen keinen Titel an)

Beim Hochladen eines Pakets auf nuget.org ist das title Feld auf 256 Zeichen beschränkt, wird jedoch nicht für Anzeigezwecke verwendet.

Auflistungselemente

packageTypes

(3.5 und höher) Eine Auflistung, die kein <packageType>-Element oder mindestens eins enthält und den Pakettyp angibt, wenn es sich nicht um ein gewöhnliches Abhängigkeitspaket handelt. Jeder „packageType“ verfügt über Attribute von name und version. Informationen dazu finden Sie unter Setting a package type (Festlegen eines Pakettypen).

Abhängigkeiten

Eine Auflistung, die kein <dependency>-Element oder mindestens eins enthält und Abhängigkeiten für das Paket angibt. Jede Abhängigkeit verfügt über Attribute von id, version, include und exclude (3.x und höher). Informationen dazu finden Sie im Abschnitt Abhängigkeiten.

frameworkAssemblies

(1.2 und höher) Eine Auflistung, die kein <frameworkAssembly>-Element oder mindestens eins enthält und die für das Paket erforderlichen Verweise auf .NET Framework-Assemblys erkennt und sicherstellt, dass Verweise zu Projekten hinzugefügt werden, die das Paket verarbeiten. Jedes frameworkAssembly-Element verfügt über die Attribute assemblyName und targetFramework. Informationen dazu finden Sie unter Specifying framework assembly references GAC (Angeben von GAC-Verweisen auf Frameworkassemblys).

Verweist auf

(1.5 und höher) Eine Auflistung, die kein <reference>-Element oder mindestens eins enthält, das Assemblys in dem lib-Ordner des Pakets benennt, die als Projektverweise hinzugefügt werden. Jeder Verweis verfügt über ein file-Attribut. <references> kann außerdem ein <group>-Element mit einem targetFramework-Attribut enthalten, das anschließend <reference>-Elemente enthält. Wenn das Element nicht angegeben ist, werden alle Verweise in lib eingefügt. Informationen dazu finden Sie unter Specifying explicit assembly references (Angeben von expliziten Assemblyverweisen).

contentFiles

(3.3 und höher) Eine Auflistung von <files>-Elementen, die Inhaltsdateien ermitteln, die in das verarbeitende Projekt eingefügt werden sollen. Diese Dateien werden zusammen mit mehreren Attributen angegeben, die beschreiben, wie sie in dem Projektsystem verwendet werden sollen. Informationen dazu finden Sie unter Specifying files to include in the package (Angeben von Dateien, die in das Paket eingefügt werden sollen).

files

Der <package>-Knoten enthält möglicherweise einen <files>-Knoten, der <metadata> gleichgeordnet ist, und eine untergeordnete <contentFiles>-Datei unter <metadata>, um anzugeben, welche Assembly- und Inhaltsdateien in das Paket eingefügt werden sollen. Details dazu finden Sie im Folgenden in den Abschnitten Einfügen von Assemblydateien und Einfügen von Inhaltsdateien.

Metadatenattribute

minClientVersion

Gibt die minimale Version des NuGet-Clients an, der dieses Paket installieren kann. Dies wird von nuget.exe und dem Paket-Manager von Visual Studio erzwungen. Dieses Attribut wird verwendet, wenn das Paket von bestimmten Funktionen der .nuspec-Datei abhängig ist, die in einer bestimmten Version des NuGet-Clients hinzugefügt wurden. Beispielsweise sollte ein Paket, das das developmentDependency-Attribut verwendet, „2.8“ für minClientVersion angeben. Genauso sollte ein Paket, das das contentFiles-Element verwendet (vgl. nächster Abschnitt), minClientVersion auf „3.3“ festlegen. Beachten Sie außerdem, dass NuGet-Clients vor Version 2.5 diese Kennzeichnung nicht erkennen und daher die Installation des Pakets, unabhängig vom Inhalt von minClientVersion, immer verweigern.

<?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>

Ersetzungstokens

Bei der Erstellung eines Pakets ersetzt der nuget pack-Befehl durch $ getrennte Tokens in den <metadata>- und <files>-Knoten der .nuspec-Datei durch Werte, die entweder einer Projektdatei oder dem pack-Schalter des -properties-Befehls entstammen.

Geben Sie in der Befehlszeile die Tokenwerte mit nuget pack -properties <name>=<value>;<name>=<value> an. Beispielsweise können Sie ein Token wie $owners$ und $desc$ in der .nuspec-Datei verwenden und die Werte zur Packzeit wie im Folgenden dargestellt bereitstellen:

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

Geben Sie die in der untenstehenden Tabelle beschriebenen Tokens an, um Werte aus einem Projekt zu verwenden (AssemblyInfo verweist auf Dateien wie AssemblyInfo.cs oder AssemblyInfo.vb in Properties).

Führen Sie anstelle von .nuspec nur nuget pack in der Projektdatei aus, um diese Tokens zu verwenden. Beispielsweise werden bei der Verwendung des folgenden Befehls die Tokens $id$ und $version$ in einer .nuspec-Datei durch die Werte AssemblyName und AssemblyVersion des Projekts ersetzt:

nuget pack MyProject.csproj

In der Regel erstellen Sie .nuspec in einem Projekt zuerst mithilfe von nuget spec MyProject.csproj, wodurch automatisch einige dieser Standardtokens eingefügt werden. Wenn in einem Projekt allerdings keine Werte für erforderliche .nuspec-Elemente enthalten sind, schlägt nuget pack fehl. Stellen Sie außerdem bei der Änderung von Projektwerten sicher, dass Sie diese neu erstellen, bevor Sie das Paket erstellen. Dies können Sie ganz einfach über den build-Paketschalter des Befehls tun.

Mit Ausnahme von $configuration$ werden Werte in dem Projekt gegenüber Werten bevorzugt, die demselben Token in der Befehlszeile zugeordnet sind.

Token	Wertquelle	Wert
$id$	Projektdatei	AssemblyName (Titel) aus der Projektdatei
$version$	AssemblyInfo	„AssemblyInformationalVersion“, falls vorhanden, andernfalls „AssemblyVersion“
$author$	AssemblyInfo	AssemblyCompany
$Titel$	AssemblyInfo	AssemblyTitle
$description$	AssemblyInfo	AssemblyDescription
$copyright$	AssemblyInfo	AssemblyCopyright
$configuration$	Assembly-DLL	Konfiguration, die zur Erstellung der Assembly verwendet wird und standardmäßig auf „Debuggen“ festgelegt ist. Achten Sie darauf, dass Sie stets -properties Configuration=Release in der Befehlszeile verwenden, um mithilfe einer Releasekonfiguration ein Paket zu erstellen.

Tokens können auch zum Auflösen von Pfaden verwendet werden, wenn Sie Assemblydateien und Inhaltsdateien hinzufügen. Die Namen der Tokens und der MSBuild-Eigenschaften stimmen miteinander überein, wodurch Sie abhängig von der aktuellen Buildkonfiguration Dateien auswählen können, die eingefügt werden sollen. Wenn Sie beispielsweise die folgenden Tokens in der .nuspec-Datei verwenden

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

und Sie eine Assembly mit der Release-Konfiguration in MSBuild erstellen, deren AssemblyNameLoggingLibrary ist, sehen die dadurch entstandenen Zeilen in der .nuspec-Datei in den Paketen wie folgt aus:

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

Abhängigkeit-Element

Das <dependencies>-Element in <metadata> enthält eine beliebige Anzahl von <dependency>-Elementen, die andere Pakete finden, von denen die Pakete auf der obersten Ebene abhängig sind. Im Folgenden werden die Attribute für jede <dependency> dargestellt:

Attribute	Beschreibung
id	(Erforderlich) Die Paket-ID der Abhängigkeit, z.B. „EntityFramework“ und „NUnit“, die der Name des Pakets „nuget.org“ ist, wird auf einer Paketseite angezeigt.
version	(Erforderlich) Der Bereich an Versionen, die als Abhängigkeiten akzeptiert werden. Die genaue Syntax finden Sie unter Paketversionsverwaltung. Unverankerte Versionen werden nicht unterstützt.
include	Eine durch Kommas abgetrennte Liste mit Include/Exclude-Tags (s. Tabelle unten), in der auf die Abhängigkeit verwiesen wird, die in das endgültige Paket eingefügt werden soll. Der Standardwert ist all.
Ausschließen	Eine durch Kommas abgetrennte Liste mit Include/Exclude-Tags (s. Tabelle unten), in der auf die Abhängigkeit verwiesen wird, die nicht in das endgültige Paket eingefügt werden soll. Der Standardwert ist build,analyzers, der überschrieben werden kann. Aber auch content/ ContentFiles werden implizit im endgültigen Paket ausgeschlossen, das nicht überscchrieben werden kann. exclude-Tags haben Vorrang gegenüber include-Tags. include="runtime, compile" exclude="compile" entspricht beispielsweise include="runtime".

Beim Hochladen eines Pakets in nuget.org ist jedes Attribut der Abhängigkeit id auf 128 Zeichen beschränkt, und das version Attribut ist auf 256 Zeichen beschränkt.

Include/Exclude-Tag	Betroffene Ordner im Ziel
contentFiles	Inhalt
runtime	Runtime, Ressourcen und Frameworkassemblys
Compile	lib
build	Build (MSBuild-Eigenschaften und -Ziele)
Systemeigen	Systemeigen
keine	Keine Ordner
all	Alle Ordner

Beispielsweise verweisen die folgenden Zeilen auf Abhängigkeiten auf PackageA Version 1.1.0 und höher und PackageB Version 1.x.

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

In den folgenden Zeilen wird zwar auf Abhängigkeiten von denselben Paketen verwiesen, allerdings wird auch angegeben, dass die Ordner contentFiles und build von PackageA sowie alle anderen Ordner bis auf native und compile von PackageB angegeben werden sollen.

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

Wichtig

Bei der Erstellung von .nuspec mithilfe von nuget spec aus einem Projekt werden in diesem Projekt bestehende Abhängigkeiten nicht automatisch in die resultierende .nuspec-Datei eingefügt. Verwenden Sie nuget pack myproject.csprojstattdessen die .nuspec-Datei aus der generierten nupkg-Datei und rufen Sie sie ab. Diese .nuspec enthält die Abhängigkeiten.

Abhängigkeitsgruppen

Version 2.0 und höher

Als Alternative zu einer einzelnen flachen Liste können Abhängigkeiten auf der Grundlage des Frameworkprofils des Zielprojekts angegeben werden, das <group>-Elemente in <dependencies> verwendet.

Jede Gruppe verfügt über ein Attribut mit dem Namen targetFramework und enthält entweder kein <dependency>-Element oder mindestens eins. Diese Abhängigkeiten werden zusammen installiert, wenn das Zielframework kompatibel mit dem Frameworkprofil des Projekts ist.

Das <group>-Element ohne ein targetFramework-Attribut wird als Standard- oder Ausweichliste der Abhängigkeiten verwendet. Die genauen Frameworkbezeichner finden Sie unter Zielframeworks.

Wichtig

Das Gruppenformat kann nicht mit einer flachen Liste vermischt werden.

Hinweis

Das Format von Target Framework Moniker (TFM), das im lib/ref Ordner verwendet wird, unterscheidet sich im Vergleich zu dem TFM, das in dependency groups genutzt wird. Wenn die im dependencies group und lib/ref Ordner der .nuspec Datei deklarierten Zielframeworks keine genauen Übereinstimmungen aufweisen, löste pack den Befehl NuGet-Warnung NU5128 aus.

Im folgenden Beispiel werden verschiedene Variationen des <group>-Elements dargestellt:

<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>

Explizite Assemblyverweise

Das <references> Element wird von Projekten mit packages.config verwendet, die explizit die Assemblies angeben, auf die das Zielprojekt verweisen soll, wenn es das Paket verwendet. In der Regel werden Verweise nur für Assemblys zur Entwurfszeit verwendet. Weitere Informationen finden Sie auf der Seite zur Auswahl von Assemblies auf die in Projekten verwiesen wird.

Beispielsweise gibt das folgende <references>-Element NuGet die Anweisung, Verweise nur zu xunit.dll und xunit.extensions.dll hinzuzufügen, wenn zusätzliche Assemblys in dem Paket enthalten sind:

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

Verweisgruppen

Als Alternative zu einer einzelnen flachen Liste können Verweise auf der Grundlage des Frameworkprofils des Zielprojekts angegeben werden, das <group>-Elemente in <references> verwendet.

Jede Gruppe verfügt über ein Attribut mit dem Namen targetFramework und enthält entweder kein <reference>-Element oder mindestens eins. Diese Verweise werden einem Projekt hinzugefügt, wenn das Zielframework mit dem Frameworkprofil des Projekts kompatibel ist.

Das <group>-Element ohne ein targetFramework-Attribut wird als Standard- oder Ausweichliste der Verweise verwendet. Die genauen Frameworkbezeichner finden Sie unter Zielframeworks.

Wichtig

Das Gruppenformat kann nicht mit einer flachen Liste vermischt werden.

Im folgenden Beispiel werden verschiedene Variationen des <group>-Elements dargestellt:

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

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

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

Verweise auf Frameworkassemblys

Frameworkassemblys gehören zum .NET Framework und sollten für jeden vorhandenen Computer bereits im globalen Assemblycache vorhanden sein. Pakete können sicherstellen, dass die erforderlichen Verweise, falls nötig, dem Projekt hinzugefügt werden, indem es diese Assemblys im <frameworkAssemblies>-Element erkennt. Solche Assemblys sind nicht von Anfang an in Paketen enthalten.

Das <frameworkAssemblies>-Element enthält entweder kein <frameworkAssembly>-Element oder mindestens eins, das die folgenden Attribute angibt:

Attribute	Beschreibung
assemblyName	(Erforderlich) Der vollqualifizierte Assemblyname.
targetFramework	(Optional) Gibt das Zielframework an, auf das sich dieser Verweis bezieht. Wenn dieses Attribut nicht vorhanden ist, deutet dies darauf hin, dass sich der Verweis auf alle Frameworks bezieht. Die genauen Frameworkbezeichner finden Sie unter Zielframeworks.

Im folgenden Beispiel werden Verweise auf System.Net für alle Zielframeworks und auf System.ServiceModel für ausschließlich .NET Framework 4.0 dargestellt:

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

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

Einfügen von Assemblydateien

Wenn Sie die unter Creating a Package (Erstellen eines Pakets) beschriebenen Anweisungen ausführen, müssen Sie nicht explizit eine Liste mit Dateien in der .nuspec-Datei angeben. Der nuget pack-Befehl ruft die benötigten Dateien automatisch ab.

Wichtig

Wenn ein Paket in einem Projekt installiert wird, fügt NuGet automatisch der DLL des Pakets Assemblyverweise hinzu. Die Verweise, die mit .resources.dll benannt sind werden dabei allerdings nicht hinzugefügt, da angenommen wird, dass es sich dabei um lokalisierte Satellitenassemblys handelt. Vermeiden Sie aus diesem Grund die Verwendung von .resources.dll für Dateien, die darüber hinaus wichtigen Paketcode enthalten.

Legen Sie ein <files>-Element als untergeordnetes Element von <package> und als gleichgeordnetes Element von <metadata> fest, das jeder Datei ein separates <file>-Element zuordnet, um diese automatischen Vorgänge zu umgehen und genau zu kontrollieren, welche Dateien in einem Paket enthalten sind. Zum Beispiel:

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

Das <files>-Element wird bei NuGet 2.x und früher sowie bei Projekten, die packages.config verwenden, außerdem verwendet, um unveränderliche Inhaltsdateien während der Paketinstallation einzufügen. Bei NuGet 3.3 und höher und Projekten, die PackageReference verwenden, wird stattdessen das <contentFiles>-Element verwendet. Weitere Informationen finden Sie unter Einfügen von Inhaltsdateien.

Dateielementattribute

Jedes <file>-Element gibt die folgenden Attribute an:

Attribute	Beschreibung
src	Der Speicherort der Dateien, die eingefügt werden sollen, unterliegt Ausnahmen, die von dem exclude-Attribut angegeben werden. Der Pfad ist relativ zur .nuspec-Datei, wenn kein absoluter Pfad angegeben ist. Das Platzhalterzeichen * ist zulässig, und das zweifache Platzhalterzeichen ** impliziert eine rekursive Ordnersuche.
Ziel	Der relative Pfad zu dem Ordner in dem Paket, in dem die Quelldateien platziert sind, der mit lib, content, build oder tools beginnt. Informationen dazu finden Sie unter Creating a .nuspec from a convention-based working directory (Erstellen einer NUSPEC-Datei aus einem auf Konventionen basierenden Arbeitsverzeichnis).
Exclude…	Eine durch Semikolons abgetrennte Datei oder Dateimuster, die sich nicht im src-Speicherort befinden dürfen. Das Platzhalterzeichen * ist zulässig, und das zweifache Platzhalterzeichen ** impliziert eine rekursive Ordnersuche.

Beispiele

Einzelne Assembly

Source file:
    library.dll

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

Packaged result:
    lib\library.dll

Einzelne Assembly, die für ein Zielframework spezifisch ist

Source file:
    library.dll

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

Packaged result:
    lib\net40\library.dll

Mehrere DLLS, die Platzhalterzeichen verwenden

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

DLLs für verschiedene Frameworks

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

Ausschließen von Dateien

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)

Einfügen von Inhaltsdateien

Bei Inhaltsdateien handelt es sich um unveränderliche Dateien, die ein Paket in ein Projekt einfügen muss. Da sie unveränderlich sind, sollen sie auch nicht von dem verarbeitenden Projekt geändert werden. Zu den Inhaltsdateien gehören z.B.:

• Bilder, die als Ressourcen eingebettet werden
• Quelldateien, die bereits kompiliert sind
• Skripts, die in die Buildausgabe des Projekts eingefügt werden müssen
• Konfigurationsdateien für das Paket, die zwar in das Projekt eingefügt werden müssen, an denen jedoch keine projektspezifischen Änderungen vorgenommen werden müssen.

Inhaltsdateien werden in ein Paket eingefügt, das das <files>-Element verwendet, das den content-Ordner im target-Attribut angibt. Allerdings werden diese Dateien ignoriert, wenn das Paket über PackageReference in ein Projekt installiert wird, das stattdessen das <contentFiles>-Element verwendet.

Im Idealfall geben Pakete die Inhaltsdateien in beiden Elementen an, um ein höchstmögliches Maß an Kompatibilität mit den verarbeitenden Projekten zu erreichen.

Verwenden des Dateielements für Inhaltsdateien

Verwenden Sie für Inhaltsdateien einfach dasselbe Format wie für Assemblydateien. Geben Sie dabei allerdings content als Basisordner im target-Attribut an, wie in den folgenden Beispielen dargestellt wird.

Grundlegende Inhaltsdateien

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

Inhaltsdateien mit Verzeichnisstruktur

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

Inhaltsdatei, die für ein Zielframework spezifisch ist

Source file:
    css\cool\style.css

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

Packaged result:
    content\style.css

Inhaltsdatei, die in einen Ordner mit einem Punkt im Namen kopiert wird

In diesem Fall erkennt NuGet, dass die Erweiterung in target nicht mit der Erweiterung in src übereinstimmt, und behandelt dieses Bestandteil des Namens in target als einen Ordner:

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

Inhaltsdateien ohne Erweiterungen

Verwenden Sie die Platzhalterzeichen * oder **, um Dateien ohne Erweiterungen einzufügen:

Source file:
    flags\installed

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

Packaged result:
    flags\installed

Inhaltsdateien mit tiefen Pfaden und tiefen Zielen

In diesem Fall nimmt NuGet an, dass das Ziel ein Dateiname und kein Ordner ist, da die Dateierweiterungen von Quelle und Ziel übereinstimmen:

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

Umbenennen einer Inhaltsdatei im Paket

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

Ausschließen von Dateien

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)

Verwenden des contentFiles-Elements für Inhaltsdateien

NuGet 4.0 und höher mit PackageReference

Standardmäßig platzieren Pakete Inhalte in einem contentFiles-Ordner (s. unten), in den nuget pack alle Dateien mithilfe von Standardattributen eingefügt hat. In diesem Fall ist es nicht notwendig, einen contentFiles-Knoten in .nuspec einzufügen.

Das <contentFiles>-Element gibt eine Auflistung von <files>-Elementen an, die die eingefügten Dateien erkennen, um zu kontrollieren, welche Dateien eingefügt wurden.

Diese Dateien werden zusammen mit mehreren Attributen angegeben, die beschreiben, wie sie in dem Projektsystem verwendet werden sollen:

Attribute	Beschreibung
include	(Erforderlich) Der Speicherort der Dateien, die eingefügt werden sollen, unterliegt Ausnahmen, die von dem exclude-Attribut angegeben werden. Der Pfad ist relativ zum contentFiles-Ordner, wenn kein absoluter Pfad angegeben ist. Das Platzhalterzeichen * ist zulässig, und das zweifache Platzhalterzeichen ** impliziert eine rekursive Ordnersuche.
Exclude…	Eine durch Semikolons abgetrennte Datei oder Dateimuster, die sich nicht im src-Speicherort befinden dürfen. Das Platzhalterzeichen * ist zulässig, und das zweifache Platzhalterzeichen ** impliziert eine rekursive Ordnersuche.
buildAction	Die Buildaktion, die dem Inhaltselement für MSBuild zugewiesen werden soll. z. B. Content, None, Embedded Resource, Compile etc. der Standard ist Compile.
copyToOutput	Ein boole’scher Wert, der angibt, ob Inhaltselemente in den Ausgabeordner des Builds kopiert (oder veröffentlicht) werden sollen. Die Standardeinstellung ist „false“.
flatten	Ein boolescher Wert, der angibt, ob Inhaltselemente in einen Ordner in der Buildausgabe kopiert werden sollen (TRUE) oder ob die Ordnerstruktur in den Paketen beibehalten werden soll (FALSE). Diese Flag funktioniert nur, wenn das copyToOutput-Flag auf TRUE festgelegt ist. Die Standardeinstellung ist „false“.

NuGet wendet die untergeordneten Elemente von <contentFiles> bei der Installation eines Pakets von unten nach oben an. Wenn mehrere Einträge in einer Datei vorhanden sind, werden sie alle angewendet. Der höher geordnete Eintrag setzt die untergeordneten Einträge außer Kraft, wenn ein Konflikt für ein Attribut entsteht.

Paketordnerstruktur

Das Paketprojekt sollte Inhalte mithilfe des folgenden Musters strukturieren:

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

• codeLanguages kann cs, vb, fs, any oder das klein geschriebene Äquivalent einer $(ProjectLanguage) sein.
• TxM ist ein für das Zielframework zulässiger Moniker, der NuGet unterstützt (Informationen dazu finden Sie unter Zielframeworks).
• An das Ende der Syntax kann eine beliebige Ordnerstruktur angehängt werden.

Zum Beispiel:

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

Für leere Ordner kann _._ eingefügt werden, wenn diese keine Inhalte mehr für bestimmte Sprachen und TxM bereitstellen sollen. Z.B.:

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

Beispiel: Abschnitt „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>

Framework-Referenzgruppen

Version 5.1+ nur mit PackageReference

Frameworkreferenzen sind ein .NET Core-Konzept, das freigegebene Frameworks wie WPF oder Windows Forms darstellt. Durch Angeben eines shared Frameworks stellt das Paket sicher, dass alle zugehörigen Frameworkabhängigkeiten im referenzierenden Projekt enthalten sind.

Jedes <group> Element erfordert ein targetFramework Attribut und null oder mehr <frameworkReference> Elemente.

Das folgende Beispiel zeigt eine nuspec, die für ein .NET Core-WPF-Projekt generiert wurde. Beachten Sie, dass das Erstellen von nuspecs, die Frameworkreferenzen enthalten, nicht empfohlen wird. Erwägen Sie stattdessen die Verwendung des Zielpakets, das diese automatisch vom Projekt ableiten wird.

<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>

Beispiel: nuspec-Dateien

Eine einfache .nuspec-Datei, die weder Abhängigkeiten noch Dateien enthält

<?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>

Eine .nuspec-Datei mit Abhängigkeiten

<?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>

Eine .nuspec-Datei mit Dateien

<?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>

Eine .nuspec-Datei mit Frameworkassemblys

<?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 diesem Beispiel werden die folgenden Elemente für bestimmte Projektziele installiert:

• .NET4 – >System.Web, System.Net
• .NET4-Clientprofil – >System.Net
• Silverlight 3 – >System.Json
• Windows-Telefon ->Microsoft.Devices.Sensors