.NET Desktop SDK 專案的 MSBuild 參考

  • 發行項

此頁面是 MSBuild 屬性和項目參考，您可以搭配 .NET Desktop SDK 來設定 Windows Forms (WinForms) 和 Windows Presentation Foundation (WPF) 專案。

注意

本文記載 .NET SDK 與傳統型應用程式相關的部分 MSBuild 屬性。 如需一般 .NET SDK 特定 MSBuild 屬性的清單，請參閱 .NET SDK 專案的 MSBuild 參考。 如需一般 MSBuild 屬性清單，請參閱一般 MSBuild 屬性。

啟用 .NET Desktop SDK

若要使用 WinForms 或 WPF，請設定專案檔。

.NET 5.0 與更新版本

在 WinForms 或 WPF 專案的專案檔中，指定下列設定：

  • 以 .NET SDK Microsoft.NET.Sdk 為目標。 如需詳細資訊，請參閱專案檔。
  • 將 TargetFramework 設定為 Windows 特定的目標架構 Moniker，例如 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 預設 include 和 exclude

SDK 專案會定義一組規則，以隱含地包含或排除專案中的檔案。 這些規則也會自動設定檔案的建置動作。 這與較舊的非 SDK .NET Framework 專案不同，這些專案沒有預設包含或排除規則。 .NET Framework 專案需要您明確宣告要包含在專案中的檔案。

.NET 專案檔包含一組標準規則，可自動處理檔案。 WPF 專案會新增其他規則。

下表顯示當 UseWPF 專案屬性設定為 true 時，在 .NET Desktop SDK 中包含和排除哪些元素和 glob：

Element 包含 Glob 排除 Glob 移除 Glob
ApplicationDefinition App.xaml 或 Application.xaml N/A N/A
Page **/*.xaml **/*.user；**/*.*proj；**/*.sln；**/*.vssscc
由 ApplicationDefinition　定義的任何 XAML		 N/A
None N/A N/A **/*.xaml

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

Element 包含 Glob 排除 Glob 移除 Glob
Compile **/*.cs；**/*.vb (或其他語言副檔名) **/*.user；**/*.*proj；**/*.sln；**/*.vssscc N/A
EmbeddedResource **/*.resx **/*.user；**/*.*proj；**/*.sln；**/*.vssscc N/A
None **/* **/*.user；**/*.*proj；**/*.sln；**/*.vssscc **/*.cs；**/*.resx

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

  • 包含了重複的 'ApplicationDefinition' 項目。
  • 包含了重複的 'Page' 項目。

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

您可以將 EnableDefaultItems 屬性設定為 false，完全停用所有隱含 include。

WPF 設定

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

UseWPF

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

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

當此屬性設定為 true 時，.NET 5+ 專案會自動匯入 .NET Desktop SDK。

.NET Core 3.1 專案必須明確地以 .NET Desktop 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 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 列舉值：

值 Description
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 專案和相關檔案。 預設值是 false。 將 UseWindowsForms 屬性設定為 true，以啟用 Windows Forms 支援。 啟用此設定時，您只能以 Windows 平台為目標。

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

當此屬性設定為 true 時，.NET 5+ 專案會自動匯入 .NET Desktop SDK。

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

共用設定

DisableWinExeOutputInference

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

當應用程式設定 OutputType 屬性的 Exe 值時，如果應用程式不是從主控台執行，就會建立主控台視窗。 這通常不是 Windows 傳統型應用程式的預期行為。 使用 WinExe 值時，不會建立主控台視窗。 從 .NET 5 SDK 開始，Exe 值會自動轉換成 WinExe。

DisableWinExeOutputInference 屬性會還原將 Exe 視為 WinExe 的行為。 將此值設定為 true，以還原 ExeOutputType 屬性值的行為。 預設值是 false。

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

另請參閱