通过

.NET 桌面 SDK 项目的 MSBuild 参考

  • 项目

这是page使用 .NET 桌面 SDK 配置 Windows 窗体 （WinForms） 和 Windows Presentation Foundation （WPF） 项目的 MSBuild 属性和项的参考。

注意

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

启用 .NET 桌面 SDK

若要使用 WinForms 或 WPF，请在 WinForms 或 WPF 项目的项目文件中指定以下设置：

  • 将 .NET SDK Microsoft.NET.Sdk 作为目标。 有关详细信息，请参阅项目文件。
  • 设置为TargetFramework特定于 Windows 的目标框架名字对象，例如 net8.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>

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 与你的设置冲突的结果。 要解决此问题，请将 EnableDefaultApplicationDefinition 或 EnableDefaultPageItems 设置为 false。 设置这些值可 false 还原到以前的 SDK 的行为，在这些 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 项目会自动导入 .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 项目会自动导入 .NET 桌面 SDK。

另请参阅