Erweiterungen des CSPROJ-Formats für .NET Core

In diesem Dokument werden die Änderungen erläutert, die an die Projektdateien beim Wechsel von project.json auf csproj und MSBuild hinzugefügt wurden. Weitere Informationen über die allgemeine Projektdateisyntax und eine Referenz finden Sie in der Dokumentation zur MSBuild-Projektdatei.

Implizite Paketverweise

Es wird implizit auf Metapakete verwiesen, basierend auf der Grundlage des/der Zielfameworks, das/die in der <TargetFramework>- oder <TargetFrameworks>-Eigenschaft Ihrer Projektdatei angegeben wurde/n. <TargetFrameworks> wird ignoriert, wenn <TargetFramework> angegeben wird, egal wie die Reihenfolge ist.

 <PropertyGroup>
   <TargetFramework>netcoreapp1.1</TargetFramework>
 </PropertyGroup>
<PropertyGroup>
  <TargetFrameworks>netcoreapp1.1;net462</TargetFrameworks>
</PropertyGroup>

Empfehlungen

Da implizit auf die Microsoft.NETCore.App- oder NetStandard.Library-Metapakete verwiesen wird, sehen Sie im Folgenden unsere empfohlenen bewährten Methoden:

  • Es darf nie ein expliziter Verweis auf die Microsoft.NETCore.App- oder NetStandard.Library-Metapakete über das <PackageReference>-Element in Ihrer Projektdatei vorhanden sein.
  • Wenn Sie eine bestimmte Version der Laufzeit benötigen, sollten Sie die <RuntimeFrameworkVersion>-Eigenschaft in Ihrem Projekt (z.B. 1.0.4) verwenden, anstatt auf Metapakete zu verweisen.
  • Sollten Sie eine bestimmte Version der NetStandard.Library-Metapakete benötigen, können Sie die <NetStandardImplicitPackageVersion>-Eigenschaft verwenden und die Version festlegen, die Sie benötigen.

Standardkompilierung in .NET Core-Projekten

Beim Wechsel zum csproj-Format in den neuesten SDK-Versionen, haben wir die Standardaufnahmen- und ausschlüsse für Compile-Elemente und eingebettete Ressourcen zu den SDK-Eigenschaftendateien verschoben. Dies bedeutet, dass Sie diese Elemente nicht länger in Ihrer Projektdatei angeben müssen.

Der Hauptgrund dafür ist die Übersichtlichkeit in Ihrer Projektdatei. Die Standardeinstellungen im SDK sollten die gängigen Anwendungsbeispiele abdecken. Es besteht keine Notwendigkeit, sie in jedem Projekt zu wiederholen, das Sie erstellen. Dies führt zu kleineren Projektdateien, die viel einfacher zu verstehen und bei Bedarf auch manuell zu bearbeiten sind.

Die folgende Tabelle zeigt, welche Elemente und welche Globs im SDK enthalten und ausgeschlossen sind:

Element Glob einschließen Glob ausschließen Glob entfernen
Compile **/*.cs (oder andere Spracherweiterungen) **/*.user; **/*.*proj; **/*.sln; **/*.vssscc Nicht zutreffend
EmbeddedResource **/*.resx **/*.user; **/*.*proj; **/*.sln; **/*.vssscc Nicht zutreffend
Keine **/* **/*.user; **/*.*proj; **/*.sln; **/*.vssscc - **/*.cs; **/*.resx

Wenn Sie über Globs in Ihrem Projekt verfügen, und Sie versuchen, es mit dem neuesten SDK zu erstellen, erhalten Sie den folgenden Fehler:

Doppelte Compile-Elemente waren enthalten. .NET SDK enthält Compile-Elemente aus Ihrem Projektverzeichnis in der Standardeinstellung. Sie können diese Elemente aus Ihrer Projektdatei entfernen oder die Eigenschaft „EnableDefaultCompileItems“ auf „FALSE“ festlegen, wenn Sie sie explizit in Ihrer Projektdatei einfügen möchten.

Um diesen Fehler zu umgehen, können Sie entweder die expliziten Compile-Elemente entfernen, die mit denen übereinstimmen, die in der vorherigen Tabelle aufgeführt sind, oder Sie können die <EnableDefaultCompileItems>-Eigenschaft auf false wie folgt festlegen:

<PropertyGroup>
    <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
</PropertyGroup>

Wenn diese Eigenschaft auf false festgelegt wird, wird die implizite Aufnahme überschrieben, und das Verhalten wird wieder auf die früheren SDKs gesetzt, als Sie die Standardglobs in Ihrem Projekt angeben mussten.

Diese Änderung ändert die Hauptfunktionsweise anderer Aufnahmen nicht. Wenn Sie z.B. einige Dateien angeben möchten, die mit Ihrer Anwendung veröffentlicht werden, können Sie weiterhin die bekannten Mechanismen in csproj dafür nutzen (z.B. das <Content>-Element).

Empfehlung

Für csproj empfehlen wir, dass Sie die Standardglobs aus Ihrem Projekt entfernen und nur Dateipfade mit Globs für die Artefakte hinzufügen, die Ihre App/Bibliothek für verschiedene Szenarios benötigt (z.B. Runtime und NuGet-Paket).

Anzeige des gesamten Projekts wie in MSBuild

Obwohl diese csproj-Änderungen für eine erhebliche Vereinfachung der Projektdateien sorgen, möchten Sie vielleicht das vollständig erweiterte Projekt anzeigen, so wie es von MSBuild erkannt wird, nachdem das SDK und die zugehörigen Ziele eingeschlossen wurden. Führen Sie eine Vorverarbeitung des Projekts mit der /pp-Option des Befehls dotnet msbuild durch. Dieser zeigt die importierten Dateien, ihre Quellen und ihren Beitrag zum Build, ohne das Projekt tatsächlich zu erstellen:

dotnet msbuild /pp:fullproject.xml

Wenn das Projekt mehrere Zielframeworks umfasst, sollten nur Ergebnisse für ein Framework ausgegeben werden, indem dieses als MSBuild-Eigenschaft angegeben wird:

dotnet msbuild /p:TargetFramework=netcoreapp2.0 /pp:fullproject.xml

Erweiterungen

SDK-Attribut

Das <Project>-Element der .csproj-Datei hat ein neues Attribut namens Sdk. Sdk gibt an, welches SDK vom Projekt verwendet wird. Das SDK ist, wie das Schichtendokument beschreibt, ein Satz von MSBuild-Aufgaben und -Zielen, die .NET Core-Code erstellen können. Wir liefern zwei Haupt-SDKs mit .NET Core-Tools:

  1. Das .NET Core SDK mit der Microsoft.NET.Sdk-ID
  2. Das .NET Core Web-SDK mit der Microsoft.NET.Sdk.Web-ID

Das Sdk-Attribut muss auf eine dieser IDs auf dem <Project>-Element festgelegt werden, um die .NET Core-Tools nutzen und Codes erstellen zu können.

PackageReference

Element, das eine NuGet-Abhängigkeit im Projekt angibt. Das Include-Attribut gibt die Paket-ID an.

<PackageReference Include="<package-id>" Version="" PrivateAssets="" IncludeAssets="" ExcludeAssets="" />

Version

Version gibt die Version des wiederherzustellenden Pakets an. Das Attribut berücksichtigt die Regeln für das NuGet-Versionsschema. Das Standardverhalten ist eine genau Übereinstimmung mit der Version. Beispiel: Die Angabe von Version="1.2.3" ist gleichbedeutend mit der NuGet-Notation [1.2.3] für die genaue 1.2.3 Version des Pakets.

IncludeAssets, ExcludeAssets und PrivateAssets

Das IncludeAssets-Attribut gibt an, welche Objekte, die zu dem durch <PackageReference> angegebenen Paket gehören, genutzt werden sollen.

Das ExcludeAssets-Attribut gibt an, welche Objekte, die zu dem durch <PackageReference> angegebenen Paket gehören, nicht genutzt werden sollen.

Das PrivateAssets-Attribut gibt an, welche Objekte, die zu dem durch <PackageReference> angegebenen Paket gehören, genutzt, aber nicht an das nächste Projekt übertragen werden sollen.

Hinweis

PrivateAssets entspricht dem Element project.json/xproj SuppressParent.

Diese Attribute können eines oder mehrere der folgenden Elemente enthalten:

  • Compile: Gibt an, dass die Inhalte des Ordners „lib“ zum Kompilieren verfügbar sind
  • Runtime: Gibt an, dass die Inhalte des Ordners „runtime“ verteilt werden
  • ContentFiles: Gibt an, dass die Inhalte des contentfiles-Ordner verwendet werden.
  • Build: Gibt an, dass die Eigenschaften/Ziele im Ordner „build“ verwendet werden
  • Native: Gibt an, dass die Inhalte der nativen Objekte für die Runtime in den Ausgabeordner kopiert werden
  • Analyzers: Gibt an, dass Analysen verwendet werden

Alternativ kann das Attribut Folgendes enthalten:

  • None: Keines der Objekte wird verwendet.
  • All: Alle Objekte werden verwendet.

DotNetCliToolReference

Das <DotNetCliToolReference>-Element gibt das CLI-Tool an, das der Benutzer im Kontext des Projekts wiederherstellen möchte. Es ist ein Ersatz für den tools-Knoten in project.json.

<DotNetCliToolReference Include="<package-id>" Version="" />

Version

Version gibt die Version des wiederherzustellenden Pakets an. Das Attribut berücksichtigt die Regeln für das NuGet-Versionsschema. Das Standardverhalten ist eine genau Übereinstimmung mit der Version. Beispiel: Die Angabe von Version="1.2.3" ist gleichbedeutend mit der NuGet-Notation [1.2.3] für die genaue 1.2.3 Version des Pakets.

RuntimeIdentifiers

Das Element <RuntimeIdentifiers> ermöglicht die Angabe einer durch Semikolons getrennten Liste von Runtime-IDs (RIDs) für das Projekt. RIDs ermöglichen das Veröffentlichen einer eigenständigen Bereitstellung.

<RuntimeIdentifiers>win10-x64;osx.10.11-x64;ubuntu.16.04-x64</RuntimeIdentifiers>

RuntimeIdentifier

Das <RuntimeIdentifier>-Element ermöglicht die Angabe von nur einer einzigen Runtime-ID (RID) für das Projekt. RIDs ermöglichen das Veröffentlichen einer eigenständigen Bereitstellung.

<RuntimeIdentifier>ubuntu.16.04-x64</RuntimeIdentifier>

PackageTargetFallback

Das <PackageTargetFallback>-Element ermöglicht die Angabe eines Satzes von kompatiblen Zielen, die verwendet werden sollen, wenn Pakete wiederhergestellt werden. Dies soll ermöglichen, dass Pakete, in denen das .NET TxM (Target x Moniker) verwendet wird, mit Paketen funktionieren, in denen kein .NET TxM deklariert ist. Wird in einem Projekt das .NET TxM verwendet, müssen alle Pakete, zu denen es eine Abhängigkeit gibt, ebenfalls ein .NET TxM haben. Dies trifft nur dann nicht zu, wenn Sie das <PackageTargetFallback>-Element zu Ihrem Projekt hinzufügen, sodass Nicht-.NET-Plattformen mit .NET kompatibel sind.

Im folgenden Beispiel werden die Fallbacks für alle Ziele in Ihrem Projekt bereitgestellt:

<PackageTargetFallback>
    $(PackageTargetFallback);portable-net45+win8+wpa81+wp8
</PackageTargetFallback >

Im folgenden Beispiel werden nur die Fallbacks für das netcoreapp1.0-Ziel angegeben:

<PackageTargetFallback Condition="'$(TargetFramework)'=='netcoreapp1.0'">
    $(PackageTargetFallback);portable-net45+win8+wpa81+wp8
</PackageTargetFallback >

NuGet-Metadateneigenschaften

Mit dem Wechsel zu MSBuild haben wir die Eingabemetadaten, die beim Packen eines NuGet-Pakets verwendet werden, aus project.json in .csproj-Dateien verschoben. Die Eingaben sind MSBuild-Eigenschaften, sodass sie in eine <PropertyGroup>-Gruppe wechseln müssen. In der folgenden Liste sind die Eigenschaften aufgeführt, die als Eingaben für den Packvorgang verwendet werden, wenn der Befehl dotnet pack oder das MSBuild-Ziel Pack verwendet wird, das Bestandteil des SDKs ist.

IsPackable

Ein Boolescher Wert, der angibt, ob das Projekt verpackt werden kann. Der Standardwert ist true.

PackageVersion

Gibt die Version an, die das resultierende Paket haben wird. Akzeptiert alle Arten von NuGet-Versionszeichenfolgen. 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.

Titel

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. Wenn nicht angegeben, wird stattdessen die Paket-ID verwendet.

Authors

Eine durch Semikolons getrennte Liste der Paketautoren, die mit Profilnamen unter nuget.org übereinstimmen. Diese werden im NuGet-Katalog unter nuget.org angezeigt und werden verwendet, um Querverweise auf Pakete von den gleichen Autoren zu geben.

Beschreibung

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

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. Die Standardeinstellung ist false.

PackageLicenseUrl

Eine URL für die Lizenz, die auf das Paket angewendet werden kann.

PackageProjectUrl

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

PackageIconUrl

Eine URL für ein 64x64-Bild mit transparentem Hintergrund, das als Symbol für das Paket in der UI-Anzeige verwendet wird.

PackageReleaseNotes

Anmerkungen zu diesem 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. Dieses Paket wird eine .symbols.nupkg-Erweiterung haben und die PDB-Dateien zusammen mit der DLL und anderen Ausgabedateien kopieren.

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.

IsTool

Gibt an, ob alle Ausgabedateien in den Tools-Ordner anstelle des Lib-Ordners kopiert werden. Beachten Sie, dass dies anders als ein DotNetCliTool ist, der angegeben wird, indem die PackageType in der .csproj-Datei eingestellt wird.

RepositoryUrl

Gibt die URL für das Repository an, in der sich der Quellcode für das Paket befindet und/oder aus der es erstellt wird.

RepositoryType

Gibt den Verzeichnistyp an. Der Standardwert ist „Git“.

NoPackageAnalysis

Gibt an, dass der Packvorgang keine Paketanalyse nach dem Erstellen des Pakets 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 Werte 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. Die Standardeinstellung ist true.

BuildOutputTargetFolder

Gibt den Ordner an, in dem die Ausgabeassemblys positioniert werden. Die Ausgabeassemblys (und andere Ausgabedateien) werden in ihre jeweiligen Frameworkordner kopiert.

ContentTargetFolders

Diese Eigenschaft gibt den Standardspeicherort an, an dem alle Inhaltsdateien gespeichert werden sollten, wenn PackagePath für sie nicht angegeben ist. Der Standardwert ist „content;contentFiles“.

NuspecFile

Relativer oder absoluter Pfad zur .nuspec-Datei, die für die Komprimierung verwendet wird.

Hinweis

Wenn die .nuspec-Datei angegeben ist, wird sie ausschließlich zur Verpackung von Informationen verwendet, und die Information in den Projekten wird nicht verwendet.

NuspecBasePath

Der Basispfad für die .nuspec-Datei.

NuspecProperties

Durch Semikolons getrennte Liste der Schlüssel = Wertpaare.