Bagikan melalui

Referensi MSBuild untuk proyek .NET Desktop SDK

  • Artikel

Halaman ini adalah referensi untuk properti MSBuild dan item yang Anda gunakan untuk mengonfigurasi proyek Formulir Windows (WinForms) dan Windows Presentation Foundation (WPF) dengan .NET Desktop SDK.

Catatan

Artikel ini mencakup subset properti MSBuild untuk .NET SDK karena berkaitan dengan aplikasi desktop. Untuk daftar properti MSBuild khusus .NET SDK umum, lihat Referensi MSBuild untuk proyek .NET SDK. Untuk daftar properti MSBuild umum, lihat Properti MSBuild Umum.

Aktifkan .NET Desktop SDK

Untuk menggunakan WinForms atau WPF, tentukan pengaturan berikut dalam file proyek proyek WinForms atau proyek WPF Anda:

  • Targetkan .NET SDK Microsoft.NET.Sdk. Untuk informasi selengkapnya, lihat File proyek.
  • Atur TargetFramework ke moniker kerangka kerja target khusus Windows, seperti net8.0-windows.
  • Tambahkan properti kerangka kerja UI (atau keduanya, jika perlu):
    • Atur UseWPF ke true untuk mengimpor dan menggunakan WPF.
    • Atur UseWindowsForms ke true untuk mengimpor dan menggunakan WinForms.
  • (Opsional) Atur OutputType ke WinExe. Pengaturan ini menghasilkan aplikasi dibandingkan dengan pustaka. Untuk menghasilkan pustaka, hilangkan properti ini.
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows</TargetFramework>

    <UseWPF>true</UseWPF>
    <!-- and/or -->
    <UseWindowsForms>true</UseWindowsForms>
  </PropertyGroup>

</Project>

Default WPF mencakup dan mengecualikan

Proyek SDK menentukan sekumpulan aturan untuk secara implisit menyertakan atau mengecualikan file dari proyek. Aturan ini juga secara otomatis mengatur tindakan build file. Perilaku ini tidak seperti proyek .NET Framework non-SDK yang lebih lama, yang tidak memiliki aturan sertakan atau kecualikan default. Proyek .NET Framework mengharuskan Anda untuk secara eksplisit mendeklarasikan file mana yang akan disertakan dalam proyek.

File proyek .NET menyertakan sekumpulan aturan standar untuk memproses file secara otomatis. Proyek WPF menambahkan aturan tambahan.

Tabel berikut menunjukkan elemen dan glob mana yang disertakan dan dikecualikan dalam .NET Desktop SDK saat UseWPF properti proyek diatur ke true:

Elemen Sertakan glob Mengecualikan glob Menghapus glob
ApplicationDefinition App.xaml atau Application.xaml T/A T/A
Page **/*.Xaml **/*.Pengguna; **/*.*Proj; **/*.sln; **/*.vssscc
Setiap XAML yang ditentukan oleh ApplicationDefinition		 T/A
None T/A T/A **/*.Xaml

Berikut adalah pengaturan sertakan dan kecualikan default untuk semua jenis proyek. Untuk mengetahui informasi selengkapnya, lihat Penyertaan dan pengecualian default.

Elemen Sertakan glob Mengecualikan glob Menghapus glob
Compile **/*.Cs; **/*.vb (atau ekstensi bahasa lainnya) **/*.Pengguna; **/*.*Proj; **/*.sln; **/*.vssscc T/A
EmbeddedResource **/*.resx **/*.Pengguna; **/*.*Proj; **/*.sln; **/*.vssscc T/A
None **/* **/*.Pengguna; **/*.*Proj; **/*.sln; **/*.vssscc **/*.Cs; **/*.resx

Jika Anda secara eksplisit menambahkan file ke proyek Anda, atau meminta glob XAML untuk secara otomatis menyertakan file dalam proyek, Anda mungkin mendapatkan salah satu kesalahan berikut:

  • Item duplikat 'ApplicationDefinition' disertakan.
  • Item duplikat 'Page' disertakan.

Kesalahan ini adalah hasil dari implisit Sertakan glob yang bertentangan dengan pengaturan Anda. Untuk mengatasi masalah ini, atur atau EnableDefaultApplicationDefinitionEnableDefaultPageItems ke false. Mengatur nilai-nilai ini untuk false kembali ke perilaku SDK sebelumnya di mana Anda harus secara eksplisit menentukan glob default atau file yang akan disertakan dalam proyek Anda.

Anda dapat sepenuhnya menonaktifkan semua implisit termasuk dengan mengatur EnableDefaultItems properti ke false.

Pengaturan WPF

Untuk informasi tentang pengaturan proyek khusus non-WPF, lihat Referensi MSBuild untuk proyek .NET SDK.

GunakanWPF

Properti UseWPF mengontrol apakah akan menyertakan referensi ke pustaka WPF atau tidak. Pengaturan ini juga mengubah alur MSBuild untuk memproses proyek WPF dan file terkait dengan benar. Nilai defaultnya adalah false. Atur UseWPF properti ke true untuk mengaktifkan dukungan WPF. Anda hanya dapat menargetkan platform Windows ketika properti ini diaktifkan.

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

Ketika properti ini diatur ke true, .NET 5+ proyek secara otomatis mengimpor .NET Desktop SDK.

EnableDefaultApplicationDefinition

Properti EnableDefaultApplicationDefinition mengontrol apakah ApplicationDefinition item secara implisit disertakan dalam proyek. Nilai defaultnya adalah true. Atur EnableDefaultApplicationDefinition properti ke false untuk menonaktifkan penyertaan file implisit.

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

Properti ini mengharuskan EnableDefaultItems properti diatur ke true, yang merupakan pengaturan default.

Aktifkan ItemDefaultPage

Properti EnableDefaultPageItems mengontrol apakah Page item, yang merupakan file .xaml , secara implisit disertakan dalam proyek. Nilai defaultnya adalah true. Atur EnableDefaultPageItems properti ke false untuk menonaktifkan penyertaan file implisit.

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

Properti ini mengharuskan EnableDefaultItems properti diatur ke true, yang merupakan pengaturan default.

pengaturan Formulir Windows

Untuk informasi tentang properti proyek khusus non-WinForms, lihat Referensi MSBuild untuk proyek .NET SDK.

ApplicationDefaultFont

Properti ApplicationDefaultFont menentukan informasi font kustom untuk diterapkan di seluruh aplikasi. Ini mengontrol apakah API yang dihasilkan sumber memancarkan ApplicationConfiguration.Initialize() panggilan ke metode atau Application.SetDefaultFont(Font) tidak. Nilai default adalah string kosong, dan itu berarti font default aplikasi bersumber dari Control.DefaultFont properti .

Nilai yang tidak kosong harus sesuai dengan format yang setara dengan output FontConverter.ConvertTo metode yang dipanggil dengan budaya invarian (yaitu, pemisah daftar=, dan pemisah desimal=.). Formatnya adalah: name, size[units[, style=style1[, style2, ...]]].

<PropertyGroup>
  <ApplicationDefaultFont>Calibri, 11pt, style=regular</ApplicationDefaultFont>
</PropertyGroup>

Properti ini didukung oleh .NET 6 dan versi yang lebih baru, dan Visual Studio 2022 dan versi yang lebih baru.

ApplicationHighDpiMode

Properti ApplicationHighDpiMode menentukan default seluruh aplikasi untuk mode DPI tinggi. Ini mengontrol argumen metode yang dipancarkan Application.SetHighDpiMode(HighDpiMode) oleh API yang dihasilkan ApplicationConfiguration.Initialize() sumber. Nilai defaultnya adalah SystemAware.

<PropertyGroup>
  <ApplicationHighDpiMode>PerMonitorV2</ApplicationHighDpiMode>
</PropertyGroup>

ApplicationHighDpiMode dapat diatur ke salah HighDpiMode satu nilai enum:

Nilai Deskripsi
DpiUnaware Jendela aplikasi tidak menskalakan perubahan DPI dan selalu mengasumsikan faktor skala 100%.
DpiUnawareGdiScaled Mirip DpiUnawaredengan , tetapi meningkatkan kualitas konten berbasis GDI/GDI+.
PerMonitor Jendela memeriksa DPI saat dibuat dan menyesuaikan faktor skala saat DPI berubah.
PerMonitorV2 Mirip PerMonitordengan , tetapi memungkinkan pemberitahuan perubahan DPI jendela anak, peningkatan penskalaan kontrol comctl32, dan penskalaan dialog.
SystemAware Default jika tidak ditentukan.
Jendela mengkueri DPI monitor utama sekali dan menggunakan nilai ini untuk aplikasi pada semua monitor.

Properti ini didukung oleh .NET 6 dan versi yang lebih baru.

ApplicationUseCompatibleTextRendering

Properti ApplicationUseCompatibleTextRendering menentukan default seluruh aplikasi untuk properti yang UseCompatibleTextRendering ditentukan pada kontrol tertentu. Ini mengontrol argumen metode yang dipancarkan Application.SetCompatibleTextRenderingDefault(Boolean) oleh API yang dihasilkan ApplicationConfiguration.Initialize() sumber. Nilai defaultnya adalah false.

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

Properti ini didukung oleh .NET 6 dan versi yang lebih baru.

ApplicationVisualStyles

Properti ApplicationVisualStyles menentukan default seluruh aplikasi untuk mengaktifkan gaya visual. Ini mengontrol apakah API yang dihasilkan sumber memancarkan ApplicationConfiguration.Initialize() panggilan ke Application.EnableVisualStyles(). Nilai defaultnya adalah true.

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

Properti ini didukung oleh .NET 6 dan versi yang lebih baru.

GunakanWindowsForms

Properti UseWindowsForms mengontrol apakah aplikasi Anda dibangun untuk menargetkan Formulir Windows atau tidak. Properti ini mengubah alur MSBuild untuk memproses proyek Formulir Windows dan file terkait dengan benar. Nilai defaultnya adalah false. Atur UseWindowsForms properti ke true untuk mengaktifkan dukungan Formulir Windows. Anda hanya dapat menargetkan platform Windows ketika pengaturan ini diaktifkan.

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

Ketika properti ini diatur ke true, .NET 5+ proyek secara otomatis mengimpor .NET Desktop SDK.

Pengaturan bersama

DisableWinExeOutputInference

Berlaku untuk .NET 5 SDK dan yang lebih baru.

Saat aplikasi memiliki Exe nilai yang ditetapkan untuk OutputType properti , jendela konsol dibuat jika aplikasi tidak berjalan dari konsol. Perilaku ini umumnya tidak diinginkan untuk aplikasi Windows Desktop. WinExe Dengan nilai , jendela konsol tidak dibuat. Dimulai dengan .NET 5 SDK, Exe nilai secara otomatis diubah menjadi WinExe.

Properti DisableWinExeOutputInference mengembalikan perilaku memperlakukan Exe sebagai WinExe. Atur nilai ini ke true untuk memulihkan perilaku OutputType nilai properti .Exe Nilai defaultnya adalah false.

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

Lihat juga