MSBuild-Referenz für Projekte mit dem .NET Desktop SDK

  • Artikel

Bei dieser Seite handelt es sich um eine Referenz für die MSBuild-Eigenschaften und -Elemente, die Sie zum Konfigurieren von Windows Forms- (WinForms) und Windows Presentation Foundation-Projekten (WPF) mit dem .NET Desktop SDK.

Hinweis

In diesem Artikel wird eine Teilmenge der MSBuild-Eigenschaften für das .NET SDK dokumentiert, da diese sich auf Desktop-Apps beziehen. Eine Liste gängiger MSBuild-Eigenschaften für das .NET SDK finden Sie in der MSBuild-Referenz für .NET SDK-Projekte. Eine Liste der gängigen MSBuild-Eigenschaften finden Sie unter Gemeinsame MSBuild-Projekteigenschaften.

Aktivieren des .NET Desktop SDK

Um WinForms oder WPF zu verwenden, geben Sie die folgenden Einstellungen in der Projektdatei Ihres WinForms- oder WPF-Projekts an:

  • Legen Sie das .NET SDK Microsoft.NET.Sdk als Ziel fest. Weitere Informationen finden Sie unter Projektdateien.
  • Festlegen TargetFramework auf einen Windows-spezifischen Zielframework-Moniker, z net8.0-windows. B. .
  • Fügen Sie bei Bedarf eine UI-Framework-Eigenschaft (oder beides) hinzu:
    • Legen Sie UseWPF auf true fest, um WPF zu importieren und zu verwenden.
    • Legen Sie UseWindowsForms auf true fest, um WinForms zu importieren und zu verwenden.
  • (Optional) Legen Sie OutputType auf WinExe fest. Diese Einstellung erzeugt eine App im Gegensatz zu einer Bibliothek. Lassen Sie diese Eigenschaft aus, um eine Bibliothek zu erstellen.
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows</TargetFramework>

    <UseWPF>true</UseWPF>
    <!-- and/or -->
    <UseWindowsForms>true</UseWindowsForms>
  </PropertyGroup>

</Project>

Standardmäßige Einschlüsse und Ausschlüsse von WPF

SDK-Projekte definieren Regeln, um Dateien implizit in das Projekt einzubeziehen oder aus diesem auszuschließen. Diese Regeln legen auch automatisch den Buildvorgang der Datei fest. Dieses Verhalten unterscheidet sich von den älteren Nicht-SDK .NET Framework-Projekten, die keine Standardregeln enthalten oder ausschließen. .NET Framework Projekte erfordern, dass Sie explizit deklarieren, welche Dateien in das Projekt eingeschlossen werden sollen.

.NET-Projektdateien schließen Standardregeln für die automatische Verarbeitung von Dateien ein. WPF-Projekte fügen zusätzliche Regeln hinzu.

In der folgenden Tabelle wird gezeigt, welche Elemente und Globs im .NET Desktop SDK ein- und ausgeschlossen werden, wenn die Projekteigenschaft UseWPF auf true festgelegt wird:

Element Glob einschließen Glob ausschließen Glob entfernen
ApplicationDefinition App.xaml oder Application.xaml – –
Page **/*.xaml **/*.user; **/*.*proj; **/*.sln; **/*.vssscc
Jeglicher von ApplicationDefinition definierter XAML-Code		 –
None – – **/*.xaml

Im Folgenden finden Sie die Standardeinstellungen für Einschlüsse und Ausschlüsse für alle Projekttypen. Weitere Informationen finden Sie unter dem Abschnitt zu standardmäßigen Include- und Excludedateien.

Element Glob einschließen Glob ausschließen Glob entfernen
Compile **/*.cs; **/*.vb (oder andere Spracherweiterungen) **/*.user; **/*.*proj; **/*.sln; **/*.vssscc –
EmbeddedResource **/*.resx **/*.user; **/*.*proj; **/*.sln; **/*.vssscc –
None **/* **/*.user; **/*.*proj; **/*.sln; **/*.vssscc **/*.cs; **/*.resx

Wenn Sie explizit Dateien zu Ihrem Projekt hinzugefügt haben oder über XAML-Globs zum automatischen Einschließen von Dateien in Ihr Projekt verfügen, wird möglicherweise einer der folgenden Fehler ausgelöst:

  • Doppelte ApplicationDefinition-Elemente wurden eingeschlossen.
  • Doppelte Page-Elemente wurden eingeschlossen.

Diese Fehler werden von den impliziten Include-Globs verursacht, die im Konflikt mit Ihren Einstellungen stehen. Legen Sie entweder EnableDefaultApplicationDefinition oder EnableDefaultPageItems auf false fest, um dieses Problem zu umgehen. Legen Sie diese Werte auf false rückgängig machen s auf das Verhalten früherer SDKs fest, bei denen Sie explizit entweder die Standard-Globs oder die Dateien definieren mussten, die in Ihr Projekt aufgenommen werden sollen.

Sie können alle impliziten Einschlüsse vollständig deaktivieren, indem Sie die EnableDefaultItems-Eigenschaft auf false festlegen.

WPF-Einstellungen

Informationen über Projekteinstellungen, die nicht spezifisch für WPF gelten, finden Sie in der MSBuild-Referenz für Projekte mit dem .NET SDK.

UseWPF

Die Eigenschaft UseWPF steuert, ob Verweise auf WPF-Bibliotheken eingeschlossen werden sollen oder nicht. Diese Einstellung ändert auch die MSBuild-Pipeline so, dass ein WPF-Projekt und zugehörige Dateien ordnungsgemäß verarbeitet werden. Der Standardwert ist false. Legen Sie die UseWPF-Eigenschaft auf true fest, um die WPF-Unterstützung zu aktivieren. Wenn diese Eigenschaft aktiviert ist, können Sie nur die Windows-Plattform als Ziel verwenden.

<PropertyGroup>
  <UseWPF>true</UseWPF>
</PropertyGroup>

Wenn diese Eigenschaft auf true.NET 5+-Projekte festgelegt ist, importieren Sie automatisch das .NET Desktop SDK.

EnableDefaultApplicationDefinition

Die Eigenschaft EnableDefaultApplicationDefinition steuert, ob ApplicationDefinition-Elemente implizit in das Projekt eingeschlossen werden. Der Standardwert ist true. Legen Sie die EnableDefaultApplicationDefinition-Eigenschaft auf false fest, um die implizite Dateieinbindung zu deaktivieren.

<PropertyGroup>
  <EnableDefaultApplicationDefinition>false</EnableDefaultApplicationDefinition>
</PropertyGroup>

Diese Eigenschaft erfordert, dass die EnableDefaultItems-Eigenschaft auf true festgelegt wird. Dabei handelt es sich um die Standardeinstellung.

EnableDefaultPageItems

Die EnableDefaultPageItems-Eigenschaft steuert, ob Page-Elemente, bei denen es sich um XAML-Dateien handelt, implizit in das Projekt eingeschlossen werden. Der Standardwert ist true. Legen Sie die EnableDefaultPageItems-Eigenschaft auf false fest, um die implizite Dateieinbindung zu deaktivieren.

<PropertyGroup>
  <EnableDefaultPageItems>false</EnableDefaultPageItems>
</PropertyGroup>

Diese Eigenschaft erfordert, dass die EnableDefaultItems-Eigenschaft auf true festgelegt wird. Dabei handelt es sich um die Standardeinstellung.

Windows Forms-Einstellungen

Informationen über Projekteigenschaften, die nicht spezifisch für WinForms gelten, finden Sie in der MSBuild-Referenz für Projekte mit dem .NET SDK.

ApplicationDefaultFont

Die Eigenschaft ApplicationDefaultFont gibt benutzerdefinierte Schriftartinformationen an, die anwendungsweit angewendet werden sollen. Sie steuert, ob die von der Quelle generierte ApplicationConfiguration.Initialize()-API einen Aufruf der Application.SetDefaultFont(Font)-Methode ausgibt oder nicht. Der Standardwert ist eine leere Zeichenfolge, was bedeutet, dass die Standardschriftart der Anwendung aus der Eigenschaft Control.DefaultFont stammt.

Ein nicht leerer Wert muss einem Format entsprechen, das der Ausgabe der Methode FontConverter.ConvertTo entspricht, die mit der invarianten Kultur aufgerufen wird (d. h. Listentrennzeichen=, und Dezimaltrennzeichen=. ). Das Format lautet: name, size[units[, style=style1[, style2, ...]]].

<PropertyGroup>
  <ApplicationDefaultFont>Calibri, 11pt, style=regular</ApplicationDefaultFont>
</PropertyGroup>

Diese Eigenschaft wird von .NET 6 und höher sowie von Visual Studio 2022 und höher unterstützt.

ApplicationHighDpiMode

Die Eigenschaft ApplicationHighDpiMode gibt den anwendungsweiten Standardwert für den Modus mit hohem DPI-Wert an. Sie steuert das Argument der Methode Application.SetHighDpiMode(HighDpiMode), die durch die von der Quelle generierte ApplicationConfiguration.Initialize()-API ausgegeben wird. Der Standardwert ist SystemAware.

<PropertyGroup>
  <ApplicationHighDpiMode>PerMonitorV2</ApplicationHighDpiMode>
</PropertyGroup>

ApplicationHighDpiMode kann auf einen der Enumerationswerte von HighDpiMode festgelegt werden:

Wert Beschreibung
DpiUnaware Das Anwendungsfenster skaliert nicht für DPI-Änderungen und geht immer von einem Skalierungsfaktor von 100 % aus.
DpiUnawareGdiScaled Ähnlich wie DpiUnaware, verbessert aber die Qualität von GDI/GDI+-basierten Inhalten.
PerMonitor Bei der Erstellung des Fensters werden die DPI-Einstellungen überprüft. Der Skalierungsfaktor wird angepasst, wenn sich die DPI-Einstellungen ändern.
PerMonitorV2 Ähnelt PerMonitor, ermöglicht aber eine Benachrichtigung bei Änderung der DPI-Einstellungen eines untergeordneten Fensters, eine bessere Skalierung von comCtl32-Steuerelementen und Dialogfeldskalierung.
SystemAware Standard, wenn nicht angegeben.
Das Fenster fragt einmal nach dem DPI-Wert des primären Monitors ab und verwendet diesen Wert für die Anwendung auf allen Monitoren.

Diese Eigenschaft wird von .NET 6 und höheren Versionen unterstützt.

ApplicationUseCompatibleTextRendering

Die Eigenschaft ApplicationUseCompatibleTextRendering legt den anwendungsweiten Standardwert für die Eigenschaft UseCompatibleTextRendering fest, die in bestimmten Steuerelementen definiert ist. Sie steuert das Argument der Methode Application.SetCompatibleTextRenderingDefault(Boolean), die durch die von der Quelle generierte ApplicationConfiguration.Initialize()-API ausgegeben wird. Der Standardwert ist false.

<PropertyGroup>
  <ApplicationUseCompatibleTextRendering>true</ApplicationUseCompatibleTextRendering>
</PropertyGroup>

Diese Eigenschaft wird von .NET 6 und höheren Versionen unterstützt.

ApplicationVisualStyles

Die Eigenschaft ApplicationVisualStyles gibt den anwendungsweiten Standardwert für die Aktivierung visueller Formate an. Sie steuert, ob die von der Quelle generierte ApplicationConfiguration.Initialize()-API einen Aufruf an Application.EnableVisualStyles() ausgibt oder nicht. Der Standardwert ist true.

<PropertyGroup>
  <ApplicationVisualStyles>true</ApplicationVisualStyles>
</PropertyGroup>

Diese Eigenschaft wird von .NET 6 und höheren Versionen unterstützt.

UseWindowsForms

Die UseWindowsForms-Eigenschaft steuert, ob Ihre Anwendung auf Windows Forms ausgerichtet ist oder nicht. Diese Eigenschaft ändert die MSBuild-Pipeline so, dass ein Windows Forms-Projekt und zugehörige Dateien ordnungsgemäß verarbeitet werden. Der Standardwert ist false. Legen Sie die UseWindowsForms-Eigenschaft auf true fest, um die Windows Forms-Unterstützung zu aktivieren. Wenn diese Einstellung aktiviert ist, können Sie nur die Windows-Plattform als Ziel verwenden.

<PropertyGroup>
  <UseWindowsForms>true</UseWindowsForms>
</PropertyGroup>

Wenn diese Eigenschaft auf true.NET 5+-Projekte festgelegt ist, importieren Sie automatisch das .NET Desktop SDK.

Übergreifende Einstellungen

DisableWinExeOutputInference

Gilt für .NET 5 SDK und höher.

Wenn die OutputType-Eigenschaft einer App auf den Wert Exe festgelegt ist, wird ein Konsolenfenster erstellt, wenn die App nicht über eine Konsole ausgeführt wird. Dieses Verhalten ist in der Regel für eine Windows-Desktop-App nicht wünschenswert. Wenn der Wert WinExe festgelegt ist, wird kein Konsolenfenster erstellt. Ab dem .NET 5 SDK wird der Wert Exe automatisch in WinExe umgewandelt.

Die Eigenschaft DisableWinExeOutputInference kehrt das Verhalten um, dass Exe als WinExe behandelt wird. Legen Sie diesen Wert auf true fest, um das Exe-Verhalten des OutputType-Eigenschaftswerts wiederherzustellen. Der Standardwert ist false.

<PropertyGroup>
  <DisableWinExeOutputInference>true</DisableWinExeOutputInference>
</PropertyGroup>

Siehe auch