.NET 桌面 SDK 项目的 MSBuild 参考

此页是有关用于通过 .NET 桌面 SDK 配置 Windows 窗体 (WinForms) 和 Windows Presentation Foundation (WPF) 项目的 MSBuild 属性和项的参考。

注意

本文介绍了 .NET SDK 的 MSBuild 属性的子集,因为它与桌面应用相关。 有关常用 .NET SDK 特定 MSBuild 属性的列表,请参见 .NET SDK 项目的 MSBuild 参考。 有关通用 MSBuild 属性的列表,请参阅通用 MSBuild 属性

启用 .NET 桌面 SDK

若要使用 WinForms 或 WPF,请配置你的项目文件。

.NET 5 及更高版本

在 WinForms 或 WPF 项目的项目文件中指定以下设置:

  • 将 .NET SDK Microsoft.NET.Sdk 作为目标。 有关详细信息,请参阅项目文件
  • TargetFramework 设置为特定于 Windows 的目标框架名字对象,比如 net6.0-windows
  • 添加 UI 框架属性(或两者,如果必要):
    • UseWPF 设置为 true 以导入并使用 WPF。
    • UseWindowsForms 设置为 true 以导入并使用 WinForms。
  • (可选)将 OutputType 设置为 WinExe。 这将生成应用,而不是库。 若要生成库,请省略此属性。
<Project Sdk="Microsoft.NET.Sdk">

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

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

</Project>

.NET Core 3.1

在 WinForms 或 WPF 项目的项目文件中指定以下设置:

  • 将 .NET SDK Microsoft.NET.Sdk.WindowsDesktop 作为目标。 有关详细信息,请参阅项目文件
  • TargetFramework 设置为 netcoreapp3.1
  • 添加 UI 框架属性(或两者,如果必要):
    • UseWPF 设置为 true 以导入并使用 WPF。
    • UseWindowsForms 设置为 true 以导入并使用 WinForms。
  • (可选)将 OutputType 设置为 WinExe。 这将生成应用,而不是库。 若要生成库,请省略此属性。
<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 默认包含和排除的内容

SDK 项目定义一组规则,用于在项目中隐式包含或排除文件。 这些规则还自动设置文件的生成操作。 这与较旧的非 SDK .NET Framework 项目不同,后者没有默认的包含或排除规则。 .NET Framework 项目需要你显式声明要将哪些文件包含在项目中。

.NET 项目文件包括一组标准规则,用于自动处理文件。 WPF 项目添加了更多规则。

下表显示当 UseWPF 项目属性设置为 true 时在 .NET 桌面 SDK 中包含和排除哪些元素和 glob

元素 包含 glob 排除 glob 删除 glob
ApplicationDefinition App.xaml 或 Application.xaml 不适用 空值
Page **/*.xaml **/*.user; **/*.*proj; **/*.sln; **/*.vssscc
ApplicationDefinition 定义的任何 XAML
空值
None 空值 空值 **/*.xaml

下面是所有项目类型的默认包含和排除设置。 有关详细信息,请参阅默认的包括和排除

元素 包含 glob 排除 glob 删除 glob
Compile **/*.cs; **/*.vb (or other language extensions) **/*.user; **/*.*proj; **/*.sln; **/*.vssscc 空值
EmbeddedResource **/*.resx **/*.user; **/*.*proj; **/*.sln; **/*.vssscc 空值
None **/* **/*.user; **/*.*proj; **/*.sln; **/*.vssscc **/*.cs; **/*.resx

如果已将文件显式添加到项目,或让 XAML glob 自动将文件包含在项目中,则可能会收到以下错误之一:

  • 包含重复的“ApplicationDefinition”项。
  • 包含重复的“Page”项。

这些错误是隐式包含 glob 与你的设置冲突的结果。 要解决此问题,请将 EnableDefaultApplicationDefinitionEnableDefaultPageItems 设置为 false。 将这些值设置为 false 会恢复到以前 SDK 的行为,其中你必须在项目中显式定义默认 glob,或者显式定义要包括在项目中的文件。

可以通过将 EnableDefaultItems 属性设置为 false 来完全禁用所有隐式包含。

WPF 设置

有关非特定于 WPF 的项目设置的信息,请参阅 .NET SDK 项目的 MSBuild 参考

UseWPF

UseWPF 属性控制是否包含对 WPF 库的引用。 这还会更改 MSBuild 管道,以便正确处理 WPF 项目和相关文件。 默认值为 false。 将 UseWPF 属性设置为 true 以启用 WPF 支持。 仅当启用了此属性时,才能将 Windows 平台作为目标。

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

如果将此属性设置为 true,则 .NET 5+ 项目会自动导入 .NET 桌面 SDK

.NET Core 3.1 项目需要将 .NET 桌面 SDK 显式设为目标才能使用此属性。

EnableDefaultApplicationDefinition

EnableDefaultApplicationDefinition 属性控制是否在项目中隐式包含 ApplicationDefinition 项。 默认值为 true。 若要禁用隐式文件包含,请将 EnableDefaultApplicationDefinition 属性设置为 false

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

此属性要求将 EnableDefaultItems 属性设置为 true,这是默认设置。

EnableDefaultPageItems

EnableDefaultPageItems 属性控制是否在项目中隐式包含 Page 项(即 .xaml 文件)。 默认值为 true。 若要禁用隐式文件包含,请将 EnableDefaultPageItems 属性设置为 false

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

此属性要求将 EnableDefaultItems 属性设置为 true,这是默认设置。

Windows 窗体设置

有关非特定于 WinForms 的项目属性的信息,请参阅 .NET SDK 项目的 MSBuild 参考

ApplicationDefaultFont

ApplicationDefaultFont 属性指定要在应用程序范围内应用的自定义字体信息。 它控制源生成的 ApplicationConfiguration.Initialize() API 是否发出对 Application.SetDefaultFont(Font) 方法的调用。 默认值为空字符串,这意味着应用程序默认字体来源于 Control.DefaultFont 属性。

非空值必须符合与以下相同的格式:通过固定区域性调用的 FontConverter.ConvertTo 方法(即,列表分隔符为 , 且十进制分隔符为 .)。 格式为:name, size[units[, style=style1[, style2, ...]]]

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

.NET 6 及更高版本和 Visual Studio 2022 及更高版本支持此属性。

ApplicationHighDpiMode

ApplicationHighDpiMode 属性为高 DPI 模式指定应用程序范围内的默认值。 它控制由源生成的 ApplicationConfiguration.Initialize() API 发出的 Application.SetHighDpiMode(HighDpiMode) 方法的参数。 默认值是 SystemAware

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

ApplicationHighDpiMode 可设置为 HighDpiMode 枚举值之一:

“值” 说明
DpiUnaware 应用程序窗口不会随着 DPI 更改而缩放,始终假定缩放比例为 100%。
DpiUnawareGdiScaled 类似于 DpiUnaware,但提高了基于 GDI/GDI+ 的内容的质量。
PerMonitor 此窗口会在创建 DPI 时对其进行检查,并在 DPI 更改时调整缩放比例。
PerMonitorV2 类似于 PerMonitor,但启用了子窗口 DPI 更改通知、comctl32 控件的改进缩放和对话框缩放。
SystemAware 如果未指定,则为默认值。
此窗口会查询一次主监视器的 DPI,并将其用于所有监视器上的应用程序。

.NET 6 及更高版本支持此属性。

ApplicationUseCompatibleTextRendering

ApplicationUseCompatibleTextRendering 属性为某些控件上定义的 UseCompatibleTextRendering 属性指定应用程序范围内的默认值。 它控制由源生成的 ApplicationConfiguration.Initialize() API 发出的 Application.SetCompatibleTextRenderingDefault(Boolean) 方法的参数。 默认值是 false

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

.NET 6 及更高版本支持此属性。

ApplicationVisualStyles

ApplicationVisualStyles 属性指定应用程序范围内的默认值来启用视觉样式。 它控制源生成的 ApplicationConfiguration.Initialize() API 是否发出对 Application.EnableVisualStyles() 的调用。 默认值是 true

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

.NET 6 及更高版本支持此属性。

UseWindowsForms

UseWindowsForms 属性控制应用程序是否构建为以 Windows 窗体作为目标。 此属性会更改 MSBuild 管道,以便正确处理 Windows 窗体项目和相关文件。 默认值为 false。 将 UseWindowsForms 属性设置为 true 可启用 Windows 窗体支持。 仅当启用了此设置时,才能将 Windows 平台作为目标。

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

如果将此属性设置为 true,则 .NET 5+ 项目会自动导入 .NET 桌面 SDK

.NET Core 3.1 项目需要将 .NET 桌面 SDK 显式设为目标才能使用此属性。

共享设置

DisableWinExeOutputInference

适用于 .NET 5 SDK 及更高版本。

当应用的 OutputType 属性设置为 Exe 值时,如果该应用未从控制台运行,则将创建一个控制台窗口。 这通常不是所需的 Windows 桌面应用行为。 如果使用 WinExe 值,则不会创建控制台窗口。 从 .NET 5 SDK 开始,Exe 值会自动转换为 WinExe

DisableWinExeOutputInference 属性会还原将 Exe 视为 WinExe 的行为。 将此值设置为 true 可还原 OutputType 属性值 Exe 的行为。 默认值为 false

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

请参阅