MSBuild-Eigenschaften und -Ziele in einem Paket

Artikel
08/10/2023

Zusätzlich zu den herkömmlichen Assemblys können NuGet-Pakete manchmal benutzerdefinierte Buildziele oder -eigenschaften zu Projekten hinzufügen, die dieses Paket nutzen. Dies kann durch Hinzufügen einer gültigen MSBuild-Datei im Formular <package_id>.targets oder <package_id>.props (z. B. Contoso.Utility.UsefulStuff.targets) innerhalb der Buildordner des Projekts erreicht werden.

Erstellen von Ordnern

Da NuGet weiterentwickelt wurde, wurden verschiedene unterschiedliche Ordner für den Build .props und .targets hinzugefügt.

Ordner	NuGet-Version	Verwenden
build	2.5 und höher	Buildlogik für jedes Framework eines Projekts
buildMultiTargeting	4.0+	Buildlogik für `outer build` für Projekte, die auf mehrere Frameworks abzielen. Nur PackageReference.
buildTransitive	5.0 und höher	Buildlogik für Ressourcen, die transitiv in beliebige verarbeitende Projekte eingefügt werden. Weitere Informationen finden Sie auf der Seite Feature. Nur PackageReference.

Frameworkspezifischer Buildordner

Alle drei Buildordner folgen demselben Muster, um eine Entscheidung über die am besten geeignete Datei basierend auf dem Projektzielframework zu treffen.

Dateien im Buildordner des Stammverzeichnisses, build/<package_id>.targets und build/<package_id>.props, 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

Bevorzugen Sie wann immer möglich die Verwendung von frameworkspezifischen Buildordnern, um falsch positive Installationen in Projekten zu vermeiden, die möglicherweise nicht von Ihrem Paket unterstützt werden.

Beachten Sie, dass dieses Paket als kompatibel mit allen Projekten betrachtet wird, wenn ein Paket keine Dateien in den Ordnern lib oder ref enthält und nur Dateien unter einem frameworkspezifischen Buildordner enthalten sind. In den neuesten Versionen der Pakettools wird die Warnung NU5127 ausgelöst, wenn solche Pakete erstellt werden.

Projekte, die Pakete mit Builddateien verwenden

PackageReference-Projekte

.props und .targets werden nicht zur Projektdatei hinzugefügt, sondern über {projectName}.nuget.g.targets und {projectName}.nuget.g.propszur Verfügung gestellt. Diese Dateien werden automatisch generiert, wenn die Wiederherstellung ausgeführt wird.

Wenn ein Projekt auf mehrere Frameworks ausgerichtet ist, sind die Importe in diese Dateien vom Zielframeworknamen abhängig.

MSBuild-.props- und -.targets-Dateien für Ziele in mehreren Frameworks können im Ordner \buildMultiTargeting abgelegt werden. Wenn die Importe generiert werden, wird die Bedingung festgelegt, dass die MSBuild-Eigenschaft $(TargetFramework) leer ist.

packages.config-Projekte

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; .targets wird unten hinzugefügt.) Für jedes Zielframework wird ein separates bedingtes MSBuild-Element <Import> hinzugefügt.

Erstellen von Paketen mit MSBuild-Eigenschaften und -Zielen

Sie können eines der folgenden Tools verwenden, um die MSBuild-Instanzen .props und .targets in dieses Paket einzuschließen.

Anleitungen für den Inhalt von MSBuild-Eigenschaften und -Zielen

NuGet beschränkt nicht, wie Sie .props und .targets erstellen, da diese auf den Anforderung des Paketautors sowie den Zielprojekten selbst basieren.

Einige Aktionen dürfen nicht in .props und .targets in Paketen ausgeführt werden. Dazu zählen das Angeben von Eigenschaften und Elementen, die die Wiederherstellen beeinflussen, da diese automatisch ausgeschlossen werden.

Einige Beispiele für Eigenschaften, die nicht hinzugefügt oder aktualisiert werden dürfen: TargetFramework, TargetFrameworkMoniker, TargetPlatformMoniker und AssetTargetFallback.
Einige Beispiele für Elemente, die nicht hinzugefügt oder aktualisiert werden dürfen: PackageReference, PackageVersion und PackageDownload.