Fichiers de règles XML des pages de propriétés

Les pages de propriétés du projet dans l’IDE sont configurées par des fichiers XML dans le dossier de règles par défaut. Les fichiers XML décrivent les noms des règles, des catégories et des propriétés individuelles, leur type de données, leurs valeurs par défaut et comment les afficher. Quand vous définissez une propriété dans l’IDE, la nouvelle valeur est stockée dans le fichier projet.

Le chemin d’accès au dossier de règles par défaut dépend des paramètres régionaux et de la version de Visual Studio en cours d’utilisation. Dans une invite de commandes développeur Visual Studio 2019 ou ultérieure, le dossier règles est %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\<locale>\, où la <version> valeur se trouve v160 dans Visual Studio 2019. Il <locale> s’agit d’un LCID, par exemple, 1033 pour l’anglais. Dans Visual Studio 2017, le dossier règles est %VSINSTALLDIR%Common7\IDE\VC\VCTargets\<locale>\. Dans une invite de commandes développeur Visual Studio 2015 ou antérieure, le dossier règles est %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>\. Vous utiliserez un chemin différent pour chaque édition de Visual Studio installée et pour chaque langue. Par exemple, le chemin d’accès au dossier de règles par défaut pour Visual Studio 2019 Community edition en anglais peut être C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\1033\.

Vous devez uniquement comprendre les fonctionnements internes de ces fichiers et l’IDE Visual Studio dans quelques scénarios :

• Vous souhaitez créer une page de propriétés personnalisée ou
• Vous souhaitez personnaliser vos propriétés de projet sans utiliser l’IDE Visual Studio.

Contenu des fichiers de règle

Tout d’abord, nous allons ouvrir les pages de propriétés d’un projet. Cliquez avec le bouton droit sur le nœud du projet dans Explorateur de solutions et choisissez Propriétés :

Chaque nœud sous Propriétés de configuration est appelé règle. Une règle représente parfois un seul outil comme le compilateur. En général, le terme fait référence à quelque chose qui a des propriétés, qui s’exécute et qui peut produire une sortie. Chaque règle est remplie à partir d’un fichier XML dans le dossier de règles par défaut. Par exemple, la règle C/C++ illustrée ici est remplie par cl.xml.

Chaque règle a un ensemble de propriétés, qui sont organisées en catégories. Chaque sous-nœud sous une règle représente une catégorie. Par exemple, le nœud Optimisation sous C/C++ contient toutes les propriétés liées à l’optimisation de l’outil de compilateur. Les propriétés et leurs valeurs sont rendues dans un format de grille dans le volet droit.

Vous pouvez ouvrir cl.xml dans le Bloc-notes ou n’importe quel éditeur XML. Vous verrez un nœud racine appelé Rule. Il définit la même liste de propriétés qui s’affichent dans l’interface utilisateur, ainsi que des métadonnées supplémentaires.

<?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>

Il existe un fichier XML pour chaque nœud sous Propriétés de configuration dans l’interface utilisateur des pages de propriétés. Vous pouvez ajouter ou supprimer des règles dans l’interface utilisateur : elle est effectuée en incluant ou en supprimant des emplacements aux fichiers XML correspondants dans le projet. Par exemple, il s’agit de la façon dont Microsoft.CppBuild.targets (trouvé un niveau supérieur au dossier 1033) inclut cl.xml:

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

Si vous supprimez cl.xml toutes les données, vous disposez de cette infrastructure de base :

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

La section suivante décrit chaque élément principal et certaines des métadonnées que vous pouvez attacher.

Attributs de règle

Un <Rule> élément est le nœud racine du fichier XML. Il peut avoir de nombreux attributs :

<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: l’attribut Name est un ID pour le Rule. Il doit être unique parmi tous les fichiers XML de la page de propriétés d’un projet.

• PageTemplate: la valeur de cet attribut est utilisée par l’interface utilisateur pour choisir parmi une collection de modèles d’interface utilisateur. Le modèle « tool » montre les propriétés selon un format de grille standard. D’autres valeurs prédéfinies de cet attribut sont « debugger » et « generic ». Regardez respectivement le nœud Debugging et le nœud General pour voir le format d’interface utilisateur qui résulte de la spécification de ces valeurs. L’interface utilisateur du modèle de page « débogueur » utilise une zone de liste déroulante pour basculer entre les propriétés des différents débogueurs. Le modèle « générique » affiche différentes catégories de propriétés dans une seule page, au lieu d’avoir plusieurs sous-nœuds de catégorie sous le Rule nœud. Cet attribut est simplement une suggestion à l’interface utilisateur. Le fichier XML est conçu pour être indépendant de l’interface utilisateur. Une autre interface utilisateur peut utiliser cet attribut à des fins différentes.

• SwitchPrefix: préfixe utilisé dans la ligne de commande pour les commutateurs. Une valeur de "/" cela entraînerait des commutateurs qui ressemblent /ZI, /nologoet /W3ainsi de suite.

• Order: suggestion d’un client d’interface utilisateur potentiel sur l’emplacement relatif de celui-ci Rule par rapport à toutes les autres règles du système.

• xmlns: élément XML standard. Vous pouvez voir trois espaces de noms répertoriés. Ces attributs correspondent aux espaces de noms des classes de désérialisation XML, au schéma XML et à l’espace de noms système, respectivement.

• DisplayName: nom affiché dans l’interface utilisateur de la page de propriétés du Rule nœud. Cette valeur est localisée. Nous avons créé DisplayName en tant qu’élément enfant plutôt Rule qu’en tant qu’attribut (comme Name ou SwitchPrefix) en raison des exigences de l’outil de localisation interne. Du point de vue XML, les deux sont équivalents. Vous pouvez donc simplement en faire un attribut pour réduire l’encombrement ou le laisser tel quel.

• DataSource: cette propriété importante indique au système de projet l’emplacement pour lire et écrire la valeur de la propriété et son regroupement (expliqué plus loin). Pour cl.xml, ces valeurs sont les suivantes :

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

  • Persistence="ProjectFile" indique au système de projet que toutes les propriétés du Rule fichier projet doivent être écrites dans le fichier projet ou dans le fichier de feuille de propriétés (selon le nœud utilisé pour générer les pages de propriétés). L’autre valeur possible est "UserFile", qui écrit la valeur dans le .user fichier.

  • ItemType="ClCompile" indique que les propriétés seront stockées en tant que métadonnées ItemDefinition ou que métadonnées d’élément (ces dernières seulement si les pages de propriétés ont été générées à partir d’un nœud de fichier dans l’Explorateur de solutions) de ce type d’élément. Si ce champ n’est pas défini, la propriété est écrite en tant que propriété commune dans un PropertyGroup.

  • Label="" indique que quand les propriétés sont écrites en tant que métadonnées ItemDefinition, l’étiquette de l’élément ItemDefinitionGroup parent est vide (tous les éléments MSBuild peuvent avoir une étiquette). Visual Studio 2017 et les versions ultérieures utilisent des groupes étiquetés pour naviguer dans le fichier projet .vcxproj. Les groupes qui contiennent la plupart des Rule propriétés ont une chaîne vide sous forme d’étiquette.

  • HasConfigurationCondition="true" indique au système de projet d’ajouter une condition de configuration à la valeur pour qu’elle s’applique uniquement à la configuration de projet actuelle (la condition peut être appliquée au groupe parent ou à la valeur elle-même). Par exemple, ouvrez les pages de propriétés hors du nœud du projet et définissez la valeur de la propriété Traiter les avertissements comme une erreur sous Propriétés > de configuration C/C++ Général sur « Oui ». La valeur suivante est écrite dans le fichier projet. Notez la condition de configuration associée à l’élément ItemDefinitionGroup parent.

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

    Si cette valeur est définie dans la page de propriétés d’un fichier spécifique, par stdafx.cppexemple, la valeur de propriété doit être écrite sous l’élément stdafx.cpp du fichier projet, comme indiqué ici. Notez comment la condition de configuration est directement attachée aux métadonnées proprement dites :

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

  Un autre attribut non DataSource répertorié ici est PersistedName. Vous pouvez utiliser cet attribut pour représenter une propriété dans le fichier projet en utilisant un nom différent. Par défaut, cet attribut est défini sur la propriété Name.

  Une propriété individuelle peut remplacer le DataSource parent de son parent Rule. Dans ce cas, l’emplacement de la valeur de cette propriété sera différent des autres propriétés dans le Rule.

• Il existe d’autres attributs d’un Rule, y compris Description et SupportsFileBatching, qui ne sont pas affichés ici. L’ensemble complet d’attributs applicables à un Rule ou sur n’importe quel autre élément peut être obtenu en parcourant la documentation de ces types. Vous pouvez aussi examiner les propriétés publiques sur les types dans l’espace de noms Microsoft.Build.Framework.XamlTypes de l’assembly Microsoft.Build.Framework.dll.

• DisplayName, PageTemplateet Order sont des propriétés liées à l’interface utilisateur qui sont présentes dans ce modèle de données indépendant de l’interface utilisateur. Ces propriétés sont généralement utilisées par les interfaces utilisateur utilisées pour afficher les pages de propriétés. DisplayName et Description sont deux propriétés présentes sur presque tous les éléments du fichier XML. Et ces deux propriétés sont les seules qui sont localisées.

Éléments de catégorie

Un Rule peut avoir plusieurs Category éléments. L’ordre dans lequel les catégories sont répertoriées dans le fichier XML est une suggestion à l’interface utilisateur d’afficher les catégories dans le même ordre. Par exemple, l’ordre des catégories sous le nœud C/C++ que vous voyez dans l’interface utilisateur est identique à l’ordre dans cl.xml. Voici un exemple de catégorie :

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

Cet extrait de code affiche les NameDisplayName attributs et les attributs qui ont été décrits précédemment. Une fois de plus, il existe d’autres attributs qui ne sont pas affichés Category dans l’exemple. Vous pouvez en savoir plus sur ces derniers en lisant la documentation ou en examinant les assemblys à l’aide ildasm.exede .

Éléments de propriété

La plupart du fichier de règle se compose d’éléments Property . Ils contiennent la liste de toutes les propriétés d’un Rule. Chaque propriété peut être l’un des cinq types possibles affichés dans l’infrastructure de base : BoolProperty, , EnumProperty, IntProperty, StringPropertyet StringListProperty. Vous n’avez peut-être que quelques-uns de ces types dans votre fichier. Une propriété a un certain nombre d’attributs qui lui permettent d’être décrite en détail. La StringProperty description est décrite ici. Le reste est similaire.

<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>

La plupart des attributs de l’extrait de code ont été décrits précédemment. Les nouveaux sont Subtype, Categoryet Switch.

• Subtype est un attribut disponible uniquement pour et pour StringProperty les StringListProperty éléments. Il fournit des informations contextuelles. Par exemple, la valeur file indique que la propriété représente un chemin d’accès au fichier. Visual Studio utilise ces informations contextuelles pour améliorer l’expérience d’édition. Par exemple, il peut fournir une fenêtre d’Explorateur Windows qui permet à l’utilisateur de choisir le fichier visuellement en tant qu’éditeur de la propriété.

• Category: catégorie sous laquelle cette propriété tombe. Recherchez cette propriété sous la catégorie Fichiers de sortie dans l’interface utilisateur.

• Switch: lorsqu’une règle représente un outil tel que l’outil du compilateur, la plupart des Rule propriétés sont transmises en tant que commutateurs à l’exécutable de l’outil au moment de la génération. La valeur de cet attribut indique quel littéral basculer à utiliser. L’exemple <StringProperty> spécifie que son commutateur doit être Fo. Combinée à l’attribut SwitchPrefix sur le parent Rule, cette propriété est transmise à l’exécutable en tant que /Fo"Debug\". Elle est visible dans la ligne de commande pour C/C++ dans l’interface utilisateur de la page de propriétés.

  Voici d’autres attributs de propriété :

• Visible: si vous ne souhaitez pas que votre propriété apparaisse dans les pages de propriétés, mais si elle est disponible au moment de la génération, définissez cet attribut falsesur .

• ReadOnly: Si vous souhaitez fournir une vue en lecture seule de la valeur de cette propriété dans les pages de propriétés, définissez cet attribut truesur .

• IncludeInCommandLine: Au moment de la génération, un outil n’a peut-être pas besoin de certaines de ses propriétés. Définissez cet attribut pour false empêcher la transmission d’une propriété particulière.