Referencia de MSBuild para proyectos del SDK de Escritorio de .NET

  • Artículo

Se trata page de una referencia para las propiedades y elementos de MSBuild que se usan para configurar proyectos de Windows Forms (WinForms) y Windows Presentation Foundation (WPF) con el SDK de escritorio de .NET.

Nota:

En este artículo se documenta un subconjunto de las propiedades de MSBuild para el SDK de .NET en lo que se refiere a las aplicaciones de escritorio. Para obtener una lista de propiedades de MSBuild específicas del SDK de .NET, vea Referencia de MSBuild para proyectos de SDK de .NET. Para obtener una lista de las propiedades comunes de MSBuild, vea Propiedades comunes de MSBuild.

Habilitación del SDK de Escritorio de .NET

Para usar WinForms o WPF, especifique la siguiente configuración en el archivo de proyecto del proyecto de su proyecto winForms o WPF:

  • Seleccione como destino el SDK Microsoft.NET.Sdk de .NET. Para obtener más información, vea Archivos del proyecto.
  • Establézcalo TargetFramework en un moniker de la plataforma de destino específico de Windows, como net8.0-windows.
  • Agregue una propiedad de marco de interfaz de usuario (o ambas, si es necesario):
    • Establezca UseWPF en true para importar y usar WPF.
    • Establezca UseWindowsForms en true para importar y usar WinForms.
  • (Opcional) Establezca OutputType en WinExe. Esta configuración genera una aplicación en lugar de una biblioteca. Para generar una biblioteca, omita esta propiedad.
<Project Sdk="Microsoft.NET.Sdk">

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

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

</Project>

Inclusiones y exclusiones predeterminadas de WPF

Los proyectos de SDK definen un conjunto de reglas para incluir o excluir archivos del proyecto de forma implícita. Estas reglas también establecen automáticamente la acción de compilación del archivo. Este comportamiento es diferente de los proyectos anteriores de .NET Framework que no son del SDK, que no tienen reglas de inclusión o exclusión predeterminadas. En los proyectos de .NET Framework es necesario declarar de forma explícita los archivos que se van a incluir en el proyecto.

Los archivos del proyecto de .NET incluyen un conjunto estándar de reglas para el procesamiento automático de los archivos. Los proyectos de WPF agregan reglas adicionales.

En la tabla siguiente se muestra qué elementos y qué patrones globales se incluyen y excluyen en el SDK de Escritorio de .NET cuando la propiedad del proyecto UseWPF se establece en true:

Elemento Glob para incluir Glob para excluir Glob para quitar
ApplicationDefinition App.xaml o Application.xaml N/D N/D
Page **/*.xaml **/*.user; **/*.*proj; **/*.sln; **/*.vssscc
Cualquier XAML definido por ApplicationDefinition		 N/D
None N/D N/D **/*.xaml

Estos son los valores de configuración de las inclusiones y exclusiones predeterminadas para todos los tipos de proyecto. Para obtener más información, consulte Inclusiones y exclusiones predeterminadas.

Elemento Glob para incluir Glob para excluir Glob para quitar
Compile **/*.cs; **/*.vb (o extensiones de otros lenguajes) **/*.user; **/*.*proj; **/*.sln; **/*.vssscc N/D
EmbeddedResource **/*.resx **/*.user; **/*.*proj; **/*.sln; **/*.vssscc N/D
None **/* **/*.user; **/*.*proj; **/*.sln; **/*.vssscc **/*.cs; **/*.resx

Si ha agregado archivos de forma explícita al proyecto, o bien si tiene patrones globales de XAML para incluir archivos automáticamente en el proyecto, es posible que se produzca uno de los errores siguientes:

  • Se han incluido elementos "ApplicationDefinition" duplicados.
  • Se han incluido elementos "Page" duplicados.

Estos errores son el resultado de patrones globales Include implícitos en conflicto con la configuración. Para solucionar temporalmente este problema, establezca EnableDefaultApplicationDefinition o EnableDefaultPageItems en false. Establecer estos valores para false revertir al comportamiento de los SDK anteriores en los que tenía que definir explícitamente los globs predeterminados o los archivos que se van a incluir en el proyecto.

Puede deshabilitar completamente todas las inclusiones implícitas si establece la propiedad EnableDefaultItems en false.

Configuración de WPF

Para obtener información sobre la configuración de proyectos no específicos de WPF, vea Referencia de MSBuild para los proyectos del SDK de .NET.

UseWPF

La propiedad UseWPF controla si se deben incluir o no referencias a las bibliotecas de WPF. Esta configuración también modifica la canalización de MSBuild para procesar correctamente un proyecto de WPF y archivos relacionados. El valor predeterminado es false. Establezca la propiedad UseWPF en true para habilitar la compatibilidad con WPF. Cuando esta propiedad está habilitada, solo puede seleccionar como destino la plataforma Windows.

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

Cuando esta propiedad se establece trueen , los proyectos de .NET importan automáticamente el SDK de escritorio de .NET.

EnableDefaultApplicationDefinition

La propiedad EnableDefaultApplicationDefinition controla si los elementos ApplicationDefinition se incluyen en el proyecto de forma implícita. El valor predeterminado es true. Establezca la propiedad EnableDefaultApplicationDefinition en false para deshabilitar la inclusión de archivos implícita.

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

Esta propiedad necesita que la propiedad EnableDefaultItems esté establecida en true, que es el valor de configuración predeterminado.

EnableDefaultPageItems

La propiedad EnableDefaultPageItems controla si los elementos Page, que son archivos .xaml, se incluyen en el proyecto de forma implícita. El valor predeterminado es true. Establezca la propiedad EnableDefaultPageItems en false para deshabilitar la inclusión de archivos implícita.

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

Esta propiedad necesita que la propiedad EnableDefaultItems esté establecida en true, que es el valor de configuración predeterminado.

Configuración de Windows Forms

Para obtener información sobre las propiedades de proyecto que no son específicas de WinForms, vea Referencia de MSBuild para los proyectos del SDK de .NET.

ApplicationDefaultFont

La propiedad ApplicationDefaultFont especifica la información de fuente personalizada que se va a implementar en toda la aplicación. Controla si la API ApplicationConfiguration.Initialize() generada por el origen emite o no una llamada al método Application.SetDefaultFont(Font). El valor predeterminado es una cadena vacía y significa que la fuente predeterminada de la aplicación tiene como origen la propiedad Control.DefaultFont.

Un valor no vacío debe cumplir un formato equivalente a la salida del método FontConverter.ConvertTo invocado con la referencia cultural invariable (es decir, con el separador de listas=, y el separador de decimales=.). El formato es el siguiente: name, size[units[, style=style1[, style2, ...]]].

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

Esta propiedad es compatible con .NET 6 y versiones posteriores y con Visual Studio 2022 y versiones posteriores.

ApplicationHighDpiMode

La propiedad ApplicationHighDpiMode especifica el valor predeterminado de toda la aplicación para el modo de valores altos de PPP. Controla el argumento del método Application.SetHighDpiMode(HighDpiMode) que emite la API ApplicationConfiguration.Initialize() generada por el origen. El valor predeterminado es SystemAware.

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

El elemento ApplicationHighDpiMode puede establecerse en uno de los valores de la enumeración HighDpiMode:

Value Descripción
DpiUnaware La ventana de la aplicación no se escala para los cambios de PPP y siempre supone un factor de escala del 100 %.
DpiUnawareGdiScaled Similar a DpiUnaware, pero mejora la calidad del contenido basado en GDI/GDI+.
PerMonitor La ventana comprueba el tamaño de PPP en el momento de la creación y ajusta el factor de escala cuando cambia la configuración de PPP.
PerMonitorV2 Similar a PerMonitor, pero habilita la notificación de cambio de PPP de ventana secundaria, el escalado mejorado de los controles comctl32 y el escalado de diálogo.
SystemAware Default si no se especifica.
La ventana consulta el PPP del monitor principal una vez y usa este valor para la aplicación en todos los monitores.

Esta propiedad es compatible con .NET 6 y versiones posteriores.

ApplicationUseCompatibleTextRendering

La propiedad ApplicationUseCompatibleTextRendering especifica el valor predeterminado de la aplicación para la propiedad UseCompatibleTextRendering definida en ciertos controles. Controla el argumento del método Application.SetCompatibleTextRenderingDefault(Boolean) que emite la API ApplicationConfiguration.Initialize() generada por el origen. El valor predeterminado es false.

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

Esta propiedad es compatible con .NET 6 y versiones posteriores.

ApplicationVisualStyles

La propiedad ApplicationVisualStyles especifica el valor predeterminado de toda la aplicación para habilitar estilos visuales. Controla si la API ApplicationConfiguration.Initialize() generada por el origen emite o no una llamada a Application.EnableVisualStyles(). El valor predeterminado es true.

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

Esta propiedad es compatible con .NET 6 y versiones posteriores.

UseWindowsForms

La propiedad UseWindowsForms controla si la aplicación se compila o no para destinarla a Windows Forms. Esta propiedad también altera la canalización de MSBuild para procesar correctamente un proyecto de Windows Forms y los archivos relacionados. El valor predeterminado es false. Establezca la propiedad UseWindowsForms en true para habilitar la compatibilidad con Windows Forms. Cuando este valor de configuración está habilitado, solo puede seleccionar como destino la plataforma Windows.

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

Cuando esta propiedad se establece trueen , los proyectos de .NET importan automáticamente el SDK de escritorio de .NET.

Consulte también