Arquivos de regra XML da Página de Propriedades

As páginas de propriedades do projeto no IDE são configuradas por arquivos XML na pasta de regras padrão. Os arquivos XML descrevem os nomes das regras, as categorias e as propriedades individuais, seu tipo de dados, valores padrão e como exibi-los. Quando você define uma propriedade no IDE, o novo valor é armazenado no arquivo de projeto.

O caminho para a pasta de regras padrão depende da localidade e da versão do Visual Studio em uso. Em um prompt de comando do desenvolvedor do Visual Studio 2019 ou posterior, a pasta de regras é %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\<locale>\, em que o valor <version> é v160 no Visual Studio 2019. O <locale> é um LCID; por exemplo, 1033 para inglês. No Visual Studio 2017, a pasta de regras é %VSINSTALLDIR%Common7\IDE\VC\VCTargets\<locale>\. Em um prompt de comando do desenvolvedor do Visual Studio 2015 ou anterior, a pasta de regra é %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>\. Você usará um caminho diferente para cada linguagem e edição instalada do Visual Studio. Por exemplo, o caminho da pasta de regras padrão no Visual Studio 2019 Community Edition em inglês poderia ser C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\1033\.

Você só precisa entender o funcionamento interno desses arquivos e o IDE do Visual Studio em alguns cenários:

• Você deseja criar uma página de propriedades personalizada ou
• Você deseja personalizar as propriedades do projeto sem o uso do IDE do Visual Studio.

Conteúdo de arquivos de regra

Primeiro, vamos abrir as páginas de propriedades de um projeto. Clique com o botão direito do mouse no nó do projeto no Gerenciador de Soluções e selecione Propriedades:

Cada nó em Propriedades de Configuração é chamado de Regra. Uma regra às vezes representa uma só ferramenta como o compilador. Em geral, o termo se refere a algo que tem propriedades, que é executado e que pode produzir uma saída. Cada regra é preenchida com base em um arquivo XML na pasta de regras padrão. Por exemplo, a regra do C/C++ mostrada acima é preenchida por cl.xml.

Cada Regra tem um conjunto de propriedades que são organizadas em categorias. Cada subnó em uma regra representa uma categoria. Por exemplo, o nó Otimização no C/C++ contém todas as propriedades relacionadas à otimização da ferramenta de compilador. As propriedades e seus valores são renderizados em um formato de grade no painel direito.

Você pode abrir cl.xml no bloco de notas ou em qualquer editor XML. Você verá um nó raiz chamado Rule. Ele define a mesma lista de propriedades exibidas na interface do usuário, além de metadados adicionais.

<?xml version="1.0" encoding="utf-8"?>
<!--Copyright, Microsoft Corporation, All rights reserved.-->
<Rule Name="CL" PageTemplate="tool" DisplayName="C/C++" SwitchPrefix="/" Order="10" xmlns="http://schemas.microsoft.com/build/2009/properties" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:sys="clr-namespace:System;assembly=mscorlib">
  <Rule.Categories>
    <Category Name="General" DisplayName="General" />
    <Category Name="Optimization" DisplayName="Optimization" />
    <Category Name="Preprocessor" DisplayName="Preprocessor" />
    <Category Name="Code Generation" DisplayName="Code Generation" />
    <Category Name="Language" DisplayName="Language" />
    <Category Name="Precompiled Headers" DisplayName="Precompiled Headers" />
    <Category Name="Output Files" DisplayName="Output Files" />
    <Category Name="Browse Information" DisplayName="Browse Information" />
    <Category Name="Advanced" DisplayName="Advanced" />
    <Category Name="All Options" DisplayName="All Options" Subtype="Search" />
    <Category Name="Command Line" DisplayName="Command Line" Subtype="CommandLine" />
  </Rule.Categories>
  <!-- . . . -->
</Rule>

Há um arquivo XML para a cada nó em Propriedades de Configuração na interface do usuário das páginas de propriedades. Adicione ou remova as regras na interface do usuário: isso é feito incluindo ou removendo locais para arquivos XML correspondentes no projeto. Por exemplo, é como Microsoft.CppBuild.targets (encontrado um nível maior que a pasta 1033) inclui cl.xml:

<PropertyPageSchema Condition="'$(ConfigurationType)' != 'Utility'" Include="$(VCTargetsPath)$(LangID)\cl.xml"/>

Se você remover cl.xml de todos os dados, terá esta estrutura básica:

<?xml version="1.0" encoding="utf-8"?>
<Rule>
  <Rule.DataSource />
  <Rule.Categories>
    <Category />
    <!-- . . . -->
  </Rule.Categories>
  <BoolProperty />
  <EnumProperty />
  <IntProperty />
  <StringProperty />
  <StringListProperty />
</Rule>

A próxima seção descreve cada elemento principal e alguns dos metadados que você pode anexar.

Atributos de regra

Um elemento <Rule> é o nó raiz no arquivo XML. Ele pode ter muitos atributos:

<Rule Name="CL" PageTemplate="tool" SwitchPrefix="/" Order="10"
          xmlns="http://schemas.microsoft.com/build/2009/properties"
          xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
          xmlns:sys="clr-namespace:System;assembly=mscorlib">
  <Rule.DisplayName>
    <sys:String>C/C++</sys:String>
  </Rule.DisplayName>

• Name: o atributo Name é uma ID para a Rule. Precisa ser exclusivo entre todos os arquivos XML da página de propriedades de um projeto.

• PageTemplate: o valor desse atributo é usado pela interface do usuário para a escolha de um item em uma coleção de modelos de interface do usuário. O modelo de "ferramenta" renderiza as propriedades em um formato de grade padrão. Outros valores internos para esse atributo são "depurador" e "genérico". Veja os nós Depuração e Geral, respectivamente, para ver o formato de interface do usuário resultante da especificação desses valores. A interface do usuário do modelo de página "depurador" usa uma caixa suspensa para alternar entre as propriedades de diferentes depuradores. O modelo "genérico" exibe categorias de diferentes propriedades em uma só página, em vez de ter vários subnós de categoria abaixo do nó Rule. Esse atributo é apenas uma sugestão para a interface do usuário. O arquivo XML foi projetado para ser independente da interface do usuário. Outra interface do usuário pode usar esse atributo para diferentes finalidades.

• SwitchPrefix: o prefixo usado na linha de comando para as opções. Um valor de "/" resultaria em opções semelhantes /ZI, /nologo, /W3 etc.

• Order: é uma sugestão para um cliente de interface do usuário em potencial no local relativo desta Rule em comparação com todas as outras Regras no sistema.

• xmlns: um elemento XML padrão. É possível ver três namespaces listados. Esses atributos correspondem aos namespaces para as classes de desserialização de XML, o esquema XML e o namespace do sistema, respectivamente.

• DisplayName: o nome mostrado na interface do usuário da página de propriedades para o nó Rule. Esse valor está localizado. Criamos DisplayName como um elemento filho de Rule, em vez de um atributo (como Name ou SwitchPrefix) devido aos requisitos da ferramenta de localização interna. Da perspectiva do XML, ambos são equivalentes. Portanto, basta torná-lo um atributo para reduzir a desordem ou deixá-lo como é.

• DataSource: essa propriedade importante informa ao sistema de projeto o local em que ler e gravar o valor da propriedade e seu agrupamento (explicado posteriormente). Para cl.xml, esses valores são:

  <DataSource Persistence="ProjectFile" ItemType="ClCompile" Label="" HasConfigurationCondition="true" />
  

  • Persistence="ProjectFile" informa o sistema do projeto que todas as propriedades para a Rule devem ser gravadas no arquivo de projeto ou no arquivo de folha de propriedades (dependendo de qual nó foi usado para gerar as páginas de propriedades). O outro valor possível é "UserFile", que gravará o valor no arquivo .user.

  • ItemType="ClCompile" indica que as propriedades serão armazenadas como metadados de ItemDefinition ou metadados de item (o último somente ocorrerá se as páginas de propriedades foram geradas com base em um nó de arquivo no Gerenciador de Soluções) desse tipo de item. Se esse campo não é definido, a propriedade é gravada como uma propriedade comum em um PropertyGroup.

  • Label="" indica que quando as propriedades forem gravadas como metadados de ItemDefinition, o rótulo do ItemDefinitionGroup pai ficará vazio (cada elemento do MSBuild pode ter um Rótulo). O Visual Studio 2017 e posterior usa grupos rotulados para navegar pelo arquivo de projeto .vcxproj. Os grupos que contêm a maioria das propriedades Rule têm uma cadeia de caracteres vazia como etiqueta.

  • HasConfigurationCondition="true" instrui o sistema do projeto a afixar uma condição de configuração ao valor, de modo que ele entre em vigor apenas na configuração do projeto atual (a condição pode ser afixada ao grupo pai ou ao próprio valor). Por exemplo, abra as páginas de propriedades do nó do projeto e defina o valor da propriedade Tratar Avisos como Erros em Propriedades de Configuração > Geral do C/C++ como "Sim". O valor a seguir é gravado no arquivo de projeto. Observe a condição de configuração anexada ao ItemDefinitionGroup pai.

    <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">
      <ClCompile>
        <TreatWarningAsError>true</TreatWarningAsError>
      </ClCompile>
    </ItemDefinitionGroup>
    

    Se esse valor está definido na página de propriedades de um arquivo específico, como stdafx.cpp, o valor da propriedade deve ser gravado sob o item stdafx.cpp no arquivo de projeto, conforme mostrado aqui. Observe como a condição de configuração está diretamente anexada aos próprios metadados:

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

  Outro atributo de DataSource não listado acima é PersistedName. Use esse atributo para representar uma propriedade no arquivo de projeto usando outro nome. Por padrão, esse atributo é definido com o Name da propriedade.

  Uma propriedade individual pode substituir a DataSource da Rule pai. Nesse caso, o local para o valor da propriedade será diferente das outras propriedades na Rule.

• Há outros atributos de uma Rule, como Description e SupportsFileBatching, que não são mostrados aqui. Obtenha o conjunto completo de atributos aplicáveis a uma Rule ou a qualquer outro elemento navegando pela documentação desses tipos. Como alternativa, você pode examinar as propriedades públicas nos tipos no namespace Microsoft.Build.Framework.XamlTypes do assembly Microsoft.Build.Framework.dll.

• DisplayName, PageTemplate e Order são propriedades relacionadas à interface do usuário que estão presentes nesse modelo de dados, de outro modo, independente de interface do usuário. Quase certamente, essas propriedades serão usadas por qualquer interface do usuário usada para exibir as páginas de propriedades. DisplayName e Description são duas propriedades que estão presentes em quase todos os elementos do arquivo XML. E essas duas propriedades são as únicas localizadas.

Elementos de categoria

Um Rule pode ter vários elementos Category. A ordem na qual as categorias são listadas no arquivo XML é uma sugestão para que a interface do usuário exiba as categorias na mesma ordem. Por exemplo, a ordem das categorias no nó C/C++ que você vê na interface do usuário é a mesma ordem que em cl.xml. Uma categoria de exemplo tem esta aparência:

<Category Name="Optimization">
  <Category.DisplayName>
    <sys:String>Optimization</sys:String>
  </Category.DisplayName>
</Category>

O snippet acima mostra os atributos Name e DisplayName descritos antes. Mais uma vez, há outros atributos que um Category pode ter e que não são mostrados no exemplo. Aprenda mais sobre eles lendo a documentação ou examinando os assemblies usando ildasm.exe.

Elementos de propriedade

A maioria do arquivo de regra consiste em elementos Property. Eles contêm a lista de todas as propriedades em um Rule. Cada propriedade pode ter um dos cinco tipos possíveis mostrados na estrutura básica: BoolProperty, EnumProperty, IntProperty, StringProperty e StringListProperty. Você pode ter apenas alguns desses tipos em seu arquivo. Uma propriedade tem diversos atributos que permitem que ela seja descrita em detalhes. A StringProperty é descrita aqui. O restante é muito parecido.

<StringProperty Subtype="file" Name="ObjectFileName" Category="Output Files" Switch="Fo">
  <StringProperty.DisplayName>
    <sys:String>Object File Name</sys:String>
  </StringProperty.DisplayName>
  <StringProperty.Description>
    <sys:String>Specifies a name to override the default object file name; can be file or directory name.(/Fo[name])</sys:String>
  </StringProperty.Description>
</StringProperty>

A maioria dos atributos no snippet foi descrita antes. Os novos são Subtype, Category e Switch.

• Subtype é um atributo disponível apenas para elementos StringProperty e StringListProperty. Ele fornece informações contextuais. Por exemplo, o valor de file indica que a propriedade representa um caminho de arquivo. O Visual Studio usa essas informações contextuais para aprimorar a experiência de edição. Por exemplo, ele pode fornecer uma janela do Windows Explorer que permite que o usuário escolha o arquivo visualmente como editor da propriedade.

• Category: a categoria na qual essa propriedade se enquadra. Tente encontrar essa propriedade na categoria Arquivos de Saída na interface do usuário.

• Switch: quando uma regra representa uma ferramenta, como a ferramenta do compilador, a maioria das propriedades da Rule é passada como opções para o executável da ferramenta no momento do build. O valor desse atributo indica qual literal de opção usar. O exemplo <StringProperty> especifica que sua opção deve ser Fo. Combinada com o atributo SwitchPrefix na Rule pai, essa propriedade é passada para o executável como /Fo"Debug\". Ele fica visível na linha de comando para C/C++ na interface do usuário da página de propriedades.

  Outros atributos de propriedade incluem:

• Visible: se você não quiser que sua propriedade apareça nas páginas de propriedades, mas quiser que ela esteja disponível no tempo de compilação, defina esse atributo como false.

• ReadOnly: caso deseje fornecer uma exibição somente leitura do valor dessa propriedade nas páginas de propriedades, defina esse atributo como true.

• IncludeInCommandLine: em tempo de compilação, uma ferramenta pode não precisar de algumas de suas propriedades. Defina esse atributo como false para impedir que uma propriedade específica seja passada.