.vcxproj e .props estrutura de arquivos

MSBuild é o sistema de projeto padrão no Visual Studio; quando você escolhe Arquivo>Novo Projeto, na maioria dos casos você está criando um projeto MSBuild cujas configurações são armazenadas em um arquivo de projeto XML que tem a extensão .vcxproj. O arquivo de projeto também pode importar .props arquivos e .targets arquivos onde as configurações podem ser armazenadas.

Se você pretende manter as propriedades do projeto no IDE, recomendamos apenas criar e modificar seus .vcxproj projetos no IDE e evitar edições manuais nos arquivos. Na maioria dos casos, você nunca precisa editar manualmente o arquivo de projeto. Edições manuais podem quebrar as conexões de projeto necessárias para modificar as configurações do projeto nas páginas de propriedades do Visual Studio e podem causar erros de compilação que são difíceis de depurar e reparar. Para obter mais informações sobre como usar as páginas de propriedades, consulte Definir compilador C++ e criar propriedades no Visual Studio.

Em escala, gerenciar muitos projetos individuais no IDE torna-se tedioso e propenso a erros. É difícil manter a consistência ou impor a padronização em dezenas ou centenas de projetos. Nesses casos, vale a pena editar seus arquivos de projeto para usar arquivos personalizados .props ou .targets para propriedades comuns em muitos projetos. Você também pode usar esses arquivos quando precisar de personalizações que não são possíveis no IDE. Os locais úteis para inserir personalizações são os Directory.Build.props arquivos e Directory.Build.targets , que são importados automaticamente em todos os projetos baseados no MSBuild.

Em alguns casos, arquivos personalizados .props ou .targets por si só podem não ser suficientes para suas necessidades de gerenciamento de projetos. Talvez ainda seja necessário modificar .vcxproj arquivos de projeto ou folhas de propriedades manualmente. A edição manual requer um bom entendimento do MSBuild e deve seguir as diretrizes deste artigo. Para que o IDE carregue e atualize .vcxproj arquivos automaticamente, esses arquivos têm várias restrições que não se aplicam a outros arquivos de projeto do MSBuild. Erros podem fazer com que o IDE falhe ou se comporte de maneiras inesperadas.

Para cenários de edição manual, este artigo contém informações básicas sobre a estrutura e .vcxproj arquivos relacionados.

Considerações importantes

Se você optar por editar manualmente um .vcxproj arquivo, esteja ciente destes fatos:

• A estrutura do arquivo deve seguir um formulário prescrito, que é descrito neste artigo.

• O sistema de projeto Visual Studio C++ atualmente não oferece suporte a curingas ou listas diretamente em itens de projeto. Por exemplo, estes formulários não são suportados:

  <ItemGroup>
     <None Include="*.txt"/>
     <ClCompile Include="a.cpp;b.cpp"/>
  </ItemGroup>
  

  Para obter mais informações sobre o suporte a curingas em projetos e possíveis soluções alternativas, consulte .vcxproj Arquivos e curingas.

• O sistema de projeto Visual Studio C++ atualmente não oferece suporte a macros em caminhos de item de projeto. Por exemplo, este formulário não é suportado:

  <ItemGroup>
     <ClCompile Include="$(IntDir)\generated.cpp"/>
  </ItemGroup>
  

  "Não suportado" significa que não é garantido que as macros funcionem para todas as operações no IDE. As macros que não alteram seu valor em configurações diferentes devem funcionar, mas podem não ser preservadas se um item for movido para um filtro ou projeto diferente. Macros que alteram seu valor para configurações diferentes causarão problemas. O IDE não espera que os caminhos de item de projeto sejam diferentes para diferentes configurações de projeto.

• Para adicionar, remover ou modificar as propriedades do projeto corretamente quando você editá-las na caixa de diálogo Propriedades do projeto , o arquivo deve conter grupos separados para cada configuração do projeto. As condições devem assumir a seguinte forma:

  Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"
  

• Cada propriedade deve ser especificada no grupo com seu rótulo correto, conforme especificado no arquivo de regra de propriedade. Para obter mais informações, consulte Arquivos de regras xml da página de propriedades.

.vcxproj elementos de arquivo

Você pode inspecionar o conteúdo de um .vcxproj arquivo usando qualquer editor de texto ou XML. Você pode exibi-lo no Visual Studio clicando com o botão direito do mouse no projeto no Gerenciador de Soluções, escolhendo Descarregar projeto e, em seguida, escolhendo Editar Foo.vcxproj.

A primeira coisa a notar é que os elementos de nível superior aparecem em uma ordem específica. Por exemplo:

• A maioria dos grupos de propriedades e grupos de definição de item ocorrem após a importação para Microsoft.Cpp.Default.props.

• Todos os destinos são importados no final do arquivo.

• Existem vários grupos de propriedades, cada um com um rótulo exclusivo, e eles ocorrem em uma ordem específica.

A ordem dos elementos no arquivo de projeto é de vital importância, porque o MSBuild é baseado em um modelo de avaliação sequencial. Se o arquivo de projeto, incluindo todos os arquivos e .props arquivos importados.targets, consistir em várias definições de uma propriedade, a última definição substituirá as anteriores. No exemplo a seguir, o valor "xyz" será definido durante a compilação porque o mecanismo MSBUild o encontra por último durante sua avaliação.

  <MyProperty>abc</MyProperty>
  <MyProperty>xyz</MyProperty>

O trecho a seguir mostra um arquivo mínimo .vcxproj . Qualquer .vcxproj arquivo gerado pelo Visual Studio conterá esses elementos MSBuild de nível superior. E eles aparecerão nesta ordem, embora possam conter várias cópias de cada um desses elementos de nível superior. Quaisquer Label atributos são marcas arbitrárias que são usadas apenas pelo Visual Studio como sinais para edição, eles não têm outra função.

<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns='http://schemas.microsoft.com/developer/msbuild/2003'>
  <ItemGroup Label="ProjectConfigurations" />
  <PropertyGroup Label="Globals" />
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.default.props" />
  <PropertyGroup Label="Configuration" />
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
  <ImportGroup Label="ExtensionSettings" />
  <ImportGroup Label="PropertySheets" />
  <PropertyGroup Label="UserMacros" />
  <PropertyGroup />
  <ItemDefinitionGroup />
  <ItemGroup />
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
  <ImportGroup Label="ExtensionTargets" />
</Project>

As seções a seguir descrevem a finalidade de cada um desses elementos e por que eles são ordenados dessa maneira:

Elemento do projeto

<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns='http://schemas.microsoft.com/developer/msbuild/2003' >

Project é o nó raiz. Ele especifica a versão do MSBuild a ser usada e também o destino padrão a ser executado quando esse arquivo é passado para MSBuild.exe.

ProjectConfigurations ItemGroup elemento

<ItemGroup Label="ProjectConfigurations" />

ProjectConfigurations Contém a descrição da configuração do projeto. Exemplos são Debug|Win32, Lançamento|Win32, Depurar|ARM e assim por diante. Muitas configurações de projeto são específicas para uma determinada configuração. Por exemplo, você provavelmente desejará definir propriedades de otimização para uma compilação de versão, mas não para uma compilação de depuração.

O ProjectConfigurations grupo de itens não é usado no momento da compilação. O IDE do Visual Studio requer que ele carregue o projeto. Esse grupo de itens pode ser movido para um .props arquivo e importado para o .vcxproj arquivo. No entanto, nesse caso, se você precisar adicionar ou remover configurações, deverá editar manualmente o .props arquivo, não podendo usar o IDE.

Elementos ProjectConfiguration

O trecho a seguir mostra uma configuração de projeto. Neste exemplo, 'Debug|x64' é o nome da configuração. O nome da configuração do projeto deve estar no formato $(Configuration)|$(Platform). Um ProjectConfiguration nó pode ter duas propriedades: Configuration e Platform. Essas propriedades são definidas automaticamente com os valores especificados aqui quando a configuração está ativa.

<ProjectConfiguration Include="Debug|x64">
  <Configuration>Debug</Configuration>
  <Platform>x64</Platform>
</ProjectConfiguration>

O IDE espera encontrar uma configuração de projeto para qualquer combinação e ConfigurationPlatform valores usados em todos os ProjectConfiguration itens. Muitas vezes, isso significa que um projeto pode ter configurações de projeto sem sentido para atender a esse requisito. Por exemplo, se um projeto tiver estas configurações:

• Depuração|Win32
• Retalho|x64
• Depurar|x64
• Retalho|Win32

Em seguida, se você adicionar uma nova configuração ao projeto, diga "Otimização especial de 32 bits|Win32", então você também deve adicionar a configuração "Special 32-bit Optimization|x64", mesmo que "Special 32-bit Optimization" não faça sentido para x64.

Você pode desabilitar os comandos build e deploy para qualquer configuração no Solution Configuration Manager.

Elemento Globals PropertyGroup

<PropertyGroup Label="Globals" />

Globals contém configurações de nível de projeto, como ProjectGuid, RootNamespacee ApplicationType ou ApplicationTypeRevision. Os dois últimos geralmente definem o sistema operacional de destino. Um projeto só pode ter como alvo um único sistema operacional porque, atualmente, as referências e os itens do projeto não podem ter condições. Essas propriedades normalmente não são substituídas em outro lugar no arquivo de projeto. Esse grupo não depende da configuração e, normalmente, existe apenas um Globals grupo no arquivo de projeto.

Elemento de importação Microsoft.Cpp.default.props

<Import Project="$(VCTargetsPath)\Microsoft.Cpp.default.props" />

A folha de propriedades Microsoft.Cpp.default.props vem com o Visual Studio e não pode ser modificada. Ele contém as configurações padrão para o projeto. Os padrões podem variar dependendo do ApplicationType.

Elementos Configuration PropertyGroup

<PropertyGroup Label="Configuration" />

Um Configuration grupo de propriedades tem uma condição de configuração anexada (como Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'") e vem em várias cópias, uma por configuração. Este grupo de propriedades hospeda as propriedades definidas para uma configuração específica. As propriedades de configuração incluem PlatformToolset e também controlam a inclusão de folhas de propriedades do sistema em Microsoft.Cpp.props. Por exemplo, se você definir a propriedade <CharacterSet>Unicode</CharacterSet>, então a folha de propriedades do sistema microsoft. Cpp.unicodesupport.props serão incluídos. Se você inspecionar Microsoft.Cpp.props, verá a linha: <Import Condition="'$(CharacterSet)' == 'Unicode'" Project="$(VCTargetsPath)\microsoft.Cpp.unicodesupport.props" />.

Elemento de importação Microsoft.Cpp.props

<Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />

A folha de propriedades Microsoft.Cpp.props (diretamente ou por meio de importações) define os valores padrão para muitas propriedades específicas da ferramenta. Os exemplos incluem as propriedades Optimization e Warning Level do compilador, a propriedade TypeLibraryName da ferramenta MIDL e assim por diante. Ele também importa várias folhas de propriedades do sistema com base nas propriedades de configuração definidas no grupo de propriedades imediatamente antes dele.

Elemento ExtensionSettings ImportGroup

<ImportGroup Label="ExtensionSettings" />

O ExtensionSettings grupo contém importações para as folhas de propriedades que fazem parte das Personalizações de Compilação. Uma personalização de compilação é definida por até três arquivos: um .targets arquivo, um .props arquivo e um .xml arquivo. Este grupo de importação contém as importações para o .props arquivo.

Elementos PropertySheets ImportGroup

<ImportGroup Label="PropertySheets" />

O PropertySheets grupo contém as importações para folhas de propriedades do usuário. Essas importações são as folhas de propriedades que você adiciona por meio do modo de exibição Gerenciador de propriedades no Visual Studio. A ordem em que essas importações são listadas é importante e se reflete no Gerente de Propriedades. O arquivo de projeto normalmente contém várias instâncias desse tipo de grupo de importação, uma para cada configuração de projeto.

Elemento UserMacros PropertyGroup

<PropertyGroup Label="UserMacros" />

UserMacros Contém propriedades que você cria como variáveis que são usadas para personalizar seu processo de compilação. Por exemplo, você pode definir uma macro de usuário para definir seu caminho de saída personalizado como $(CustomOutputPath) e usá-lo para definir outras variáveis. Este grupo de propriedades abriga tais propriedades. No Visual Studio, esse grupo não é preenchido no arquivo de projeto porque o Microsoft C++ não oferece suporte a macros de usuário para configurações. As macros de usuário são suportadas em folhas de propriedades.

Elementos PropertyGroup por configuração

<PropertyGroup />

Há várias instâncias desse grupo de propriedades, uma por configuração para todas as configurações do projeto. Cada grupo de propriedades deve ter uma condição de configuração anexada. Se alguma configuração estiver faltando, a caixa de diálogo Propriedades do projeto não funcionará corretamente. Ao contrário dos grupos de propriedades listados anteriormente, este não tem um rótulo. Este grupo contém definições de nível de configuração do projeto. Essas configurações se aplicam a todos os arquivos que fazem parte do grupo de itens especificado. Os metadados de definição de item de personalização de compilação são inicializados aqui.

Este PropertyGroup deve vir depois <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> e não deve haver nenhum outro PropertyGroup sem um Label antes dele (caso contrário, a edição de Propriedades do projeto não funcionará corretamente).

Elementos ItemDefinitionGroup por configuração

<ItemDefinitionGroup />

Contém definições de item. Essas definições devem seguir as mesmas regras de condições que os elementos sem rótulo por configuração PropertyGroup .

Elementos ItemGroup

<ItemGroup />

ItemGroup contêm os itens (arquivos de origem e assim por diante) no projeto. Não há suporte para condições para itens do Project (ou seja, tipos de item que são tratados como itens de projeto por definições de regras).

Os metadados devem ter condições de configuração para cada configuração, mesmo que sejam todas iguais. Por exemplo:

<ItemGroup>
  <ClCompile Include="stdafx.cpp">
    <TreatWarningAsError Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">true</TreatWarningAsError>
    <TreatWarningAsError Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">true</TreatWarningAsError>
  </ClCompile>
</ItemGroup>

O sistema de projeto Visual Studio C++ atualmente não oferece suporte a curingas em itens de projeto.

<ItemGroup>
  <ClCompile Include="*.cpp"> <!--Error-->
</ItemGroup>

O sistema de projeto Visual Studio C++ atualmente não oferece suporte a macros em itens de projeto.

<ItemGroup>
  <ClCompile Include="$(IntDir)\generated.cpp"> <!--not guaranteed to work in all scenarios-->
</ItemGroup>

As referências são especificadas em um ItemGroup e têm estas limitações:

• As referências não suportam condições.

• Os metadados de referência não suportam condições.

Elemento de importação Microsoft.Cpp.targets

<Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />

Define (diretamente ou por meio de importações) destinos C++ como compilação, limpeza e assim por diante.

Elemento ExtensionTargets ImportGroup

<ImportGroup Label="ExtensionTargets" />

Esse grupo contém importações para os arquivos de destino de Personalização de Compilação.

Consequências de uma encomenda incorreta

O IDE do Visual Studio depende do arquivo de projeto com a ordem descrita anteriormente. Por exemplo, quando você define um valor de propriedade nas páginas de propriedades, o IDE geralmente coloca a definição de propriedade no grupo de propriedades com o rótulo vazio. Essa ordenação garante que os valores padrão trazidos nas folhas de propriedades do sistema sejam substituídos por valores definidos pelo usuário. Da mesma forma, os arquivos de destino são importados no final, uma vez que consomem as propriedades definidas anteriormente e como geralmente não definem as próprias propriedades. Da mesma forma, as folhas de propriedades do usuário são importadas após as folhas de propriedades do sistema (incluídas pelo Microsoft.Cpp.props). Essa ordem garante que o usuário possa substituir quaisquer padrões trazidos pelas folhas de propriedades do sistema.

Se um .vcxproj arquivo não seguir esse layout, os resultados da compilação podem não ser os esperados. Por exemplo, se você importar por engano uma folha de propriedades do sistema após as folhas de propriedades definidas pelo usuário, as configurações do usuário serão substituídas pelas folhas de propriedades do sistema.

Até mesmo a experiência de tempo de design do IDE depende, até certo ponto, da ordenação correta dos elementos. Por exemplo, se o .vcxproj arquivo não tiver o PropertySheets grupo de importação, o IDE talvez não consiga determinar onde colocar uma nova folha de propriedades que o usuário criou no Gerenciador de propriedades. Isso pode resultar em uma folha de usuário sendo substituída por uma folha de sistema. Embora a heurística usada pelo IDE possa tolerar pequenas inconsistências no layout do .vcxproj arquivo, é altamente recomendável que você não se desvie da estrutura mostrada anteriormente neste artigo.

Como o IDE usa rótulos de elementos

No IDE, quando você define a propriedade UseOfAtl na página de propriedades geral, ela é gravada no grupo de propriedades Configuration no arquivo de projeto. A propriedade TargetName na mesma página de propriedades é gravada no grupo de propriedades sem rótulo por configuração. O Visual Studio examina o arquivo xml da página de propriedades para obter informações sobre onde escrever cada propriedade. Para a página de propriedades Geral , supondo que você tenha uma versão em inglês do Visual Studio 2019 Enterprise Edition, esse arquivo é %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033\general.xml. O arquivo de regra XML da página de propriedades define as informações estáticas sobre uma Regra e todas as suas propriedades. Uma dessas informações é a posição preferencial de uma propriedade Rule no arquivo de destino (o arquivo onde seu valor será gravado). A posição preferida é especificada pelo atributo Label nos elementos do arquivo de projeto.

Layout da Folha de Propriedades

O trecho XML a seguir é um layout mínimo de um arquivo de folha de propriedades (.props). É semelhante a um .vcxproj arquivo, e a funcionalidade dos .props elementos pode ser inferida a partir da discussão anterior.

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <ImportGroup Label="PropertySheets" />
  <PropertyGroup Label="UserMacros" />
  <PropertyGroup />
  <ItemDefinitionGroup />
  <ItemGroup />
</Project>

Para criar sua própria folha de propriedades, copie um dos arquivos na pasta e modifique-o .propsVCTargets para seus propósitos. Para o Visual Studio 2019 Enterprise edition, o caminho padrão VCTargets é %ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets.

Consulte também

Definir compilador C++ e criar propriedades no Visual Studio
Arquivos XML da página de propriedades
.vcxproj arquivos e curingas