Referência do MSBuild para projetos do SDK do .NET Desktop

  • Artigo

Esta página é uma referência para as propriedades e os itens do MSBuild que você usa para configurar projetos do WinForms (Windows Forms) e do WPF (Windows Presentation Foundation) com o SDK do .NET Desktop.

Observação

Este artigo documenta um subconjunto das propriedades do MSBuild para o SDK do .NET em relação aos aplicativos da área de trabalho. Para obter uma lista das propriedades do MSBuild específicas do SDK do .NET comuns, confira a Referência do MSBuild para projetos do SDK do .NET. Para obter uma lista das propriedades comuns do MSBuild, confira Propriedades comuns do MSBuild.

Habilitar o SDK do .NET Desktop

Para usar WinForms ou WPF, especifique as seguintes configurações no arquivo de projeto do seu projeto WinForms ou WPF:

  • Direcione o projeto ao SDK do .NET Microsoft.NET.Sdk. Para obter mais informações, confira Arquivos de projeto.
  • Defina TargetFramework como um Moniker da Estrutura de Destino específico do Windows, como net8.0-windows.
  • Adicione uma propriedade de estrutura de interface do usuário (ou ambas, se necessário):
    • Defina UseWPF como true para importar e usar o WPF.
    • Defina UseWindowsForms como true para importar e usar o WinForms.
  • (Opcional) Definir OutputType como WinExe. Isso produz um aplicativo em vez de uma biblioteca. Para produzir uma biblioteca, omita essa propriedade.
<Project Sdk="Microsoft.NET.Sdk">

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

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

</Project>

Inclusões e exclusões do padrão do WPF

Os projetos do SDK definem um conjunto de regras para incluir ou excluir arquivos de projeto implicitamente. Essas regras também definem automaticamente a ação de build do arquivo. Isso é diferente dos projetos mais antigos que não são do SDK .NET Framework, que não têm regras padrão de inclusão ou exclusão. Os projetos do .NET Framework exigem que você declare explicitamente quais arquivos devem ser incluídos no projeto.

Os arquivos de projeto do .NET incluem um conjunto padrão de regras para processar arquivos automaticamente. Os projetos do WPF contêm regras adicionais.

A seguinte tabela mostra quais elementos e globs são incluídos e excluídos no SDK do .NET Desktop quando a propriedade de projeto UseWPF é definida como true:

Elemento Incluir glob Excluir glob Remover glob
ApplicationDefinition App.xaml ou Application.xaml N/D N/D
Page **/*.xaml **/*.user; **/*.*proj; **/*.sln; **/*.vssscc
Qualquer XAML definido por ApplicationDefinition		 N/D
None N/D N/D **/*.xaml

Aqui estão as configurações padrão de inclusão e exclusão para todos os tipos de projeto. Para obter mais informações, confira Inclusões e exclusões padrão.

Elemento Incluir glob Excluir glob Remover glob
Compile **/*.cs; **/*.vb (ou outras extensões de linguagem) **/*.user; **/*.*proj; **/*.sln; **/*.vssscc N/D
EmbeddedResource **/*.resx **/*.user; **/*.*proj; **/*.sln; **/*.vssscc N/D
None **/* **/*.user; **/*.*proj; **/*.sln; **/*.vssscc **/*.cs; **/*.resx

Se você adicionou arquivos ao projeto explicitamente ou tem globs XAML para incluir automaticamente os arquivos no projeto, os seguintes erros poderão ser observados:

  • Itens 'ApplicationDefinition' duplicados foram incluídos.
  • Itens 'Page' duplicados foram incluídos.

Esses erros são resultado dos globs de inclusão implícitos conflitantes com suas configurações. Para contornar esse problema, defina EnableDefaultApplicationDefinition ou EnableDefaultPageItems como false. A definição desses valores como false reverte o comportamento para o dos SDKs anteriores em que você precisava definir explicitamente os globs padrão no projeto ou definir explicitamente os arquivos a serem incluídos no projeto.

Você pode desabilitar completamente todas as inclusões implícitas definindo a propriedade EnableDefaultItems como false.

Configurações do WPF

Para obter informações sobre configurações de projeto que não são específicas do WPF, confira Referência do MSBuild para projetos do SDK do .NET.

UseWPF

A propriedade UseWPF controla se devem ou não ser incluídas referências a bibliotecas do WPF. Ela também altera o pipeline do MSBuild para processar corretamente um projeto do WPF e os arquivos relacionados. O valor padrão é false. Defina a propriedade UseWPF como true para habilitar o suporte ao WPF. Você só pode usar plataforma Windows como destino quando essa propriedade está habilitada.

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

Quando essa propriedade estiver definida como true, os projetos do .NET 5 e posteriores importarão automaticamente o SDK do .NET Desktop.

EnableDefaultApplicationDefinition

A propriedade EnableDefaultApplicationDefinition controla se os itens ApplicationDefinition são incluídos implicitamente no projeto. O valor padrão é true. Defina a propriedade EnableDefaultApplicationDefinition como false para desabilitar a inclusão implícita de arquivos.

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

Essa propriedade requer que a EnableDefaultItemspropriedade seja definida para true, que é a configuração padrão.

EnableDefaultPageItems

A propriedade EnableDefaultPageItems controla se os itens Page, que são arquivos .xaml, são incluídos implicitamente no projeto. O valor padrão é true. Defina a propriedade EnableDefaultPageItems como false para desabilitar a inclusão implícita de arquivos.

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

Essa propriedade requer que a EnableDefaultItemspropriedade seja definida para true, que é a configuração padrão.

Configurações do Windows Forms

Para obter informações sobre propriedades de projeto específicas que são não do WinForms, confira Referência do MSBuild para projetos do SDK do .NET.

ApplicationDefaultFont

A propriedade ApplicationDefaultFont especifica informações de fonte personalizadas a serem aplicadas em todo o aplicativo. Ela controla se a API ApplicationConfiguration.Initialize() gerada pela origem emite ou não uma chamada ao método Application.SetDefaultFont(Font). O valor padrão é uma cadeia de caracteres vazia e significa que a fonte padrão do aplicativo é originada da propriedade Control.DefaultFont.

Um valor não vazio precisa estar em conformidade com um formato equivalente à saída do método FontConverter.ConvertTo invocado com a cultura invariável (ou seja, o separador de lista = , e o separador decimal = .). O formato é: name, size[units[, style=style1[, style2, ...]]].

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

Há suporte para essa propriedade no .NET 6 e versões posteriores e no Visual Studio 2022 e versões posteriores.

ApplicationHighDpiMode

A propriedade ApplicationHighDpiMode especifica o padrão do modo de alto DPI em todo o aplicativo. Ela controla o argumento do método Application.SetHighDpiMode(HighDpiMode) emitido pela API ApplicationConfiguration.Initialize() gerada pela origem. O valor padrão é SystemAware.

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

A ApplicationHighDpiMode pode ser definida como um dos valores de enumeração HighDpiMode:

Valor Descrição
DpiUnaware A janela do aplicativo não é dimensionada para alterações de DPI e sempre assume um fator de escala de 100%.
DpiUnawareGdiScaled Semelhante a DpiUnaware, mas melhora a qualidade do conteúdo baseado em GDI/GDI+.
PerMonitor A janela verifica o DPI quando é criada e ajusta o fator de escala quando o DPI é alterado.
PerMonitorV2 Semelhante a PerMonitor, mas habilita a notificação de alteração de DPI da janela filho, dimensionamento aprimorado de controles comctl32 e dimensionamento de caixa de diálogo.
SystemAware Padrão, se não especificado.
A janela consulta o DPI do monitor primário uma vez e o usa para o aplicativo em todos os monitores.

Essa propriedade é compatível com o .NET 6 e versões posteriores.

ApplicationUseCompatibleTextRendering

A propriedade ApplicationUseCompatibleTextRendering especifica o padrão da UseCompatibleTextRendering propriedade definida em determinados controles para todo o aplicativo. Ela controla o argumento do método Application.SetCompatibleTextRenderingDefault(Boolean) emitido pela API ApplicationConfiguration.Initialize() gerada pela origem. O valor padrão é false.

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

Essa propriedade é compatível com o .NET 6 e versões posteriores.

ApplicationVisualStyles

A propriedade ApplicationVisualStyles especifica o padrão para habilitar estilos visuais em todo o aplicativo. Ela controla se a API ApplicationConfiguration.Initialize() gerada pela origem emite ou não uma chamada para Application.EnableVisualStyles(). O valor padrão é true.

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

Essa propriedade é compatível com o .NET 6 e versões posteriores.

UseWindowsForms

A propriedade UseWindowsForms controla se o aplicativo é criado como direcionado ao Windows Forms. Essa propriedade altera o pipeline do MSBuild para processar corretamente um projeto do Windows Forms os arquivos relacionados. O valor padrão é false. Defina a propriedade UseWindowsForms como true para habilitar o suporte ao Windows Forms. Você só pode usar plataforma Windows como destino quando essa configuração está habilitada.

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

Quando essa propriedade estiver definida como true, os projetos do .NET 5 e posteriores importarão automaticamente o SDK do .NET Desktop.

Configurações compartilhadas

DisableWinExeOutputInference

Aplica-se ao SDK do .NET 5 e posteriores.

Quando um aplicativo tem o valor Exe definido para a propriedade OutputType, uma janela do console é criada quando o aplicativo não é executado por meio de um console. Geralmente, esse não é o comportamento desejado para um aplicativo da área de trabalho do Windows. Com o valor WinExe, uma janela do console não é criada. Do SDK do .NET 5 em diante, o valor Exe é transformado automaticamente em WinExe.

A propriedade DisableWinExeOutputInference reverte o comportamento de tratar Exe como WinExe. Defina esse valor como true para restaurar o comportamento do valor da propriedade OutputType como Exe. O valor padrão é false.

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

Confira também