Erstellen eines Pakets mithilfe der „nuget.exe“-CLI

Unabhängig davon, welchen Zweck Ihr Paket erfüllt oder welchen Code es enthält, verwenden Sie eines der CLI-Tools (entweder nuget.exe oder dotnet.exe), um diese Funktionalität in einer Komponente zu verpacken, die für andere Entwickler freigegeben und von ihnen verwendet werden kann. Informationen zur Installation von NuGet-CLI-Tools finden Sie unter Installieren von NuGet-Clienttools. Beachten Sie, dass Visual Studio nicht automatisch ein CLI-Tool enthält.

Technisch gesehen ist ein NuGet-Paket eine ZIP-Datei, die mit der .nupkg-Erweiterung umbenannt wurde und deren Inhalt bestimmten Konventionen entspricht. In diesem Thema werden die Schritte zum Erstellen eines Pakets, das diesen Konventionen entspricht, ausführlich beschrieben.

Das Packen beginnt mit dem kompilierten Code (Assemblys), Symbolen und/oder anderen Dateien, die Sie als Paket übermitteln möchten. Weitere Informationen finden Sie unter Overview and workflow (Übersicht und Workflow). Dieser Vorgang wird unabhängig vom Kompilieren oder jeder anderen Methode zum Erstellen der Dateien ausgeführt, die in das Paket einfließen. Sie können die kompilierten Assemblys und Pakete jedoch mithilfe der Informationen in einer Projektdatei kontinuierlich synchronisieren.

Wichtig

Dieses Thema gilt für Nicht-SDK-Projekte, in der Regel andere als .NET Core- und .NET Standard-Projekte mit Visual Studio 2017 und höheren Versionen und NuGet 4.0 und höher.

Welche Assemblys sollten gepackt werden?

Die meisten allgemeinen Pakete enthalten mindestens eine Assembly, die andere Entwickler in ihren eigenen Projekten verwenden können.

  • Es ist empfehlenswert, in jedem NuGet-Paket eine Assembly zu haben, vorausgesetzt, dass jede Assembly für sich nützlich ist. Beispiel: Wenn Utilities.dll von Parser.dll abhängt und Parser.dll für sich allein bereits nützlich ist, dann müssen Sie für jede Datei ein eigenes Paket erstellen. So können Entwickler Parser.dll unabhängig von Utilities.dll verwenden.

  • Wenn Ihre Bibliothek aus mehreren Assemblys besteht, die für sich allein nicht nützlich sind, können diese in einem Paket zusammengefasst werden. Bleiben wir beim vorherigen Beispiel: Wenn Parser.dll Code enthält, der nur von Utilities.dll verwendet wird, kann Parser.dll in dasselbe Paket eingefügt werden.

  • Auch Utilities.dll und Utilities.resources.dll können im selben Paket zusammengefasst werden, wenn erstere DLL von der letzteren abhängt und die letztere nicht für sich allein nützlich ist.

Ressourcen hingegen sind ein besonderer Fall. Wenn ein Paket in einem Projekt installiert wird, fügt NuGet automatisch den DLLs 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. Weitere Informationen finden Sie unter Creating localized NuGet packages (Erstellen lokalisierter NuGet-Pakete). Vermeiden Sie aus diesem Grund die Verwendung von .resources.dll für Dateien, die darüber hinaus wichtigen Paketcode enthalten.

Wenn Ihre Bibliothek COM-Interop-Assemblys enthält, führen Sie die zusätzlichen Schritte unter Erstellen von Paketen mit COM-Interop-Assemblys aus.

Rolle und Struktur der NUSPEC-Datei

Nachdem Sie entschieden haben, welche Dateien gepackt werden sollen, erstellen Sie ein Paketmanifest in einer .nuspec-XML-Datei.

Das Manifest:

  1. Beschreibt den Inhalt des Pakets und ist im Paket enthalten.
  2. Ist unerlässlich für die Erstellung des Pakets und weist NuGet an, wie das Paket in ein Projekt installiert werden soll. Das Manifest erkennt z.B. andere Paketabhängigkeiten, sodass NuGet bei der Installation des Hauptpakets auch diese installieren kann.
  3. Enthält wie unten beschrieben erforderliche und optionale Eigenschaften. Weitere Informationen, einschließlich anderer Eigenschaften, die hier nicht erwähnt werden, finden Sie unter .nuspec reference (NUSPEC-Referenz).

Erforderliche Eigenschaften:

  • Der Paketbezeichner. Dieser muss im Katalog, der das Paket hostet, eindeutig sein.
  • Eine bestimmte Versionsnummer in der Schreibweise Hauptversion.Nebenversion.Patch[-Suffix] , wobei im -Suffix die Vorabversionen angegeben werden
  • Der Titel des Pakets, so wie er auf dem Host (z.B. „nuget.org“) angezeigt werden sollte
  • Informationen zum Autor und zum Besitzer
  • Eine ausführliche Beschreibung des Pakets

Allgemeine optionale Eigenschaften:

  • Anmerkungen zu diesem Release
  • Copyrightinformationen
  • Eine kurze Beschreibung der Paket-Manager-UI in Visual Studio
  • Eine Gebietsschema-ID
  • Projekt-URL
  • Eine Lizenz als Ausdruck oder Datei (licenseUrl wird als veraltet markiert. Nutzen Sie stattdessen das Nuspec-Metadatenelement license.)
  • Eine Symboldatei (iconUrl wird als veraltet markiert. Nutzen Sie stattdessen das Nuspec-Metadatenelement icon.)
  • Listen der Abhängigkeiten und Verweise
  • Tags für die Katalogsuche

Im folgenden Beispiel sehen Sie eine typische, aber fiktive .nuspec-Datei mit Kommentaren, die die Eigenschaften beschreiben:

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

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

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

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

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

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

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

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

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

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

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

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

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

Weitere Informationen zum Deklarieren von Abhängigkeiten und zum Angeben von Versionsnummern finden Sie unter packages.config und Package versioning (Paketversionsverwaltung). Es ist auch möglich, Ressourcen aus Abhängigkeiten mithilfe der Attribute include und exclude des Elements dependency direkt im Paket verfügbar zu machen. Informationen dazu finden Sie unter .nuspec Reference – Dependencies (NUSPEC-Referenz: Abhängigkeiten).

Da das Manifest im Paket enthalten ist, aus dem es erstellt wurde, finden Sie viele weitere Beispiele in den vorhandenen Paketen. Eine gute Quelle ist z.B. der Ordner global-packages auf Ihrem Computer, der sich mithilfe des folgenden Befehls öffnen lässt:

nuget locals -list global-packages

Wechseln Sie in einen Ordner unter package\version, kopieren die .nupkg- in eine .zip-Datei, öffnen Sie dann die .zip-Datei, und sehen Sie sich die .nuspec-Datei darin an.

Hinweis

Wenn Sie eine .nuspec-Datei aus einem Visual Studio-Projekt erstellen, enthält das Manifest Tokens, die bei der Paketerstellung durch Informationen aus dem Projekt ersetzt werden. Weitere Informationen finden Sie im Abschnitt Aus einem Visual Studio-Projekt.

Erstellen der NUSPEC-Datei

Das Erstellen eines vollständigen Manifests beginnt in der Regel mit einer einfachen .nuspec-Datei, die mithilfe einer der folgenden Methoden generiert wird:

Anschließend bearbeiten Sie die Datei manuell, sodass sie den genauen Inhalt beschreibt, den das letzte Paket enthalten soll.

Wichtig

Generierte .nuspec-Dateien enthalten Platzhalter. Diese müssen geändert werden, bevor das Paket mit dem Befehl nuget pack erstellt wird, da dieser fehlschlägt, wenn die .nuspec-Datei Platzhalter enthält.

Aus einem konventionsbasierten Arbeitsverzeichnis

Da ein NuGet-Paket nur eine mit der .nupkg-Erweiterung umbenannte ZIP-Datei ist, ist es oftmals am einfachsten, die gewünschte Ordnerstruktur in Ihrem lokalen Dateisystem und die .nuspec-Datei anschließend direkt aus dieser Struktur zu erstellen. Der Befehl nuget pack fügt dann automatisch alle Dateien in dieser Ordnerstruktur ein (außer den Ordnern, die mit einem . beginnen, sodass private Dateien in der gleichen Struktur bleiben können).

Der Vorteil dieses Ansatzes ist, dass Sie nicht wie weiter unten in diesem Thema erläutert im Manifest angeben müssen, welche Dateien im Paket enthalten sein sollen. Sie können einfach beim Buildprozess die genaue Ordnerstruktur für das Paket erstellen lassen und problemlos weitere Dateien aufnehmen, die andernfalls zu keinem Projekt gehören würden:

  • Inhalt und Quellcode, der in das Zielprojekt eingefügt werden soll.
  • PowerShell-Skripts
  • Transformationen in vorhandene Konfigurations- und Quellcodedateien in einem Projekt.

Die Ordnerkonventionen lauten folgendermaßen:

Ordner Beschreibung Aktion bei der Paketinstallation
(Stammverzeichnis) Speicherort für „readme.txt“ In Visual Studio wird die Datei „readme.txt“ im Stammverzeichnis des Pakets angezeigt, wenn das Paket installiert wird.
lib/{tfm} Assembly- (.dll), Dokumentations- (.xml) und Symboldateien (.pdb) für den angegebenen Zielframeworkmoniker (Target Framework Moniker, TFM) Assemblys werden als Verweise für die Kompilierzeit ebenso wie für die Laufzeit hinzugefügt, und .xml sowie .pdb werden in Projektordner kopiert. Informationen zum Erstellen von für das Zielframework spezifischen Unterordnern finden Sie unter Supporting multiple .NET framework versions (Unterstützen mehrerer .NET Framework-Versionen).
ref/{tfm} Dateien für Assembly (.dll) und Symbole (.pdb) für den angegebenen Zielframeworkmoniker (Target Framework Moniker, TFM) Assemblys werden nur als Verweise für die Kompilierzeit hinzugefügt, daher werden keine Daten in den bin-Ordner des Projekts kopiert.
runtimes Architekturspezifische Assembly- (.dll), Symbol- (.pdb) und native Ressourcendateien (.pri) Assemblys werden nur als Verweise für die Laufzeit hinzugefügt. Andere Dateien werden in Projektordner kopiert. Es sollte immer eine entsprechende für AnyCPU spezifische TFM-Assembly im Ordner /ref/{tfm} vorhanden sein, um eine entsprechende Assembly für die Kompilierzeit bereitzustellen. Weitere Informationen finden Sie unter Supporting multiple .NET framework versions (Unterstützen mehrerer .NET Framework-Versionen).
content Beliebige Dateien Inhalte werden in das Projektstammverzeichnis kopiert. Der Ordner content (Inhalt) entspricht in etwa dem Stammverzeichnis der Zielanwendung, die das Paket letztendlich nutzt. Damit das Paket dem Ordner /images der Anwendung ein Image hinzufügt, müssen Sie es im Ordner content/images ablegen.
build (3.x+) MSBuild-Dateien .targets und .props Wird automatisch in das Projekt eingefügt.
buildMultiTargeting (4.0+) MSBuild-Dateien .targets und .props für frameworkübergreifende Ziele Wird automatisch in das Projekt eingefügt.
buildTransitive (5.0 und höher) : MSBuild-Dateien .targets und .props, die transitiv in beliebige verarbeitende Projekte eingefügt werden. Weitere Informationen finden Sie auf der Seite Feature. Wird automatisch in das Projekt eingefügt.
Tools PowerShell-Skripts und -Programme, auf die über die Paket-Manager-Konsole zugegriffen werden kann Der Ordner tools wird nur zur Umgebungsvariable PATH der Paket-Manager-Konsole hinzugefügt, niemals jedoch zu PATH, so wie es für MSBuild beim Erstellen des Projekts festgelegt ist.

Da die Ordnerstruktur beliebig viele Assemblys für beliebig viele Zielframeworks enthalten kann, ist diese Methode für das Erstellen von Paketen erforderlich, die mehrere Frameworks unterstützen.

Sobald Sie die gewünschte Ordnerstruktur eingerichtet haben, führen Sie den folgenden Befehl in diesem Ordner aus, um die .nuspec-Datei zu erstellen:

nuget spec

Die generierte .nuspec-Datei enthält wie bereits erwähnt keine expliziten Verweise auf Dateien in der Ordnerstruktur. NuGet schließt bei der Paketerstellung automatisch alle Dateien ein. Die Platzhalterwerte müssen jedoch trotzdem noch in anderen Teilen des Manifests bearbeitet werden.

Aus einer Assembly-DLL

Das Erstellen eines Pakets aus einer Assembly ist ein einfacher Vorgang. Dabei können Sie eine .nuspec-Datei aus den Metadaten in der Assembly mithilfe des folgenden Befehls generieren:

nuget spec <assembly-name>.dll

Bei dieser Schreibweise werden einige Platzhalter im Manifest durch bestimmte Werte aus der Assembly ersetzt. Die Eigenschaft <id> wird beispielsweise auf den Assemblynamen festgelegt und <version> auf die Version. Andere Manifesteigenschaften haben jedoch keine übereinstimmenden Werte in der Assembly und enthalten somit weiterhin Platzhalter.

Aus einem Visual Studio-Projekt

Es empfiehlt sich, eine .nuspec-Datei aus einer .csproj- oder .vbproj-Datei zu erstellen, da auf andere Pakete, die in dieses Projekt installiert wurden, automatisch als Abhängigkeiten verwiesen wird. Verwenden Sie einfach den folgenden Befehl im Ordner der Projektdatei:

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

Die anschließend erstellte <project-name>.nuspec-Datei enthält Tokens, die zur Packzeit durch Werte aus dem Projekt ersetzt werden, einschließlich der Verweise auf alle anderen Pakete, die bereits installiert wurden.

Wenn Sie Paketabhängigkeiten in die NUSPEC-Datei einbinden müssen, verwenden Sie stattdessen nuget pack, und rufen Sie die NUSPEC-Datei aus der generierten NUPKG-Datei ab. Verwenden Sie z.B. den folgenden Befehl.

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

Ein Token wird auf beiden Seiten der Projekteigenschaft durch das Symbol $ begrenzt. Wird der Wert <id> auf diese Weise in einem Manifest generiert, wird er in der Regel folgendermaßen angezeigt:

<id>$id$</id>

Dieses Token wird zur Packzeit durch den Wert AssemblyName aus der Projektdatei ersetzt. Weitere Informationen zur genauen Zuordnung von Projektwerten und .nuspec-Tokens finden Sie im Abschnitt Replacement tokens (Ersetzungstokens) im Artikel „.nuspec reference“ (NUSPEC-Referenz).

Durch Tokens müssen Sie wichtige Werte wie die Versionsnummer in der .nuspec-Datei nicht mit dem Projekt zusammen aktualisieren. Sie können die Tokens bei Bedarf jederzeit durch Literalwerte ersetzen.

Wenn Sie in einem Visual Studio-Projekt arbeiten, haben weitere Packoptionen zur Auswahl. Dies wird weiter unten im Abschnitt Ausführen von „nuget pack“ zum Generieren der NUPKG-Datei beschrieben.

Pakete auf Projektmappenebene

Nur NuGet 2.x. Nicht verfügbar in NuGet 3.0 und höher.

In NuGet 2.x werden Pakete auf Projektmappenebene unterstützt, über die Tools oder zusätzliche Befehle für die Paket-Manager-Konsole installiert werden (der Inhalt des Ordners tools), die jedoch weder Verweise noch Inhalt hinzufügen oder Anpassungen für Projekte in der Projektmappe erstellen. Solche Pakete enthalten keine Dateien in den direkten Ordnern lib, content oder build, und keine der dazugehörigen Abhängigkeiten besitzt Dateien in den jeweiligen lib-, content- oder build-Ordnern.

NuGet verfolgt installierte Pakete auf Projektmappenebene in einer packages.config-Datei im Ordner .nuget nach, statt in der packages.config-Datei des Projekts.

Neue Datei mit Standardwerten

Mit dem folgenden Befehl wird ein Standardmanifest mit Platzhaltern erstellt, das gewährleistet, dass Sie mit der richtigen Dateistruktur beginnen:

nuget spec [<package-name>]

Wenn Sie <package-name> auslassen, ergibt sich daraus die Datei Package.nuspec. Wenn Sie einen Namen wie Contoso.Utility.UsefulStuff angeben, lautet die Datei Contoso.Utility.UsefulStuff.nuspec.

Die resultierende .nuspec-Datei enthält Platzhalter für Werte wie projectUrl. Denken Sie daran, die Datei zu bearbeiten, bevor Sie mit ihr die endgültige .nupkg-Datei erstellen.

Auswählen eines eindeutigen Paketbezeichners und Festlegen der Versionsnummer

Der Paketbezeichner (<id>-Element) und die Versionsnummer (<version>-Element) sind die beiden wichtigsten Werte im Manifest, da sie eindeutig den exakten Code bezeichnen, der im Paket enthalten ist.

Bewährte Methoden für den Paketbezeichner:

  • Eindeutigkeit: Der Bezeichner muss auf „nuget.org“ bzw. in dem Katalog, in dem das Paket gehostet wird, eindeutig sein. Bevor Sie sich für einen Bezeichner entscheiden, vergewissern Sie sich, dass dieser im entsprechenden Katalog nicht bereits verwendet wird. Zur Vermeidung von Konflikten empfiehlt es sich, den Namen Ihres Unternehmens im ersten Teil des Bezeichners zu nutzen, z.B. Contoso..
  • Namespace-ähnliche Namen: Verwenden Sie Punkte statt Bindestrichen, wie bei der Notation von Namespaces in .NET. Schreiben Sie z.B. Contoso.Utility.UsefulStuff statt Contoso-Utility-UsefulStuff oder Contoso_Utility_UsefulStuff. Benutzer finden es auch hilfreich, wenn der Paketbezeichner den im Code verwendeten Namespaces entspricht.
  • Beispielpakete: Wenn Sie ein Paket mit Beispielcode erstellen, das veranschaulicht, wie ein anderes Paket verwendet wird, fügen Sie .Sample als Suffix an den Bezeichner an, z. B. Contoso.Utility.UsefulStuff.Sample. Das Beispielpaket würde natürlich vom anderen Paket abhängen. Verwenden Sie beim Erstellen eines Beispielpakets wie weiter oben beschrieben das konventionsbasierte Arbeitsverzeichnis. Arrangieren Sie den Beispielcode im Ordner content in einem Ordner namens \Samples\<identifier>, z.B. \Samples\Contoso.Utility.UsefulStuff.Sample.

Bewährte Methoden für die Paketversion:

  • Legen Sie die Version des Pakets auf die der Bibliothek fest, obwohl dies nicht zwingend erforderlich ist. Dies ist sehr einfach, wenn Sie ein Paket, wie zuvor im Abschnitt Welche Assemblys sollen gepackt werden? beschrieben, auf eine einzelne Assembly beschränken. Bedenken Sie, dass NuGet sich beim Auflösen der Abhängigkeiten nach den Paketversionen richtet, nicht nach den Assemblyversionen.
  • Wenn Sie ein nicht standardmäßiges Versionsschema verwenden, müssen Sie die NuGet-Versionsregeln wie unter Package versioning (Paketversionsverwaltung beschrieben anwenden.

Die folgenden kurzen Blogbeiträge enthalten weitere Informationen zur Versionsverwaltung:

Hinzufügen einer Infodatei und anderer Dateien

Verwenden Sie den <files>-Knoten in der .nuspec-Datei, die dem <metadata>-Tag folgt, um Dateien, die in das Paket aufgenommen werden sollen, direkt anzugeben:

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

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

Tipp

Bei einem konventionsbasierten Arbeitsverzeichnis können Sie die Datei „readme.txt“ im Stammverzeichnis des Pakets und andere Inhalte im Ordner content platzieren. Dazu sind keine <file>-Elemente im Manifest erforderlich.

Wenn Sie eine Datei namens readme.txt im Stammverzeichnis des Pakets einschließen, zeigt Visual Studio unmittelbar nach der direkten Installation des Pakets den Inhalt der Datei als Nur-Text an. Für Pakete, die als Abhängigkeiten installiert wurden, werden keine Infodateien angezeigt. Die Infodatei für das Paket „HtmlAgilityPack“ wird z.B. folgendermaßen angezeigt:

Anzeige einer Infodatei für ein NuGet-Paket nach der Installation

Hinweis

Wenn Sie einen leeren <files>-Knoten in die .nuspec-Datei einschließen, fügt NuGet dem Paket keine weiteren Inhalte außer denen im Ordner lib hinzu.

Einfügen von MSBuild-Eigenschaften und -Zielen in ein Paket

In einigen Fällen (z.B. beim Ausführen eines benutzerdefinierten Tools oder Prozesses während des Buildvorgangs) sollten Sie benutzerdefinierte Buildziele oder -eigenschaften zu Projekten hinzufügen, die Ihr Paket nutzen. Platzieren Sie dazu Dateien mit der Schreibweise <package_id>.targets oder <package_id>.props (z.B. Contoso.Utility.UsefulStuff.targets) im \build-Ordner des Projekts.

Dateien im \build-Stammverzeichnis gelten als für alle Zielframeworks geeignet. Um frameworkspezifische Dateien bereitzustellen, platzieren Sie zuerst Dateien wie die folgenden in den entsprechenden Unterordnern:

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

Verweisen Sie dann in der .nuspec-Datei im <files>-Knoten auf diese Dateien:

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

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

Das Einfügen von MSBuild-Eigenschaften und -Zielen in ein Paket wurde mit NuGet 2.5 eingeführt. Daher wird empfohlen, dem Element metadata das minClientVersion="2.5"-Attribut hinzuzufügen, damit die für das Paket erforderliche Mindestversion des NuGet-Clients angegeben wird.

Wenn NuGet ein Paket mit \build-Dateien erstellt, werden der Projektdatei MSBuild-<Import>-Elemente hinzufügt, die auf die .targets- und .props-Dateien zeigen. .props wird oben in der Projektdatei hinzugefügt und .targets ganz unten. Für jedes Zielframework wird ein eigenes bedingtes MSBuild-<Import>-Element hinzugefügt.

MSBuild-.props- und -.targets-Dateien für frameworkübergreifende Ziele können im Ordner \buildMultiTargeting abgelegt werden. Bei der Paketinstallation fügt NuGet die entsprechenden <Import>-Elemente in die Projektdatei mit der Bedingung ein, dass das Zielframework nicht festgelegt ist (die MSBuild-Eigenschaft $(TargetFramework) muss leer sein).

In NuGet 3.x werden Ziele nicht zum Projekt hinzugefügt, sondern über {projectName}.nuget.g.targets und {projectName}.nuget.g.props zur Verfügung gestellt.

Ausführen von „nuget pack“ zum Generieren der NUPKG-Datei

Wenn Sie eine Assembly oder das konventionsbasierte Arbeitsverzeichnis verwenden, erstellen Sie ein Paket, indem Sie den Befehl nuget pack mit der .nuspec-Datei ausführen und dabei <project-name> durch den bestimmten Dateinamen ersetzen:

nuget pack <project-name>.nuspec

Wenn Sie ein Visual Studio-Projekt verwenden, führen Sie nuget pack mit der Projektdatei aus, die automatisch die .nuspec-Datei des Projekts lädt und alle Tokens darin durch die Werte in der Projektdatei ersetzt:

nuget pack <project-name>.csproj

Hinweis

Die direkte Verwendung der Projektdatei ist für die Tokenersetzung erforderlich, da das Projekt die Quelle der Tokenwerte ist. Die Tokenersetzung wird nicht ausgeführt, wenn Sie nuget pack mit einer .nuspec-Datei verwenden.

nuget pack schließt auf jeden Fall Ordner aus, die mit einem Punkt beginnen, z.B. .git oder .hg.

NuGet gibt an, ob die .nuspec-Datei Fehler enthält, die korrigiert werden müssen, z.B. nicht geänderte Platzhalterwerte im Manifest.

Wenn nuget pack erfolgreich ausgeführt wurde, können Sie die erstellte .nupkg-Datei wie in Publishing packages (Veröffentlichen von Paketen) beschrieben in einem geeigneten Katalog veröffentlichen.

Tipp

Wenn Sie sich das erstellte Paket genauer ansehen möchten, öffnen Sie es einfach im Paket-Explorer. Dieser stellt den Inhalt des Pakets und das Manifest grafisch dar. Sie können die resultierende .nupkg-Datei auch in eine .zip-Datei umbenennen und deren Inhalt direkt prüfen.

Zusätzliche Optionen

Sie können nuget pack mit verschiedenen Befehlszeilenparameter verwenden, um z.B. Dateien auszuschließen, die Versionsnummer im Manifest zu überschreiben und den Ausgabeordner zu ändern. Eine vollständige Liste finden Sie in der Referenz zum Packbefehl.

Folgende Optionen werden beispielsweise häufig in Visual Studio-Projekten verwendet:

  • Referenzierte Projekte: Wenn das Projekt auf andere verweist, können Sie die referenzierten Projekte mithilfe der Option -IncludeReferencedProjects als Teil des Pakets oder als Abhängigkeiten hinzufügen:

    nuget pack MyProject.csproj -IncludeReferencedProjects
    

    Diese Einschließung ist rekursiv. Wenn also MyProject.csproj auf die Projekte B und C verweist und diese Projekte ihrerseits auf die Projekte D, E und F, dann werden Dateien aus B, C, D, E und F in das Paket aufgenommen.

    Wenn ein referenziertes Projekt selbst eine .nuspec-Datei enthält, fügt NuGet dieses Projekt stattdessen als Abhängigkeit hinzu. Dieses Projekt muss separat gepackt und veröffentlicht werden.

  • Buildkonfiguration: NuGet verwendet die in der Projektdatei festgelegte Standardbuildkonfiguration, üblicherweise Debuggen. Um Dateien aus einer anderen Buildkonfiguration zu packen, z.B. Release, verwenden Sie die Option -properties mit folgender Konfiguration:

    nuget pack MyProject.csproj -properties Configuration=Release
    
  • Symbole: Um Symbole einzuschließen, mit denen Benutzer den Paketcode im Debugger schrittweise ausführen können, verwenden Sie die Option -Symbols:

    nuget pack MyProject.csproj -symbols
    

Testen der Paketinstallation

Vor dem Veröffentlichen eines Pakets testen Sie in der Regel die Installation eines Pakets in einem Projekt. Diese Tests stellen sicher, dass die erforderlichen Dateien an den richtigen Orten im Projekt installiert werden.

Installationen lassen sich manuell in Visual Studio oder mithilfe der normalen Paketinstallationsschritte über die Befehlszeile testen.

Für automatisierte Tests gehen Sie folgendermaßen vor:

  1. Kopieren Sie die .nupkg-Datei in einen lokalen Ordner.
  2. Fügen Sie den Ordner mithilfe des nuget sources add -name <name> -source <path>-Befehls den Paketquellen hinzu. Weitere Informationen finden Sie unter sources command (NuGet CLI) (sources-Befehl (NuGet-CLI)). Diese lokale Quelle muss auf einem Computer nur einmal festgelegt werden.
  3. Installieren Sie das Paket aus dieser Quelle mithilfe von nuget install <packageID> -source <name>, wobei <name> dem Namen der Quelle entspricht, so wie er an nuget sources übergeben wurde. Durch das Angeben der Quelle wird sichergestellt, dass das Paket nur aus dieser Quelle installiert wird.
  4. Überprüfen Sie Ihr Dateisystem, um sicherzustellen, dass Dateien richtig installiert wurden.

Nächste Schritte

Nachdem Sie ein Paket erstellt haben, das eine .nupkg-Datei ist, können Sie sie wie unter Publishing packages (Veröffentlichen von Paketen) beschrieben im Katalog Ihrer Wahl veröffentlichen.

Sie können auch die Funktionen des Pakets erweitern oder wie in den folgenden Themen beschrieben andere Szenarios unterstützen:

Außerdem sollten Sie die folgenden zusätzlichen Pakettypen berücksichtigen: