MSBuild reference for .NET Desktop SDK projects

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.

Enable .NET Desktop SDK

To use WinForms or WPF, configure your project file.

.NET 5+

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 net6.0-windows.
• Add a UI framework property (or both, if necessary):
  • Set UseWPF to true to import and use WPF.
  • Set UseWindowsForms to true to import and use WinForms.
• (Optional) Set OutputType to WinExe. This 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>net6.0-windows</TargetFramework>

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

</Project>

.NET Core 3.1

Specify the following settings in the project file of your WinForms or WPF project:

• Target the .NET SDK Microsoft.NET.Sdk.WindowsDesktop. For more information, see Project files.
• Set TargetFramework to netcoreapp3.1.
• Add a UI framework property (or both, if necessary):
  • Set UseWPF to true to import and use WPF.
  • Set UseWindowsForms to true to import and use WinForms.
• (Optional) Set OutputType to WinExe. This produces an app as opposed to a library. To produce a library, omit this property.

<Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">

  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>netcoreapp3.1</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 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:

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

Errors related to "duplicate" items

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 the default globs in your project, or explicitly define the files to include in the project.

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

WPF settings

• UseWPF
• EnableDefaultApplicationDefinition
• EnableDefaultPageItems

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 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 5+ projects will automatically import the .NET Desktop SDK.

.NET Core 3.1 projects need to explicitly target the .NET Desktop SDK to use this property.

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 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 property is set to true, which is the default setting.

Windows Forms settings

• ApplicationDefaultFont
• ApplicationHighDpiMode
• ApplicationUseCompatibleTextRendering
• ApplicationVisualStyles
• UseWindowsForms

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:

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 5+ projects will automatically import the .NET Desktop SDK.

.NET Core 3.1 projects need to explicitly target the .NET Desktop SDK to use this property.

Shared settings

• DisableWinExeOutputInference

DisableWinExeOutputInference

Applies to .NET 5 SDK and later.

When an app has the Exe value set for the OutputType property, a console window is created if the app isn't running from a console. This is generally not the desired behavior of a Windows Desktop app. With the WinExe value, a console window isn't created. Starting with the .NET 5 SDK, the Exe value is automatically transformed to WinExe.

The DisableWinExeOutputInference property reverts the behavior of treating Exe as WinExe. Set this value to true to restore the behavior of the OutputType property value of Exe. The default value is false.

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

See also

• .NET project SDKs
• MSBuild reference for .NET SDK projects
• MSBuild schema reference
• Common MSBuild properties
• Customize a build