.net Desktop SDK 專案的 MSBuild 參考

此頁面是 MSBuild 屬性和專案的參考,您可用來設定 Windows Forms (WinForms) 和使用 .net 桌面 SDK Windows Presentation Foundation WPF (專案。

注意

本文說明 .net SDK 的 MSBuild 屬性子集,因為它與桌面應用程式相關。 如需常見 .net sdk 特定 MSBuild 屬性的清單,請參閱.net sdk 專案 MSBuild 參考。 如需常見的 MSBuild 屬性清單,請參閱常見的 MSBuild 屬性

啟用 .NET 桌面 SDK

若要使用 WinForms 或 WPF,請設定您的專案檔。

.NET 5 和更新版本

在 WinForms 或 WPF 專案的專案檔中,指定下列設定:

  • 以 .NET SDK Microsoft.NET.Sdk 為目標。 如需詳細資訊,請參閱Project檔案。
  • 設定 TargetFramework 為 Windows 特定的目標 framework 標記,例如 net6.0-windows
  • 如有必要,請新增 UI 架構屬性 (或兩者) :
    • 設定 UseWPFtrue 以匯入和使用 WPF。
    • 將設定 UseWindowsFormstrue ,以匯入並使用 WinForms。
  • (選擇性) 設定 OutputTypeWinExe 。 這會產生應用程式,而不是程式庫。 若要產生程式庫,請省略此屬性。
<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

在 WinForms 或 WPF 專案的專案檔中,指定下列設定:

  • 以 .NET SDK Microsoft.NET.Sdk.WindowsDesktop 為目標。 如需詳細資訊,請參閱Project檔案。
  • TargetFramework 設定為 netcoreapp3.1
  • 如有必要,請新增 UI 架構屬性 (或兩者) :
    • 設定 UseWPFtrue 以匯入和使用 WPF。
    • 將設定 UseWindowsFormstrue ,以匯入並使用 WinForms。
  • (選擇性) 設定 OutputTypeWinExe 。 這會產生應用程式,而不是程式庫。 若要產生程式庫,請省略此屬性。
<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 專案會新增其他規則。

下表顯示當專案屬性設定為 true ,.NET 桌面 SDK 中包含和排除的元素和glob

元素 包含 Glob 排除 Glob 移除 Glob
ApplicationDefinition App.xaml 或 Application.xaml N/A N/A
Page * */* .xaml * */*. 使用者;* */*. * proj;* */* .sln;* */*. >.vssscc
定義的任何 XAML ApplicationDefinition
N/A
None N/A N/A * */* .xaml

以下是所有專案類型的預設包含和排除設定。 如需詳細資訊,請參閱 預設包含和排除

元素 包含 Glob 排除 Glob 移除 Glob
Compile * */* .cs;* */* .vb (或其他語言延伸模組) * */*. 使用者;* */*. * proj;* */* .sln;* */*. >.vssscc N/A
EmbeddedResource * */* .resx * */*. 使用者;* */*. * proj;* */* .sln;* */*. >.vssscc N/A
None **/* * */*. 使用者;* */*. * proj;* */* .sln;* */*. >.vssscc * */* .cs;* */* .resx

如果您明確地將檔案新增至專案,或讓 XAML glob 自動將檔案包含在您的專案中,您可能會收到下列其中一個錯誤:

  • 包含重複的 ' ApplicationDefinition ' 專案。
  • 包含重複的 ' Page ' 專案。

這些錯誤是隱含 包含 glob 與您的設定衝突的結果。 若要解決這個問題,請將或 EnableDefaultPageItemsEnableDefaultApplicationDefinitionfalse 。 將這些值設定為 false 會還原為先前 sdk 的行為,而您必須在專案中明確定義預設 glob,或明確地定義要包含在專案中的檔案。

您可以藉由將屬性設定false ,來完全停用所有隱含的包含。

WPF 設定

如需非 WPF 特定專案設定的詳細資訊,請參閱.net SDK 專案的 MSBuild 參考

UseWPF

UseWPF屬性控制是否要包含 WPF 程式庫的參考。 這也會改變 MSBuild 管線,以正確處理 WPF 專案和相關檔案。 預設值是 falseUseWPF將屬性設為 true ,以啟用 WPF 支援。 當啟用這個屬性時,您只能以 Windows 平臺為目標。

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

當這個屬性設定為 true 時,.net 5 + 專案將會自動匯入 true

.NET Core 3.1 專案必須明確地以 .Net 桌面 SDK 為目標,才能使用此屬性。

EnableDefaultApplicationDefinition

EnableDefaultApplicationDefinition屬性會控制專案中是否 ApplicationDefinition 隱含包含專案。 預設值是 trueEnableDefaultApplicationDefinition將屬性設為 false ,以停用隱含檔案包含。

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

這個屬性會要求 property屬性(property)設定為 true ,這是預設設定。

EnableDefault Page 專案

EnableDefaultPageItems屬性會控制專案(也就是EnableDefaultPageItems檔案)是否 Page 會隱含地包含在專案中。 預設值是 trueEnableDefaultPageItems將屬性設為 false ,以停用隱含檔案包含。

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

這個屬性會要求 property屬性(property)設定為 true ,這是預設設定。

Windows Forms 設定

如需非 WinForms 特定專案屬性的詳細資訊,請參閱.net SDK 專案 MSBuild 參考

ApplicationDefaultFont

ApplicationDefaultFont屬性會指定要套用至整個應用程式的自訂字型資訊。 它會控制來源產生 ApplicationConfiguration.Initialize() 的 API 是否發出呼叫方法的呼叫 Application.SetDefaultFont(Font) 。 預設值為空字串,表示應用程式預設字型源自 Control.DefaultFont 于屬性。

非空白的值必須符合相當於以不因文化特性( FontConverter.ConvertTo )所叫用之方法的輸出 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 Forms 所建立。 這個屬性會改變 MSBuild 管線,以正確處理 Windows Forms 專案和相關檔案。 預設值是 falseUseWindowsForms將屬性設為 true ,以啟用 Windows Forms 支援。 當啟用此設定時,您只能以 Windows 平臺為目標。

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

當這個屬性設定為 true 時,.net 5 + 專案將會自動匯入 true

.NET Core 3.1 專案必須明確地以 .Net 桌面 SDK 為目標,才能使用此屬性。

共用設定

DisableWinExeOutputInference

適用于 .NET 5 SDK 和更新版本。

當應用程式已設定 OutputType 屬性的 Exe 值時,如果應用程式不是從主控台執行,則會建立主控台視窗。 這通常不是 Windows 桌面應用程式所需的行為。 使用此 WinExe 值時,不會建立主控台視窗。 從 .NET 5 SDK 開始, Exe 值會自動轉換為 WinExe

DisableWinExeOutputInference屬性會還原視為 ExeWinExe 的行為。 將此值設定為 true ,以還原屬性值 Exe 的行為 OutputType 。 預設值是 false

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

另請參閱