Extensibilidade do sistema do projeto Visual Studio C++ e integração de ferramentas de compilação

O sistema de projeto Visual C++ é usado para arquivos .vcxproj. Ele é baseado no Visual Studio Common Project System (CPS) e fornece pontos de extensibilidade adicionais específicos do C++ para facilitar a integração do novo sistema de projeto MSBuild C++, arquiteturas de compilação e plataformas de destino.

Estrutura de alvos C++ MSBuild

Todos os ficheiros .vcxproj importam estes ficheiros:

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

Esses arquivos definem pouco por si só. Em vez disso, eles importam outros arquivos com base nesses valores de propriedade:

• $(ApplicationType)

  Exemplos: Microsoft Store, Android, Linux

• $(ApplicationTypeRevision)

  Esta deve ser uma cadeia de caracteres de versão válida, do formato major.minor[.build[.revision]].

  Exemplos: 1.0, 10.0.0.0

• $(Platform)

  A arquitetura de construção, chamada de "Plataforma" por razões históricas.

  Exemplos: Win32, x86, x64, ARM

• $(PlatformToolset)

  Exemplos: v140, v141, v141_xp, llvm

Esses valores de propriedade especificam nomes de pastas na pasta raiz $(VCTargetsPath):

$(VCTargetsPath)\
     Tipo de Aplicação\
        $(ApplicationType)\
            $(ApplicationTypeRevision)\
                 Plataformas\
                    $(Platform)\
                         Conjuntos de ferramentas da plataforma\
                            $(PlatformToolset)
     Plataformas\
        $(Platform)\
             Conjuntos de ferramentas da plataforma\
                $(PlatformToolset)

A pasta $(VCTargetsPath)\Platforms\ é usada quando $(ApplicationType) está vazia, para projetos da Área de Trabalho do Windows.

Adicionar um novo conjunto de ferramentas de plataforma

Para adicionar um novo conjunto de ferramentas, por exemplo, "MyToolset" para a plataforma Win32 existente, crie uma pasta MyToolset na $(VCTargetsPath)\Platforms\Win32\PlatformToolsets\e crie os arquivos o Toolset.props e o Toolset.targets nela.

Cada nome de pasta sob PlatformToolsets aparece na caixa de diálogo Propriedades do Projeto como um Platform Toolset disponível para a plataforma especificada, conforme mostrado aqui:

Crie pastas semelhantes MyToolset e ficheiros Toolset.props e Toolset.targets em cada pasta de plataforma existente que este conjunto de ferramentas suporta.

Adicionar uma nova plataforma

Para adicionar uma nova plataforma, por exemplo, "MyPlatform", crie uma pasta MyPlatform em $(VCTargetsPath)\Platforms\e crie Platform.default.props , Platform.propse Platform.targets arquivos nela. Crie também uma $(VCTargetsPath)pasta \Platforms\MyPlatform\PlatformToolsets\ e crie pelo menos um conjunto de ferramentas nela.

Todos os nomes de pastas na pasta de Plataformas para cada $(ApplicationType) e $(ApplicationTypeRevision) aparecem no IDE como opções de Plataforma disponíveis para um projeto.

Adicionar um novo tipo de aplicativo

Para adicionar um novo tipo de aplicativo, crie uma pasta MyApplicationType em $(VCTargetsPath) \Application Type\ e crie um arquivo Defaults.props nele. Pelo menos uma revisão é necessária para um tipo de aplicativo, portanto, crie também uma $(VCTargetsPath)pasta de \Application Type\MyApplicationType\1.0 e crie um arquivo Defaults.props nela. Você também deve criar uma $(VCTargetsPath)pasta de \ApplicationType\MyApplicationType\1.0\Platforms e criar pelo menos uma plataforma nela.

As propriedades $(ApplicationType) e $(ApplicationTypeRevision) não são visíveis na interface de utilizador. Eles são definidos nos modelos de projeto e não podem ser alterados depois que o projeto é criado.

A árvore de importação .vcxproj

Uma árvore simplificada de importações para arquivos de destino e props do Microsoft C++ tem a seguinte aparência:

$(VCTargetsPath) \ Microsoft.Cpp.Default.props
     $(MSBuildExtensionsPath) \ $(MSBuildToolsVersion) \ Microsoft.Common.props
     $(VCTargetsPath) \ ImportBefore\padrão \*.adereços
     $(VCTargetsPath) \ Tipo de aplicativo\$(ApplicationType)\Default.props
     $(VCTargetsPath) \ Tipo de aplicativo\$(ApplicationType)\$(ApplicationTypeRevision)\Default.props
     $(VCTargetsPath) \ tipo de aplicativo\$(ApplicationType)\$(ApplicationTypeRevision)\plataformas\$(Platform)\Platform.default.props
     $(VCTargetsPath) \ ImportAfter\padrão\*.adereços

Os projetos da Área de Trabalho do Windows não definem $(ApplicationType), portanto, eles só importam

$(VCTargetsPath) \ Microsoft.Cpp.Default.props
     $(MSBuildExtensionsPath) \ $(MSBuildToolsVersion) \ Microsoft.Common.props
     $(VCTargetsPath) \ ImportBefore\padrão \*.adereços
     $(VCTargetsPath) \ Plataformas\$(Platform)\Platform.default.props
     $(VCTargetsPath) \ ImportAfter\padrão\*.adereços

Usaremos a propriedade $(_PlatformFolder) para armazenar os locais das pastas da plataforma $(Platform). Esta propriedade é

$(VCTargetsPath) \ Plataformas\$(Platform)

para aplicações de ambiente de trabalho no Windows e

$(VCTargetsPath) \ Tipo de Aplicação\$(ApplicationType)\$(ApplicationTypeRevision)\Plataformas\$(Platform)

para tudo o resto.

Os arquivos props são importados nesta ordem:

$(VCTargetsPath) \ Microsoft.Cpp.props
     $(_PlatformFolder) \ Platform.props
         $(VCTargetsPath) \ Microsoft.Cpp.Platform.props
             $(_PlatformFolder) \ ImportBefore\*.adereços
             $(_PlatformFolder) \ PlatformToolsets\$(PlatformToolset)\Toolset.props
             $(_PlatformFolder) \ ImportAfter\*.adereços

Os arquivos de destino são importados nesta ordem:

$(VCTargetsPath) \ Microsoft.Cpp.targets
     $(VCTargetsPath) \ Microsoft.Cpp.Current.targets
         $(_PlatformFolder) \ Platform.targets
             $(VCTargetsPath) \ Microsoft.Cpp.Platform.targets
                 $(_PlatformFolder) \ ImportBefore\*.alvos
                 $(_PlatformFolder) \ Conjuntos de Ferramentas da Plataforma\$(PlatformToolset)\Toolset.target
                 $(_PlatformFolder) \ ImportAfter\*.alvos

Se você precisar definir algumas propriedades padrão para seu conjunto de ferramentas, poderá adicionar arquivos às pastas apropriadas ImportBefore e ImportAfter.

Crie arquivos Toolset.props e Toolset.targets

Toolset.props e arquivos Toolset.targets têm controle total sobre o que acontece durante uma compilação quando esse conjunto de ferramentas é usado. Eles também podem controlar os depuradores disponíveis, parte da interface do usuário do IDE, como o conteúdo na caixa de diálogo Property Pages e alguns outros aspetos do comportamento do projeto.

Embora um conjunto de ferramentas possa substituir todo o processo de compilação, geralmente você deseja apenas que seu conjunto de ferramentas modifique ou adicione algumas etapas de compilação, ou use ferramentas de compilação diferentes, como parte de um processo de compilação existente. Para atingir esse objetivo, há uma série de props e arquivos de destino comuns que seu conjunto de ferramentas pode importar. Dependendo do que você deseja que seu conjunto de ferramentas faça, esses arquivos podem ser úteis para usar como importações ou como exemplos:

• $(VCTargetsPath) \ Microsoft.CppCommon.targets

  Esse arquivo define as partes principais do processo de compilação nativo e também importa:

  • $(VCTargetsPath) \ Microsoft.CppBuild.targets

  • $(VCTargetsPath) \ Microsoft.BuildSteps.targets

  • $(MSBuildToolsPath) \ Microsoft.Common.Targets

• $(VCTargetsPath) \ Microsoft.Cpp.Common.props

  Define padrões para conjuntos de ferramentas que usam os compiladores da Microsoft e o Windows de destino.

• $(VCTargetsPath) \ Microsoft.Cpp.WindowsSDK.props

  Esse arquivo determina o local do SDK do Windows e define algumas propriedades importantes para aplicativos destinados ao Windows.

Integre destinos específicos do conjunto de ferramentas com o processo de compilação C++ padrão

O processo de compilação C++ padrão é definido em Microsoft.CppCommon.targets. Os objetivos não chamam nenhuma ferramenta de construção específica; eles especificam as principais etapas de compilação, sua ordem e dependências.

A compilação C++ tem três etapas principais, que são representadas pelos seguintes destinos:

• BuildGenerateSources

• BuildCompile

• BuildLink

Como cada etapa de compilação pode ser executada independentemente, os destinos executados em uma etapa não podem confiar nos grupos de itens e propriedades definidos nos destinos executados como parte de uma etapa diferente. Esta divisão permite determinadas otimizações de desempenho de construção. Embora não seja usado por padrão, você ainda é incentivado a honrar essa separação.

Os alvos que são executados em cada passo são controlados por estas propriedades.

• $(BuildGenerateSourcesTargets)

• $(BuildCompileTargets)

• $(BeforeBuildLinkTargets)

Cada etapa também tem propriedades de Antes e de Depois.

<Target
  Name="_BuildGenerateSourcesAction"
  DependsOnTargets="$(CommonBuildOnlyTargets);$(BeforeBuildGenerateSourcesTargets);$(BuildGenerateSourcesTargets);$(AfterBuildGenerateSourcesTargets)" />

<Target
  Name="\_BuildCompileAction"
  DependsOnTargets="$(CommonBuildOnlyTargets);$(BeforeBuildCompileTargets);$(BuildCompileTargets);$(AfterBuildCompileTargets)" />

<Target
  Name="\_BuildLinkAction"
  DependsOnTargets="$(CommonBuildOnlyTargets);$(BeforeBuildLinkTargets);$(BuildLinkTargets);$(AfterBuildLinkTargets)" />

Consulte o ficheiro Microsoft.CppBuild.targets para obter exemplos dos alvos incluídos em cada etapa.

<BuildCompileTargets Condition="'$(ConfigurationType)'\!='Utility'">
  $(BuildCompileTargets);
  _ClCompile;
  _ResGen;
  _ResourceCompile;
  $(BuildLibTargets);
</BuildCompileTargets>

Se você olhar para os alvos, como _ClCompile, verá que eles não fazem nada diretamente sozinhos, mas dependem de outros alvos, incluindo ClCompile:

<Target Name="_ClCompile"
  DependsOnTargets="$(BeforeClCompileTargets);$(ComputeCompileInputsTargets);MakeDirsForCl;ClCompile;$(AfterClCompileTargets)" >
</Target>

ClCompile e outros destinos específicos da ferramenta de compilação são definidos como destinos vazios em Microsoft.CppBuild.targets:

<Target Name="ClCompile"/>

Como o destino ClCompile está vazio, a menos que seja substituído por um conjunto de ferramentas, nenhuma ação de compilação real é executada. Os destinos do conjunto de ferramentas podem substituir o destino ClCompile, ou seja, podem conter outra definição ClCompile após importar Microsoft.CppBuild.targets.

<Target Name="ClCompile"
  Condition="'@(ClCompile)' != ''"
  DependsOnTargets="SelectClCompile">
  <!-- call some MSBuild tasks -->
</Target>

Apesar do seu nome, que foi criado antes do Visual Studio implementar o suporte multiplataforma, o destino ClCompile não precisa chamar CL.exe. Ele também pode chamar Clang, gcc ou outros compiladores usando tarefas apropriadas do MSBuild.

O destino ClCompile não deve ter dependências, exceto o destino SelectClCompile, que é necessário para que o comando single file compile funcione no IDE.

Tarefas do MSBuild a serem usadas em destinos de conjunto de ferramentas

Para invocar uma ferramenta de compilação real, o destino precisa chamar uma tarefa do MSBuild. Há uma tarefa básica do Exec que permite especificar uma linha de comando para executar. No entanto, as ferramentas de compilação geralmente têm muitas opções, entradas e saídas para rastrear compilações incrementais, por isso faz mais sentido ter tarefas especiais para elas. Por exemplo, a tarefa CL converte as propriedades do MSBuild em opções CL.exe, grava-as em um arquivo de resposta e chama CL.exe. Ele também rastreia todos os arquivos de entrada e saída para compilações incrementais posteriores. Para obter mais informações, consulte Compilações incrementais e up-toverificações de data.

O Microsoft.Cpp.Common.Tasks.dll implementa estas tarefas:

• BSCMake

• CL

• ClangCompile (opções clang-gcc)

• LIB

• LINK

• MIDL

• Mt

• RC

• XDCMake

• CustomBuild (como Exec, mas com rastreamento de entrada e saída)

• SetEnv

• GetOutOfDateItems

Se você tiver uma ferramenta que execute a mesma ação que uma ferramenta existente e que tenha opções de linha de comando semelhantes (como clang-cl e CL), você pode usar a mesma tarefa para ambos.

Se você precisar criar uma nova tarefa para uma ferramenta de compilação, poderá escolher entre as seguintes opções:

1. Se você usar essa tarefa raramente, ou se alguns segundos não importam para sua compilação, você pode usar tarefas 'embutidas' do MSBuild:

   • Tarefa Xaml (uma regra de compilação personalizada)

     Para obter um exemplo de uma declaração de tarefa Xaml, consulte $(VCTargetsPath)\BuildCustomizations\masm.xmle, para seu uso, consulte $(VCTargetsPath)\BuildCustomizations\masm.targets.

   • Tarefa de código

2. Se você quiser um melhor desempenho de tarefas ou apenas precisar de funcionalidades mais complexas, use o MSBuild regular processo de escrita de tarefas.

   Se nem todas as entradas e saídas da ferramenta estiverem listadas na linha de comando da ferramenta, como nos casos CL, MIDLe RC, e se você quiser o rastreamento automático de arquivos de entrada e saída e a criação de arquivos .tlog, derive sua tarefa da classe Microsoft.Build.CPPTasks.TrackedVCToolTask. No momento, embora haja documentação para a classe base ToolTask , não há exemplos ou documentação para os detalhes da classe TrackedVCToolTask. Se isso for de particular interesse, adicione sua voz a uma solicitação em Comunidade de Desenvolvedores.

Compilações incrementais e verificações de "up-to-date"

Os destinos de compilação incremental padrão do MSBuild usam atributos Inputs e Outputs. Se os especificar, o MSBuild chamará o alvo apenas se alguma das entradas tiver um carimbo de data/hora mais recente do que todas as saídas. Como os arquivos de origem geralmente incluem ou importam outros arquivos e as ferramentas de compilação produzem saídas diferentes dependendo das opções da ferramenta, é difícil especificar todas as entradas e saídas possíveis nos destinos do MSBuild.

Para gerenciar esse problema, a compilação C++ usa uma técnica diferente para oferecer suporte a compilações incrementais. A maioria dos alvos não especifica entradas e saídas e, como resultado, é sempre executada durante a compilação. As tarefas chamadas pelos alvos gravam informações sobre todas as entradas e saídas em arquivos tlog que têm uma extensão .tlog. Os arquivos .tlog são usados por compilações posteriores para verificar o que mudou e precisa ser reconstruído, e o que está up-todata. Os ficheiros .tlog são também a única fonte para a verificação da data de compilação padrão up-tono IDE.

Para determinar todas as entradas e saídas, as tarefas da ferramenta nativa usam tracker.exe e a classe FileTracker fornecida pelo MSBuild.

Microsoft.Build.CPPTasks.Common.dll define a classe base abstrata pública TrackedVCToolTask. A maioria das tarefas da ferramenta nativa é derivada dessa classe.

A partir da atualização 15.8 do Visual Studio 2017, você pode usar a tarefa GetOutOfDateItems implementada no Microsoft.Cpp.Common.Tasks.dll para produzir arquivos .tlog para destinos personalizados com entradas e saídas conhecidas. Como alternativa, você pode criá-los usando a tarefa WriteLinesToFile. Veja o destino _WriteMasmTlogs em $(VCTargetsPath)\BuildCustomizations\masm.targets como exemplo.

Arquivos .tlog

Há três tipos de arquivos .tlog: de leitura, de gravação e de linha de comando. Os arquivos .tlog de leitura e gravação são usados por compilações incrementais e pela verificação de data de up-tono IDE. Os arquivos .tlog de linha de comando são usados apenas em compilações incrementais.

MSBuild fornece estas classes auxiliares para ler e gravar arquivos .tlog:

• CanonicalTrackedInputFiles

• CanonicalTrackedOutputFiles

Pode usar a classe FlatTrackingData para aceder tanto a arquivos .tlog de leitura como de gravação, e identificar quando as entradas são mais recentes do que as saídas ou se uma saída estiver em falta. Ele é usado na verificação de data up-to.

Os arquivos .tlog de linha de comando contêm informações sobre linhas de comando usadas na compilação. Eles são usados apenas para compilações incrementais, não para verificações de data up-to, portanto, o formato interno é determinado pela tarefa MSBuild que os produz.

Ler o formato .tlog

Ler os arquivos .tlog (*.read.*.tlog) contêm informações sobre os arquivos de origem e as suas dependências.

Um cursor (^) no início de uma linha indica uma ou mais fontes. As fontes que compartilham as mesmas dependências são separadas por uma barra vertical (|).

Os arquivos de dependência são listados após as fontes, cada um numa linha própria. Todos os nomes de arquivo são caminhos completos.

Por exemplo, suponha que os códigos-fonte do projeto sejam encontrados em F:\test\ConsoleApplication1\ConsoleApplication1. Se o seu ficheiro de origem, Class1.cpp, contiver estas inclusões,

#include "stdafx.h" //precompiled header
#include "Class1.h"

em seguida, o arquivo CL.read.1.tlog contém o arquivo de origem seguido por suas duas dependências:

^F:\TEST\CONSOLEAPPLICATION1\CONSOLEAPPLICATION1\CLASS1.CPP
F:\TEST\CONSOLEAPPLICATION1\CONSOLEAPPLICATION1\DEBUG\CONSOLEAPPLICATION1.PCH
F:\TEST\CONSOLEAPPLICATION1\CONSOLEAPPLICATION1\CLASS1.H

Não é necessário escrever nomes de arquivo em maiúsculas, mas é uma conveniência para algumas ferramentas.

Escrever formato .tlog

Gravar arquivos .tlog (*.write.*.tlog) conectam fontes e saídas.

Um cursor (^) no início de uma linha indica uma ou mais fontes. Várias fontes são separadas por uma barra vertical (|).

Os arquivos de saída construídos a partir das fontes devem ser listados após as fontes, cada um em sua própria linha. Todos os nomes de arquivo devem ser caminhos completos.

Por exemplo, para um projeto simples de ConsoleApplication que tenha um arquivo de origem adicional Class1.cpp, o ficheiro link.write.1.tlog pode conter:

^F:\TEST\CONSOLEAPPLICATION1\CONSOLEAPPLICATION1\DEBUG\CLASS1.OBJ|F:\TEST\CONSOLEAPPLICATION1\CONSOLEAPPLICATION1\DEBUG\CONSOLEAPPLICATION1.OBJ|F:\TEST\CONSOLEAPPLICATION1\CONSOLEAPPLICATION1\DEBUG\STDAFX.OBJ
F:\TEST\CONSOLEAPPLICATION1\DEBUG\CONSOLEAPPLICATION1.ILK
F:\TEST\CONSOLEAPPLICATION1\DEBUG\CONSOLEAPPLICATION1.EXE
F:\TEST\CONSOLEAPPLICATION1\DEBUG\CONSOLEAPPLICATION1.PDB

Construção em tempo de projeto

No IDE, projetos .vcxproj usam um conjunto de alvos MSBuild para obter informações adicionais do projeto e regenerar ficheiros de saída. Alguns desses alvos são usados apenas em compilações em tempo de desenvolvimento, mas muitos deles são usados tanto em compilações regulares como em compilações em tempo de desenvolvimento.

Para obter informações gerais sobre compilações em tempo de design, consulte a documentação do CPS para compilações em tempo de design. Esta documentação é apenas parcialmente aplicável a projetos Visual C++.

Os alvos CompileDesignTime e Compile mencionados na documentação das compilações durante a fase de design nunca são executados para projetos .vcxproj. Os projetos do Visual C++ .vcxproj usam diferentes alvos de tempo de design para obter informações de IntelliSense.

Metas de tempo de design para informações do IntelliSense

Os alvos de tempo de design utilizados em projetos .vcxproj são definidos em $(VCTargetsPath)\Microsoft.Cpp.DesignTime.targets.

O destino GetClCommandLines coleta opções do compilador para o IntelliSense:

<Target
  Name="GetClCommandLines"
  Returns="@(ClCommandLines)"
  DependsOnTargets="$(DesignTimeBuildInitTargets);$(ComputeCompileInputsTargets)">

• DesignTimeBuildInitTargets – alvos apenas na fase de design, necessários para a inicialização da compilação na fase de design. Entre outras coisas, esses alvos desativam algumas das funcionalidades de compilação regulares para melhorar o desempenho.

• ComputeCompileInputsTargets – um conjunto de destinos que modifica opções e itens do compilador. Esses alvos são executados durante o design e em compilações regulares.

O destino chama a tarefa CLCommandLine para criar a linha de comando a ser usada para o IntelliSense. Mais uma vez, apesar do nome, ele pode lidar não apenas com as opções CL, mas também com as opções Clang e gcc. O tipo das opções do compilador é controlado pela propriedade ClangMode.

Atualmente, a linha de comando produzida pela tarefa CLCommandLine sempre usa switches CL (mesmo no modo Clang) porque eles são mais fáceis de analisar pelo mecanismo IntelliSense.

Se você estiver adicionando um destino que é executado antes da compilação, seja regular ou em tempo de design, certifique-se de que ele não interrompa as compilações em tempo de design ou afete o desempenho. A maneira mais simples de testar seu destino é abrir um prompt de comando do desenvolvedor e executar este comando:

msbuild /p:SolutionDir=*solution-directory-with-trailing-backslash*;Configuration=Debug;Platform=Win32;BuildingInsideVisualStudio=true;DesignTimebuild=true /t:\_PerfIntellisenseInfo /v:d /fl /fileloggerparameters:PerformanceSummary \*.vcxproj

Este comando produz um log de compilação detalhado, msbuild.log, que apresenta no final um resumo de desempenho para os alvos e tarefas.

Certifique-se de usar Condition ="'$(DesignTimeBuild)' != 'true'" em todas as operações que só fazem sentido para compilações regulares e não para compilações em tempo de design.

Metas de tempo de design que geram fontes

Este recurso está desativado por padrão para projetos nativos da área de trabalho e não é suportado atualmente em projetos armazenados em cache.

Se GeneratorTarget metadados forem definidos para um item de projeto, o destino será executado automaticamente quando o projeto for carregado e quando o arquivo de origem for alterado.

Por exemplo, para gerar automaticamente arquivos .cpp ou .h a partir de arquivos .xaml, os arquivos de $(VSInstallDir)\MSBuild\Microsoft\WindowsXaml\v16.0\*\Microsoft.Windows.UI.Xaml.CPP.Targets definem estas entidades:

<ItemDefinitionGroup>
  <Page>
    <GeneratorTarget>DesignTimeMarkupCompilation</GeneratorTarget>
  </Page>
  <ApplicationDefinition>
    <GeneratorTarget>DesignTimeMarkupCompilation</GeneratorTarget>
  </ApplicationDefinition>
</ItemDefinitionGroup>
<Target Name="DesignTimeMarkupCompilation">
  <!-- BuildingProject is used in Managed builds (always true in Native) -->
  <!-- DesignTimeBuild is used in Native builds (always false in Managed) -->
  <CallTarget Condition="'$(BuildingProject)' != 'true' Or $(DesignTimeBuild) == 'true'" Targets="DesignTimeMarkupCompilationCT" />
</Target>

Para usar Task.HostObject para obter o conteúdo não salvo de ficheiros de origem, os alvos e a tarefa devem ser registados como MsbuildHostObjects para os projetos indicados num pkgdef:

\[$RootKey$\\Projects\\{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}\\MSBuildHostObjects\]
\[$RootKey$\\Projects\\{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}\\MSBuildHostObjects\\DesignTimeMarkupCompilationCT;CompileXaml\]
@="{83046B3F-8984-444B-A5D2-8029DEE2DB70}"

Extensibilidade do projeto Visual C++ no IDE do Visual Studio

O sistema de projeto Visual C++ é baseado no VS Project Systeme usa seus pontos de extensibilidade. No entanto, a implementação da hierarquia do projeto é específica para o Visual C++ e não baseada no CPS, portanto, a extensibilidade da hierarquia é limitada aos itens do projeto.

Páginas de propriedades do projeto

Para obter informações gerais sobre design, consulte Framework Multi-Targeting for VC++ Projects.

Em termos simples, as páginas de propriedades que vê na caixa de diálogo Propriedades do Projeto para um projeto C++ são definidas por ficheiros de regras . Um arquivo de regra especifica um conjunto de propriedades a serem exibidas em uma página de propriedades e como e onde elas devem ser salvas no arquivo de projeto. Os arquivos de regra são arquivos .xml que usam o formato Xaml. Os tipos usados para serializá-los são descritos em Microsoft.Build.Framework.XamlTypes. Para obter mais informações sobre o uso de arquivos de regra em projetos, consulte Property Page XML rule files.

Os arquivos de regras devem ser adicionados ao grupo de itens PropertyPageSchema:

<ItemGroup>
  <PropertyPageSchema Include="$(VCTargetsPath)$(LangID)\general.xml;"/>
  <PropertyPageSchema Include="$(VCTargetsPath)$(LangID)\general_file.xml">
    <Context>File</Context>
  </PropertyPageSchema>
</ItemGroup>

Context metadados limita a visibilidade da regra, que também é controlada por tipo de regra e pode ter um destes valores:

Project | File | PropertySheet

O CPS oferece suporte a outros valores para o tipo de contexto, mas eles não são usados em projetos do Visual C++.

Se a regra deve ser visível em mais de um contexto, use ponto-e-vírgula (;) para separar os valores de contexto, conforme mostrado aqui:

<PropertyPageSchema Include="$(MyFolder)\MyRule.xml">
  <Context>Project;PropertySheet</Context>
</PropertyPageSchema>

Formato da regra e tipos principais

O formato da regra é simples, portanto, esta seção descreve apenas os atributos que afetam a aparência da regra na interface do usuário.

<Rule
  Name="ConfigurationGeneral"
  DisplayName="General"
  PageTemplate="generic"
  Description="General"
  xmlns="http://schemas.microsoft.com/build/2009/properties">

O atributo PageTemplate define como a regra é exibida no diálogo de Property Pages. O atributo pode ter um destes valores:

Se a regra usar um dos modelos baseados em Grade de Propriedades, ela poderá usar estes pontos de extensibilidade para suas propriedades:

• Editores de valores de propriedade

• Provedor de valores de enum dinâmico

Estender uma regra

Se você quiser usar uma regra existente, mas precisar adicionar ou remover (ou seja, ocultar) apenas algumas propriedades, poderá criar uma regra de Extensão .

Substituir uma regra

Talvez você queira que seu conjunto de ferramentas use a maioria das regras padrão do projeto, mas substitua apenas uma ou algumas delas. Por exemplo, digamos que você queira alterar apenas a regra C/C++ para mostrar opções de compilador diferentes. Você pode fornecer uma nova regra com o mesmo nome e nome de exibição da regra existente e incluí-la no grupo de itens PropertyPageSchema após a importação de destinos cpp padrão. Apenas uma regra com um nome próprio é usada no projeto, e a última incluída no grupo de itens PropertyPageSchema vence.

Itens de projeto

O arquivo ProjectItemsSchema.xml define os valores ContentType e ItemType para Itens que são tratados como Itens de Projeto e define FileExtension elementos para determinar a qual grupo de Itens um novo arquivo é adicionado.

O arquivo ProjectItemsSchema padrão é encontrado em $(VCTargetsPath)\1033\ProjectItemsSchema.xml. Para estendê-lo, você deve criar um arquivo de esquema com um novo nome, como MyProjectItemsSchema.xml:

<ProjectSchemaDefinitions xmlns="http://schemas.microsoft.com/build/2009/properties">

  <ItemType Name="MyItemType" DisplayName="C/C++ compiler"/>

  <ContentType
    Name="MyItems"
    DisplayName="My items"
    ItemType=" MyItemType ">
  </ContentType>

  <FileExtension Name=".abc" ContentType=" MyItems"/>

</ProjectSchemaDefinitions>

Em seguida, no arquivo de destinos, adicione:

<ItemGroup>
  <PropertyPageSchema Include="MyProjectItemsSchema.xml"/>
</ItemGroup>

Exemplo: $(VCTargetsPath)\BuildCustomizations\masm.xml

Depuradores

O serviço de depuração no Visual Studio oferece suporte à extensibilidade para o motor de depuração. Para obter mais informações, consulte estes exemplos:

• MIEngine, um projeto de código aberto que suporta a depuração com lldb

• Exemplo de mecanismo de depuração do Visual Studio

Para especificar os mecanismos de depuração e outras propriedades para a sessão de depuração, deve-se implementar um componente MEF do Debug Launcher e adicionar uma regra debugger. Para obter um exemplo, consulte o arquivo $(VCTargetsPath)\1033\debugger_local_windows.xml.

Implantar

os projetos .vcxproj utilizam a extensibilidade do Visual Studio Project System para Deploy Providers.

Build up-To- verificação de data

Por padrão, a verificação build up-to-date requer que os arquivos .tlog de leitura e gravação sejam criados na pasta $(TlogLocation) durante a compilação para todas as entradas e saídas de compilação.

Para usar uma verificação de data up-topersonalizada:

1. Desative a verificação de data padrão de up-toao adicionar a capacidade NoVCDefaultBuildUpToDateCheckProvider no arquivo Toolset.targets.

   <ItemGroup>
     <ProjectCapability Include="NoVCDefaultBuildUpToDateCheckProvider" />
   </ItemGroup>
   

2. Implemente o seu próprio IBuildUpToDateCheckProvider.

Atualização do projeto

Atualizador padrão de projetos .vcxproj

O atualizador de projeto .vcxproj padrão altera o PlatformToolset, ApplicationTypeRevision, a versão do conjunto de ferramentas MSBuild e o .NET Framework. Os dois últimos são sempre alterados para os padrões de versão do Visual Studio, mas PlatformToolset e ApplicationTypeRevision podem ser controlados por propriedades especiais do MSBuild.

O atualizador usa estes critérios para decidir se um projeto pode ser atualizado ou não:

1. Para projetos que definem ApplicationType e ApplicationTypeRevision, há uma pasta com um número de revisão maior do que a atual.

2. A propriedade _UpgradePlatformToolsetFor_<safe_toolset_name> é definida para o conjunto de ferramentas atual e seu valor não é igual ao conjunto de ferramentas atual.

   Nesses nomes de propriedade, <safe_toolset_name> representa o nome do conjunto de ferramentas com todos os caracteres não alfanuméricos substituídos por um sublinhado (_).

Quando um projeto pode ser melhorado, é incluído no Solution Retargeting. Para obter mais informações, veja IVsTrackProjectRetargeting2.

Se você quiser adornar nomes de projeto em Gerenciador de Soluções quando os projetos usam um conjunto de ferramentas específico, defina uma propriedade _PlatformToolsetShortNameFor_<safe_toolset_name>.

Para obter exemplos de definições de propriedade _UpgradePlatformToolsetFor_<safe_toolset_name> e _PlatformToolsetShortNameFor_<safe_toolset_name>, consulte o arquivo Microsoft.Cpp.Default.props. Para obter exemplos de uso, consulte o ficheiro $(VCTargetPath)\Microsoft.Cpp.Platform.targets.

Atualizador de projeto personalizado

Para usar um objeto de upgrade de projeto personalizado, implemente um componente MEF, conforme mostrado aqui:

/// </summary>
[Export("MyProjectUpgrader", typeof(IProjectRetargetHandler))]
[Export(typeof(IProjectRetargetHandler))]
[ExportMetadata("Name", "MyProjectUpgrader")]
[OrderPrecedence(20)]
[PartMetadata(ProjectCapabilities.Requires, ProjectCapabilities.VisualC)]

internal class MyProjectUpgrader: IProjectRetargetHandler
{
    // ...
}

O seu código pode importar e chamar o objeto atualizador padrão de .vcxproj:

// ...
[Import("VCDefaultProjectUpgrader")]
// ...
    IProjectRetargetHandler Lazy<IProjectRetargetHandler>
    VCDefaultProjectUpgrader { get; set; }
// ...

IProjectRetargetHandler é definido em Microsoft.VisualStudio.ProjectSystem.VS.dll e é semelhante a IVsRetargetProjectAsync.

Defina a propriedade VCProjectUpgraderObjectName para informar ao sistema de projeto para usar seu objeto de upgrade personalizado:

<PropertyGroup>
  <VCProjectUpgraderObjectName>MyProjectUpgrader</VCProjectUpgraderObjectName>
</PropertyGroup>

Desativar atualização do projeto

Para desativar as atualizações do projeto, use um valor NoUpgrade.

<PropertyGroup>
  <VCProjectUpgraderObjectName>NoUpgrade</VCProjectUpgraderObjectName>
</PropertyGroup>

Cache e extensibilidade do projeto

Para melhorar o desempenho ao trabalhar com grandes soluções C++ no Visual Studio 2017, a cache de projeto foi introduzida. Ele é implementado como um banco de dados SQLite preenchido com dados do projeto e, em seguida, usado para carregar projetos sem carregar projetos MSBuild ou CPS na memória.

Como não há objetos CPS presentes para .vcxproj projetos carregados do cache, os componentes MEF da extensão que importam UnconfiguredProject ou ConfiguredProject não podem ser criados. Para oferecer suporte à extensibilidade, o cache do projeto não é usado quando o Visual Studio deteta se um projeto usa (ou provavelmente usará) extensões MEF.

Esses tipos de projeto são sempre totalmente carregados e têm objetos CPS na memória, portanto, todas as extensões MEF são criadas para eles:

• Projetos de startup

• Projetos que têm um atualizador de projeto personalizado, ou seja, definem uma propriedade VCProjectUpgraderObjectName

• Projetos que não se destinam ao Desktop Windows, isto é, aqueles que definem uma propriedade ApplicationType

• Projetos de Itens Partilhados (.vcxitems) e quaisquer projetos que façam referência a eles através da importação de projetos .vcxitems.

Se nenhuma dessas condições for detetada, um cache de projeto será criado. O cache inclui todos os dados do projeto MSBuild necessários para responder a consultas get em interfaces VCProjectEngine. Isso significa que todas as modificações ao nível dos ficheiros de propriedades e alvos do MSBuild feitas por uma extensão devem simplesmente funcionar em projetos carregados do cache.

Envio da extensão

Para obter informações sobre como criar arquivos VSIX, consulte Distribuindo extensões do Visual Studio. Para obter informações sobre como adicionar arquivos a locais de instalação especiais, por exemplo, para adicionar arquivos em $(VCTargetsPath), consulte Instalando fora da pasta de extensões.

Recursos adicionais

O Microsoft Build System (MSBuild) fornece o mecanismo de compilação e o formato baseado em XML extensível para arquivos de projeto. Você deve estar familiarizado com conceitos básicos MSBuild e com como MSBuild para Visual C++ funciona para estender o sistema de projeto Visual C++.

O Managed Extensibility Framework (MEF) fornece as APIs de extensão que são usadas pelo CPS e o sistema de projeto Visual C++. Para obter uma visão geral de como o MEF é usado pelo CPS, consulte CPS e MEF na visão geral do MEF no VSProjectSystem.

Você pode personalizar o sistema de compilação existente para adicionar etapas de compilação ou novos tipos de arquivo. Para obter mais informações, consulte Visão geral do MSBuild (Visual C++) e Trabalhando com propriedades do projeto.