Archivos XML de página de propiedades

Las páginas de propiedades del proyecto en el IDE se configuran con archivos XML en la carpeta de reglas predeterminada. Los archivos XML describen los nombres de las reglas, las categorías y las propiedades individuales, su tipo de datos, los valores predeterminados y cómo se muestran. Cuando se establece una propiedad en el IDE, el valor nuevo se almacena en el archivo de proyecto.

La ruta de acceso a la carpeta del archivo de reglas predeterminado depende de la configuración regional y de la versión de Visual Studio en uso. En un símbolo del sistema para desarrolladores de Visual Studio 2019 o posterior, la carpeta de reglas es %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\<locale>\, donde el valor <version> es v160 en Visual Studio 2019. <locale> es un LCID, por ejemplo, 1033 para inglés. En Visual Studio 2017, la carpeta de reglas es %VSINSTALLDIR%Common7\IDE\VC\VCTargets\<locale>\. En un símbolo del sistema para desarrolladores de Visual Studio 2015 o anterior, la carpeta de reglas es %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>\. Se usa una ruta de acceso diferente para cada edición de Visual Studio instalada, y para cada idioma. Por ejemplo, la ruta predeterminada de la carpeta de reglas de Visual Studio 2019 edición Community en inglés podría ser C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\1033\.

Solo se necesita entender el funcionamiento interno de estos archivos y del IDE de Visual Studio en un par de escenarios:

• Cuando se quiere crear una página de propiedades personalizada.
• Cuando se quiere personalizar las propiedades del proyecto sin usar el IDE de Visual Studio.

Contenido de los archivos de reglas

En primer lugar, abra las páginas de propiedades de un proyecto. Haga clic con el botón derecho en el nodo del proyecto en el Explorador de soluciones y elija Propiedades:

Cada nodo situado bajo las Propiedades de configuración se denomina una regla. A veces, una regla representa una única herramienta, como el compilador. En general, el término hace referencia a algo que tiene propiedades, que se ejecuta y que puede generar algún resultado. Cada regla se rellena a partir de un archivo XML en la carpeta de reglas predeterminada. Por ejemplo, la regla de C/C++ que se muestra aquí se rellena por cl.xml.

Cada regla tiene un conjunto de propiedades que están organizadas en categorías. Cada subnodo de una regla representa una categoría. Por ejemplo, el nodo Optimización en C/C++ contiene todas las propiedades relacionadas con la optimización de la herramienta de compilador. Las propiedades y sus valores se presentan en un formato de cuadrícula en el panel de la derecha.

Puede abrir cl.xml en el Bloc de notas o en cualquier editor XML. Se verá un nodo raíz denominado Rule. Define la misma lista de propiedades que se muestran en la interfaz de usuario, junto con los metadatos adicionales.

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

Hay un archivo XML para cada nodo en las Propiedades de configuración en la interfaz de usuario de páginas de propiedades. Puede agregar o quitar reglas en la interfaz de usuario: se realiza mediante la inclusión o eliminación de las ubicaciones de los archivos XML correspondientes en el proyecto. Por ejemplo, es la manera cómo Microsoft.CppBuild.targets (que se encuentra en un nivel superior a la carpeta 1033) incluye a cl.xml:

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

Si se quita cl.xml de todos los datos, se tiene este marco básico:

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

La siguiente sección describe cada uno de los elementos principales y algunos de los metadatos que se pueden adjuntar.

Atributos de regla

Un elemento <Rule> es el nodo raíz del archivo XML. Puede tener muchos 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: el atributo Name es un id. para Rule. Debe ser único entre todos los archivos XML de la página de propiedades de un proyecto.

• PageTemplate: la interfaz de usuario usa el valor de este atributo para elegir entre una colección de plantillas de interfaz de usuario. La plantilla "tool" representa las propiedades en un formato de cuadrícula estándar. Otros valores integrados para este atributo son "debugger" y "generic". Vea el nodo Depuración y el nodo General, respectivamente, para ver el formato de la interfaz de usuario resultante de la especificación de estos valores. La interfaz de usuario de la plantilla de la página del "depurador" usa un cuadro desplegable para cambiar entre las propiedades de los diferentes depuradores. La plantilla "genérica" muestra las diferentes categorías de propiedades en una sola página, en lugar de tener varios subnodos de categoría en el nodo Rule. Este atributo únicamente una sugerencia para la interfaz de usuario. El archivo XML está diseñado para ser independiente de la interfaz de usuario. Es posible que en otra interfaz de usuario este atributo se use para otros fines.

• SwitchPrefix: es el prefijo que se usa en la línea de comandos para los modificadores. Un valor de "/" genera modificadores similares a /ZI, /nologo, /W3, etc.

• Order: es una sugerencia a un cliente potencial de interfaz de usuario en la ubicación relativa de esta Rule en comparación con todas las demás reglas del sistema.

• xmlns: un elemento XML estándar. Puede ver tres espacios de nombres enumerados. Estos atributos corresponden con los espacios de nombres para las clases de deserialización XML, el esquema XML y el espacio de nombres del sistema, respectivamente.

• DisplayName: es el nombre que se muestra en la interfaz de usuario de página de propiedades para el nodo Rule. Este valor se localiza. Se ha creado DisplayName como un elemento secundario de Rule en lugar de un atributo (por ejemplo, Name o SwitchPrefix) debido a los requisitos de la herramienta de localización interna. Desde la perspectiva de XML, ambos son equivalentes. Por tanto, se puede convertir simplemente en un atributo para reducir el desorden o dejarlo tal cual.

• DataSource: esta propiedad importante indica al sistema del proyecto la ubicación para leer y escribir el valor de la propiedad y su agrupación (se explica más adelante). Para cl.xml, estos valores son:

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

  • Persistence="ProjectFile" indica al sistema del proyecto que todas las propiedades de Rule se deben escribir en el archivo de proyecto o el archivo de hoja de propiedades (en función del nodo que se haya usado para generar las páginas de propiedades). El otro valor posible es "UserFile", que escribirá el valor en el archivo .user.

  • ItemType="ClCompile" indica que las propiedades se almacenarán como metadatos de ItemDefinition o metadatos de elemento (este último solo si las páginas de propiedades se generaron desde un nodo de archivo en el Explorador de soluciones) de este tipo de elemento. Si no se establece este campo, la propiedad se escribe como una propiedad común en un PropertyGroup.

  • Label="" indica que cuando las propiedades se escriben como metadatos de ItemDefinition, la etiqueta del elemento primario ItemDefinitionGroup estará vacía (todos los elementos de MSBuild pueden tener una etiqueta). En Visual Studio 2017 y versiones posteriores se usan grupos con etiquetas para navegar por el archivo de proyecto .vcxproj. Los grupos que contienen la mayoría de las propiedades de Rule tienen una cadena vacía como etiqueta.

  • HasConfigurationCondition="true" indica al sistema de proyecto que adjunte una condición de configuración al valor para que solo surta efecto para la configuración del proyecto actual (la condición se puede adjuntar al grupo primario o al propio valor). Por ejemplo, abra las páginas de propiedades del nodo de proyecto y establezca el valor de la propiedad Tratar advertencias como errores en Propiedades de configuración > C/C++ general en "Sí". En el archivo del proyecto se escribe el valor siguiente. Observe la condición de configuración adjunta al elemento primario ItemDefinitionGroup.

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

    Si este valor se establece en la página de propiedades de un archivo concreto, como stdafx.cpp, entonces el valor de propiedad debe escribirse bajo el elemento stdafx.cpp en el archivo del proyecto como se muestra aquí. Observe cómo la condición de configuración se adjunta directamente a los propios metadatos:

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

  Otro atributo de DataSource que no aparece aquí es PersistedName. Puede usar este atributo para representar una propiedad en el archivo del proyecto mediante otro nombre. De forma predeterminada, este atributo se establece en el Name de la propiedad.

  Una propiedad individual puede invalidar la DataSource de su Rule primaria. En ese caso, la ubicación para el valor de esa propiedad será diferente al de otras propiedades de la Rule.

• Hay otros atributos de una Rule, incluidas la Description y el SupportsFileBatching, que no se muestran aquí. Para obtener el conjunto completo de los atributos aplicables a una Rule o en cualquier otro elemento, examine la documentación para estos tipos. Como alternativa, puede examinar las propiedades públicas de los tipos en el espacio de nombres Microsoft.Build.Framework.XamlTypes del ensamblado Microsoft.Build.Framework.dll.

• DisplayName, PageTemplate, y Order son propiedades relacionadas con la interfaz de usuario que están presentes en este modelo de datos que, en otros casos, es independiente de la interfaz de usuario. Con toda probabilidad estas propiedades se usarán en cualquier interfaz de usuario que se use para mostrar las páginas de propiedades. DisplayName y Description son dos propiedades que están presentes en casi todos los elementos del archivo XML. Además, estas dos propiedades son las únicas localizadas.

Elementos de categoría

Una Rule puede tener varios elementos de Category. El orden en que se muestran las categorías en el archivo XML es una sugerencia para que la interfaz de usuario muestre las categorías en el mismo orden. Por ejemplo, el orden de las categorías en el nodo C/C++ que se ve en la interfaz de usuario es el mismo que el orden en cl.xml. Una categoría de ejemplo tiene el aspecto siguiente:

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

Este fragmento de código muestra los atributos Name y DisplayName que se describieron anteriormente. Una vez más, hay otros atributos que Category puede tener que no se muestran en el ejemplo. Puede obtener información sobre ellos si lee la documentación o examina los ensamblados al usar ildasm.exe.

Elementos de propiedad

La mayoría del archivo de regla consta de elementos Property. Contienen la lista de todas las propiedades de una Rule. Cada propiedad puede ser uno de los cinco tipos posibles que se muestran en el marco: BoolProperty, EnumProperty, IntProperty, StringProperty y StringListProperty. Es posible que sólo tenga algunos de esos tipos en el archivo. Una propiedad tiene un número de atributos que permiten que se pueda describir de manera detallada. La StringProperty se describe aquí. Los demás son similares.

<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 mayoría de los atributos del fragmento de código se han descrito antes. Los nuevos son Subtype, Category y Switch.

• Subtype es un atributo disponible solo para los elementos de StringProperty y StringListProperty. Proporciona información contextual. Por ejemplo, el valor file indica que la propiedad representa una ruta de acceso del archivo. Visual Studio usa esta información contextual para mejorar la experiencia de edición. Por ejemplo, puede proporcionar una ventana del Explorador de Windows que permita al usuario elegir visualmente el archivo como editor de la propiedad.

• Category: es la categoría a la que pertenece esta propiedad. Intente buscar esta propiedad en la categoría Archivos de salida de la interfaz de usuario.

• Switch: cuando una regla representa una herramienta como la del compilador, la mayoría de las propiedades de la Rule se pasan como modificadores al archivo ejecutable de la herramienta en el tiempo de compilación. El valor de este atributo indica qué literal de modificador se debe usar. El ejemplo <StringProperty> especifica que su modificador debe ser Fo. Combinado con el atributo SwitchPrefix en la Rule primaria, esta propiedad se pasa al ejecutable como /Fo"Debug\". Está visible en la línea de comandos de C/C++ en la interfaz de usuario de la página de propiedades.

  Otros atributos de propiedad incluyen los siguientes:

• Visible: si no desea que la propiedad aparezca en las páginas de propiedades, pero quiere que esté disponible en el tiempo de compilación, establezca este atributo en false.

• ReadOnly: si quiere proporcionar una vista de solo lectura del valor de esta propiedad en las páginas de propiedades, establezca este atributo en true.

• IncludeInCommandLine: en tiempo de compilación, es posible que una herramienta no necesite algunas de sus propiedades. Establezca este atributo en false para evitar que se pase una propiedad concreta.