Muokkaa

Jaa

MSBuild reference for .NET Desktop SDK projects

  • Artikkeli

This page is a reference for the MSBuild properties and items that you use to configure Windows Forms (WinForms) and Windows Presentation Foundation (WPF) projects with the .NET Desktop SDK.

Note

This article documents a subset of the MSBuild properties for the .NET SDK as it relates to desktop apps. For a list of common .NET SDK-specific MSBuild properties, see MSBuild reference for .NET SDK projects. For a list of common MSBuild properties, see Common MSBuild properties.

Enable .NET Desktop SDK

To use WinForms or WPF, specify the following settings in the project file of your WinForms or WPF project:

  • Target the .NET SDK Microsoft.NET.Sdk. For more information, see Project files.
  • Set TargetFramework to a Windows-specific target framework moniker, such as net8.0-windows.
  • Add a UI framework property (or both, if necessary):
  • (Optional) Set OutputType to WinExe. This setting produces an app as opposed to a library. To produce a library, omit this property.
<Project Sdk="Microsoft.NET.Sdk">

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

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

</Project>

WPF default includes and excludes

SDK projects define a set of rules to implicitly include or exclude files from the project. These rules also automatically set the file's build action. This behavior is unlike the older non-SDK .NET Framework projects, which have no default include or exclude rules. .NET Framework projects require you to explicitly declare which files to include in the project.

.NET project files include a standard set of rules for automatically processing files. WPF projects add additional rules.

The following table shows which elements and globs are included and excluded in the .NET Desktop SDK when the UseWPF project property is set to true:

Element Include glob Exclude glob Remove glob
ApplicationDefinition App.xaml or Application.xaml N/A N/A
Page **/*.xaml **/*.user; **/*.*proj; **/*.sln; **/*.vssscc
Any XAML defined by ApplicationDefinition		 N/A
None N/A N/A **/*.xaml

Here are the default include and exclude settings for all project types. For more information, see Default includes and excludes.

Element Include glob Exclude glob Remove glob
Compile **/*.cs; **/*.vb (or other language extensions) **/*.user; **/*.*proj; **/*.sln; **/*.vssscc N/A
EmbeddedResource **/*.resx **/*.user; **/*.*proj; **/*.sln; **/*.vssscc N/A
None **/* **/*.user; **/*.*proj; **/*.sln; **/*.vssscc **/*.cs; **/*.resx

If you explicitly added files to your project, or have XAML globs to automatically include files in your project, you might get one of the following errors:

  • Duplicate 'ApplicationDefinition' items were included.
  • Duplicate 'Page' items were included.

These errors are a result of the implicit Include globs conflicting with your settings. To work around this problem, set either EnableDefaultApplicationDefinition or EnableDefaultPageItems to false. Setting these values to false reverts to the behavior of previous SDKs where you had to explicitly define either the default globs or the files to include in your project.

You can completely disable all implicit includes by setting the EnableDefaultItems property to false.

WPF settings

For information about non-WPF-specific project settings, see MSBuild reference for .NET SDK projects.

UseWPF

The UseWPF property controls whether or not to include references to WPF libraries. This setting also alters the MSBuild pipeline to correctly process a WPF project and related files. The default value is false. Set the UseWPF property to true to enable WPF support. You can only target the Windows platform when this property is enabled.

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

When this property is set to true, .NET projects automatically import the .NET Desktop SDK.

EnableDefaultApplicationDefinition

The EnableDefaultApplicationDefinition property controls whether ApplicationDefinition items are implicitly included in the project. The default value is true. Set the EnableDefaultApplicationDefinition property to false to disable the implicit file inclusion.

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

This property requires that the EnableDefaultItems property is set to true, which is the default setting.

EnableDefaultPageItems

The EnableDefaultPageItems property controls whether Page items, which are .xaml files, are implicitly included in the project. The default value is true. Set the EnableDefaultPageItems property to false to disable the implicit file inclusion.

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

This property requires that the EnableDefaultItems property is set to true, which is the default setting.

Windows Forms settings

For information about non-WinForms-specific project properties, see MSBuild reference for .NET SDK projects.

ApplicationDefaultFont

The ApplicationDefaultFont property specifies custom font information to be applied application-wide. It controls whether or not the source-generated ApplicationConfiguration.Initialize() API emits a call to the Application.SetDefaultFont(Font) method. The default value is an empty string, and it means the application default font is sourced from the Control.DefaultFont property.

A non-empty value must conform to a format equivalent to the output of the FontConverter.ConvertTo method invoked with the invariant culture (that is, list separator=, and decimal separator=.). The format is: name, size[units[, style=style1[, style2, ...]]].

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

This property is supported by .NET 6 and later versions, and Visual Studio 2022 and later versions.

ApplicationHighDpiMode

The ApplicationHighDpiMode property specifies the application-wide default for the high DPI mode. It controls the argument of the Application.SetHighDpiMode(HighDpiMode) method emitted by the source-generated ApplicationConfiguration.Initialize() API. The default value is SystemAware.

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

The ApplicationHighDpiMode can be set to one of the HighDpiMode enum values:

Value Description
DpiUnaware The application window doesn't scale for DPI changes and always assumes a scale factor of 100%.
DpiUnawareGdiScaled Similar to DpiUnaware, but improves the quality of GDI/GDI+ based content.
PerMonitor The window checks for DPI when it's created and adjusts scale factor when the DPI changes.
PerMonitorV2 Similar to PerMonitor, but enables child window DPI change notification, improved scaling of comctl32 controls, and dialog scaling.
SystemAware Default if not specified.
The window queries for the DPI of the primary monitor once and uses this value for the application on all monitors.

This property is supported by .NET 6 and later versions.

ApplicationUseCompatibleTextRendering

The ApplicationUseCompatibleTextRendering property specifies the application-wide default for the UseCompatibleTextRendering property defined on certain controls. It controls the argument of the Application.SetCompatibleTextRenderingDefault(Boolean) method emitted by the source-generated ApplicationConfiguration.Initialize() API. The default value is false.

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

This property is supported by .NET 6 and later versions.

ApplicationVisualStyles

The ApplicationVisualStyles property specifies the application-wide default for enabling visual styles. It controls whether or not the source-generated ApplicationConfiguration.Initialize() API emits a call to Application.EnableVisualStyles(). The default value is true.

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

This property is supported by .NET 6 and later versions.

UseWindowsForms

The UseWindowsForms property controls whether or not your application is built to target Windows Forms. This property alters the MSBuild pipeline to correctly process a Windows Forms project and related files. The default value is false. Set the UseWindowsForms property to true to enable Windows Forms support. You can only target the Windows platform when this setting is enabled.

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

When this property is set to true, .NET projects automatically import the .NET Desktop SDK.

See also