XML-файлы правил для страниц свойств

Страницы свойств проекта в интегрированной среде разработки настраиваются XML-файлами в папке правил по умолчанию. XML-файлы описывают имена правил, категорий и отдельных свойств, их типа данных, значений по умолчанию и их отображения. При задании свойства в интегрированной среде разработки новое значение сохраняется в файле проекта.

Путь к папке правил по умолчанию зависит от языкового стандарта и используемой версии Visual Studio. В командной строке разработчика Visual Studio 2019 или более поздних версий папка правил располагается по пути %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\<locale>\, где <version> для Visual Studio 2019 имеет значение v160. <locale> определяет код языка, например 1033 для английского языка. В Visual Studio 2017 папка правил располагается по пути %VSINSTALLDIR%Common7\IDE\VC\VCTargets\<locale>\. В командной строке разработчика Visual Studio 2015 или более ранних версий папка правил располагается по пути %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>\. У вас будет отдельный путь для каждого устанавливаемого выпуска Visual Studio и каждого языка. Например, путь к папке с правилами по умолчанию для Visual Studio 2019 Community на английском языке может выглядеть так: C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\1033\.

Вам нужно только понять внутренние действия этих файлов и интегрированной среды разработки Visual Studio в нескольких сценариях:

• Вы хотите создать страницу пользовательского свойства или
• Вы хотите настроить свойства проекта без использования интегрированной среды разработки Visual Studio.

Содержимое файлов правил

Во-первых, давайте открываем страницы свойств для проекта. Щелкните правой кнопкой мыши узел проекта в Обозреватель решений и выберите пункт "Свойства":

Каждый узел в разделе "Свойства конфигурации" называется правилом. Иногда правило представляет собой один инструмент, например компилятор. Как правило, термин ссылается на то, что имеет свойства, которые выполняются и могут производить некоторые выходные данные. Каждое правило заполняется из XML-файла в папке правил по умолчанию. Например, правило C/C++, отображаемое здесь, заполняется cl.xml.

Каждое правило имеет набор свойств, которые упорядочены по категориям. Каждый вложенный узел в правиле представляет категорию. Например, узел оптимизации в C/C++ содержит все свойства, связанные с оптимизацией средства компилятора. Свойства и их значения отображаются в формате сетки в правой области.

Вы можете открыть cl.xml блокнот или любой редактор XML. Вы увидите корневой узел Rule. Он определяет тот же список свойств, которые отображаются в пользовательском интерфейсе, а также дополнительные метаданные.

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

Существует один XML-файл для каждого узла в разделе "Свойства конфигурации" в пользовательском интерфейсе страниц свойств. Вы можете добавить или удалить правила в пользовательском интерфейсе: это делается путем включения или удаления расположений в соответствующие XML-файлы в проекте. Например, это то, как Microsoft.CppBuild.targets (найден один уровень выше папки 1033) включает cl.xml:

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

Если вы отрезаете cl.xml все данные, у вас есть базовая платформа:

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

В следующем разделе описываются все основные элементы и некоторые метаданные, которые можно присоединить.

Атрибуты правила

Элемент <Rule> является корневым узлом в XML-файле. Он может иметь множество атрибутов:

<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: атрибут Name — это идентификатор для атрибута Rule. Он должен быть уникальным среди всех XML-файлов страницы свойств для проекта.

• PageTemplate: значение этого атрибута используется пользовательским интерфейсом для выбора из коллекции шаблонов пользовательского интерфейса. Шаблон tool отображает свойства в виде стандартной таблицы. Другими встроенными значениями для этого атрибута являются debugger и generic. См. описание узлов Debugging и General соответственно, чтобы узнать о формате, который дает указание этих значений. Пользовательский интерфейс для шаблона страницы "отладчик" использует раскрывающийся список для переключения между свойствами разных отладчиков. Шаблон "generic" отображает различные категории свойств на одной странице, а не несколько подузлов категорий под Rule узлом. Этот атрибут является просто предложением пользовательского интерфейса. XML-файл предназначен для обеспечения независимости пользовательского интерфейса. Другой пользовательский интерфейс может использовать этот атрибут в иных целях.

• SwitchPrefix: префикс, используемый в командной строке для коммутаторов. Значение "/" приведет к переключениям, которые выглядят как /ZI, /nologoи /W3т. д.

• Order: предложение потенциальному клиенту пользовательского интерфейса относительное расположение этого Rule по сравнению со всеми другими правилами в системе.

• xmlns: стандартный XML-элемент. Видно, что указано три пространства имен. Эти атрибуты соответствуют пространствам имен для классов десериализации XML, схемы XML и пространства имен системы соответственно.

• DisplayName: имя, отображаемое на пользовательском интерфейсе страницы свойств для Rule узла. Это значение не локализуется. Мы создали DisplayName как дочерний элемент Rule , а не как атрибут (например Name , или SwitchPrefix) из-за требований внутреннего средства локализации. С точки зрения XML оба эквивалентны. Таким образом, вы можете сделать его атрибутом, чтобы убрать все лишнее, или оставить все как есть.

• DataSource: это важное свойство сообщает системе проекта расположение для чтения и записи значения свойства, а также его группировки (описано далее). Для cl.xmlэтих значений:

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

  • Persistence="ProjectFile" сообщает системе проекта, что все свойства для Rule файла проекта или файла листа свойств (в зависимости от того, какой узел использовался для создания страниц свойств). Другое возможное значение— "UserFile"это значение, которое записывает значение в .user файл.

  • ItemType="ClCompile" сообщает, что свойства будут храниться в виде метаданных ItemDefinition или метаданных элемента (только в том случае, если страницы свойств были порождены от узла файла в обозревателе решений) этого типа элемента. Если это поле не задано, свойство записывается как общее свойство в PropertyGroup.

  • Label="" указывает, что при записи свойств в виде метаданных ItemDefinition метка родительского объекта ItemDefinitionGroup будет пустой (каждый элемент MSBuild может иметь метку). Visual Studio 2017 и более поздних версий использует группы с меткой для перехода по файлу проекта VCXPROJ. Группы, содержащие большинство Rule свойств, имеют пустую строку в виде метки.

  • HasConfigurationCondition="true" предписывает системе проектов прикрепить условие конфигурации к значению, чтобы оно вступало в силу только для текущей конфигурации проекта (условие можно прикрепить к родительской группе или самому значению). Например, откройте страницы свойств с узла проекта и задайте значение свойства "Предупреждение как ошибка" в разделе "Свойства > конфигурации" c/C++ " Да". Следующее значение записывается в файл проекта. Обратите внимание, что к родительскому объекту ItemDefinitionGroup прикреплено условие конфигурации.

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

    Если это значение задано на странице свойств для определенного файла, например stdafx.cpp, значение свойства должно быть записано под stdafx.cpp элементом в файле проекта, как показано ниже. Обратите внимание, как условие конфигурации напрямую подключено к самому метаданным:

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

  Ниже приведен еще один атрибут, не указанный DataSource здесь PersistedName. Его можно использовать для представления свойства в файле проекта под другим именем. По умолчанию этот атрибут присваивается свойству Name.

  Отдельное свойство может переопределить DataSource родительский Ruleэлемент. В этом случае расположение для значения этого свойства будет отличаться от других свойств в объекте Rule.

• Существуют и другие атрибуты Rule, включая Description и SupportsFileBatching, которые не отображаются здесь. Полный набор атрибутов, применимых к Rule любому другому элементу, можно получить путем просмотра документации по этим типам. Кроме того, можно проверить открытые свойства для типов в пространстве имен Microsoft.Build.Framework.XamlTypes в сборке Microsoft.Build.Framework.dll.

• DisplayName, PageTemplateи Order являются свойствами, связанными с пользовательским интерфейсом, которые присутствуют в этой модели данных, независимо от пользовательского интерфейса. Эти свойства почти наверняка будут использоваться любым пользовательским интерфейсом, служащим для отображения страниц свойств. DisplayName и Description являются двумя свойствами, которые присутствуют почти во всех элементах XML-файла. И эти два свойства являются единственными локализованными.

Элементы категории

Может Rule содержать несколько Category элементов. Порядок, в котором категории перечислены в XML-файле, является предложением пользовательскому интерфейсу отображать категории в том же порядке. Например, порядок категорий в узле C/C++ , который отображается в пользовательском интерфейсе, совпадает с порядком в cl.xml. Пример категории выглядит следующим образом:

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

В этом фрагменте показаны Name DisplayName и атрибуты, которые были описаны ранее. Еще раз есть другие атрибуты Category , которые не отображаются в примере. Их можно узнать, прочитав документацию или проверив сборки с помощью ildasm.exe.

Элементы свойства

Большинство файлов правил состоит из Property элементов. Они содержат список всех свойств в объекте Rule. Каждое свойство может быть одним из пяти возможных типов, отображаемых в базовой платформе: BoolProperty, , EnumPropertyIntPropertyи StringListPropertyStringProperty. В файле может быть только несколько этих типов. Свойство имеет ряд атрибутов, которые позволяют подробно описывать его. Здесь StringProperty описано. Остальные похожи.

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

Большинство атрибутов в этом фрагменте коды было описано выше. Новые : Subtype, Categoryи Switch.

• Subtype — это атрибут, доступный только для StringProperty элементов и StringListProperty элементов. Он предоставляет контекстную информацию. Например, значение file указывает, что свойство представляет путь к файлу. Visual Studio использует такие контекстные сведения для улучшения возможностей редактирования. Например, он может предоставить окно проводника Windows, позволяющее пользователю визуально выбрать файл в качестве редактора свойства.

• Category: категория, под которой попадает это свойство. Попробуйте найти это свойство в категории Выходные файлы в пользовательском интерфейсе.

• Switch: когда правило представляет инструмент, например средство компилятора, большинство Rule свойств передаются в виде переключений в исполняемый файл средства во время сборки. Значение этого атрибута указывает, какой литерал переключения следует использовать. В <StringProperty> примере указывается, что его переключатель должен быть Fo. В сочетании с атрибутом SwitchPrefix родительского Ruleобъекта это свойство передается исполняемому файлу в виде /Fo"Debug\". Он отображается в командной строке для C/C++ в пользовательском интерфейсе страницы свойств.

  Другие атрибуты свойства:

• Visible: если вы не хотите, чтобы свойство отображалось на страницах свойств, но хотите, чтобы оно было доступно во время сборки, задайте для этого атрибута falseзначение .

• ReadOnly: если вы хотите предоставить только для чтения представление значения этого свойства на страницах свойств, задайте для этого атрибута trueзначение.

• IncludeInCommandLine: во время сборки средство может не нуждаться в некоторых его свойствах. Задайте этот атрибут, чтобы false предотвратить передаче определенного свойства.