.NET 데스크톱 SDK 프로젝트의 MSBuild 참조

  • 아티클

이 페이지는 .NET 데스크톱 SDK를 사용하여 WinForms(Windows Forms) 및 WPF(Windows Presentation Foundation) 프로젝트를 구성하는 데 사용하는 MSBuild 속성 및 항목의 참조입니다.

참고 항목

이 문서에서는 데스크톱 앱과 관련된 .NET SDK의 MSBuild 속성 하위 집합을 설명합니다. 일반적인 .NET SDK 관련 MSBuild 속성 목록은 .NET SDK 프로젝트의 MSBuild 참조를 참조하세요. 일반적인 MSBuild 속성의 목록을 보려면 일반 MSBuild 속성을 참조하세요.

.NET 데스크톱 SDK 사용

WinForms 또는 WPF를 사용하려면 WinForms 또는 WPF 프로젝트의 프로젝트 파일에서 다음 설정을 지정합니다.

  • .NET SDK Microsoft.NET.Sdk를 대상으로 지정합니다. 자세한 내용은 프로젝트 파일을 참조하세요.
  • Windows 관련 대상 프레임워크 모니커(예: .)로 net8.0-windows설정합니다TargetFramework.
  • 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 (또는 기타 언어 확장) **/*.user; **/*.*proj; **/*.sln; **/*.vssscc 해당 없음
EmbeddedResource **/*.resx **/*.user; **/*.*proj; **/*.sln; **/*.vssscc 해당 없음
None **/* **/*.user; **/*.*proj; **/*.sln; **/*.vssscc **/*.cs; **/*.resx

프로젝트에 파일을 명시적으로 추가했거나 XAML GLOB가 프로젝트에 파일을 자동으로 포함하도록 하려면 다음 오류 중 하나가 발생할 수 있습니다.

  • 중복 ‘ApplicationDefinition’ 항목이 포함되었습니다.
  • 중복 ‘Page’ 항목이 포함되었습니다.

해당 오류는 설정과 충돌하는 암시적 Include GLOB의 결과입니다. 이 문제를 해결하려면 EnableDefaultApplicationDefinition 또는 EnableDefaultPageItems를 false로 설정합니다. 이러한 값을 false 되돌리기 기본 GLOB 또는 프로젝트에 포함할 파일을 명시적으로 정의해야 하는 이전 SDK의 동작으로 설정합니다.

EnableDefaultItems 속성을 false로 설정하여 모든 암시적 포함을 완전히 사용하지 않도록 설정할 수 있습니다.

WPF 설정

비 WPF 관련 프로젝트 설정에 관한 자세한 내용은 .NET SDK 프로젝트의 MSBuild 참조를 참조하세요.

UseWPF

UseWPF 속성은 WPF 라이브러리에 대한 참조를 포함할지 여부를 제어합니다. 또한 이 설정은 WPF 프로젝트 및 관련 파일을 올바르게 처리하도록 MSBuild 파이프라인을 변경합니다. 기본값은 false입니다. UseWPF 속성을 true로 설정하여 WPF 지원을 사용하도록 설정합니다. 해당 속성을 사용하는 경우 Windows 플랫폼만 대상으로 지정할 수 있습니다.

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

이 속성이 설정true되면 .NET 5+ 프로젝트는 자동으로 .NET Desktop SDK를 가져옵니다.

EnableDefaultApplicationDefinition

EnableDefaultApplicationDefinition 속성은 ApplicationDefinition 항목을 프로젝트에 암시적으로 포함할지 여부를 제어합니다. 기본값은 true입니다. EnableDefaultApplicationDefinition 속성을 false로 설정하여 암시적 파일 포함을 사용하지 않도록 설정합니다.

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

해당 속성을 사용하려면 EnableDefaultItems 속성을 기본 설정인 true로 설정해야 합니다.

EnableDefaultPageItems

EnableDefaultPageItems 속성은 .xaml 파일인 Page 항목이 프로젝트에 암시적으로 포함되는지 여부를 제어합니다. 기본값은 true입니다. EnableDefaultPageItems 속성을 false로 설정하여 암시적 파일 포함을 사용하지 않도록 설정합니다.

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

해당 속성을 사용하려면 EnableDefaultItems 속성을 기본 설정인 true로 설정해야 합니다.

Windows Forms 설정

비 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를 확인하고 DPI가 변경될 때 배율을 크기를 조정합니다.
PerMonitorV2 PerMonitor와 비슷하지만 자식 창 DPI 변경 알림, comctl32.dll 컨트롤 크기 조정 개선, 대화 상자 크기 조정이 가능합니다.
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 Forms를 대상으로 하도록 빌드되는지 여부를 제어합니다. 해당 속성은 MSBuild 파이프라인을 변경하여 Windows Forms 프로젝트 및 관련 파일을 올바르게 처리합니다. 기본값은 false입니다. UseWindowsForms 속성을 true로 설정하여 Windows Forms 지원을 사용하도록 설정합니다. 해당 설정을 사용하는 경우 Windows 플랫폼만 대상으로 지정할 수 있습니다.

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

이 속성이 설정true되면 .NET 5+ 프로젝트는 자동으로 .NET Desktop SDK를 가져옵니다.

공유 설정

DisableWinExeOutputInference

.NET 5 SDK 이상에 적용됩니다.

앱에서 OutputType 속성에 Exe 값이 설정되어 있을 때 앱이 콘솔에서 실행되고 있지 않으면 콘솔 창이 만들어집니다. 이 동작은 일반적으로 Windows 데스크톱 앱에 적합하지 않습니다. WinExe 값을 사용하면 콘솔 창이 생성되지 않습니다. .NET 5 SDK부터는 Exe 값이 WinExe로 자동으로 변환됩니다.

DisableWinExeOutputInference 속성은 Exe를 WinExe로 처리하는 동작을 되돌립니다. 해당 값을 true로 설정하여 Exe의 OutputType 속성 값 동작을 복원합니다. 기본값은 false입니다.

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

참고 항목