Referencia de MSBuild para proyectos del SDK de Escritorio de .NET
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, comonet8.0-windows
. - Agregue una propiedad de marco de interfaz de usuario (o ambas, si es necesario):
- Establezca
UseWPF
entrue
para importar y usar WPF. - Establezca
UseWindowsForms
entrue
para importar y usar WinForms.
- Establezca
- (Opcional) Establezca
OutputType
enWinExe
. 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 |
Errores relacionados con elementos "duplicados"
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 true
en , 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
- ApplicationDefaultFont
- ApplicationHighDpiMode
- ApplicationUseCompatibleTextRendering
- ApplicationVisualStyles
- UseWindowsForms
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 true
en , los proyectos de .NET importan automáticamente el SDK de escritorio de .NET.