NuGet „pack“ und „restore“ als MSBuild-Ziele

  • Artikel

NuGet 4.0+

Mit dem PackageReference-Format kann NuGet 4.0 (und höher) alle Manifestmetadaten direkt in einer Projektdatei speichern, anstatt eine separate .nuspec-Datei zu verwenden.

Mit MSBuild 15.1 und höher stellt NuGet auch einen MSBuild-Angehörigen der ersten Klasse mit den Zielen pack und restore dar, wie im Folgenden beschrieben. Durch diese Ziele können Sie mit NuGet wie mit jeder anderen MSBuild-Task oder jedem anderen -Ziel arbeiten. Anweisungen zum Erstellen eines NuGet-Pakets mithilfe von MSBuild finden Sie unter Erstellen eines NuGet-Pakets mithilfe von MSBuild. (Bei NuGet 3.x und früher verwenden Sie die Befehle pack und restore stattdessen über die NuGet-CLI.)

Buildreihenfolge für Ziele

Da es sich bei pack und restore um MSBuild-Ziele handelt, können Sie zur Verbesserung Ihres Workflows darauf zugreifen. Angenommen, Sie möchten Ihr Paket nach dem Packen in eine Netzwerkfreigabe kopieren. Fügen Sie hierzu Folgendes in Ihrer Projektdatei hinzu:

<Target Name="CopyPackage" AfterTargets="Pack">
  <Copy
    SourceFiles="$(OutputPath)..\$(PackageId).$(PackageVersion).nupkg"
    DestinationFolder="\\myshare\packageshare\"
    />
</Target>

Gleichermaßen können Sie eine MSBuild-Task schreiben, Ihr eigenes Ziel schreiben und NuGet-Eigenschaften in der MSBuild-Task verwenden.

Hinweis

$(OutputPath) ist relativ und erwartet, dass Sie den Befehl aus dem Projektstamm ausführen.

Pack-Ziel

Bei .NET-Projekten, die das PackageReference-Format verwenden, werden bei Nutzung von msbuild -t:pack Eingaben aus der Projektdatei zum Erstellen eines NuGet-Pakets verwendet.

In der folgenden Tabelle werden die MSBuild-Eigenschaften beschrieben, die im ersten <PropertyGroup>-Knoten zu einer Projektdatei hinzugefügt werden können. Sie können diese Änderungen problemlos in Visual Studio 2017 und höheren Versionen vornehmen, indem Sie mit der rechten Maustaste auf das Projekt klicken und {Project_name} bearbeiten im Kontextmenü auswählen. Der Einfachheit halber ist die Tabelle nach der entsprechenden Eigenschaft in einer .nuspec-Datei organisiert.

Hinweis

Beachten Sie, dass die Eigenschaften Owners und Summary aus .nuspec in MSBuild nicht unterstützt werden.

Attribut/nuspec-Wert MSBuild-Eigenschaft Standard Hinweise
Id PackageId $(AssemblyName) Extraktion von $(AssemblyName) aus MSBuild
Version PackageVersion Version Dies ist mit SemVer kompatibel, z. B. 1.0.0, 1.0.0-beta oder 1.0.0-beta-00345. Der Standardwert ist Version, falls er nicht anders festgelegt wird.
VersionPrefix VersionPrefix empty Durch Festlegen von PackageVersion wird VersionPrefix überschrieben
VersionSuffix VersionSuffix empty Durch Festlegen von PackageVersion wird VersionSuffix überschrieben
Authors Authors Name des aktuellen Benutzers Eine durch Semikolon getrennte Liste von Paketautoren, die den Profilnamen in nuget.org entsprechen. Diese werden im NuGet-Katalog auf nuget.org angezeigt und werden für Querverweispakete von denselben Autoren verwendet.
Owners N/V Nicht in nuspec vorhanden.
Title Title $(PackageId) Ein benutzerfreundlicher Titel des Pakets, der in der Regel in der Benutzeroberfläche wie auf nuget.org angezeigt wird und der Paket-Manager in Visual Studio.
Description Description „Paketbeschreibung“ Eine lange Beschreibung für die Assembly. Wenn PackageDescription nicht angegeben ist, wird diese Eigenschaft auch als Beschreibung des Pakets verwendet.
Copyright Copyright empty Copyright-Informationen für das Paket.
RequireLicenseAcceptance PackageRequireLicenseAcceptance false Ein Boolescher Wert, der angibt, ob der Client den Verbraucher dazu auffordern muss, die Paketlizenz vor der Installation des Pakets zu akzeptieren.
license PackageLicenseExpression empty Entspricht <license type="expression"> Siehe Packen eines Lizenzausdrucks oder einer Lizenzdatei.
license PackageLicenseFile empty Pfad zu einer Lizenzdatei innerhalb des Pakets, wenn Sie eine benutzerdefinierte Lizenz oder eine Lizenz verwenden, der kein SPDX-Bezeichner zugewiesen wurde. Sie müssen die Lizenzdatei, auf die verwiesen wird, explizit packen. Entspricht <license type="file"> Siehe Packen eines Lizenzausdrucks oder einer Lizenzdatei.
LicenseUrl PackageLicenseUrl empty PackageLicenseUrl ist veraltet. Verwenden Sie stattdessen PackageLicenseExpression oder PackageLicenseFile.
ProjectUrl PackageProjectUrl empty
Icon PackageIcon empty Ein Pfad zu einem Bild im Paket, das als Paketsymbol verwendet werden soll. Sie müssen die Symbolbilddatei, auf die verwiesen wird, explizit packen. Weitere Informationen finden Sie unter Packen einer Symbolbilddatei und icon-Metadaten.
IconUrl PackageIconUrl empty PackageIconUrl wird zugunsten von PackageIcon eingestellt. Um jedoch die beste Downlevel-Erfahrung zu erzielen, sollten Sie zusätzlich zu PackageIcon auch PackageIconUrl festlegen.
Readme PackageReadmeFile empty Sie müssen die Infodatei, auf die verwiesen wird, explizit packen.
Tags PackageTags empty Eine durch Semikolons getrennte Liste von Tags, die das Paket festlegt.
ReleaseNotes PackageReleaseNotes empty Anmerkungen zu diesem Paket.
Repository/Url RepositoryUrl empty Repository-URL zum Klonen oder Abrufen von Quellcode. Beispiel: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git.
Repository/Type RepositoryType empty Repositorytyp. Beispiele: git (Standard), tfs.
Repository/Branch RepositoryBranch empty Optionale Repository-Verzweigungsinformationen. RepositoryUrl muss ebenfalls angegeben werden, damit diese Eigenschaft einbezogen wird. Beispiel: Master (NuGet 4.7.0+).
Repository/Commit RepositoryCommit empty Optionaler Repositorycommit oder ein Changeset, um anzugeben, für welches Quellpaket die Erstellung erfolgt ist. RepositoryUrl muss ebenfalls angegeben werden, damit diese Eigenschaft einbezogen wird. Beispiel: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+).
PackageType <PackageType>CustomType1, 1.0.0.0;CustomType2</PackageType> Gibt die beabsichtigte Verwendung des Pakets an. Pakettypen verwenden dasselbe Format wie Paket-IDs und werden durch ;abgegrenzt. Pakettypen können durch Anfügen einer ,- und einer Version-Zeichenkette versioniert werden. Siehe NuGet-Pakettyp festlegen (NuGet 3.5.0+).
Summary Nicht unterstützt

Eingaben für das Ziel „pack“

Eigenschaft Beschreibung
IsPackable Ein Boolescher Wert, der angibt, ob das Projekt verpackt werden kann. Der Standardwert ist true.
SuppressDependenciesWhenPacking Auf true festlegen, um Paketabhängigkeiten vom generierten NuGet-Paket zu unterdrücken.
PackageVersion Gibt die Version an, die das resultierende Paket haben wird. Akzeptiert alle Arten von NuGet-Versionszeichenketten. Standardmäßig beträgt der Wert $(Version) der Eigenschaft Version im Projekt.
PackageId Gibt den Namen für das resultierende Paket an. Wenn nicht angegeben, verwendet der pack-Vorgang standardmäßig AssemblyName oder den Verzeichnisnamen als Paketnamen.
PackageDescription Eine ausführliche Beschreibung des Pakets für die Anzeige der Benutzeroberfläche.
Authors Eine durch Semikolon getrennte Liste von Paketautoren, die den Profilnamen in nuget.org entsprechen. Diese werden im NuGet-Katalog auf nuget.org angezeigt und werden für Querverweispakete von denselben Autoren verwendet.
Description Eine lange Beschreibung für die Assembly. Wenn PackageDescription nicht angegeben ist, wird diese Eigenschaft auch als Beschreibung des Pakets verwendet.
Copyright Copyright-Informationen für das Paket.
PackageRequireLicenseAcceptance Ein Boolescher Wert, der angibt, ob der Client den Verbraucher dazu auffordern muss, die Paketlizenz vor der Installation des Pakets zu akzeptieren. Der Standardwert ist false.
DevelopmentDependency 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 (ab NuGet 4.8) bedeutet dieses Flag auch, dass Ressourcen zur Kompilierzeit von der Kompilierung ausgeschlossen werden. Weitere Informationen finden Sie unter DevelopmentDependency support for PackageReference (DevelopmentDependency-Unterstützung für PackageReference).
PackageLicenseExpression Ein SPDX-Lizenzbezeichner oder ein Ausdruck, z. B. Apache-2.0. Weitere Informationen finden Sie unter Packen eines Lizenzausdrucks oder einer Lizenzdatei.
PackageLicenseFile Pfad zu einer Lizenzdatei innerhalb des Pakets, wenn Sie eine benutzerdefinierte Lizenz oder eine Lizenz verwenden, der kein SPDX-Bezeichner zugewiesen wurde.
PackageLicenseUrl PackageLicenseUrl ist veraltet. Verwenden Sie stattdessen PackageLicenseExpression oder PackageLicenseFile.
PackageProjectUrl
PackageIcon Gibt den Paketsymbolpfad relativ zum Stammverzeichnis des Pakets an. Weitere Informationen finden Sie unter Packen einer Symbolbilddatei.
PackageReleaseNotes Anmerkungen zu diesem Paket.
PackageReadmeFile Infodatei für das Paket.
PackageTags Eine durch Semikolons getrennte Liste von Tags, die das Paket festlegt.
PackageOutputPath Bestimmt den Ausgabepfad, in dem das gepackte Paket abgelegt wird. Der Standardwert ist $(OutputPath).
IncludeSymbols Dieser Boolesche Wert gibt an, ob das Paket ein zusätzliches Symbolpaket erstellen soll, wenn das Projekt verpackt wird. Das Format des Symbolpakets wird durch die Eigenschaft SymbolPackageFormat gesteuert. Weitere Informationen finden Sie unter IncludeSymbols.
IncludeSource Dieser Boolesche Wert gibt an, ob der Packprozess ein Quellpaket erstellen sollte. Das Quellpaket enthält den Quellcode der Bibliothek sowie die PDB-Dateien. Quelldateien werden im src/ProjectName-Verzeichnis in der resultierenden Paketdatei gespeichert. Weitere Informationen finden Sie unter IncludeSource.
PackageType
IsTool Gibt an, ob alle Ausgabedateien in den Tools-Ordner anstelle des Lib-Ordners kopiert werden. Weitere Informationen finden Sie unter IsTool.
RepositoryUrl Repository-URL zum Klonen oder Abrufen von Quellcode. Beispiel: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git.
RepositoryType Repositorytyp. Beispiele: git (Standard), tfs.
RepositoryBranch Optionale Repository-Verzweigungsinformationen. RepositoryUrl muss ebenfalls angegeben werden, damit diese Eigenschaft einbezogen wird. Beispiel: Master (NuGet 4.7.0+).
RepositoryCommit Optionaler Repositorycommit oder ein Changeset, um anzugeben, für welches Quellpaket die Erstellung erfolgt ist. RepositoryUrl muss ebenfalls angegeben werden, damit diese Eigenschaft einbezogen wird. Beispiel: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+).
SymbolPackageFormat Gibt das Format des Symbolpakets an. Im Fall von „symbols.nupkg“ wird ein älteres Symbolpaket mit der Erweiterung .symbols.nupkg erstellt, das PDB-, DLL- und andere Ausgabedateien enthält. Im Fall von „snupkg“ wird ein snupkg-Symbolpaket erstellt, das die portierbaren PDB-Dateien enthält. Der Standardwert ist „symbols.nupkg“.
NoPackageAnalysis Gibt an, dass pack nach dem Erstellen des Pakets keine Paketanalyse ausführen sollte.
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.
IncludeBuildOutput Dieser Boolesche Wert gibt an, ob die Buildausgabeassemblys in die NUPKG-Datei gepackt werden sollen oder nicht.
IncludeContentInPack Dieser Boolesche Wert gibt an, ob alle Elemente, die über einen Content-Typ verfügen, automatisch im resultierenden Paket enthalten sind. Der Standardwert ist true.
BuildOutputTargetFolder Gibt den Ordner an, in dem die Ausgabeassemblys abgelegt werden. Die Ausgabeassemblys (und andere Ausgabedateien) werden in ihre jeweiligen Frameworkordner kopiert. Weitere Informationen finden Sie unter Ausgabe-Assemblys.
ContentTargetFolders Diese Eigenschaft gibt den Standardstandort an, an dem alle Inhaltsdateien gespeichert werden sollten, wenn PackagePath für sie nicht angegeben ist. Der Standardwert ist „content;contentFiles“. Weitere Informationen finden Sie unter Inhalt in ein Paket einschließen.
NuspecFile Relativer oder absoluter Pfad zur .nuspec-Datei, der für das Packen verwendet wird. Wenn angegeben, wird sie ausschließlich zur Verpackung von Informationen verwendet. Die Information in den Projekten wird nicht verwendet. Weitere Informationen finden Sie unter Packen mit Hilfr von .nuspec.
NuspecBasePath Der Basispfad für die .nuspec-Datei. Weitere Informationen finden Sie unter Packen mit Hilfr von .nuspec.
NuspecProperties Durch Semikolons getrennte Liste der Schlüssel = Wertpaare. Weitere Informationen finden Sie unter Packen mit Hilfr von .nuspec.

Pack-Szenarios

Unterdrücken von Abhängigkeiten

Um Paketabhängigkeiten vom generierten NuGet-Paket zu unterdrücken, legen Sie SuppressDependenciesWhenPacking auf true fest. Dadurch können alle Abhängigkeiten aus der generierten nupkg-Datei übersprungen werden.

PackageIconUrl

PackageIconUrl ist zugunsten der PackageIcon-Eigenschaft veraltet. Ab NuGet 5.3 und Visual Studio 2019, Version 16.3, löst pack die NU5048-Warnung aus, wenn die Paketmetadaten nur PackageIconUrl angeben.

PackageIcon

Tipp

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

Packen einer Symbolbilddatei

Verwenden Sie beim Packen von Symbolbilddateien die Eigenschaft PackageIcon, um den Symboldateipfad relativ zum Stammverzeichnis des Pakets anzugeben. Achten Sie außerdem darauf, dass die Datei im Paket enthalten ist. 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.

Zum Beispiel:

<PropertyGroup>
    ...
    <PackageIcon>icon.png</PackageIcon>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="images\icon.png" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

Muster für ein Paketsymbol.

Werfen Sie für das nuspec-Äquivalent einen Blick auf den nuspecVerweis auf das Symbol.

PackageReadmeFile (Infodatei des Pakets)

Unterstützt von NuGet 5.10.0 Vorschau 2 / .NET SDK 5.0.300 und höher

Beim Packen einer Infodatei müssen Sie die PackageReadmeFile-Eigenschaft 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).

Zum Beispiel:

<PropertyGroup>
    ...
    <PackageReadmeFile>readme.md</PackageReadmeFile>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="docs\readme.md" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

Werfen Sie für das nuspec-Äquivalent einen Blick auf den nuspecVerweis auf die Infodatei.

Ausgabeassemblys

nuget pack kopiert Ausgabedateien mit den Erweiterungen .exe, .dll, .xml, .winmd, .json und .pri. Welche Ausgabedateien kopiert werden, hängt davon ab, was MSBuild aus dem Ziel BuiltOutputProjectGroup bereitstellt.

Es gibt zwei MSBuild-Eigenschaften, die Sie in Ihrer Projektdatei oder Befehlszeile verwenden können, um das Ziel der Ausgabeassemblys zu steuern:

  • IncludeBuildOutput: Ein boolescher Wert, der bestimmt, ob die Ausgabeassemblys des Builds in das Paket eingeschlossen werden sollten.
  • BuildOutputTargetFolder: Gibt den Ordner an, in dem die Ausgabeassemblys angeordnet werden sollten. Die Ausgabeassemblys (und andere Ausgabedateien) werden in ihre jeweiligen Frameworkordner kopiert.

Paketverweise

Siehe Package References in Project Files (Paketverweise in Projektdateien).

Projekt-zu-Projekt-Verweise

Projekt-zu-Projekt-Verweise gelten standardmäßig als NuGet-Paketverweise. Zum Beispiel:

<ProjectReference Include="..\UwpLibrary2\UwpLibrary2.csproj"/>

Sie können auf folgende Metadaten zu Ihrem Projektverweis hinzufügen:

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

Einschließlich der Inhalte in einem Paket

Fügen Sie zusätzliche Metadaten zu dem vorhandenen <Content>-Element hinzu, um Inhalte einzuschließen. Standardmäßig werden alle Elemente vom Typ „Content“ in das Paket eingeschlossen, sofern Sie diese Elemente nicht mit Einträgen wie den folgenden überschreiben:

<Content Include="..\win7-x64\libuv.txt">
 <Pack>false</Pack>
</Content>

Standardmäßig werden alle Elemente zum Stammverzeichnis der Ordner content und contentFiles\any\<target_framework> innerhalb eines Pakets hinzugefügt, und die relative Ordnerstruktur wird beibehalten, sofern Sie keinen Paketpfad angeben:

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles\</PackagePath>
</Content>

Wenn Sie alle Ihre Inhalte in nur einen bestimmten Stammordner kopieren möchten (statt in die Ordner content und contentFiles), können Sie die MSBuild-Eigenschaft ContentTargetFolders verwenden, die standardmäßig auf „content;contentFiles“ festgelegt ist, aber auf beliebige andere Ordnernamen festgelegt werden kann. Beachten Sie Folgendes: Wenn Sie in ContentTargetFolders nur „contentFiles“ angeben, werden Dateien unter contentFiles\any\<target_framework> oder contentFiles\<language>\<target_framework> basierend auf buildAction angeordnet.

PackagePath kann eine durch Semikolons (;) getrennte Reihe von Zielpfaden sein. Durch die Angabe eines leeren Paketpfads würde die Datei zum Stammverzeichnis des Pakets hinzugefügt. Im Folgenden wird beispielsweise libuv.txt zucontent\myfiles, content\samples und dem Stammverzeichnis des Pakets hinzugefügt:

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles;content\sample;;</PackagePath>
</Content>

Es gibt auch eine MSBuild-Eigenschaft, $(IncludeContentInPack), die standardmäßig auf true festgelegt ist. Wenn diese in einem Projekt auf false festgelegt wird, werden die Inhalte aus diesem Projekt nicht in das NuGet-Paket eingeschlossen.

Weitere für das Ziel „pack“ spezifische Metadaten, die Sie auf ein beliebiges der oben genannten Elemente festlegen können, enthalten <PackageCopyToOutput> und <PackageFlatten>, die die Werte CopyToOutput und Flatten in der ausgegebenen nuspec-Datei auf den contentFiles-Eintrag festlegen.

Hinweis

Die Metadaten <Pack> und <PackagePath> können nicht nur auf Inhaltselemente, sondern auch auf Dateien mit den Buildvorgängen „Compile“, „EmbeddedResource“, „ApplicationDefinition“, „Page“, „Resource“, „SplashScreen“, „DesignData“, „DesignDataWithDesignTimeCreateableTypes“, „CodeAnalysisDictionary“, „AndroidAsset“, „AndroidResource“, „BundleResource“ oder „None“ festgelegt werden.

Damit das Ziel „pack“ bei der Verwendung von Globmustern den Dateinamen an Ihren Paketpfad anhängt, muss Ihr Paketpfad mit dem Ordnertrennzeichen enden. Andernfalls wird der Paketpfad als vollständiger Pfad einschließlich des Dateinamens behandelt.

IncludeSymbols

Bei Verwendung von MSBuild -t:pack -p:IncludeSymbols=true werden die entsprechenden .pdb-Dateien zusammen mit anderen Ausgabedateien kopiert (.dll, .exe, .winmd, .xml, .json, .pri). Beachten Sie, dass durch das Festlegen von IncludeSymbols=true ein reguläres Paket und ein Symbolpaket erstellt werden.

IncludeSource

Dies ist mit IncludeSymbols identisch. Der einzige Unterschied besteht darin, dass Quelldateien auch zusammen mit .pdb-Dateien kopiert werden. Alle Dateien vom Typ Compile werden in src\<ProjectName>\ kopiert. Dabei wird die Ordnerstruktur im relativen Pfad im resultierenden Paket beibehalten. Gleiches gilt auch für Quelldateien einer beliebigen ProjectReference, bei der TreatAsPackageReference auf false festgelegt ist.

Wenn sich eine Datei vom Typ „Compile“ außerhalb des Projektordners befindet, wird sie nur zu src\<ProjectName>\ hinzugefügt.

Packen eines Lizenzausdrucks oder einer Lizenzdatei

Nutzen Sie bei Verwendung eines Lizenzausdrucks die PackageLicenseExpression-Eigenschaft. Ein Beispiel finden Sie im Muster für den Lizenzausdruck.

<PropertyGroup>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>

Weitere Informationen zu Lizenzausdrücken und Lizenzen, die von NuGet.org akzeptiert werden, finden Sie unter Lizenzmetadaten.

Beim Packen einer Lizenzdatei müssen Sie das PackageLicenseFile-Element verwenden, um den Paketpfad relativ zum Stammverzeichnis des Pakets anzugeben. Achten Sie außerdem darauf, dass die Datei im Paket enthalten ist. Zum Beispiel:

<PropertyGroup>
    <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
</PropertyGroup>

<ItemGroup>
    <None Include="licenses\LICENSE.txt" Pack="true" PackagePath=""/>
</ItemGroup>

Ein Beispiel finden Sie im Muster für eine Lizenzdatei.

Hinweis

PackageLicenseExpression, PackageLicenseFile oder PackageLicenseUrl können jeweils nur einzeln angegeben werden.

Packen einer Datei ohne Erweiterung

In einigen Szenarien, z. B. beim Packen einer Lizenzdatei, sollten Sie auch eine Datei ohne Erweiterung einschließen. Aus historischen Gründen behandeln NuGet und MSBuild Pfade ohne Erweiterung als Verzeichnisse.

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0</TargetFrameworks>
    <PackageLicenseFile>LICENSE</PackageLicenseFile>
  </PropertyGroup>

  <ItemGroup>
    <None Include="LICENSE" Pack="true" PackagePath=""/>
  </ItemGroup>

Muster einer Datei ohne Erweiterung.

IsTool

Bei Verwendung von MSBuild -t:pack -p:IsTool=true werden alle Ausgabedateien entsprechend den Angaben im Szenario Ausgabeassemblys in den Ordner tools und nicht in den Ordner lib kopiert. Beachten Sie, dass sich dies von einem DotNetCliTool unterscheidet, das durch Festlegen von PackageType in der .csproj-Datei angegeben wird.

Packen mit einer .nuspec-Datei

Obwohl es empfohlen wird, alle Eigenschaften, die sich normalerweise in der .nuspec-Datei befinden, stattdessen in die Projektdatei aufzunehmen, können Sie wahlweise auch eine .nuspec-Datei verwenden, um Ihr Projekt zu packen. Für ein Projekt im Nicht-SDK-Format, das PackageReference verwendet, müssen Sie NuGet.Build.Tasks.Pack.targets importieren, damit die Packaufgabe ausgeführt werden kann. Sie müssen das Projekt noch wiederherstellen, bevor Sie eine nuspec-Datei packen können. (Ein Projekt im SDK-Format enthält standardmäßig die Packziele.)

Das Zielframework der Projektdatei ist irrelevant und wird beim Packen vonnuspec nicht verwendet. Die folgenden drei MSBuild-Eigenschaften sind für das Packen mit einer .nuspec relevant:

  1. NuspecFile: Relativer oder absoluter Pfad zur .nuspec-Datei, der für das Packen verwendet wird.
  2. NuspecProperties: Durch Semikolons (;) getrennte Liste der Schlüssel/Wert-Paare. Aufgrund der Funktionsweise der MSBuild-Befehlszeilenanalyse müssen mehrere Eigenschaften wie folgt angegeben werden: -p:NuspecProperties="key1=value1;key2=value2".
  3. NuspecBasePath: Der Basispfad für die .nuspec-Datei.

Wenn Sie Ihr Projekt mithilfe der Datei dotnet.exe packen, verwenden Sie einen Befehl wie den folgenden:

dotnet pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path>

Wenn Sie Ihr Projekt mithilfe der Datei MSBuild packen, verwenden Sie einen Befehl wie den folgenden:

msbuild -t:pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path>

Bitte beachten Sie, dass das Packen von nuspec mit dotnet.exe oder msbuild auch dazu führt, dass das Projekt standardmäßig erstellt wird. Dies kann vermieden werden, indem die --no-build-Eigenschaft an dotnet.exe übergeben wird. Dies entspricht der Einstellung <NoBuild>true</NoBuild> in Ihrer Projektdatei, zusammen mit der Einstellung <IncludeBuildOutput>false</IncludeBuildOutput> in der Projektdatei.

Ein Beispiel für eine .csproj-Datei zum Packen einer nuspec-Datei ist:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <NoBuild>true</NoBuild>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <NuspecFile>PATH_TO_NUSPEC_FILE</NuspecFile>
    <NuspecProperties>add nuspec properties here</NuspecProperties>
    <NuspecBasePath>optional to provide</NuspecBasePath>
  </PropertyGroup>
</Project>

Verbesserte Erweiterungspunkte zum Erstellen benutzerdefinierter Pakete

Das pack-Ziel stellt zwei Erweiterungspunkte bereit, die im inneren, zielframeworkspezifischen Build ausgeführt werden. Die Erweiterungspunkte unterstützen die Aufnahme von zielframeworkspezifischen Inhalten und Assemblys in ein Paket:

  • TargetsForTfmSpecificBuildOutput-Ziel: Für Dateien im lib-Ordner verwenden, oder Ordner, für die angegeben wurde, dass BuildOutputTargetFolder verwendet wird.
  • TargetsForTfmSpecificContentInPackage-Ziel: Für Dateien außerhalb von BuildOutputTargetFolder verwenden.

TargetsForTfmSpecificBuildOutput

Schreiben Sie ein benutzerdefiniertes Ziel, und geben Sie es als Wert der $(TargetsForTfmSpecificBuildOutput)-Eigenschaft an. Für alle Dateien, die in BuildOutputTargetFolder wechseln müssen (standardmäßig die Bibliothek), sollte das Ziel diese Dateien in die ItemGroup BuildOutputInPackage schreiben und die folgenden beiden Metadatenwerte festlegen:

  • FinalOutputPath: Der absolute Pfad der Datei; wenn nicht angegeben, wird zum Auswerten des Quellpfads die Identität herangezogen.
  • TargetPath: (Optional) Festlegen, wenn die Datei in einen Unterordner innerhalb von lib\<TargetFramework> wechseln muss, z. B. Satellitenassemblys, die unter ihren jeweiligen Kulturordnern abgelegt werden. Der Standardwert ist der Name der Datei.

Beispiel:

<PropertyGroup>
  <TargetsForTfmSpecificBuildOutput>$(TargetsForTfmSpecificBuildOutput);GetMyPackageFiles</TargetsForTfmSpecificBuildOutput>
</PropertyGroup>

<Target Name="GetMyPackageFiles">
  <ItemGroup>
    <BuildOutputInPackage Include="$(OutputPath)cs\$(AssemblyName).resources.dll">
        <TargetPath>cs</TargetPath>
    </BuildOutputInPackage>
  </ItemGroup>
</Target>

TargetsForTfmSpecificContentInPackage

Schreiben Sie ein benutzerdefiniertes Ziel, und geben Sie es als Wert der $(TargetsForTfmSpecificContentInPackage)-Eigenschaft an. Damit Dateien in das Paket aufgenommen werden können, sollte das Ziel diese Dateien in die ItemGroup TfmSpecificPackageFile schreiben und die folgenden optionalen Metadaten festlegen:

  • PackagePath: Der Pfad, in dem die Datei im Paket ausgegeben werden soll. NuGet gibt eine Warnung aus, wenn mehrere Dateien zum selben Paketpfad hinzugefügt werden.
  • BuildAction: Die Buildaktion, die der Datei zugewiesen werden soll. Nur erforderlich, wenn sich der Paketpfad im contentFiles-Ordner befindet. Der Standardwert ist „None“.

Ein Beispiel:

<PropertyGroup>
  <TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);CustomContentTarget</TargetsForTfmSpecificContentInPackage>
</PropertyGroup>

<Target Name="CustomContentTarget">
  <ItemGroup>
    <TfmSpecificPackageFile Include="abc.txt">
      <PackagePath>mycontent/$(TargetFramework)</PackagePath>
    </TfmSpecificPackageFile>
    <TfmSpecificPackageFile Include="Extensions/ext.txt" Condition="'$(TargetFramework)' == 'net46'">
      <PackagePath>net46content</PackagePath>
    </TfmSpecificPackageFile>  
  </ItemGroup>
</Target>

Wiederherstellungsziel

Das Ziel MSBuild -t:restore (das von nuget restore und dotnet restore in .NET Core-Projekten verwendet wird), stellt wie folgt Pakete wieder her, auf die in der Projektdatei verwiesen wird:

  1. Lesen aller Projekt-zu-Projekt-Verweise
  2. Lesen der Projekteigenschaften, um den Zwischenordner und Zielframeworks zu finden
  3. Übergeben von MSBuild-Daten an NuGet.Build.Tasks.dll
  4. Ausführen des Befehls „restore“
  5. Herunterladen von Paketen
  6. Schreiben von Assetdatei, Zielen und Eigenschaften

Das restore-Ziel funktioniert für Projekte, die das PackageReference-Format nutzen. MSBuild 16.5+ verfügt außerdem über eine Opt-In-Unterstützung für das packages.config-Format.

Hinweis

Das restore-Ziel sollte nicht in Kombination mit dem build-Ziel ausgeführt werden.

Wiederherstellen von Eigenschaften

Weitere Wiederherstellungseigenschaften können aus MSBuild-Eigenschaften in der Projektdatei stammen. Werte können auch mithilfe des -p:-Switch über die Befehlszeile festgelegt werden (siehe nachfolgende Beispiele).

Eigenschaft Beschreibung
RestoreSources Eine durch Semikolons (;) getrennte Liste mit Paketquellen.
RestorePackagesPath Ordnerpfad der Pakete für Benutzer.
RestoreDisableParallel Begrenzt Downloads auf jeweils einen Download.
RestoreConfigFile Der Pfad zu einer anzuwendenden Nuget.Config-Datei.
RestoreNoHttpCache Wenn wahr, wird die Verwendung von zwischengespeicherten HTTP-Paketen vermieden. Siehe Verwalten von globalen Paketen und Cacheordnern.
RestoreIgnoreFailedSources Wenn „TRUE“ festgelegt ist, werden fehlerhafte oder fehlende Paketquellen ignoriert.
RestoreFallbackFolders Fallbackordner, die auf die gleiche Weise wie der Benutzerpaketordner verwendet werden.
RestoreAdditionalProjectSources Zusätzliche Quellen, die während der Wiederherstellung verwendet werden können.
RestoreAdditionalProjectFallbackFolders Zusätzliche Fallbackordner, die während der Wiederherstellung verwendet werden können.
RestoreAdditionalProjectFallbackFoldersExcludes Schließt Fallbackordner aus, die in RestoreAdditionalProjectFallbackFolders angegeben sind.
RestoreTaskAssemblyFile Pfad zu NuGet.Build.Tasks.dll.
RestoreGraphProjectInput Durch Semikolons (;) getrennte Liste mit wiederherzustellenden Projekten, die absolute Pfade enthalten sollten.
RestoreUseSkipNonexistentTargets Wenn die Projekte über MSBuild gesammelt werden, bestimmt es, ob sie mithilfe der SkipNonexistentTargets-Optimierung gesammelt werden. Wenn nicht festgelegt, ist der Standardwert true. Die Folge ist ein Fail-Fast-Verhalten, wenn die Ziele eines Projekts nicht importiert werden können.
MSBuildProjectExtensionsPath Ausgabeordner, der standardmäßig auf BaseIntermediateOutputPath und den Ordner obj festgelegt ist.
RestoreForce Erzwingt bei auf PackageReference basierenden Projekten das Auflösen aller Abhängigkeiten, auch wenn die letzte Wiederherstellung erfolgreich war. Die Angabe dieses Flags ist mit dem Löschen der Datei project.assets.json vergleichbar. Dadurch wird die HTTP-Zwischenspeicherung nicht umgangen.
RestorePackagesWithLockFile Ermöglicht die Verwendung einer Sperrdatei.
RestoreLockedMode Wiederherstellung im gesperrten Modus ausführen. Das bedeutet, dass die Wiederherstellung die Abhängigkeiten nicht neu bewertet.
NuGetLockFilePath Ein benutzerdefinierter Speicherort für die Sperrdatei. Der Standardspeicherort befindet sich neben dem Projekt und heißt packages.lock.json.
RestoreForceEvaluate Erzwingt die Wiederherstellung, um die Abhängigkeiten neu zu berechnen und die Sperrdatei ohne Warnung zu aktualisieren.
RestorePackagesConfig Eine Opt-In-Option, mit der Projekte mit packages.config wiederhergestellt werden. Wird nur von MSBuild -t:restore unterstützt.
RestoreRepositoryPath nur packages.config. Gibt das Paketverzeichnis an, in das die Pakete wiederhergestellt werden sollen. Wenn nicht angegeben, wird SolutionDirectory verwendet.
RestoreUseStaticGraphEvaluation Eine Opt-In-Option zur Verwendung der statischen Diagrammauswertung MSBuild anstelle der Standardauswertung. Die statische Diagrammauswertung ist ein experimentelles Feature, das für große Repos und Lösungen wesentlich schneller ist.

Die ExcludeRestorePackageImports-Eigenschaft ist eine interne Eigenschaft, die von NuGet verwendet wird. Sie sollte in MSBuild-Dateien nicht geändert oder festgelegt werden.

Beispiele

Befehlszeile:

msbuild -t:restore -p:RestoreConfigFile=<path>

Projektdatei:

<PropertyGroup>
    <RestoreIgnoreFailedSources>true</RestoreIgnoreFailedSources>
</PropertyGroup>

Wiederherstellen von Ausgaben

Bei der Wiederherstellung werden die folgenden Dateien im obj-Buildordner erstellt:

Datei Beschreibung
project.assets.json Enthält das Abhängigkeitsdiagramm aller Paketverweise.
{projectName}.projectFileExtension.nuget.g.props Verweist auf in Paketen enthaltene MSBuild-Eigenschaften
{projectName}.projectFileExtension.nuget.g.targets Verweist auf in Paketen enthaltene MSBuild-Ziele

Wiederherstellen und Erstellen mit einem MSBuild-Befehl

Aufgrund der Tatsache, dass NuGet Pakete wiederherstellen kann, die MSBuild-Ziele und Eigenschaften verursachen, werden die Wiederherstellungs- und Build-Bewertungen mit anderen globalen Eigenschaften ausgeführt. Das bedeutet, dass im Folgenden ein unvorhersehbares und häufig falsches Verhalten auftreten wird.

msbuild -t:restore,build

Stattdessen lautet der empfohlene Ansatz:

msbuild -t:build -restore

Die gleiche Logik gilt für andere Ziele, die build ähnlich sind.

Wiederherstellen von PackageReference- und packages.config-Projekten mit MSBuild

Mit MSBuild ab 16.5 werden packages.config auch für msbuild -t:restore unterstützt.

msbuild -t:restore -p:RestorePackagesConfig=true

Hinweis

Die packages.config-Wiederherstellung ist nur mit MSBuild 16.5+ und nicht mit dotnet.exe möglich.

Wiederherstellen mit MSBuild statischer Diagrammauswertung

Hinweis

Bei MSBuild ab 16.6 hat NuGet ein experimentelles Feature hinzugefügt, um die statische Diagrammauswertung über die Befehlszeile nutzen zu können, was die Wiederherstellungszeit für große Repositorys erheblich verbessert.

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

Alternativ können Sie dieses Feature auch nutzen, indem Sie die Eigenschaft in einer Directory.Build.Props-Datei festlegen.

<Project>
  <PropertyGroup>
    <RestoreUseStaticGraphEvaluation>true</RestoreUseStaticGraphEvaluation>
  </PropertyGroup>
</Project>

Hinweis

Ab Visual Studio 2019.x und NuGet 5.x gilt dieses Feature als experimentell und opt-in. Folgen Sie NuGet/Home#9803, um mehr darüber zu erfahren, wann dieses Feature standardmäßig aktiviert sein wird.

Die statische Diagrammwiederherstellung ändert den Msbuild-Teil der Wiederherstellung, das Lesen und Bewerten des Projekts, aber nicht den Wiederherstellungsalgorithmus! Der Wiederherstellungsalgorithmus ist für alle NuGet-Tools gleich (NuGet.exe, MSBuild.exe, dotnet.exe und Visual Studio).

In sehr wenigen Szenarien verhält sich die statische Diagrammwiederherstellung möglicherweise anders als die aktuelle Wiederherstellung. Manche deklarierte PackageReferences oder ProjectReferences können fehlen.

Um sicherzugehen, sollten Sie bei der Migration auf die statische Diagrammwiederherstellung als einmalige Überprüfung Folgendes ausführen:

msbuild.exe -t:restore -p:RestoreUseStaticGraphEvaluation=true
msbuild.exe -t:restore

NuGet sollte keine Änderungen melden. Wenn Diskrepanzen angezeigt werden, melden Sie bitte unter NuGet/Start ein Issue.

Ersetzen einer Bibliothek aus einem Wiederherstellungsdiagramm

Wenn bei einer Wiederherstellung die falsche Assembly eingebunden wurde, kann diese Paketstandardauswahl ausgeschlossen und durch Ihre eigene Wahl ersetzt werden. Schließen Sie zunächst mit einem PackageReference-Element der obersten Ebene alle Objekte aus:

<PackageReference Include="Newtonsoft.Json" Version="9.0.1">
  <ExcludeAssets>All</ExcludeAssets>
</PackageReference>

Fügen Sie als Nächstes Ihren eigenen Verweis zur entsprechenden lokalen Kopie der DLL hinzu:

<Reference Include="Newtonsoft.Json.dll" />