Справочник по MSBuild для проектов пакета SDK для классических приложений .NET

  • Статья

На этой странице приведена ссылка на свойства и элементы MSBuild, используемые для настройки проектов Windows Forms (WinForms) и Windows Presentation Foundation (WPF) с помощью пакета SDK для классических приложений .NET.

Примечание.

В этой статье приведено подмножество свойств MSBuild для пакета SDK для .NET, поскольку он связан с классическими приложениями. Список полезных свойств для проектов .NET см. в статье Справочник по MSBuild для проектов пакета SDK для .NET. Список стандартных свойств см. в статье Общие свойства MSBuild.

Включение пакета SDK для классических приложений .NET

Чтобы использовать WinForms или WPF, укажите следующие параметры в файле проекта WinForms или WPF:

  • Выполните нацеливание для Microsoft.NET.Sdk пакета SDK для .NET. Дополнительные сведения см. в разделе Файлы проекта.
  • Задайте TargetFramework для конкретной целевой платформы Windows моникер, например net8.0-windows.
  • При необходимости добавьте свойство платформы пользовательского интерфейса (или оба):
    • Присвойте параметру 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 добавляют дополнительные правила.

В следующей таблице показано, какие элементы и стандартные маски включены в пакет SDK для классических приложений .NET и исключены из него, когда свойству проекта UseWPF задано значение true:

Элемент Стандартная маска включения Стандартная маска исключения Стандартная маска удаления
ApplicationDefinition App.xaml или Application.xaml Неприменимо Неприменимо
Page **/*.Xaml **/*.Пользователя; **/*.*Proj; **/*.Sln; **/*.Vssscc
Любой XAML, определенный ApplicationDefinition		 Неприменимо
None Н/Д Неприменимо **/*.Xaml

Ниже приведены параметры включения и исключения по умолчанию для всех типов проектов. Дополнительные сведения см. в разделе Включения и исключения по умолчанию.

Элемент Стандартная маска включения Стандартная маска исключения Стандартная маска удаления
Compile **/*.Cs; **/*.vb (или другие расширения языка) **/*.Пользователя; **/*.*Proj; **/*.Sln; **/*.Vssscc Н/П
EmbeddedResource **/*.Resx **/*.Пользователя; **/*.*Proj; **/*.Sln; **/*.Vssscc Н/П
None **/* **/*.Пользователя; **/*.*Proj; **/*.Sln; **/*.Vssscc **/*.Cs; **/*.Resx

Если вы явно добавили файлы в проект или используете стандартные маски XAML для автоматического включения файлов в проект, может возникать одна из следующих ошибок:

  • Включены дублирующиеся элементы "ApplicationDefinition".
  • Включены дублирующиеся элементы "Page".

Эти ошибки являются результатом неявного включения стандартных масок, конфликтующих с вашими настройками. Чтобы обойти эту проблему, задайте параметру EnableDefaultApplicationDefinition или EnableDefaultPageItems значение false. Задайте эти значения false отменить изменения для поведения предыдущих пакетов SDK, в которых необходимо явно определить стандартные глобы или файлы, которые необходимо включить в проект.

Все неявные включения можно полностью отключить, установив для свойства EnableDefaultItems значение false.

Параметры WPF

Дополнительные сведения о параметрах проектов, отличных от WPF, см. в разделе Справочник по MSBuild для проектов пакета SDK для .NET.

UseWPF

Свойство UseWPF определяет, следует ли включать ссылки на библиотеки WPF. Этот параметр также изменяет конвейер MSBuild для правильной обработки проекта WPF и связанных файлов. Значение по умолчанию — false. Задайте для свойства UseWPF значение true, чтобы включить поддержку WPF. Выполнить нацеливание на платформу Windows можно только в том случае, если это свойство включено.

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

Если для этого свойства задано trueзначение , проекты .NET 5+ автоматически импортируют пакет SDK для классических приложений .NET.

EnableDefaultApplicationDefinition

Свойство EnableDefaultApplicationDefinition определяет, включаются ли в проект неявным образом элементы ApplicationDefinition. Значение по умолчанию — true. Задайте значение false для свойства EnableDefaultApplicationDefinition, чтобы отключить неявные включения файлов.

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

Для этого свойства требуется, чтобы EnableDefaultItems для свойства задано trueзначение , которое является параметром по умолчанию.

EnableDefaultPageItems

Свойство EnableDefaultPageItems определяет, включаются ли в проект неявным образом элементы Page, которые являются файлами .xaml. Значение по умолчанию — true. Задайте значение false для свойства EnableDefaultPageItems, чтобы отключить неявные включения файлов.

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

Для этого свойства требуется, чтобы EnableDefaultItems для свойства задано trueзначение , которое является параметром по умолчанию.

Параметры Windows Forms

Дополнительные сведения о свойствах проектов, отличных от WinForms, см. в разделе Справочник по MSBuild для проектов пакета SDK для .NET.

ApplicationDefaultFont

Свойство ApplicationDefaultFont указывает сведения о пользовательских шрифтах, которые будут применены ко всему приложению. Оно определяет, будет ли созданный код API ApplicationConfiguration.Initialize() выполнять вызов метода 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 задает значение по умолчанию на уровне приложения для режима высокого разрешения. Оно управляет аргументом метода Application.SetHighDpiMode(HighDpiMode), который будет применять созданный код API ApplicationConfiguration.Initialize(). Значение по умолчанию — 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, определенного для некоторых элементов управления. Оно управляет аргументом метода Application.SetCompatibleTextRenderingDefault(Boolean), который будет применять созданный код API ApplicationConfiguration.Initialize(). Значение по умолчанию — false.

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

Это свойство поддерживается в .NET 6 и более поздних версий.

ApplicationVisualStyles

Свойство ApplicationVisualStyles задает значение по умолчанию на уровне приложения для включения визуальных стилей. Оно определяет, будет ли созданный код API ApplicationConfiguration.Initialize() выполнять вызов Application.EnableVisualStyles(). Значение по умолчанию — true.

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

Это свойство поддерживается в .NET 6 и более поздних версий.

UseWindowsForms

Свойство UseWindowsForms определяет, предназначено ли приложение для Windows Forms. Это свойство изменяет конвейер MSBuild соответствующим образом для правильной обработки Windows Forms проекта и связанных файлов. Значение по умолчанию — false. Задайте для свойства UseWindowsForms значение true, чтобы включить поддержку Windows Forms. Выполнить нацеливание на платформу Windows можно только в том случае, если этот параметр включен.

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

Если для этого свойства задано trueзначение , проекты .NET 5+ автоматически импортируют пакет SDK для классических приложений .NET.

Общие параметры

DisableWinExeOutputInference

Применимо к пакету SDK для .NET 5 и более поздних версий.

Если в приложении свойству OutputType присвоено значение Exe, создается окно консоли, если приложение не запускается из консоли. Это поведение обычно не рекомендуется для классического приложения Windows. Если присвоено значение WinExe, окно консоли не создается. Начиная с пакета SDK для .NET 5 значение Exe автоматически преобразуется в WinExe.

Свойство DisableWinExeOutputInference возвращает поведение при обработке Exe как WinExe. Присвойте этому параметру значение true, чтобы восстановить поведение значения свойства OutputType для Exe. Значение по умолчанию — false.

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

См. также