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

  • Artigo

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

Nota

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 de propriedades comuns do MSBuild específicas do SDK do .NET, consulte Referência do MSBuild para projetos do SDK do .NET. Para obter uma lista de propriedades comuns do MSBuild, consulte 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 SDK Microsoft.NET.Sdkdo .NET . Para obter mais informações, consulte Arquivos de projeto.
  • Definido TargetFramework como um moniker de estrutura de destino específico do Windows, como net8.0-windows.
  • Adicione uma propriedade de estrutura da interface do usuário (ou ambas, se necessário):
    • Defina UseWPF para true importar e usar WPF.
    • Defina UseWindowsForms para true importar e usar WinForms.
  • (Opcional) Defina OutputType como WinExe. Essa configuração 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>

O padrão do WPF inclui e exclui

Os projetos SDK definem um conjunto de regras para incluir ou excluir implicitamente arquivos do projeto. Essas regras também definem automaticamente a ação de compilação do arquivo. Esse comportamento é diferente dos projetos .NET Framework não SDK mais antigos, 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 incluir no projeto.

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

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

Elemento Incluir glob Excluir glob Remover glob
ApplicationDefinition App.xaml ou Application.xaml N/A N/A
Page **/*.xaml **/*.utilizador; **/*.*proj; **/*.sln; **/*.vssscc
Qualquer XAML definido por ApplicationDefinition		 N/A
None N/D N/A **/*.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, consulte Inclui e exclui padrão.

Elemento Incluir glob Excluir glob Remover glob
Compile **/*.cs; **/*.vb (ou outras extensões linguísticas) **/*.utilizador; **/*.*proj; **/*.sln; **/*.vssscc N/A
EmbeddedResource **/*.resx **/*.utilizador; **/*.*proj; **/*.sln; **/*.vssscc N/A
None **/* **/*.utilizador; **/*.*proj; **/*.sln; **/*.vssscc **/*.cs; **/*.resx

Se você adicionou explicitamente arquivos ao seu projeto ou tem globs XAML para incluir automaticamente arquivos em seu projeto, você pode obter um dos seguintes erros:

  • Foram incluídos itens 'ApplicationDefinition' duplicados.
  • Foram incluídos itens 'Page' duplicados.

Esses erros são resultado do implícito Incluir globs em conflito com suas configurações. Para contornar esse problema, defina ou EnableDefaultApplicationDefinition EnableDefaultPageItems como false. Definir esses valores para false reverter para o comportamento de SDKs anteriores onde você tinha que definir explicitamente os globs padrão ou os arquivos a serem incluídos em seu projeto.

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

Configurações do WPF

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

UseWPF

A UseWPF propriedade controla se deve ou não incluir referências a bibliotecas WPF. Essa configuração também altera o pipeline do MSBuild para processar corretamente um projeto WPF e arquivos relacionados. O valor predefinido é false. Defina a propriedade como true para habilitar o UseWPF suporte ao WPF. Você só pode direcionar a plataforma Windows quando essa propriedade estiver habilitada.

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

Quando essa propriedade é definida como true, os projetos .NET importam automaticamente o SDK do .NET Desktop.

EnableDefaultApplicationDefinition

A EnableDefaultApplicationDefinition propriedade controla se ApplicationDefinition os itens são incluídos implicitamente no projeto. O valor predefinido é true. Defina a EnableDefaultApplicationDefinition propriedade como false para desativar a inclusão implícita do arquivo.

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

Esta propriedade requer que a EnableDefaultItems propriedade esteja definida como true, que é a configuração padrão.

EnableDefaultPageItens

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

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

Esta propriedade requer que a EnableDefaultItems propriedade esteja definida como true, que é a configuração padrão.

Configurações do Windows Forms

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

ApplicationDefaultFont

A ApplicationDefaultFont propriedade especifica informações de fonte personalizadas a serem aplicadas em todo o aplicativo. Ele controla se a API gerada ApplicationConfiguration.Initialize() pelo código-fonte emite ou não uma chamada para o Application.SetDefaultFont(Font) método. O valor padrão é uma cadeia de caracteres vazia e significa que a fonte padrão do aplicativo é originária da Control.DefaultFont propriedade.

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

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

Essa propriedade é suportada pelo .NET 6 e versões posteriores e pelo Visual Studio 2022 e versões posteriores.

AplicaçãoHighDpiMode

A ApplicationHighDpiMode propriedade especifica o padrão em todo o aplicativo para o modo de DPI alto. Ele controla o Application.SetHighDpiMode(HighDpiMode) argumento do método emitido pela API gerada ApplicationConfiguration.Initialize() pelo código-fonte. O valor predefinido é SystemAware.

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

O ApplicationHighDpiMode pode ser definido como um dos HighDpiMode valores de enum:

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

Esta propriedade é suportada pelo .NET 6 e versões posteriores.

ApplicationUseCompatibleTextRendering

A ApplicationUseCompatibleTextRendering propriedade especifica o padrão em todo o aplicativo para a UseCompatibleTextRendering propriedade definida em determinados controles. Ele controla o Application.SetCompatibleTextRenderingDefault(Boolean) argumento do método emitido pela API gerada ApplicationConfiguration.Initialize() pelo código-fonte. O valor predefinido é false.

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

Esta propriedade é suportada pelo .NET 6 e versões posteriores.

ApplicationVisualStyles

A ApplicationVisualStyles propriedade especifica o padrão em todo o aplicativo para habilitar estilos visuais. Ele controla se a API gerada ApplicationConfiguration.Initialize() pelo código-fonte emite ou não uma chamada para Application.EnableVisualStyles(). O valor predefinido é true.

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

Esta propriedade é suportada pelo .NET 6 e versões posteriores.

UseWindowsForms

A UseWindowsForms propriedade controla se seu aplicativo é criado ou não para o Windows Forms de destino. Essa propriedade altera o pipeline do MSBuild para processar corretamente um projeto do Windows Forms e arquivos relacionados. O valor predefinido é false. Defina a propriedade como true para habilitar o UseWindowsForms suporte a Windows Forms. Você só pode direcionar a plataforma Windows quando essa configuração estiver habilitada.

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

Quando essa propriedade é definida como true, os projetos .NET importam automaticamente o SDK do .NET Desktop.

Consulte também