MSBuild-Referenz für .NET SDK-Projekte

  • Artikel

Diese Seite ist eine Referenz für die MSBuild-Eigenschaften und -Elemente, mit denen Sie .NET-Projekte konfigurieren können.

Hinweis

Diese Seite befindet sich noch in Bearbeitung und führt nicht sämtlich nützlichen MSBuild-Eigenschaften für das .NET SDK auf. Eine Liste der gängigen MSBuild-Eigenschaften finden Sie unter Gemeinsame MSBuild-Projekteigenschaften.

Eigenschaften der Assemblyüberprüfung

Diese Eigenschaften und Elemente werden an die ValidateAssemblies-Aufgabe übergeben. Weitere Informationen zur Assemblyüberprüfung finden Sie unter Assemblyüberprüfung.

Die folgenden MSBuild-Eigenschaften sind in diesem Abschnitt dokumentiert:

Hinweis

Diese Eigenschaften sind (noch) nicht Teil des .NET SDK. Um sie zu verwenden, müssen Sie auch PackageReference zu Microsoft.DotNet.ApiCompat.Task hinzufügen.

Darüber hinaus gelten die folgenden Eigenschaften, die unter Eigenschaften der Paketüberprüfung dokumentiert sind, auch für die Assemblyüberprüfung:

ApiCompatStrictMode

Bei Festlegung auf true gibt die Eigenschaft ApiCompatStrictMode an, dass API-Kompatibilitätsprüfungen im Strict-Modus ausgeführt werden sollen.

<PropertyGroup>
  <ApiCompatStrictMode>true</ApiCompatStrictMode>
</PropertyGroup>

ApiCompatValidateAssemblies

Die Eigenschaft ApiCompatValidateAssemblies aktiviert eine Reihe von Überprüfungen für die angegebenen Assemblys. Weitere Informationen dazu finden Sie unter Assemblyüberprüfung.

<PropertyGroup>
  <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
</PropertyGroup>

Frameworkeigenschaften

Die folgenden MSBuild-Eigenschaften sind in diesem Abschnitt dokumentiert:

TargetFramework

Die Eigenschaft TargetFramework gibt die Zielframeworkversion für die App an. Eine Liste gültiger Zielframeworkmoniker finden Sie unter Zielframeworks in Projekten im SDK-Format.

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
</PropertyGroup>

Weitere Informationen finden Sie unter Zielframeworks in Projekten im SDK-Format.

TargetFrameworks

Verwenden Sie die Eigenschaft TargetFrameworks, wenn Sie Ihre App für mehrere Zielplattformen entwickeln möchten. Eine Liste gültiger Zielframeworkmoniker finden Sie unter Zielframeworks in Projekten im SDK-Format.

Hinweis

Diese Eigenschaft wird ignoriert, wenn TargetFramework (Singular) angegeben ist.

<PropertyGroup>
  <TargetFrameworks>net8.0;net462</TargetFrameworks>
</PropertyGroup>

Weitere Informationen finden Sie unter Zielframeworks in Projekten im SDK-Format.

NetStandardImplicitPackageVersion

Hinweis

Diese Eigenschaft gilt nur für Projekte, die netstandard1.x verwenden. Sie gilt nicht für Projekte, die netstandard2.x verwenden.

Verwenden Sie die Eigenschaft NetStandardImplicitPackageVersion, wenn Sie eine Frameworkversion angeben möchten, die niedriger ist als die Metapaketversion. Die Projektdatei im folgenden Beispiel gilt für netstandard1.3, verwendet aber Version 1.6.0 von NETStandard.Library.

<PropertyGroup>
  <TargetFramework>netstandard1.3</TargetFramework>
  <NetStandardImplicitPackageVersion>1.6.0</NetStandardImplicitPackageVersion>
</PropertyGroup>

Eigenschaften von Assemblyattributen

GenerateAssemblyInfo

Die GenerateAssemblyInfo-Eigenschaft steuert die Generierung des AssemblyInfo-Attributs für das Projekt. Standardwert: true. Verwenden Sie false, um die Generierung der Datei zu deaktivieren:

<PropertyGroup>
  <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>

Die Einstellung GeneratedAssemblyInfoFile steuert den Namen der generierten Datei.

Wenn der GenerateAssemblyInfo-Wert true lautet, werden paketbezogene Projekteigenschaften in Assemblyattribute umgewandelt.

Weitere Informationen zum Generieren von Assemblyattributen mithilfe einer Projektdatei finden Sie unter Festlegen von Assemblyattributen in einer Projektdatei.

GeneratedAssemblyInfoFile

Die GeneratedAssemblyInfoFile-Eigenschaft definiert den relativen oder absoluten Pfad der generierten Assemblyinformationsdatei. Standardmäßig handelt es sich dabei um eine Datei mit dem Namensformat [projektname].AssemblyInfo.[cs|vb] im Verzeichnis $(IntermediateOutputPath) (üblicherweise obj).

<PropertyGroup>
  <GeneratedAssemblyInfoFile>assemblyinfo.cs</GeneratedAssemblyInfoFile>
</PropertyGroup>

Paketeigenschaften

Beschreibende Eigenschaften

Sie können Eigenschaften wie PackageId, PackageVersion, PackageIcon, Title und Description angeben, um das Paket zu beschreiben, das aus Ihrem Projekt erstellt wird. Informationen zu diesen und anderen Eigenschaften finden Sie unter Paketziel.

<PropertyGroup>
  ...
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>John Doe</Authors>
  <Company>Contoso</Company>
</PropertyGroup>

PackRelease

Die PackRelease-Eigenschaft ähnelt der PublishRelease-Eigenschaft, mit der Ausnahme, dass sie das Standardverhalten von dotnet pack ändert. Diese Eigenschaft wurde in .NET 7 eingeführt.

<PropertyGroup>
  <PackRelease>true</PackRelease>
</PropertyGroup>

Hinweis

  • Ab dem .NET 8 SDK ist PackRelease standardmäßig auf true festgelegt. Weitere Informationen finden Sie unter „dotnet pack“ verwendet die Releasekonfiguration.
  • Nur .NET 7 SDK: Um PackRelease in einem Projekt zu verwenden, das Teil einer Visual Studio-Projektmappe ist, müssen Sie die Umgebungsvariable DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS auf true (oder einen anderen Wert) festlegen. Bei Projektmappen mit vielen Projekten erhöht das Festlegen dieser Variablen den erforderlichen Zeitaufwand für das Packen.

Paketüberprüfungseigenschaften

Diese Eigenschaften und Elemente werden an die ValidatePackage-Aufgabe übergeben. Weitere Informationen zur Paketüberprüfung finden Sie in der Übersicht über die Paketüberprüfung.

Eigenschaften für die ValidateAssemblies-Aufgabe finden Sie unter Eigenschaften der Assemblyüberprüfung.

Die folgenden MSBuild-Eigenschaften und -Elemente sind in diesem Abschnitt dokumentiert:

ApiCompatEnableRuleAttributesMustMatch

Bei Festlegung auf true aktiviert die Eigenschaft ApiCompatEnableRuleAttributesMustMatch die Überprüfungsregel, die überprüft, ob Attribute übereinstimmen. Der Standardwert ist false.

<PropertyGroup>
  <ApiCompatEnableRuleAttributesMustMatch>true</ApiCompatEnableRuleAttributesMustMatch>
</PropertyGroup>

ApiCompatEnableRuleCannotChangeParameterName

Bei Festlegung auf true aktiviert die Eigenschaft ApiCompatEnableRuleCannotChangeParameterName die Überprüfungsregel, die überprüft, ob Parameternamen in öffentlichen Methoden geändert wurden. Der Standardwert ist false.

<PropertyGroup>
  <ApiCompatEnableRuleCannotChangeParameterName>true</ApiCompatEnableRuleCannotChangeParameterName>
</PropertyGroup>

ApiCompatExcludeAttributesFile

Das ApiCompatExcludeAttributesFile-Element gibt den Pfad zu einer Datei an, die auszuschließende Attribute im Format DocId enthält.

<ItemGroup>
  <ApiCompatExcludeAttributesFile Include="ApiCompatExcludedAttributes.txt" />
  <ApiCompatExcludeAttributesFile Include="ApiCompatBaselineExcludedAttributes.txt" />
</ItemGroup>

ApiCompatGenerateSuppressionFile

Die ApiCompatGenerateSuppressionFile-Eigenschaft gibt an, ob eine Kompatibilitätsunterdrückungsdatei generiert werden soll.

<PropertyGroup>
  <ApiCompatGenerateSuppressionFile>true</ApiCompatGenerateSuppressionFile>
</PropertyGroup>

ApiCompatPermitUnnecessarySuppressions

Die ApiCompatPermitUnnecessarySuppressions-Eigenschaft gibt an, ob unnötige Unterdrückungen in der Unterdrückungsdatei zulässig sind.

Der Standardwert ist false.

<PropertyGroup>
  <ApiCompatPermitUnnecessarySuppressions>true</ApiCompatPermitUnnecessarySuppressions>
</PropertyGroup>

ApiCompatPreserveUnnecessarySuppressions

Die ApiCompatPreserveUnnecessarySuppressions-Eigenschaft gibt an, ob unnötige Unterdrückungen beim erneuten Generieren der Unterdrückungsdatei zulässig sind. Wenn eine vorhandene Unterdrückungsdatei neu generiert wird, wird der Inhalt gelesen, in eine Reihe von Unterdrückungen deserialisiert und dann in einer Liste gespeichert. Einige der Unterdrückungen sind möglicherweise nicht mehr erforderlich, wenn die Inkompatibilität behoben wurde. Wenn die Unterdrückungen wieder auf dem Datenträger serialisiert werden, können Sie auswählen, dass alle vorhandenen (deserialisierten) Ausdrücke beibehalten werden, indem Sie diese Eigenschaft auf true festlegen.

Der Standardwert ist false.

<PropertyGroup>
  <ApiCompatPreserveUnnecessarySuppressions>true</ApiCompatPreserveUnnecessarySuppressions>
</PropertyGroup>

ApiCompatRespectInternals

Die ApiCompatRespectInternals-Eigenschaft gibt an, ob internal-APIs zusätzlich zu public-APIs auf Kompatibilität überprüft werden sollen.

<PropertyGroup>
  <ApiCompatRespectInternals>true</ApiCompatRespectInternals>
</PropertyGroup>

ApiCompatSuppressionFile

Das ApiCompatSuppressionFile-Element gibt den Pfad zu einer oder mehreren Unterdrückungsdateien an, aus der/denen gelesen werden soll. Wenn keine Angabe erfolgt, wird die Unterdrückungsdatei <project-directory>/CompatibilitySuppressions.xml gelesen (sofern vorhanden).

<ItemGroup>
  <ApiCompatSuppressionFile Include="CompatibilitySuppressions.xml;CompatibilitySuppressions.WasmThreads.xml" />
</ItemGroup>

ApiCompatSuppressionOutputFile

Die ApiCompatSuppressionOutputFile-Eigenschaft gibt den Pfad zu einer Unterdrückungsdatei an, in die geschrieben werden soll, wenn <ApiCompatGenerateSuppressionFile> auf true festgelegt ist. Ohne Angabe wird das erste ApiCompatSuppressionFile-Element verwendet.

EnablePackageValidation

Die Eigenschaft EnablePackageValidation aktiviert eine Reihe von Überprüfungen für das Paket nach der Pack-Aufgabe. Weitere Informationen finden Sie unter Paketüberprüfung.

<PropertyGroup>
  <EnablePackageValidation>true</EnablePackageValidation>
</PropertyGroup>

EnableStrictModeForBaselineValidation

Bei Festlegung auf true aktiviert die EnableStrictModeForBaselineValidation-Eigenschaft den Strict-Modus für Paketbasisüberprüfungen. Der Standardwert ist false.

EnableStrictModeForCompatibleFrameworksInPackage

Bei Festlegung auf true aktiviert die EnableStrictModeForCompatibleFrameworksInPackage-Eigenschaft den Strict-Modus für Assemblys, die basierend auf ihrem Zielframework kompatibel sind. Der Standardwert ist false.

EnableStrictModeForCompatibleTfms

Bei Festlegung auf true aktiviert die EnableStrictModeForCompatibleTfms-Eigenschaft den Strict-Modus für Vertrags- und Implementierungsassemblys für alle kompatiblen Zielframeworks. Der Standardwert ist true.

NoWarn

Die NoWarn-Eigenschaft gibt die zu unterdrückenden Diagnose-IDs an.

<PropertyGroup>
  <NoWarn>$(NoWarn);PKV0001</NoWarn>
</PropertyGroup>

PackageValidationBaselineFrameworkToIgnore

Das PackageValidationBaselineFrameworkToIgnore-Element gibt ein Zielframework an, das vom Basispaket ignoriert werden soll. Die Frameworkzeichenfolge muss exakt mit dem Ordnernamen im Basispaket übereinstimmen.

<ItemGroup>
  <PackageValidationBaselineFrameworkToIgnore Include="netcoreapp2.1" />
</ItemGroup>

PackageValidationBaselineName

Die PackageValidationBaselineName-Eigenschaft gibt den Namen des Basispakets an, anhand dessen das aktuelle Paket überprüft werden soll. Ohne Angabe wird der Wert PackageId verwendet.

PackageValidationBaselineVersion

Die PackageValidationBaselineVersion-Eigenschaft gibt die Version des Basispakets an, anhand dessen das aktuelle Paket überprüft werden soll.

PackageValidationReferencePath

Das PackageValidationReferencePath-Element gibt den Verzeichnispfad an, in dem die Referenzassembly pro TFM gefunden werden kann.

<ItemGroup>
  <PackageValidationReferencePath Include="path/to/reference-assembly" TargetFramework="net7.0" />
</ItemGroup>

RoslynAssembliesPath

Die RoslynAssembliesPath-Eigenschaft gibt den Pfad zum Verzeichnis an, das die Microsoft.CodeAnalysis-Assemblys enthält, die Sie verwenden möchten. Sie müssen diese Eigenschaft nur festlegen, wenn Sie zum Testen einen neueren Compiler als den verwenden möchten, der im SDK enthalten ist.

Die folgenden MSBuild-Eigenschaften sind in diesem Abschnitt dokumentiert:

AppendTargetFrameworkToOutputPath

Die AppendTargetFrameworkToOutputPath-Eigenschaft steuert, ob der Zielframeworkmoniker (TFM, Target Framework Moniker) an den Ausgabepfad angehängt wird, der durch OutputPath definiert wird. Das .NET SDK fügt automatisch das Zielframework und, falls vorhanden, den Runtimebezeichner an den Ausgabepfad an. Wenn Sie AppendTargetFrameworkToOutputPath auf false festlegen, wird verhindert, dass der Zielframeworkmoniker an den Ausgabepfad angefügt wird. Jedoch überschreiben sich ohne den Zielframeworkmoniker im Ausgabepfad mehrere Buildartefakte gegenseitig.

Beispielsweise wird für eine .NET 5-App mit der folgenden Einstellung der Ausgabepfad von bin\Debug\net5.0 in bin\Debug geändert:

<PropertyGroup>
  <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
</PropertyGroup>

AppendRuntimeIdentifierToOutputPath

Die AppendRuntimeIdentifierToOutputPath-Eigenschaft steuert, ob der Runtimebezeichner (RID, Runtime Identifier) an den Ausgabepfad angefügt wird. Das .NET SDK fügt automatisch das Zielframework und, falls vorhanden, den Runtimebezeichner an den Ausgabepfad an. Wenn Sie AppendRuntimeIdentifierToOutputPath auf false festlegen, wird verhindert, dass der Runtimebezeichner an den Ausgabepfad angefügt wird.

For example, for a .NET 5 app and an RID of win-x64, the following setting changes the output path from bin\Debug\net5.0\win-x64bin\Debug\net5.0:

<PropertyGroup>
  <AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
</PropertyGroup>

CopyLocalLockFileAssemblies

Die Eigenschaft CopyLocalLockFileAssemblies ist nützlich für Plug-In-Projekte, die von anderen Bibliotheken abhängig sind. Wenn Sie diese Eigenschaft auf true festlegen, werden alle Abhängigkeiten von NuGet-Paketen in das Ausgabeverzeichnis kopiert. Das bedeutet, dass Sie die Ausgabe von dotnet build verwenden können, um das Plug-In auf einem beliebigen Computer auszuführen.

<PropertyGroup>
  <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
</PropertyGroup>

Tipp

Alternativ können Sie auch dotnet publish verwenden, um die Klassenbibliothek zu veröffentlichen. Weitere Informationen finden Sie unter dotnet publish.

ErrorOnDuplicatePublishOutputFiles

Die Eigenschaft ErrorOnDuplicatePublishOutputFiles bezieht sich darauf, ob das SDK den Fehler NETSDK1148 generiert, wenn MSBuild doppelte Dateien in der Veröffentlichungsausgabe erkennt, aber nicht bestimmen kann, welche Dateien entfernt werden sollen. Legen Sie die Eigenschaft ErrorOnDuplicatePublishOutputFiles auf false fest, wenn der Fehler nicht generiert werden soll.

<PropertyGroup>
  <ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
</PropertyGroup>

Diese Eigenschaft wurde in .NET 6 eingeführt.

GenerateRuntimeConfigDevFile

Ab dem .NET 6 SDK wird die Datei [Appname].runtimesettings.dev.json zur Kompilierzeit nicht mehr standardmäßig generiert. Wenn diese Datei trotzdem generiert werden soll, legen Sie die GenerateRuntimeConfigDevFile-Eigenschaft auf true fest.

<PropertyGroup>
  <GenerateRuntimeConfigDevFile>true</GenerateRuntimeConfigDevFile>
</PropertyGroup>

GenerateRuntimeConfigurationFiles

Die GenerateRuntimeConfigurationFiles-Eigenschaft steuert, ob Optionen für die Laufzeitkonfiguration aus der Datei runtimeconfig.template.json in die Datei [appname].runtimeconfig.json kopiert werden. Für Apps, die eine runtimeconfig.json-Datei erfordern – also für solche mit Exe als OutputType –, ist diese Eigenschaft standardmäßig true.

<PropertyGroup>
  <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
</PropertyGroup>

GenerateSatelliteAssembliesForCore

Die GenerateSatelliteAssembliesForCore-Eigenschaft steuert, ob Satellitenassemblys mit csc.exe oder mit Al.exe (Assembly-Linker) in .NET Framework-Projekten generiert werden. (.NET Core- und .NET 5+-Projekte verwenden immer csc.exe zum Generieren von Satellitenassemblys.) Für .NET Framework-Projekte werden Satellitenassemblys standardmäßig von al.exe erstellt. Wenn Sie die GenerateSatelliteAssembliesForCore-Eigenschaft auf true festlegen, werden Satellitenassemblys stattdessen von csc.exe erstellt. Die Verwendung von csc.exe kann in folgenden Situationen von Vorteil sein:

<PropertyGroup>
  <GenerateSatelliteAssembliesForCore>true</GenerateSatelliteAssembliesForCore>
</PropertyGroup>

IsPublishable

Die Eigenschaft IsPublishable ermöglicht die Ausführung des Ziels Publish. Diese Eigenschaft wirkt sich nur auf Prozesse aus, die *.proj-Dateien und das Publish-Ziel verwenden, z. B. der Befehl dotnet publish. Dies wirkt sich nicht auf die Veröffentlichung in Visual Studio aus, die das Ziel PublishOnly verwendet. Standardwert: true.

Diese Eigenschaft ist nützlich, wenn Sie dotnet publish für eine Lösungsdatei ausführen, da sie die automatische Auswahl von Projekten ermöglicht, die veröffentlicht werden sollen.

<PropertyGroup>
  <IsPublishable>false</IsPublishable>
</PropertyGroup>

PreserveCompilationContext

Die PreserveCompilationContext-Eigenschaft ermöglicht es einer erstellten oder veröffentlichten Anwendung, mehr Code zur Laufzeit mit denselben Einstellungen zu kompilieren, die zum Zeitpunkt der Erstellung verwendet wurden. Die Assemblys, auf die zur Buildzeit verwiesen wird, werden in das ref-Unterverzeichnis des Ausgabeverzeichnisses kopiert. Die Namen der Verweisassemblys werden in der .deps.json-Datei der Anwendung zusammen mit den Optionen gespeichert, die an den Compiler weitergeleitet werden. Sie können diese Informationen mithilfe der Eigenschaften DependencyContext.CompileLibraries und DependencyContext.CompilationOptions abrufen.

Diese Funktion wird hauptsächlich intern von ASP.NET Core MVC und Razor Pages verwendet, um die Runtime-Kompilierung von Razor-Dateien zu unterstützen.

<PropertyGroup>
  <PreserveCompilationContext>true</PreserveCompilationContext>
</PropertyGroup>

PreserveCompilationReferences

Die PreserveCompilationReferences-Eigenschaft ähnelt der PreserveCompilationContext-Eigenschaft, mit der Ausnahme, dass sie nur die referenzierten Assemblys in das Veröffentlichungsverzeichnis kopiert, nicht die .deps.json-Datei.

<PropertyGroup>
  <PreserveCompilationReferences>true</PreserveCompilationReferences>
</PropertyGroup>

Weitere Informationen finden Sie unter Razor SDK-Eigenschaften.

ProduceReferenceAssemblyInOutDir

In .NET 5 und früheren Versionen werden Verweisassemblys immer in das Verzeichnis OutDir geschrieben. In .NET 6 und höheren Versionen können Sie die ProduceReferenceAssemblyInOutDir-Eigenschaft verwenden, um zu steuern, ob Verweisassemblys in das Verzeichnis OutDir geschrieben werden. Der Standardwert ist false, und Verweisassemblys werden nur in das Verzeichnis IntermediateOutputPath geschrieben. Legen Sie den Wert auf true fest, um Verweisassemblys in das Verzeichnis OutDir zu schreiben.

<PropertyGroup>
  <ProduceReferenceAssemblyInOutDir>true</ProduceReferenceAssemblyInOutDir>
</PropertyGroup>

Weitere Informationen finden Sie unter Schreiben von Verweisassemblys in die Zwischenausgabe.

PublishDocumentationFile

Wenn diese Eigenschaft true ist, wird die XML-Dokumentationsdatei für das Projekt, falls eine generiert wird, in die Veröffentlichungsausgabe für das Projekt aufgenommen. Der Standardwert dieser Eigenschaft ist true.

Tipp

Legen Sie GenerateDocumentationFile auf true fest, um zur Kompilierzeit eine XML-Dokumentationsdatei zu generieren.

PublishDocumentationFiles

Diese Eigenschaft ist ein Aktivierungsflag für mehrere andere Eigenschaften, die steuern, ob verschiedene Arten von XML-Dokumentationsdateien standardmäßig in das Veröffentlichungsverzeichnis kopiert werden, nämlich PublishDocumentationFile und PublishReferencesDocumentationFiles. Wenn diese Eigenschaften nicht festgelegt sind, und diese Eigenschaft aber festgelegt ist, werden diese Eigenschaften standardmäßig auf true festgelegt. Der Standardwert dieser Eigenschaft ist true.

PublishReferencesDocumentationFiles

Wenn diese Eigenschaft true ist, werden XML-Dokumentationsdateien für die Verweise des Projekts in das Veröffentlichungsverzeichnis kopiert, anstatt nur Laufzeitressourcen wie DLL-Dateien. Der Standardwert dieser Eigenschaft ist true.

PublishRelease

Die PublishRelease-Eigenschaft weist dotnet publish an, die Release-Konfiguration standardmäßig anstelle der Debug-Konfiguration zu verwenden. Diese Eigenschaft wurde in .NET 7 eingeführt.

<PropertyGroup>
  <PublishRelease>true</PublishRelease>
</PropertyGroup>

Hinweis

  • Ab dem .NET 8 SDK wird PublishRelease standardmäßig für Projekte mit .NET 8 oder höher als Ziel auf true festgelegt. Weitere Informationen finden Sie unter „dotnet publish“ verwendet die Releasekonfiguration.
  • Diese Eigenschaft wirkt sich nicht auf das Verhalten von aus dotnet build /t:Publish und ändert die Konfiguration nur, wenn die Veröffentlichung über die .NET CLI erfolgt.
  • Nur .NET 7 SDK: Um PublishRelease in einem Projekt zu verwenden, das Teil einer Visual Studio-Projektmappe ist, müssen Sie die Umgebungsvariable DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS auf true (oder einen anderen Wert) festlegen. Beim Veröffentlichen einer Projektmappe mit dieser Variablen aktiviert hat der PublishRelease-Wert des ausführbaren Projekts Vorrang und leitet die neue Standardkonfiguration an alle anderen Projekte in der Projektmappe durch. Wenn eine Projektmappe mehrere ausführbare Projekte oder Projekte auf oberster Ebene mit von PublishRelease abweichenden Werten enthält, wird die Projektmappe nicht erfolgreich veröffentlicht. Bei Projektmappen mit vielen Projekten erhöht die Verwendung dieser Einstellung den erforderlichen Zeitaufwand für das Veröffentlichen.

PublishSelfContained

Die Eigenschaft PublishSelfContained informiert dotnet publish, eine App als eigenständige App zu veröffentlichen. Diese Eigenschaft ist nützlich, wenn Sie das Argument --self-contained für den Befehl dotnet publish nicht verwenden können, z. B. wenn Sie auf Lösungsebene veröffentlichen. In diesem Fall können Sie die MSBuild-Eigenschaft PublishSelfContained zu einer Projekt- oder Directory.Build.Props-Datei hinzufügen.

Diese Eigenschaft wurde in .NET 7 eingeführt. Dies ähnelt der Eigenschaft SelfContained, mit der Ausnahme, dass sie für das Verb publish spezifisch ist. Es wird empfohlen, PublishSelfContained anstelle von SelfContained zu verwenden.

<PropertyGroup>
  <PublishSelfContained>true</PublishSelfContained>
</PropertyGroup>

RollForward

Die Eigenschaft RollForward steuert, wie die Anwendung eine Runtime auswählt, wenn mehrere Runtimeversionen verfügbar sind. Dieser Wert wird als rollForward-Einstellung an .runtimeconfig.json ausgegeben.

<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

Legen Sie RollForward auf einen der folgenden Werte fest:

Wert Beschreibung
Minor Standard, wenn nicht angegeben.
Rollforward zur niedrigsten höheren Nebenversion, wenn die angeforderte Nebenversion nicht vorhanden ist. Ist die angeforderte Nebenversion vorhanden, wird die Richtlinie LatestPatch verwendet.
Major Rollforward zur nächsten verfügbaren höheren Hauptversion und zur niedrigsten Nebenversion, wenn die angeforderte Hauptversion nicht vorhanden ist. Ist die angeforderte Hauptversion vorhanden, wird die Richtlinie Minor verwendet.
LatestPatch Rollforward zur höchsten Patchversion. Mit diesem Wert wird ein Rollforward zur Nebenversion deaktiviert.
LatestMinor Rollforward zur höchsten Nebenversion – auch dann, wenn die angeforderte Nebenversion vorhanden ist.
LatestMajor Rollforward zur höchsten Hauptversion und höchsten Nebenversion – auch dann, wenn die angeforderte Hauptversion vorhanden ist.
Disable Es erfolgt kein Rollforward, sondern nur eine Bindung an die angegebene Version. Diese Richtlinie wird nicht zur allgemeinen Verwendung empfohlen, da sie die Möglichkeit eines Rollforwards zu den neuesten Patches deaktiviert. Dieser Wert wird nur zu Testzwecken empfohlen.

Weitere Informationen finden Sie unter Steuern des Rollforwardverhaltens.

RuntimeFrameworkVersion

Die Eigenschaft RuntimeFrameworkVersion gibt die Version der Runtime an, die beim Veröffentlichen verwendet werden soll. Geben Sie eine Runtimeversion an:

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

Beim Veröffentlichen einer frameworkabhängigen Anwendung gibt dieser Wert die mindestens erforderliche Version an. Beim Veröffentlichen einer eigenständigen Anwendung gibt dieser Wert die genaue erforderliche Version an.

RuntimeIdentifier

Mit der Eigenschaft RuntimeIdentifier können Sie eine einzelne Runtime-ID (RID) für das Projekt angeben. RIDs ermöglichen das Veröffentlichen einer eigenständigen Bereitstellung.

<PropertyGroup>
  <RuntimeIdentifier>linux-x64</RuntimeIdentifier>
</PropertyGroup>

RuntimeIdentifiers

Mit der Eigenschaft RuntimeIdentifiers können Sie eine durch Semikolons getrennte Liste von Runtime-IDs (RIDs) für das Projekt angeben. Verwenden Sie diese Eigenschaft, wenn die Veröffentlichung für mehrere Runtimes erfolgen muss. RuntimeIdentifiers wird zur Wiederherstellungszeit verwendet, um sicherzustellen, dass sich die richtigen Assets im Graph befinden.

Tipp

RuntimeIdentifier (Singular) kann schnellere Builds bereitstellen, wenn nur eine einzige Runtime erforderlich ist.

<PropertyGroup>
  <RuntimeIdentifiers>win-x64;osx-x64;linux-x64</RuntimeIdentifiers>
</PropertyGroup>

SatelliteResourceLanguages

Mit der SatelliteResourceLanguages-Eigenschaft können Sie angeben, für welche Sprachen die Satellitenressourcenassemblys während der Erstellung und Veröffentlichung beibehalten werden sollen. Viele NuGet-Pakete enthalten lokalisierte Satellitenressourcenassemblys im Hauptpaket. Bei Projekten, die auf diese NuGet-Pakete verweisen, die keine lokalisierten Ressourcen erfordern, können die lokalisierten Assemblys die Build- und Veröffentlichungsausgabe unnötig vergrößern. Durch Hinzufügen der SatelliteResourceLanguages-Eigenschaft zu Ihrer Projektdatei werden nur lokalisierte Assemblys für die von Ihnen angegebenen Sprachen in die Build- und Veröffentlichungsausgabe aufgenommen. In der folgenden Projektdatei bleiben beispielsweise nur die Ressourcensatellitenassemblys für Englisch (USA) und Deutsch (Deutschland) erhalten.

<PropertyGroup>
  <SatelliteResourceLanguages>en-US;de-DE</SatelliteResourceLanguages>
</PropertyGroup>

Hinweis

  • Sie müssen diese Eigenschaft in dem Projekt angeben, das auf das NuGet-Paket mit lokalisierten Satellitenressourcenassemblys verweist.

  • Um mehrere Sprachen als Argument von dotnet publish anzugeben, müssen Sie die Sprachbezeichner in drei Anführungszeichenpaare einschließen. Beispiel:

    dotnet msbuild multi.msbuildproj -p:SatelliteResourceLanguages="""de;en"""

SelfContained

Die Eigenschaft SelfContained informiert dotnet build und dotnet publish eine App als eigenständige App zu erstellen oder zu veröffentlichen. Diese Eigenschaft ist nützlich, wenn Sie das Argument --self-contained nicht mit dem Befehl dotnet verwenden können, z. B. wenn Sie auf Lösungsebene veröffentlichen. In diesem Fall können Sie die MSBuild-Eigenschaft SelfContained zu einer Projekt- oder Directory.Build.Props-Datei hinzufügen.

Diese Eigenschaft ähnelt der PublishSelfContained-Eigenschaft. Es wird empfohlen, wenn möglich PublishSelfContained anstelle von SelfContained zu verwenden.

<PropertyGroup>
  <SelfContained>true</SelfContained>
</PropertyGroup>

UseAppHost

Die UseAppHost-Eigenschaft steuert, ob eine native ausführbare Datei für eine Bereitstellung erstellt wird. Eine native ausführbare Datei ist für eigenständige Bereitstellungen erforderlich. Standardmäßig wird eine frameworkabhängige ausführbare Datei erstellt. Legen Sie die Eigenschaft UseAppHost auf false fest, um die Erzeugung der ausführbaren Datei zu deaktivieren.

<PropertyGroup>
  <UseAppHost>false</UseAppHost>
</PropertyGroup>

Weitere Informationen zur Bereitstellung finden Sie unter .NET-Anwendungsbereitstellung.

Zahlreiche MSBuild-Eigenschaften stehen zur Optimierung des Kürzens zur Verfügung, wobei es sich um ein Feature handelt, mit dem nicht verwendeter Code aus eigenständigen Bereitstellungen gekürzt wird. Diese Optionen werden detailliert unter Kürzungsoptionen erläutert. Die folgende Tabelle enthält eine Kurzübersicht.

Eigenschaft Werte BESCHREIBUNG
PublishTrimmed true oder false Steuert, ob das Kürzen während der Veröffentlichung aktiviert ist.
TrimMode full oder partial Der Standardwert ist full. Steuert die Granularität der Kürzung.
SuppressTrimAnalysisWarnings true oder false Steuert, ob Kürzungsanalysewarnungen erzeugt werden.
EnableTrimAnalyzer true oder false Steuert, ob eine Untermenge von Kürzungsanalysewarnungen erzeugt wird. Sie können die Analyse selbst dann aktivieren, wenn PublishTrimmed auf false festgelegt ist.
ILLinkTreatWarningsAsErrors true oder false Steuert, ob Kürzungswarnungen als Fehler behandelt werden. Beispielsweise können Sie diese Eigenschaft auf false festlegen, wenn TreatWarningsAsErrors auf true festgelegt ist.
TrimmerSingleWarn true oder false Steuert, ob eine einzelne Warnung pro Assembly oder alle Warnungen angezeigt werden.
TrimmerRemoveSymbols true oder false Steuert, ob alle Symbole aus einer gekürzten Anwendung entfernt werden.

Die folgenden MSBuild-Eigenschaften sind in diesem Abschnitt dokumentiert:

C#-Compileroptionen wie zum Beispiel LangVersion und Nullable können auch als MSBuild-Eigenschaften in Ihrer Projektdatei angegeben werden. Weitere Informationen finden Sie unter C#-Compileroptionen.

ContinuousIntegrationBuild

Die ContinuousIntegrationBuild-Eigenschaft zeigt an, ob ein Build auf einem CI-Server (Continuous Integration) ausgeführt wird. Wenn diese Eigenschaft auf truec festgelegt ist, aktiviert sie Einstellungen, die nur für offizielle Builds gelten, nicht für lokale Builds auf einem Entwicklercomputer. Gespeicherte Dateipfade werden beispielsweise für offizielle Builds normalisiert. Auf einem lokalen Entwicklungscomputer kann der Debugger jedoch keine lokalen Quelldateien finden, wenn Dateipfade normalisiert werden.

Hinweis

Das Festlegen dieser Eigenschaft auf true funktioniert derzeit nur, wenn Sie einen bestimmten SourceLink-Anbieterpaketverweis oder ein <SourceRoot Include="$(MyDirectory)" />-Element hinzufügen. Weitere Informationen finden Sie unter dotnet/roslyn Issue 55860.

Sie können die Variable Ihres CI-Systems verwenden, um die ContinuousIntegrationBuild-Eigenschaft bedingt festzulegen. Der Variablenname für Azure Pipelines lautet beispielsweise TF_BUILD:

<PropertyGroup Condition="'$(TF_BUILD)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

Für GitHub Actions lautet der Variablenname GITHUB_ACTIONS:

<PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

CopyDebugSymbolFilesFromPackages

Wenn diese Eigenschaft auf true festgelegt ist, werden alle Symboldateien (auch als PDB-Dateien bezeichnet) aus PackageReference-Elementen im Projekt in die Buildausgabe kopiert. Diese Dateien können informativere Stapelablaufverfolgungen für Ausnahmen bereitstellen und das Verständnis von Speicherabbildern und Ablaufverfolgungen der ausgeführten Anwendung erleichtern. Die Aufnahme dieser Dateien führt jedoch zu einer Vergrößerung des Bereitstellungspakets.

Diese Eigenschaft wurde in .NET SDK 7.0.100 eingeführt, ist jedoch standardmäßig nicht angegeben.

CopyDocumentationFilesFromPackages

Wenn diese Eigenschaft auf true festgelegt ist, werden alle generierten XML-Dokumentationsdateien aus PackageReference-Elementen im Projekt in die Buildausgabe kopiert. Beachten Sie, dass die Aktivierung dieses Features zu einer Vergrößerung des Bereitstellungspakets führt.

Diese Eigenschaft wurde in .NET SDK 7.0.100 eingeführt, ist jedoch standardmäßig nicht angegeben.

DisableImplicitFrameworkDefines

Die DisableImplicitFrameworkDefines-Eigenschaft steuert, ob das SDK Präprozessorsymbole für Zielframework und -plattform für das .NET-Projekt generiert oder nicht. Wenn diese Eigenschaft auf false festgelegt oder nicht festgelegt ist (der Standardwert), werden Präprozessorsymbole für Folgendes generiert:

  • Framework ohne Version (NETFRAMEWORK, NETSTANDARD, NET)
  • Framework mit Version (NET48, NETSTANDARD2_0, NET6_0)
  • Framework mit Mindestversionsgrenze (NET48_OR_GREATER, NETSTANDARD2_0_OR_GREATER, NET6_0_OR_GREATER)

Weitere Informationen zu Zielframeworkmonikern und diesen impliziten Präprozessorsymbolen finden Sie unter Zielframeworks.

Wenn Sie außerdem ein betriebssystemspezifisches Zielframework im Projekt angeben (z. B. net6.0-android), werden die folgenden Präprozessorsymbole generiert:

  • Plattform ohne Version (ANDROID, IOS, WINDOWS)
  • Plattform mit Version (IOS15_1)
  • Plattform mit Mindestversionsgrenze (IOS15_1_OR_GREATER)

Weitere Informationen zu betriebssystemspezifischen Zielframeworkmonikern finden Sie unter Betriebssystemspezifische TFMs.

Schließlich, wenn Ihr Zielframework Unterstützung für ältere Zielframeworks impliziert, werden Präprozessorsymbole für diese älteren Frameworks ausgegeben. Beispielsweise impliziertnet6.0 Unterstützung für net5.0 usw., bis ganz zurück zu .netcoreapp1.0. Daher wird für jedes dieser Zielframeworks das Symbol Framework mit Mindestversionsgrenze definiert.

DocumentationFile

Mit der DocumentationFile-Eigenschaft können Sie einen Dateinamen für die XML-Datei angeben, die die Dokumentation für Ihre Bibliothek enthält. Damit IntelliSense ordnungsgemäß mit Ihrer Dokumentation funktioniert, muss der Dateiname mit dem Assemblynamen identisch sein und sich im gleichen Verzeichnis wie die Assembly befinden. Wenn Sie diese Eigenschaft nicht angeben, aber GenerateDocumentationFile auf true festlegen, wird der Name der Dokumentationsdatei standardmäßig auf den Namen Ihrer Assembly festgelegt, jedoch mit der Dateierweiterung .xml. Aus diesem Grund ist es oft einfacher, diese Eigenschaft auszulassen und stattdessen die GenerateDocumentationFile-Eigenschaft zu verwenden.

Wenn Sie diese Eigenschaft angeben, aber GenerateDocumentationFile auf false festlegen, generiert der Compiler keine Dokumentationsdatei. Wenn Sie diese Eigenschaft angeben und die GenerateDocumentationFile-Eigenschaft auslassen, generiert der Compiler eine Dokumentationsdatei.

<PropertyGroup>
  <DocumentationFile>path/to/file.xml</DocumentationFile>
</PropertyGroup>

EmbeddedResourceUseDependentUponConvention

Die EmbeddedResourceUseDependentUponConvention-Eigenschaft definiert, ob Namen für Ressourcenmanifestdateien aus Typinformationen in Quelldateien generiert werden, die sich im selben Ordner wie die Ressourcendateien befinden. Wenn sich beispielsweise Form1.resx im selben Ordner wie Form1.cs befindet und EmbeddedResourceUseDependentUponConvention auf true festgelegt ist, nimmt die generierte .resources-Datei den Namen des ersten Typs an, der in Form1.cs definiert ist. Wenn MyNamespace.Form1 der erste in Form1.cs definierte Typ ist, lautet der generierte Dateiname MyNamespace.Form1.resources.

Hinweis

Wenn LogicalName-, ManifestResourceName- oder DependentUpon-Metadaten für ein EmbeddedResource-Element angegeben werden, basiert der generierte Manifestdateiname für diese Ressourcendatei stattdessen auf diesen Metadaten.

In einem neuen .NET-Projekt, das auf .NET Core 3.0 oder eine höhere Version abzielt, ist diese Eigenschaft standardmäßig auf truefestgelegt. Wenn bei Festlegung auf false keine LogicalName-, ManifestResourceName- oder DependentUpon-Metadaten für das EmbeddedResource-Element in der Projektdatei angegeben werden, basiert der Ressourcenmanifest-Dateiname auf dem Stammnamespace für das Projekt und dem relativen Dateipfad zur .resx-Datei. Weitere Informationen finden Sie unter Benennung von Ressourcenmanifestdateien.

<PropertyGroup>
  <EmbeddedResourceUseDependentUponConvention>true</EmbeddedResourceUseDependentUponConvention>
</PropertyGroup>

EnablePreviewFeatures

Die EnablePreviewFeatures-Eigenschaft definiert, ob Ihr Projekt von APIs oder Assemblys abhängig ist, die das Attribut RequiresPreviewFeaturesAttribute aufweisen. Mit diesem Attribut wird angegeben, dass eine API oder Assembly Features verwendet, die für die verwendete SDK-Version als in der Vorschau befindlich betrachtet werden. Vorschaufeatures werden nicht unterstützt und können in einer zukünftigen Version entfernt werden. Um die Verwendung von Vorschaufeatures zu aktivieren, legen Sie die Eigenschaft auf True fest.

<PropertyGroup>
  <EnablePreviewFeatures>True</EnablePreviewFeatures>
</PropertyGroup>

Wenn diese Eigenschaft in einem Projekt auf True festgelegt ist, wird der Datei AssemblyInfo.cs das folgende Attribut auf Assemblyebene hinzugefügt:

[assembly: RequiresPreviewFeatures]

Ein Analysetool gibt eine Warnung aus, wenn dieses Attribut in Abhängigkeiten für Projekte vorhanden ist, bei denen EnablePreviewFeatures nicht auf True festgelegt ist.

Bibliotheksautoren, die Vorschauassemblys ausliefern möchten, sollten diese Eigenschaft auf True festlegen. Wenn Sie eine Assembly sowohl mit Vorschau- als auch mit Nicht-Vorschau-APIs ausliefern müssen, lesen Sie den Abschnitt GenerateRequiresPreviewFeaturesAttribute weiter unten.

EnableWindowsTargeting

Legen Sie die EnableWindowsTargeting-Eigenschaft auf true fest, um Windows-Apps (z. B. Windows Forms- oder Windows Presentation Foundation-Apps) auf einer Nicht-Windows-Plattform zu erstellen. Wenn Sie diese Eigenschaft nicht auf true festlegen, erhalten Sie die Buildwarnung NETSDK1100. Dieser Fehler tritt auf, weil Zielversions- und Runtimepakete nicht automatisch auf Plattformen heruntergeladen werden, die nicht unterstützt werden. Wenn Sie diese Eigenschaft festlegen, werden diese Pakete bei Crosstargeting (abweichende Zielversion) heruntergeladen.

Hinweis

Diese Eigenschaft wird derzeit empfohlen, um die Entwicklung auf Nicht-Windows-Plattformen zu ermöglichen. Aber wenn die Anwendung zur Veröffentlichung bereit ist, sollte sie unter Windows erstellt werden. Wenn Sie auf einer Nicht-Windows-Plattform erstellen, ist die Ausgabe möglicherweise nicht dieselbe wie unter Windows. Insbesondere ist die ausführbare Datei nicht als Windows-Anwendung gekennzeichnet (was bedeutet, dass sie immer ein Konsolenfenster startet) und kein Symbol eingebettet.

<PropertyGroup>
  <EnableWindowsTargeting>true</EnableWindowsTargeting>
</PropertyGroup>

GenerateDocumentationFile

Die GenerateDocumentationFile-Eigenschaft steuert, ob der Compiler eine XML-Dokumentationsdatei für Ihre Bibliothek generiert. Wenn Sie diese Eigenschaft auf true festlegen und keinen Dateinamen über die Eigenschaft DocumentationFile angeben, wird die generierte XML-Datei im gleichen Ausgabeverzeichnis wie Ihre Assembly platziert und weist den gleichen Dateinamen auf (jedoch mit einer Erweiterung .xml).

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Weitere Informationen zum Generieren von Dokumentation aus Codekommentaren finden Sie unter XML-Dokumentationskommentare (C#), Dokumentieren von Code mit XML (Visual Basic) und Dokumentieren von Code mit XML (F#).

GenerateRequiresPreviewFeaturesAttribute

Die GenerateRequiresPreviewFeaturesAttribute-Eigenschaft ist eng mit der EnablePreviewFeatures-Eigenschaft verknüpft. Wenn Ihre Bibliothek Vorschaufeatures verwendet, Sie aber nicht möchten, dass die gesamte Assembly mit dem Attribut RequiresPreviewFeaturesAttribute gekennzeichnet wird – was erfordert, dass alle Consumer Vorschaufeatures aktivieren –, legen Sie diese Eigenschaft auf False fest.

<PropertyGroup>
    <EnablePreviewFeatures>True</EnablePreviewFeatures>
    <GenerateRequiresPreviewFeaturesAttribute>False</GenerateRequiresPreviewFeaturesAttribute>
</PropertyGroup>

Wichtig

Wenn Sie die GenerateRequiresPreviewFeaturesAttribute-Eigenschaft auf False festlegen, müssen Sie sicherstellen, dass alle öffentlichen APIs, die Vorschaufeatures nutzen, RequiresPreviewFeaturesAttribute aufweisen.

OptimizeImplicitlyTriggeredBuild

Zur Beschleunigung des Buildvorgangs überspringen Builds, die implizit von Visual Studio ausgelöst werden, die Codeanalyse, einschließlich der Analyse von Eigenschaften, die Nullwerte zulassen. Visual Studio löst z. B. beim Ausführen von Tests einen impliziten Build aus. Implizite Builds werden jedoch nur optimiert, wenn TreatWarningsAsErrors nicht true ist. Wenn Sie TreatWarningsAsErrors auf true festgelegt haben, aber dennoch implizit ausgelöste Builds optimieren möchten, können Sie OptimizeImplicitlyTriggeredBuild auf True festlegen. Um die Buildoptimierung für implizit ausgelöste Builds zu deaktivieren, legen Sie OptimizeImplicitlyTriggeredBuild auf False fest.

<PropertyGroup>
    <OptimizeImplicitlyTriggeredBuild>True</OptimizeImplicitlyTriggeredBuild>
</PropertyGroup>

DisableRuntimeMarshalling

Mit der DisableRuntimeMarshalling-Eigenschaft können Sie angeben, dass Sie die Marshallingunterstützung der Runtime für Ihr Projekt deaktivieren möchten. Wenn diese Eigenschaft auf true festgelegt ist, wird der Assembly das DisableRuntimeMarshallingAttribute hinzugefügt, und alle auf P/Invokes oder Delegate basierenden Interops folgen den Regeln für deaktiviertes Runtimemarshalling.

<PropertyGroup>
    <DisableRuntimeMarshalling>True</DisableRuntimeMarshalling>
</PropertyGroup>

Standardeigenschaften für den Elementeinschluss

Die folgenden MSBuild-Eigenschaften sind in diesem Abschnitt dokumentiert:

Weitere Informationen finden Sie unter dem Abschnitt zu standardmäßigen Include- und Excludedateien.

DefaultItemExcludes

Verwenden Sie die DefaultItemExcludes-Eigenschaft, um Globmuster für Dateien und Ordner zu definieren, die aus der Include- und Excludedatei sowie Remove-Globs ausgeschlossen werden sollen. Standardmäßig werden die Ordner ./bin und ./obj aus den Globmustern ausgeschlossen.

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);**/*.myextension</DefaultItemExcludes>
</PropertyGroup>

DefaultItemExcludesInProjectFolder

Verwenden Sie die DefaultItemExcludesInProjectFolder-Eigenschaft, um Globmuster für Dateien und Ordner im Projektordner zu definieren, die aus der Include- und Excludedatei sowie Remove-Globs ausgeschlossen werden sollen. Standardmäßig werden Ordner, die mit einem Punkt (.) beginnen, z. B. .git und .vs, aus den Globmustern ausgeschlossen.

Diese Eigenschaft ähnelt der DefaultItemExcludes-Eigenschaft, mit der Ausnahme, dass sie nur Dateien und Ordner im Projektordner berücksichtigt. Wenn ein Globmuster versehentlich mit Elementen außerhalb des Projektordners mit einem relativen Pfad übereinstimmen würde, verwenden Sie die DefaultItemExcludesInProjectFolder-Eigenschaft anstelle der DefaultItemExcludes-Eigenschaft.

<PropertyGroup>
  <DefaultItemExcludesInProjectFolder>$(DefaultItemExcludesInProjectFolder);**/myprefix*/**</DefaultItemExcludesInProjectFolder>
</PropertyGroup>

EnableDefaultItems

Die EnableDefaultItems-Eigenschaft steuert, ob Kompilierungselemente, eingebettete Ressourcenelemente und None-Elemente implizit in das Projekt eingeschlossen werden. Der Standardwert ist true. Um jedes implizite Einbeziehen von Dateien zu deaktivieren, legen Sie die EnableDefaultItems-Eigenschaft auf false fest.

<PropertyGroup>
  <EnableDefaultItems>false</EnableDefaultItems>
</PropertyGroup>

EnableDefaultCompileItems

Die EnableDefaultCompileItems-Eigenschaft steuert, ob Kompilierungselemente implizit in das Projekt eingeschlossen werden. Der Standardwert ist true. Legen Sie die EnableDefaultCompileItems-Eigenschaft auf false fest, um die implizite Einbindung von *.cs-Dateien und anderen Spracherweiterungsdateien zu deaktivieren.

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

EnableDefaultEmbeddedResourceItems

Die EnableDefaultEmbeddedResourceItems-Eigenschaft steuert, ob eingebettete Ressourcenelemente implizit in das Projekt eingeschlossen werden. Der Standardwert ist true. Legen Sie die EnableDefaultEmbeddedResourceItems-Eigenschaft auf false fest, um die implizite Einbindung eingebetteter Ressourcendateien zu deaktivieren.

<PropertyGroup>
  <EnableDefaultEmbeddedResourceItems>false</EnableDefaultEmbeddedResourceItems>
</PropertyGroup>

EnableDefaultNoneItems

Die EnableDefaultNoneItems-Eigenschaft steuert, ob None-Elemente (Dateien, die keine Rolle im Buildprozess aufweisen) implizit in das Projekt eingeschlossen werden. Der Standardwert ist true. Legen Sie die EnableDefaultNoneItems-Eigenschaft auf false fest, um die implizite Einbindung von None-Elementen zu deaktivieren.

<PropertyGroup>
  <EnableDefaultNoneItems>false</EnableDefaultNoneItems>
</PropertyGroup>

Codeanalyseeigenschaften

Die folgenden MSBuild-Eigenschaften sind in diesem Abschnitt dokumentiert:

AnalysisLevel-Eigenschaft

Mit der AnalysisLevel-Eigenschaft können Sie einen Satz von Codeanalysetools angeben, die gemäß einer .NET-Version ausgeführt werden. Jedes .NET-Release ab .NET 5 verfügt über eine Reihe von Codeanalyseregeln. Mit diesem Satz analysieren die Regeln, die für die betreffende Version standardmäßig aktiviert sind, Ihren Code. Wenn Sie beispielsweise ein Upgrade auf .NET 8 durchführen, aber nicht möchten, dass der Standardsatz von Codeanalyseregeln geändert wird, legen Sie AnalysisLevel auf 7 fest.

<PropertyGroup>
  <AnalysisLevel>preview</AnalysisLevel>
</PropertyGroup>

Optional können Sie ab .NET 6 einen Verbundwert für diese Eigenschaft angeben, der auch angibt, wie aggressiv Regeln aktiviert werden. Verbundwerte haben die Form <version>-<mode>, wobei der <mode>-Wert einer der AnalysisMode-Werte ist. Im folgenden Beispiel wird die Vorschauversion von Codeanalysetools verwendet und der empfohlene Regelsatz aktiviert.

<PropertyGroup>
  <AnalysisLevel>preview-recommended</AnalysisLevel>
</PropertyGroup>

Standardwert:

  • Wenn Ihr Projekt für .NET 5 oder höher bestimmt ist, oder Sie die AnalysisMode-Eigenschaft hinzugefügt haben, ist der Standardwert latest.
  • Andernfalls wird diese Eigenschaft ausgelassen, es sei denn, Sie fügen sie der Projektdatei explizit hinzu.

In der folgenden Tabelle werden die Werte aufgeführt, die Sie angeben können.

Wert Bedeutung
latest Die neuesten Codeanalysen, die veröffentlicht wurden, werden verwendet. Dies ist die Standardoption.
latest-<mode> Die neuesten Codeanalysen, die veröffentlicht wurden, werden verwendet. Der <mode>-Wert bestimmt, welche Regeln aktiviert sind.
preview Die neuesten Codeanalysetools werden verwendet, auch wenn sie sich in der Vorschau befinden.
preview-<mode> Die neuesten Codeanalysetools werden verwendet, auch wenn sie sich in der Vorschau befinden. Der <mode>-Wert bestimmt, welche Regeln aktiviert sind.
8.0 Der Satz von Regeln, der für das .NET 8-Release verfügbar war, wird verwendet, auch wenn neuere Regeln verfügbar sind.
8.0-<mode> Der Satz von Regeln, der für das .NET 8-Release verfügbar war, wird verwendet, auch wenn neuere Regeln verfügbar sind. Der <mode>-Wert bestimmt, welche Regeln aktiviert sind.
8 Der Satz von Regeln, der für das .NET 8-Release verfügbar war, wird verwendet, auch wenn neuere Regeln verfügbar sind.
8-<mode> Der Satz von Regeln, der für das .NET 8-Release verfügbar war, wird verwendet, auch wenn neuere Regeln verfügbar sind. Der <mode>-Wert bestimmt, welche Regeln aktiviert sind.
7.0 Der Satz von Regeln, der für das .NET 7-Release verfügbar war, wird verwendet, auch wenn neuere Regeln verfügbar sind.
7.0-<mode> Der Satz von Regeln, der für das .NET 7-Release verfügbar war, wird verwendet, auch wenn neuere Regeln verfügbar sind. Der <mode>-Wert bestimmt, welche Regeln aktiviert sind.
7 Der Satz von Regeln, der für das .NET 7-Release verfügbar war, wird verwendet, auch wenn neuere Regeln verfügbar sind.
7-<mode> Der Satz von Regeln, der für das .NET 7-Release verfügbar war, wird verwendet, auch wenn neuere Regeln verfügbar sind. Der <mode>-Wert bestimmt, welche Regeln aktiviert sind.
6.0 Die Regeln, die für das .NET 6-Release verfügbar waren, werden verwendet, auch wenn neuere Regeln verfügbar sind.
6.0-<mode> Die Regeln, die für das .NET 6-Release verfügbar waren, werden verwendet, auch wenn neuere Regeln verfügbar sind. Der <mode>-Wert bestimmt, welche Regeln aktiviert sind.
6 Die Regeln, die für das .NET 6-Release verfügbar waren, werden verwendet, auch wenn neuere Regeln verfügbar sind.
6-<mode> Die Regeln, die für das .NET 6-Release verfügbar waren, werden verwendet, auch wenn neuere Regeln verfügbar sind. Der <mode>-Wert bestimmt, welche Regeln aktiviert sind.
5.0 Die Regeln, die für das .NET 5-Release verfügbar waren, werden verwendet, auch wenn neuere Regeln verfügbar sind.
5.0-<mode> Die Regeln, die für das .NET 5-Release verfügbar waren, werden verwendet, auch wenn neuere Regeln verfügbar sind. Der <mode>-Wert bestimmt, welche Regeln aktiviert sind.
5 Die Regeln, die für das .NET 5-Release verfügbar waren, werden verwendet, auch wenn neuere Regeln verfügbar sind.
5-<mode> Die Regeln, die für das .NET 5-Release verfügbar waren, werden verwendet, auch wenn neuere Regeln verfügbar sind. Der <mode>-Wert bestimmt, welche Regeln aktiviert sind.

Hinweis

  • Ab .NET 6 wirkt sich diese Eigenschaft auf Codestilregeln (IDEXXXX) (zusätzlich zu Regeln für die Codequalität) aus, wenn Sie EnforceCodeStyleInBuild auf true festlegen.
  • Wenn Sie einen Verbundwert für AnalysisLevel festlegen, müssen Sie keinen AnalysisMode angeben. Wenn Sie jedoch einen Modus angeben, besitzt AnalysisLevel Vorrang vor AnalysisMode.
  • Diese Eigenschaft wirkt sich nicht auf die Codeanalyse in Projekten aus, die keinen Verweis auf ein Projekt-SDK beinhalten, z. B. alte .NET Framework-Projekte, die auf das NuGet-Paket „Microsoft.CodeAnalysis.NetAnalyzers“ verweisen.

AnalysisLevel<Kategorie>

Diese Eigenschaft ist mit AnalysisLevel identisch, gilt jedoch nur für eine bestimmte Kategorie von Codeanalyseregeln. Mit dieser Eigenschaft können Sie eine andere Version von Codeanalysetools für eine bestimmte Kategorie verwenden oder Regeln auf einer anderen Ebene als die anderen Regelkategorien aktivieren oder deaktivieren. Wenn Sie diese Eigenschaft für eine bestimmte Kategorie von Regeln auslassen, wird standardmäßig der AnalysisLevel-Wert verwendet. Die verfügbaren Werte sind mit denen für AnalysisLevel identisch.

<PropertyGroup>
  <AnalysisLevelSecurity>preview</AnalysisLevelSecurity>
</PropertyGroup>

<PropertyGroup>
  <AnalysisLevelSecurity>preview-recommended</AnalysisLevelSecurity>
</PropertyGroup>

In der folgenden Tabelle wird der Eigenschaftenname für jede Regelkategorie aufgeführt.

Name der Eigenschaft Regelkategorie
<AnalysisLevelDesign> Entwurfsregeln
<AnalysisLevelDocumentation> Dokumentationsregeln
<AnalysisLevelGlobalization> Globalisierungsregeln
<AnalysisLevelInteroperability> Portabilitäts- und Interoperabilitätsregeln
<AnalysisLevelMaintainability> Wartbarkeitsregeln
<AnalysisLevelNaming> Benennungsregeln
<AnalysisLevelPerformance> Leistungsregeln
<AnalysisLevelSingleFile> Einzeldateianwendungsregeln
<AnalysisLevelReliability> Zuverlässigkeitsregeln
<AnalysisLevelSecurity> Sicherheitsregeln
<AnalysisLevelStyle> Codeformatregeln (IDEXXXX)
<AnalysisLevelUsage> Nutzungsregeln

AnalysisMode

Alle Codequalitätsregeln für Zertifizierungsstellen sind im .NET SDK enthalten. Standardmäßig werden nur einige Regeln als Buildwarnungen in jeder .NET-Version aktiviert. Mit der AnalysisMode-Eigenschaft können Sie den Satz von Regeln anpassen, der standardmäßig aktiviert ist. Sie können entweder zu einem aggressiveren Analysemodus wechseln, bei dem Sie Regeln einzeln ausschließen können, oder zu einem konservativeren Analysemodus, bei dem Sie sich für bestimmte Regeln entscheiden können. Wenn Sie beispielsweise alle Regeln als Buildwarnungen aktivieren möchten, legen Sie den Wert auf All fest.

<PropertyGroup>
  <AnalysisMode>All</AnalysisMode>
</PropertyGroup>

Die folgende Tabelle zeigt die verfügbaren Optionswerte: Sie werden in aufsteigender Reihenfolge der Anzahl der Regeln, die sie aktivieren, aufgeführt.

Wert Beschreibung
None Alle Regeln sind deaktiviert. Sie können einzelne Regeln selektiv aktivieren.
Default Dies ist der Standardmodus, in dem bestimmte Regeln als Buildwarnungen bzw. Visual Studio-IDE-Vorschläge aktiviert sind und der Rest deaktiviert ist.
Minimum Aggressiverer Modus als der Modus Default. Bestimmte Vorschläge, die für die Builderzwingung dringend empfohlen werden, werden als Buildwarnungen aktiviert. Um festzustellen, welche Regeln darin enthalten sind, überprüfen Sie die Datei %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig.
Recommended Ein aggressiverer Modus als der Minimum-Modus, in dem mehr Regeln als Buildwarnungen aktiviert sind. Um festzustellen, welche Regeln darin enthalten sind, überprüfen Sie die Datei %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig.
All Alle Regeln sind als Buildwarnungen* aktiviert. Sie können einzelne Regeln deaktivieren.

* Die folgenden Regeln sind nicht durch Festlegen von AnalysisMode auf All oder durch Festlegen von AnalysisLevel auf latest-all aktiviert: CA1017, CA1045, CA1005, CA1014, CA1060, CA1021, und die Codemetrikenanalyseregeln (CA1501, CA1502, CA1505, CA1506, und CA1509). Diese Legacy-Regeln sind möglicherweise in einer zukünftigen Version veraltet. Sie können sie jedoch weiterhin einzeln mithilfe eines dotnet_diagnostic.CAxxxx.severity = <severity>-Eintrags aktivieren.

Hinweis

  • Ab .NET 6 wirkt sich diese Eigenschaft auf Codestilregeln (IDEXXXX) (zusätzlich zu Regeln für die Codequalität) aus, wenn Sie EnforceCodeStyleInBuild auf true festlegen.
  • Wenn Sie einen zusammengesetzten Wert für AnalysisLevel verwenden (z. B. <AnalysisLevel>8-recommended</AnalysisLevel>), können Sie diese Eigenschaft vollständig auslassen. Wenn Sie jedoch beide Eigenschaften angeben, besitzt AnalysisLevel Vorrang vor AnalysisMode.
  • Diese Eigenschaft wirkt sich nicht auf die Codeanalyse in Projekten aus, die keinen Verweis auf ein Projekt-SDK beinhalten, z. B. alte .NET Framework-Projekte, die auf das NuGet-Paket „Microsoft.CodeAnalysis.NetAnalyzers“ verweisen.

AnalysisMode<Kategorie>

Diese Eigenschaft ist mit AnalysisMode identisch, gilt jedoch nur für eine bestimmte Kategorie von Codeanalyseregeln. Mit dieser Eigenschaft können Sie Regeln auf einer anderen Ebene als die anderen Regelkategorien aktivieren oder deaktivieren. Wenn Sie diese Eigenschaft für eine bestimmte Kategorie von Regeln auslassen, wird standardmäßig der AnalysisMode-Wert verwendet. Die verfügbaren Werte sind mit denen für AnalysisMode identisch.

<PropertyGroup>
  <AnalysisModeSecurity>All</AnalysisModeSecurity>
</PropertyGroup>

In der folgenden Tabelle wird der Eigenschaftenname für jede Regelkategorie aufgeführt.

Name der Eigenschaft Regelkategorie
<AnalysisModeDesign> Entwurfsregeln
<AnalysisModeDocumentation> Dokumentationsregeln
<AnalysisModeGlobalization> Globalisierungsregeln
<AnalysisModeInteroperability> Portabilitäts- und Interoperabilitätsregeln
<AnalysisModeMaintainability> Wartbarkeitsregeln
<AnalysisModeNaming> Benennungsregeln
<AnalysisModePerformance> Leistungsregeln
<AnalysisModeSingleFile> Einzeldateianwendungsregeln
<AnalysisModeReliability> Zuverlässigkeitsregeln
<AnalysisModeSecurity> Sicherheitsregeln
<AnalysisModeStyle> Codeformatregeln (IDEXXXX)
<AnalysisModeUsage> Nutzungsregeln

CodeAnalysisTreatWarningsAsErrors-Eigenschaft

Mit der CodeAnalysisTreatWarningsAsErrors-Eigenschaft können Sie konfigurieren, ob Warnungen im Rahmen der Codequalitätsanalyse (CAxxxx) als Warnungen behandelt werden und den Build unterbrechen sollen. Wenn Sie beim Erstellen von Projekten das -warnaserror-Flag verwenden, werden Warnungen im Rahmen der .NET-Codequalitätsanalyse ebenfalls als Fehler behandelt. Wenn Warnungen bei der Codequalitätsanalyse nicht als Fehler behandelt werden sollen, können Sie die MSBuild-Eigenschaft CodeAnalysisTreatWarningsAsErrors in Ihrer Projektdatei auf false festlegen.

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

EnableNETAnalyzers-Eigenschaft

Die .NET-Codequalitätsanalyse ist für Projekte, die auf .NET 5 oder höher ausgerichtet sind, standardmäßig aktiviert. Wenn Sie zum Entwickeln das SDK von .NET 5 oder höher verwenden, können Sie die .NET-Codeanalyse für SDK-ähnliche Projekte aktivieren, die frühere Versionen von .NET als Ziel verwenden, indem Sie die Eigenschaft EnableNETAnalyzers auf true festlegen. Legen Sie diese Eigenschaft auf false fest, um die Codeanalyse in einem beliebigen Projekt zu deaktivieren.

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

Hinweis

Diese Eigenschaft gilt speziell für die integrierten Analysetools im .NET 5 SDK oder höher. Sie sollte nicht verwendet werden, wenn Sie ein NuGet-Codeanalysepaket installieren.

EnforceCodeStyleInBuild

Die .NET-Codeformatsanalyse ist beim Build für alle .NET-Projekte standardmäßig deaktiviert. Sie können die Codeformatsanalyse für .NET-Projekte aktivieren, indem Sie die EnforceCodeStyleInBuild-Eigenschaft auf true festlegen.

<PropertyGroup>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</PropertyGroup>

Alle Codeformatregeln, die als Warnungen oder Fehler konfiguriert sind, werden beim Build ausgeführt und melden Verstöße.

_SkipUpgradeNetAnalyzersNuGetWarning

Mit der _SkipUpgradeNetAnalyzersNuGetWarning-Eigenschaft können Sie konfigurieren, ob Sie eine Warnung erhalten, wenn Sie Codeanalysetools aus einem NuGet-Paket verwenden, das im Vergleich zu den Codeanalysetools im neuesten .NET SDK veraltet ist. Die Warnung sieht in etwa wie folgt aus:

Das .NET SDK verfügt über neuere Analysetools in Version „6.0.0“, als die Version „5.0.3“ des Pakets „Microsoft.CodeAnalysis.NetAnalyzers“ bereitstellt. Aktualisieren oder entfernen Sie diesen Paketverweis.

Um diese Warnung zu entfernen und weiterhin die Version der Codeanalysetools im NuGet-Paket zu verwenden, legen Sie in Ihrer Projektdatei _SkipUpgradeNetAnalyzersNuGetWarning auf true fest.

<PropertyGroup>
  <_SkipUpgradeNetAnalyzersNuGetWarning>true</_SkipUpgradeNetAnalyzersNuGetWarning>
</PropertyGroup>

Runtimekonfigurationseigenschaften

Sie können manche Verhaltensweisen der Runtime konfigurieren, indem Sie die MSBuild-Eigenschaften in der Projektdatei der App angeben. Informationen zu anderen Konfigurationsmöglichkeiten für das Runtimeverhalten finden Sie unter Konfigurationseinstellungen für die Runtime.

AutoreleasePoolSupport

Die AutoreleasePoolSupport-Eigenschaft konfiguriert, ob jeder verwaltete Thread bei Ausführung auf einer unterstützten macOS-Plattform einen impliziten NSAutoreleasePool empfängt. Weitere Informationen finden Sie unter AutoreleasePool für verwaltete Threads.

<PropertyGroup>
  <AutoreleasePoolSupport>true</AutoreleasePoolSupport>
</PropertyGroup>

ConcurrentGarbageCollection

Mit der ConcurrentGarbageCollection-Eigenschaft wird konfiguriert, ob die Garbage Collection im Hintergrund (parallele GC) aktiviert ist. Legen Sie den Wert auf false fest, um die Garbage Collection im Hintergrund zu deaktivieren. Weitere Informationen finden Sie unter Garbage Collection im Hintergrund.

<PropertyGroup>
  <ConcurrentGarbageCollection>false</ConcurrentGarbageCollection>
</PropertyGroup>

InvariantGlobalization

Mit der InvariantGlobalization-Eigenschaft wird konfiguriert, ob die App im globalisierungsinvarianten Modus ausgeführt wird, was bedeutet, dass sie keinen Zugriff auf kulturspezifische Daten hat. Legen Sie den Wert auf true fest, um die Ausführung im globalisierungsinvarianten Modus zu konfigurieren. Weitere Informationen finden Sie unter Invarianter Modus.

<PropertyGroup>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

PredefinedCulturesOnly

In .NET 6 und späteren Versionen konfiguriert die Eigenschaft PredefinedCulturesOnly, ob Apps andere Kulturen als die invariante Kultur erstellen können, wenn der globalisierungsinvariante Modus aktiviert ist. Der Standardwert lautet true. Legen Sie den Wert auf false fest, um die Erstellung neuer Kulturen im globalisierungsinvarianten Modus zu erlauben.

<PropertyGroup>
  <PredefinedCulturesOnly>false</PredefinedCulturesOnly>
</PropertyGroup>

Weitere Informationen finden Sie unter Kulturerstellung und Zuordnung von Groß-/Kleinbuchstaben im globalisierungsinvarianten Modus.

RetainVMGarbageCollection

Mit der RetainVMGarbageCollection-Eigenschaft wird der Garbage Collector so konfiguriert, dass gelöschte Speichersegmente in eine Standbyliste eingefügt werden, damit Sie diese zukünftig verwenden oder freigeben können. Wenn der Wert auf true festgelegt wird, wird der Garbage Collector angewiesen, die Segmente in eine Standbyliste einzufügen. Weitere Informationen finden Sie unter Beibehalten der VM.

<PropertyGroup>
  <RetainVMGarbageCollection>true</RetainVMGarbageCollection>
</PropertyGroup>

ServerGarbageCollection

Mit der ServerGarbageCollection-Eigenschaft wird konfiguriert, ob die Anwendung die Garbage Collection für Arbeitsstationen oder für Server verwendet. Legen Sie den Wert auf true fest, um die Garbage Collection für Server zu verwenden. Weitere Informationen finden Sie unter Workstation und Server im Vergleich.

<PropertyGroup>
  <ServerGarbageCollection>true</ServerGarbageCollection>
</PropertyGroup>

ThreadPoolMaxThreads

Mit der ThreadPoolMaxThreads-Eigenschaft wird die maximale Threadanzahl für den Arbeitsthreadpool konfiguriert. Weitere Informationen finden Sie unter Maximale Threadanzahl.

<PropertyGroup>
  <ThreadPoolMaxThreads>20</ThreadPoolMaxThreads>
</PropertyGroup>

ThreadPoolMinThreads

Mit der ThreadPoolMinThreads-Eigenschaft wird die minimale Threadanzahl für den Arbeitsthreadpool konfiguriert. Weitere Informationen finden Sie unter Minimale Threadanzahl.

<PropertyGroup>
  <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
</PropertyGroup>

TieredCompilation

Mit der TieredCompilation-Eigenschaft wird konfiguriert, ob der JIT-Compiler (Just-in-Time) die mehrstufige Kompilierung verwendet. Legen Sie den Wert auf false fest, um die mehrstufige Kompilierung zu deaktivieren. Weitere Informationen finden Sie unter Mehrstufige Kompilierung.

<PropertyGroup>
  <TieredCompilation>false</TieredCompilation>
</PropertyGroup>

TieredCompilationQuickJit

Mit der TieredCompilationQuickJit-Eigenschaft wird konfiguriert, ob der JIT-Compiler Quick JIT verwendet. Legen Sie den Wert auf false fest, um Quick JIT zu deaktivieren. Weitere Informationen finden Sie unter Quick JIT.

<PropertyGroup>
  <TieredCompilationQuickJit>false</TieredCompilationQuickJit>
</PropertyGroup>

TieredCompilationQuickJitForLoops

Mit der TieredCompilationQuickJitForLoops-Eigenschaft wird konfiguriert, ob der JIT-Compiler Quick JIT für Methoden mit Schleifen verwendet. Legen Sie den Wert auf true fest, um Quick JIT für Methoden mit Schleifen zu aktivieren. Weitere Informationen finden Sie unter Quick JIT für Schleifen.

<PropertyGroup>
  <TieredCompilationQuickJitForLoops>true</TieredCompilationQuickJitForLoops>
</PropertyGroup>

TieredPGO

Die TieredPGO-Eigenschaft steuert, ob die dynamische oder gestaffelte profilgesteuerte Optimierung (PGO) aktiviert ist. Legen Sie den Wert auf true fest, um die mehrstufige PGO zu aktivieren. Weitere Informationen finden Sie unter Profilgesteuerte Optimierung.

<PropertyGroup>
  <TieredPGO>true</TieredPGO>
</PropertyGroup>

UseWindowsThreadPool

Die UseWindowsThreadPool-Eigenschaft konfiguriert, ob die Threadverwaltung des Threadpools an den Windows-Threadpool delegiert wird (nur Windows). Der Standardwert ist false. In diesem Fall wird der .NET-Threadpool verwendet. Weitere Informationen finden Sie unter Windows-Threadpool.

<PropertyGroup>
  <UseWindowsThreadPool>true</UseWindowsThreadPool>
</PropertyGroup>

Die folgenden MSBuild-Eigenschaften sind in diesem Abschnitt dokumentiert:

AssetTargetFallback

Mit der Eigenschaft AssetTargetFallback können Sie zusätzliche kompatible Frameworkversionen für Projektverweise und NuGet-Pakete angeben. Wenn Sie z. B. mit PackageReference eine Paketabhängigkeit angeben, aber das entsprechende Paket keine Assets enthält, die mit dem TargetFramework Ihres Projekts kompatibel sind, kommt die Eigenschaft AssetTargetFallback ins Spiel. Die Kompatibilität des referenzierten Pakets wird erneut anhand jedes Zielframeworks überprüft, das in AssetTargetFallback angegeben ist. Diese Eigenschaft ersetzt die veraltete Eigenschaft PackageTargetFallback.

Sie können die Eigenschaft AssetTargetFallback auf eine oder mehrere Zielframeworkversionen festlegen.

<PropertyGroup>
  <AssetTargetFallback>net461</AssetTargetFallback>
</PropertyGroup>

DisableImplicitFrameworkReferences

Die Eigenschaft DisableImplicitFrameworkReferences steuert FrameworkReference-Elemente implizit, wenn .NET Core 3.0 oder höher als Ziel verwendet wird. Wenn .NET Core 2.1 oder .NET Standard 2.0 oder niedriger als Ziel verwendet wird, steuert die Eigenschaft implizit PackageReference-Elemente für Pakete in einem Metapaket. (Ein Metapaket ist ein frameworkbasiertes Paket, das nur aus Abhängigkeiten von anderen Paketen besteht.) Diese Eigenschaft steuert auch implizite Verweise wie System und System.Core, wenn .NET Framework als Ziel verwendet wird.

Legen Sie diese Eigenschaft auf true fest, um implizite FrameworkReference- oder PackageReference-Elemente zu deaktivieren. Wenn Sie diese Eigenschaft auf true festlegen, können Sie auf Framework- oder Paketebene je nach Bedarf explizite Verweise hinzufügen.

<PropertyGroup>
  <DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
</PropertyGroup>

DisableTransitiveFrameworkReferenceDownloads

Legen Sie die DisableTransitiveFrameworkReferenceDownloads-Eigenschaft auf true fest, um das Herunterladen zusätzlicher Runtime- und Zielversionspakete zu vermeiden, auf die ihr Projekt nicht direkt verweist.

<PropertyGroup>
  <DisableTransitiveFrameworkReferenceDownloads>true</DisableTransitiveFrameworkReferenceDownloads>
</PropertyGroup>

DisableTransitiveProjectReferences

Die DisableTransitiveProjectReferences-Eigenschaft steuert implizite Projektverweise. Legen Sie diese Eigenschaft auf true fest, um implizite ProjectReference-Elemente zu deaktivieren. Das Deaktivieren impliziter Projektverweise führt zu einem nicht transitiven Verhalten, das dem Legacyprojektsystem ähnelt.

Wenn diese Eigenschaft true ist, hat sie einen ähnlichen Effekt wie das Festlegen von PrivateAssets="All" für alle Abhängigkeiten des Projekts, von dem die Abhängigkeit besteht.

Wenn Sie diese Eigenschaft auf true festlegen, können Sie explizite Verweise auf nur die von Ihnen benötigten Projekte hinzufügen.

<PropertyGroup>
  <DisableTransitiveProjectReferences>true</DisableTransitiveProjectReferences>
</PropertyGroup>

ManagePackageVersionsCentrally

Die ManagePackageVersionsCentrally-Eigenschaft wurde in .NET 7 eingeführt. Indem Sie sie in einer Directory.Packages.props-Datei im Stammverzeichnis Ihres Repositorys auf true festlegen, können Sie allgemeine Abhängigkeiten in Ihren Projekten von einem Ort aus verwalten. Fügen Sie Versionen für allgemeine Paketabhängigkeiten mithilfe von PackageVersion-Elementen in der Datei Directory.Packages.props hinzu. Anschließend können Sie in den einzelnen Projektdateien Version-Attribute aus allen PackageReference-Elementen auslassen, die auf zentral verwaltete Pakete verweisen.

Beispieldatei Directory.Packages.props:

<PropertyGroup>
  <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
...
<ItemGroup>
  <PackageVersion Include="Microsoft.Extensions.Configuration" Version="7.0.0" />
</ItemGroup>

Einzelne Projektdatei:

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Configuration" />
</ItemGroup>

Weitere Informationen finden Sie unter Zentrale Paketverwaltung (CPM).

Durch das Wiederherstellen eines referenzierten Pakets werden alle seine direkten Abhängigkeiten sowie alle Abhängigkeiten dieser Abhängigkeiten installiert. Sie können die Paketwiederherstellung anpassen, indem Sie Eigenschaften wie RestorePackagesPath und RestoreIgnoreFailedSources angeben. Weitere Informationen zu diesen und anderen Eigenschaften finden Sie unter Wiederherstellungsziel.

<PropertyGroup>
  <RestoreIgnoreFailedSource>true</RestoreIgnoreFailedSource>
</PropertyGroup>

UseMauiEssentials

Legen Sie die UseMauiEssentials-Eigenschaft auf true fest, um einen expliziten Verweis auf ein Projekt oder Paket zu deklarieren, das von MAUI Essentials abhängig ist. Diese Einstellung stellt sicher, dass Ihr Projekt den richtigen bekannten Frameworkverweis für MAUI Essentials abruft. Wenn Ihr Projekt auf ein Projekt verweist, das MAUI Essentials verwendet, Sie diese Eigenschaft aber nicht auf true festlegen, wird möglicherweise die Buildwarnung NETSDK1186 angezeigt.

<PropertyGroup>
  <UseMauiEssentials>true</UseMauiEssentials>
</PropertyGroup>

ValidateExecutableReferencesMatchSelfContained

Mit der Eigenschaft ValidateExecutableReferencesMatchSelfContained können Fehler im Zusammenhang mit Verweisen in einem ausführbaren Projekt behoben werden. Wenn .NET erkennt, dass ein eigenständiges ausführbares Projekt auf ein frameworkabhängiges ausführbares Projekt verweist (oder umgekehrt), werden die Fehler NETSDK1150 bzw. NETSDK1151 generiert. Um diese Fehler im Fall eines beabsichtigten Verweises zu vermeiden, legen Sie die Eigenschaft ValidateExecutableReferencesMatchSelfContained auf false fest.

<PropertyGroup>
  <ValidateExecutableReferencesMatchSelfContained>false</ValidateExecutableReferencesMatchSelfContained>
</PropertyGroup>

WindowsSdkPackageVersion

Mit der WindowsSdkPackageVersion-Eigenschaft kann die Version des Windows SDK-Zielpakets außer Kraft gesetzt werden. Diese Eigenschaft wurde in .NET 5 eingeführt und ersetzt die Verwendung des FrameworkReference-Elements für diesen Zweck.

<PropertyGroup>
  <WindowsSdkPackageVersion>10.0.19041.18</WindowsSdkPackageVersion>
</PropertyGroup>

Hinweis

Sie sollten die Windows SDK-Version nicht überschreiben, da die Windows SDK-Zielpakete im .NET 5+ SDK enthalten sind. Aktualisieren Sie stattdessen Ihre Version des .NET SDK, um auf das aktuelle Windows SDK-Paket zu verweisen. Diese Eigenschaft sollte nur in seltenen Fällen verwendet werden, z. B. bei der Verwendung von Vorschaupaketen oder beim Überschreiben der C#/WinRT-Version.

Die folgenden Eigenschaften werden verwendet, um Apps mit dem Befehl dotnet run zu starten:

RunArguments

Die Eigenschaft RunArguments definiert die Argumente, die beim Ausführen an die App übergeben werden.

<PropertyGroup>
  <RunArguments>-mode dryrun</RunArguments>
</PropertyGroup>

Tipp

Sie können zusätzliche Argumente angeben, die an die App übergeben werden sollen, indem Sie die Option -- für dotnet runverwenden.

RunWorkingDirectory

Die Eigenschaft RunWorkingDirectory definiert das Arbeitsverzeichnis für den Anwendungsprozess, in dem diese gestartet werden soll. Dies kann ein absoluter Pfad oder ein Pfad sein, der relativ zum Projektverzeichnis ist. Wenn Sie kein Verzeichnis angeben, wird OutDir als Arbeitsverzeichnis verwendet.

<PropertyGroup>
  <RunWorkingDirectory>c:\temp</RunWorkingDirectory>
</PropertyGroup>

Die folgenden MSBuild-Eigenschaften sind in diesem Abschnitt dokumentiert:

EnableComHosting

Die EnableComHosting-Eigenschaft gibt an, dass eine Assembly einen COM-Server bereitstellt. Wenn die EnableComHosting-Eigenschaft auf true festgelegt wird, bedeutet dies auch, dass EnableDynamicLoadingtrue ist.

<PropertyGroup>
  <EnableComHosting>True</EnableComHosting>
</PropertyGroup>

Weitere Informationen finden Sie unter Verfügbarmachen von .NET Core-Komponenten in COM.

EnableDynamicLoading

Die EnableDynamicLoading-Eigenschaft gibt an, dass eine Assembly eine dynamisch geladene Komponente ist. Die Komponente kann eine COM-Bibliothek oder eine Nicht-COM-Bibliothek sein, die von einem nativen Host oder als PlugIn verwendet werden kann. Wenn diese Eigenschaft auf true festgelegt wird, hat diese die folgenden Auswirkungen:

  • Eine .runtimeconfig.json-Datei wird generiert.
  • RollForward wird auf LatestMinor festgelegt.
  • NuGet-Verweise werden lokal kopiert.
<PropertyGroup>
  <EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>

Eigenschaften der generierten Datei

Die folgenden Eigenschaften betreffen Code in generierten Dateien:

DisableImplicitNamespaceImports

Die DisableImplicitNamespaceImports-Eigenschaft kann verwendet werden, um implizite Namespaceimporte in Visual Basic-Projekten zu deaktivieren, die .NET 6 oder eine höhere Version als Ziel verwenden. Implizite Namespaces sind die Standardnamespaces, die global in ein Visual Basic-Projekt importiert werden. Legen Sie diese Eigenschaft auf true fest, um implizite Namespaceimporte zu deaktivieren.

<PropertyGroup>
  <DisableImplicitNamespaceImports>true</DisableImplicitNamespaceImports>
</PropertyGroup>

ImplicitUsings

Die ImplicitUsings-Eigenschaft kann verwendet werden, um implizite global using-Anweisungen in C#-Projekten zu aktivieren und zu deaktivieren, die auf .NET 6 oder eine neuere Version und C# 10 oder eine neuere Version ausgerichtet sind. Wenn das Feature aktiviert ist, fügt das .NET SDK global using-Anweisungen für einen Satz von Standardnamespaces basierend auf dem Typ des Projekt-SDK hinzu. Legen Sie diese Eigenschaft auf true oder enable fest, um implizite global using-Anweisungen zu aktivieren. Um implizite global using-Anweisungen zu deaktivieren, entfernen Sie die Eigenschaft, oder legen Sie sie auf false oder disable fest.

<PropertyGroup>
  <ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

Hinweis

In den Vorlagen für neue C#-Projekte für .NET 6 oder höher ist ImplicitUsings standardmäßig auf enable festgelegt.

Um eine explizite global using-Anweisung definieren, fügen Sie ein Using-Element hinzu.

Items

MSBuild-Elemente sind Eingaben in das Buildsystem. Elemente werden ihrem Typ (d. h. dem Elementnamen) entsprechend angegeben. Beispielsweise sind Compile und Reference zwei gängige Elementtypen. Die folgenden zusätzlichen Elementtypen werden vom .NET SDK zur Verfügung gestellt:

Sie können jedes Standardelementattribut (z. B. Include und Update) für diese Elemente verwenden. Verwenden Sie Include, um ein neues Element hinzuzufügen, und Update, um ein vorhandenes Element zu ändern. Beispielsweise wird Update häufig verwendet, um ein Element zu ändern, das implizit vom .NET SDK hinzugefügt wurde.

AssemblyMetadata

Das AssemblyMetadata-Element gibt ein AssemblyMetadataAttribute-Assemblyattribut mit einem Schlüssel-Wert-Paar an. Die Include-Metadaten werden zum Schlüssel, und die Value-Metadaten werden zum Wert.

<ItemGroup>
  <AssemblyMetadata Include="Serviceable" Value="True" />
</ItemGroup>

InternalsVisibleTo

Das InternalsVisibleTo-Element generiert ein InternalsVisibleToAttribute-Assemblyattribut für die angegebene Friend-Assembly.

<ItemGroup>
  <InternalsVisibleTo Include="MyProject.Tests" />
</ItemGroup>

Wenn die Friend-Assembly signiert ist, können Sie optionale Key-Metadaten angeben, um den vollständigen öffentlichen Schlüssel anzugeben. Wenn Sie keine Key-Metadaten angeben und ein $(PublicKey) verfügbar ist, wird dieser Schlüssel verwendet. Andernfalls wird dem Attribut kein öffentlicher Schlüssel hinzugefügt.

FrameworkReference

Das FrameworkReference-Element definiert einen Verweis auf ein freigegebenes .NET Framework.

Das Include-Attribut gibt die Framework-ID an.

Der Codeausschnitt für die Projektdatei im folgenden Beispiel verweist auf das freigegebene Framework Microsoft.AspNetCore.App.

<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

PackageReference

Das PackageReference-Element definiert einen Verweis auf ein NuGet-Paket.

Das Include-Attribut gibt die Paket-ID an. Das Version-Attribut gibt die Version oder den Versionsbereich an. Informationen, wie Sie eine Mindestversion, Maximalversion, einen Versionsbereich oder eine exakte Versionsübereinstimmung angeben, finden Sie unter Versionsbereiche.

Der Codeausschnitt für die Projektdatei im folgenden Beispiel verweist auf das Paket System.Runtime.

<ItemGroup>
  <PackageReference Include="System.Runtime" Version="4.3.0" />
</ItemGroup>

Sie können Abhängigkeitsobjekte auch mit Metadaten wie PrivateAssets steuern.

<ItemGroup>
  <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>

Weitere Informationen finden Sie unter Paketverweis in Projektdateien.

TrimmerRootAssembly

Mit dem TrimmerRootAssembly-Element können Sie eine Assembly aus der Kürzung ausschließen. Die Kürzung ist der Prozess, bei dem nicht verwendete Teile der Runtime aus einer gepackten Anwendung entfernt werden. In einigen Fällen können die erforderlichen Verweise durch eine Kürzung fälschlicherweise entfernt werden.

Der folgende XML-Code schließt die System.Security-Assembly aus der Kürzung aus.

<ItemGroup>
  <TrimmerRootAssembly Include="System.Security" />
</ItemGroup>

Weitere Informationen finden Sie unter Kürzungsoptionen.

Verwenden

Mit dem Using-Element können Sie einen Namespace global in Ihr C#-Projekt einbinden, sodass Sie keine using-Anweisung für den Namespace am Anfang Ihrer Quelldateien hinzufügen müssen. Dieses Element ähnelt dem Import-Element, das für den gleichen Zweck in Visual Basic-Projekten verwendet werden kann. Diese Eigenschaft ist ab .NET 6 verfügbar.

<ItemGroup>
  <Using Include="My.Awesome.Namespace" />
</ItemGroup>

Sie können das Using-Element auch verwenden, um globale using <alias>- und using static <type>-Anweisungen zu definieren.

<ItemGroup>
  <Using Include="My.Awesome.Namespace" Alias="Awesome" />
</ItemGroup>

Beispiel:

  • <Using Include="Microsoft.AspNetCore.Http.Results" Alias="Results" /> gibt global using Results = global::Microsoft.AspNetCore.Http.Results; aus
  • <Using Include="Microsoft.AspNetCore.Http.Results" Static="True" /> gibt global using static global::Microsoft.AspNetCore.Http.Results; aus

Weitere Informationen finden Sie unter using-Aliasanweisungen und using static <type>-Anweisungen.

Elementmetadaten

Zusätzlich zu den MSBuild-Standardelementattributen werden die folgenden Elementmetadatentags vom .NET SDK zur Verfügung gestellt:

CopyToPublishDirectory

Die CopyToPublishDirectory-Metadaten in einem MSBuild-Element steuern, wann das Element in das Veröffentlichungsverzeichnis kopiert wird. Zulässige Werte sind PreserveNewest, wodurch das Element nur kopiert wird, wenn es geändert wurde, Always, wodurch das Element immer kopiert wird, und Never, wodurch das Element nie kopiert wird. Aus Leistungssicht ist PreserveNewest zu bevorzugen, da so inkrementelle Builds ermöglicht werden.

<ItemGroup>
  <None Update="appsettings.Development.json" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>

LinkBase

Wenn ein Element sich außerhalb des Projektverzeichnisses und dessen Unterverzeichnissen befindet, verwendet das Veröffentlichungsziel die Link-Metadaten des Elements, um zu bestimmen, wohin es kopiert werden soll. Link legt auch fest, wie Elemente außerhalb der Projektstruktur im Projektmappen-Explorer von Visual Studio angezeigt werden.

Wenn Link für ein Element nicht angegeben ist, das sich außerhalb der Projektstruktur befindet, wird standardmäßig der Wert %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension) festgelegt. Mit LinkBase können Sie einen sinnvollen Basisordner für Elemente außerhalb der Projektstruktur angeben. Die Ordnerhierarchie des Basisordners wird mit RecursiveDir beibehalten. Wenn LinkBase nicht angegeben wird, wird das Element im Link-Pfad weggelassen.

<ItemGroup>
  <Content Include="..\Extras\**\*.cs" LinkBase="Shared"/>
</ItemGroup>

Auf der folgenden Abbildung sehen Sie, wie eine Datei, die über das Globmuster des vorherigen Elements Include eingefügt wird, im Projektmappen-Explorer dargestellt wird.

Solution Explorer showing item with LinkBase metadata.

Siehe auch