MSBuild-Referenz für .NET SDK-Projekte

  • Artikel
  • 33 Minuten Lesedauer

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.

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>netcoreapp3.1</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>netcoreapp3.1;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. In der folgenden Tabelle sind die Projekteigenschaften aufgelistet, mit denen die Attribute generiert werden. Außerdem sind die Eigenschaften aufgelistet, mit denen Sie diese Generierung auf Attributbasis deaktivieren können, z. B. folgendermaßen:

<PropertyGroup>
  <GenerateNeutralResourcesLanguageAttribute>false</GenerateNeutralResourcesLanguageAttribute>
</PropertyGroup>
MSBuild-Eigenschaft Assembly-Attribut Eigenschaft zum Deaktivieren der Attributgenerierung
Company AssemblyCompanyAttribute GenerateAssemblyCompanyAttribute
Configuration AssemblyConfigurationAttribute GenerateAssemblyConfigurationAttribute
Copyright AssemblyCopyrightAttribute GenerateAssemblyCopyrightAttribute
Description AssemblyDescriptionAttribute GenerateAssemblyDescriptionAttribute
FileVersion AssemblyFileVersionAttribute GenerateAssemblyFileVersionAttribute
InformationalVersion AssemblyInformationalVersionAttribute GenerateAssemblyInformationalVersionAttribute
Product AssemblyProductAttribute GenerateAssemblyProductAttribute
AssemblyTitle AssemblyTitleAttribute GenerateAssemblyTitleAttribute
AssemblyVersion AssemblyVersionAttribute GenerateAssemblyVersionAttribute
NeutralLanguage NeutralResourcesLanguageAttribute GenerateNeutralResourcesLanguageAttribute

Hinweise zu diesen Einstellungen:

  • AssemblyVersion und FileVersion nehmen standardmäßig den Wert von $(Version) ohne Suffix an. Wenn $(Version) beispielsweise 1.2.3-beta.4 ist, wäre der Wert 1.2.3.
  • InformationalVersion hat standardmäßig den Wert von $(Version).
  • Wenn die Eigenschaft $(SourceRevisionId) vorhanden ist, wird sie an InformationalVersion angefügt. Sie können dieses Verhalten mithilfe von IncludeSourceRevisionInInformationalVersion deaktivieren.
  • Die Eigenschaften Copyright und Description werden auch für NuGet-Metadaten verwendet.
  • Configuration weist standardmäßig den Wert Debug auf und wird für alle MSBuild-Ziele freigegeben. Sie können die Eigenschaft über die Option --configuration in dotnet-Befehlen wie dotnet pack festlegen.
  • Einige dieser Eigenschaften werden bei der Erstellung eines NuGet-Pakets verwendet. Weitere Informationen finden Sie unter Paketeigenschaften.

Migrieren vom .NET Framework

.NET Framework-Projektvorlagen erstellen eine Codedatei mit den festgelegten Assemblyinformationsattributen. Diese Datei wird in der Regel als .\Properties\AssemblyInfo.cs oder .\Properties\AssemblyInfo.vb gespeichert. SDK-Projekte generieren diese Datei den Projekteinstellungen entsprechend für Sie. Beides ist nicht möglich. Wenn Sie Ihren Code zu .NET 5 (oder .NET Core 3.1) oder höher portieren, sollten Sie einen der folgenden Schritte ausführen:

  • Deaktivieren Sie die Generierung der temporären Codedatei, die die Assemblyinformationsattribute enthält, indem Sie GenerateAssemblyInfo in Ihrer Projektdatei auf false festlegen. Dadurch können Sie die AssemblyInfo-Datei beibehalten.
  • Migrieren Sie die Einstellungen in der AssemblyInfo-Datei in die Projektdatei, und löschen Sie danach die AssemblyInfo-Datei.

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

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.

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

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.

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

<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.

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>

Diese Eigenschaft wurde in .NET 6 eingeführt.

GenerierenRuntimeConfigDevFile

Ab dem .NET 6 SDK wird die Datei [Appname].runtimesettings.dev.jsonnicht mehr standardmäßig zur Kompilierung generiert. Wenn diese Datei weiterhin generiert werden soll, legen Sie die GenerateRuntimeConfigDevFile Eigenschaft auf true.

<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 mithilfe csc.exe oder 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.exeerstellt. Durch Festlegen der GenerateSatelliteAssembliesForCore Eigenschaft auf true, werden Satellitenassemblys stattdessen von csc.exe erstellt. Die Verwendung csc.exe kann in den folgenden Situationen vorteilhaft 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. den Befehl "Dotnet-Veröffentlichung ". 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 Referenzassemblys immer in das OutDir Verzeichnis geschrieben. In .NET 6 und höher können Sie die ProduceReferenceAssemblyInOutDir Eigenschaft verwenden, um zu steuern, ob Referenzassemblys in das OutDir Verzeichnis geschrieben werden. Der Standardwert ist false, und Referenzassemblys werden nur in das IntermediateOutputPath Verzeichnis geschrieben. Legen Sie den Wert fest, true um Referenzassemblys in das OutDir Verzeichnis zu schreiben.

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

Weitere Informationen finden Sie unter Schreiben von Referenzassemblys zu Zwischenausgabe.

PublishRelease

Die PublishRelease Eigenschaft informiertdotnet publish, die Konfiguration anstelle der Debug Konfiguration zu nutzenRelease. Es wird empfohlen, diese Eigenschaft einer Directory.Build.props Datei anstelle einer Projektdatei hinzuzufügen, sodass sie früh genug ausgewertet wird, um die Konfigurationsänderung zu verteilen.

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

Hinweis

Diese Eigenschaft wirkt sich nicht auf das Verhalten von dotnet build /t:Publish.

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>ubuntu.16.04-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>win10-x64;osx.10.11-x64;ubuntu.16.04-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 werden beispielsweise nur die Satellitenressourcenassemblys für Englisch (USA) beibehalten.

<PropertyGroup>
  <SatelliteResourceLanguages>en-US</SatelliteResourceLanguages>
</PropertyGroup>

Hinweis

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

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.

In .NET Core 3.0 und höheren Versionen wird standardmäßig 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 sind verfügbar, um das Kürzen zu optimieren, was ein Feature ist, das nicht verwendete Code von eigenständigen Bereitstellungen abschneidet. Diese Optionen werden ausführlich unter Den Trimming-Optionen 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 link oder copyused Steuert die Kürzen der Granularität. Diese Eigenschaft kann global für das Projekt oder auf Assemblyebene als Metadaten festgelegt werden.
SuppressTrimAnalysisWarnings true oder false Steuert, ob Kürzungsanalysewarnungen erstellt werden.
EnableTrimAnalyzer true oder false Steuert, ob eine Teilmenge von Kürzenanalysewarnungen erzeugt wird. Sie können die Analyse auch dann aktivieren, wenn PublishTrimmed sie festgelegt falseist.
ILLinkWarningLevel 5-9999, previewoder latest Steuert die Version der Warnungen zur Kürzung der Analyse.
ILLinkTreatWarningsAsErrors true oder false Steuert, ob Warnungen als Fehler behandelt werden. Sie können diese Eigenschaft z. B. so festlegen, dass diese Eigenschaft auf false den trueWert TreatWarningsAsErrors 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.

DisableImplicitFrameworkDefines

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

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

Weitere Informationen zu Zielframework-Monikern und diesen impliziten Präprozessorsymbolen finden Sie unter Target Frameworks.

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 mindestgebundener Version (IOS15_1_OR_GREATER)

Weitere Informationen zu betriebssystemspezifischen Zielframework-Monikern finden Sie unter betriebssystemspezifische TFMs.

Wenn Ihr Zielframework die Unterstützung älterer Zielframeworks impliziert, werden Präprozessorsymbole für diese älteren Frameworks ausgegeben. Bedeutet beispielsweise net6.0 Unterstützung für net5.0 usw. zurück zu .netcoreapp1.0. Für jede dieser Zielframeworks wird das Framework mit dem mindestgebundenen Mindestsymbol für die Version 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 z. B. 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.

Standardmäßig ist diese Eigenschaft in einem neuen .NET-Projekt auf true festgelegt. 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.

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>

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>

DefaultExcludesInProjectFolder

Verwenden Sie die DefaultExcludesInProjectFolder-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 DefaultExcludesInProjectFolder-Eigenschaft anstelle der DefaultItemExcludes-Eigenschaft.

<PropertyGroup>
  <DefaultExcludesInProjectFolder>$(DefaultExcludesInProjectFolder);**/myprefix*/**</DefaultExcludesInProjectFolder>
</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 6 durchführen, aber nicht möchten, dass der Standardsatz von Codeanalyseregeln geändert wird, legen Sie AnalysisLevel auf 5 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>

Hinweis

Wenn Sie AnalysisLevel auf 5-<mode> oder 5.0-<mode> festlegen und dann das .NET 6 SDK installieren und Ihr Projekt neu kompilieren, werden möglicherweise unerwartete Warnungen zu neuen Builds angezeigt. Weitere Informationen finden Sie unter dotnet/roslyn-analyzers#5679.

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.
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

  • In .NET 5 und früheren Versionen wirkt sich diese Eigenschaft nur auf Codequalitätsregeln (CAXXXX) aus. Ab .NET 6 wirkt sich diese Eigenschaft auch auf Codestilregeln (IDEXXXX) 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 In .NET 6 eingeführte 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

Ab .NET 5 enthält das .NET SDK alle Codequalitätsregeln für Zertifizierungsstellen. Standardmäßig werden nur einige Regeln als Buildwarnungen in jeder .NET-Version aktiviert. Mit der AnalysisMode-Eigenschaft können Sie die Regeln anpassen, die standardmäßig aktiviert sind. 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 in .NET 5 und .NET 6. Sie werden in aufsteigender Reihenfolge der Anzahl der Regeln, die sie aktivieren, aufgeführt.

.NET 6-Wert oder höher .NET 5-Wert Bedeutung
None AllDisabledByDefault Alle Regeln sind deaktiviert. Sie können einzelne Regeln selektiv aktivieren.
Default 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 Default-Modus. Bestimmte Vorschläge, die für die Builderzwingung dringend empfohlen werden, werden als Buildwarnungen aktiviert.
Recommended – Aggressiverer Modus als der Minimum-Modus, in dem mehr Regeln als Buildwarnungen aktiviert sind.
All AllEnabledByDefault Alle Regeln sind als Buildwarnungen aktiviert. Sie können einzelne Regeln deaktivieren.

Hinweis

  • In .NET 5 wirkt sich diese Eigenschaft nur auf Codequalitätsregeln (CAXXXX) aus. Ab .NET 6 wirkt sich diese Eigenschaft auch auf Codestilregeln (IDEXXXX) aus, wenn Sie EnforceCodeStyleInBuild auf true festlegen.
  • Wenn Sie einen zusammengesetzten Wert für AnalysisLevel verwenden (z. B. <AnalysisLevel>5-recommended</AnalysisLevel>), können Sie diese Eigenschaft vollständig auslassen. Wenn Sie jedoch beide Eigenschaften angeben, besitzt AnalysisLevel Vorrang vor AnalysisMode.
  • Wenn AnalysisMode auf AllEnabledByDefault und AnalysisLevel auf 5 oder 5.0 festgelegt ist und Sie dann das .NET 6 SDK installieren und Ihr Projekt neu kompilieren, werden möglicherweise unerwartete Warnungen zu neuen Builds angezeigt. Weitere Informationen finden Sie unter dotnet/roslyn-analyzers#5679.
  • 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 In .NET 6 eingeführte 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.

Hinweis

Wenn Sie .NET 6 (oder Visual Studio 2022, einschließlich .NET 6) installieren, aber Ihr Projekt mithilfe von Visual Studio 2019 erstellen möchten, werden möglicherweise neue CS8032-Warnungen angezeigt, wenn die EnforceCodeStyleInBuild Eigenschaft auf true" festgelegt ist. Um die Warnungen zu beheben, können Sie die Version des .NET SDK angeben, um Ihr Projekt mit (in diesem Fall etwa 5.0.404) zu erstellen, indem Sie einen global.json-Eintrag hinzufügen.

_SkipUpgradeNetAnalyzersNuGetWarning

Mit der _SkipUpgradeNetAnalyzersNuGetWarning Eigenschaft können Sie konfigurieren, ob Sie eine Warnung erhalten, wenn Sie Codeanalyses aus einem NuGet Paket verwenden, das veraltet ist, wenn Sie mit den Codeanalyses im neuesten .NET SDK verglichen werden. Die Warnung sieht ähnlich aus wie folgt:

Das .NET SDK verfügt über neuere Analysegeräte mit Version 6.0.0" als die Version "5.0.3" des Pakets "Microsoft.CodeAnalysis.NetAnalyzers". Aktualisieren oder entfernen Sie diesen Paketverweis.

Um diese Warnung zu entfernen und weiterhin die Version von Codeanalyses im NuGet-Paket zu verwenden, legen Sie in der Projektdatei fest _SkipUpgradeNetAnalyzersNuGetWarningtrue.

<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.

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>

Verweiseigenschaften

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>

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>

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.

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 Trimming-Optionen.

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 zu using-Aliasanweisungen und using static <type>-Anweisungen finden Sie unter using-Anweisung.

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