プロパティ ページの XML 規則ファイル

IDE のプロジェクト プロパティ ページは、既定のルール フォルダー内の XML ファイルで構成されます。 XML ファイルには、規則の名前、カテゴリ、および個々のプロパティ、それらのデータ型、既定値、表示方法が記載されます。 IDE でプロパティを設定すると、新しい値がプロジェクト ファイルに格納されます。

既定のルール フォルダーへのパスは、ロケールと、使用する Visual Studio のバージョンによって異なります。 Visual Studio 2019 以降の開発者コマンド プロンプトのルール フォルダーは %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\<locale>\ です。Visual Studio 2019 の場合、<version> 値は v160 です。 <locale> は LCID です。たとえば、英語の場合は 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\ になります。

次の 2 つのシナリオにおける、これらのファイルと Visual Studio IDE の内部動作のみを理解しておけば十分です。

• カスタム プロパティ ページを作成する
• Visual Studio IDE を使用せずに、プロジェクトのプロパティをカスタマイズする

規則ファイルの内容

まず、プロジェクトのプロパティ ページを開きます。 ソリューション エクスプローラーでプロジェクト ノードを右クリックし、[プロパティ] を選択します。

[構成プロパティ] の下の各ノードは、"規則" と呼ばれます。 規則は、コンパイラのような 1 つのツールを表す場合があります。 一般に、この用語は、プロパティを持ち、実行され、何らかの出力を生成する可能性があるものを指します。 各規則は既定のルール フォルダー内の XML ファイルから設定されます。 たとえば、ここに示す C/C++ 規則は cl.xml によって設定されます。

各規則には "カテゴリ" に分類された一連のプロパティがあります。 規則の下の各サブ ノードは、カテゴリを表します。 たとえば、[C/C++] の下の [最適化] ノードには、コンパイラ ツールの最適化に関連するすべてのプロパティが含まれています。 プロパティとその値が、右側のウィンドウにグリッド形式で表示されます。

メモ帳または任意の XML エディターで cl.xml を開くことができます。 Rule というルート ノードが表示されます。 UI に表示されるプロパティと同じプロパティの一覧と、追加のメタデータが定義されます。

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

プロパティ ページ UI の [構成プロパティ] の下には、すべてのノードに対応する 1 つの XML ファイルがあります。 プロジェクト内の対応する XML ファイルに場所を含めるか削除することで、UI 内の規則を追加または削除できます。 たとえば、Microsoft.CppBuild.targets (1033 フォルダーより 1 つ上のレベルにあります) に 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 の ID です。 プロジェクトのすべてのプロパティ ページの XML ファイル間で一意である必要があります。

• PageTemplate: この属性の値は、UI テンプレートのコレクションから選択するために UI によって使用されます。 "tool" テンプレートは、標準のグリッド形式でプロパティをレンダリングします。 この属性のその他の組み込みの値は、"debugger" と "generic" です。 これらの値を指定した結果の UI 形式を確認するには、デバッグ ノードと全般ノードをそれぞれ確認します。 "デバッガー" ページ テンプレートの UI では、ドロップダウン ボックスを使用して、さまざまなデバッガーのプロパティを切り替えます。 "汎用" テンプレートでは、Rule ノードの下に複数のカテゴリ サブノードがあるのとは対照的に、1 つのページにさまざまなプロパティ カテゴリがすべて表示されます。 この属性は、UI に対するただの提案にすぎません。 XML ファイルは、UI に依存しないように設計されています。 UI ごとに異なる目的のためにこの属性を使用することができます。

• SwitchPrefix: これはコマンド ラインで使用されるスイッチのプレフィックスです。 "/" の値は、/ZI、/nologo、/W3 のようなスイッチになります。

• Order: システム内の他のすべての規則と比較した、この Rule の相対的な場所で予想される UI クライアント候補に対する提案です。

• xmlns: 標準の XML 要素。 3 つの名前空間が一覧表示されます。 これらの属性は、XML の逆シリアル化クラスの名前空間、XML スキーマ、およびシステム名前空間にそれぞれ対応しています。

• DisplayName: Rule ノードのプロパティ ページの UI に表示される名前です。 この値はローカライズされます。 内部のローカライズ ツールの要件により、DisplayName は (Name や SwitchPrefix のような) 属性としてではなく、Rule の子要素として作成されています。 XML の観点からは、どちらも同じです。 そのため、単に属性にして煩雑さを軽減することも、そのままにしておくこともできます。

• DataSource: この重要なプロパティは、プロジェクト システムにプロパティ値の読み取りおよび書き込みの場所と、そのグループ化を指示します (後で説明します)。 cl.xml の場合、これらの値は次のようになります。

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

  • Persistence="ProjectFile" は、プロジェクト システムに Rule のすべてのプロパティをプロジェクト ファイルまたはプロパティ シート ファイルに書き込む必要があることを伝えます (プロパティ ページを生成するために使用したノードに依存します)。 他の考えられる値は、値を .user ファイルに値を書き込む "UserFile" です。

  • ItemType="ClCompile" は、プロパティがこの項目の種類の ItemDefinition メタデータまたは項目メタデータ (後者は、プロパティ ページがソリューション エクスプローラーでファイル ノードから生成された場合のみ) として格納されることを示します。 このフィールドが設定されていない場合、このプロパティは、PropertyGroup の共通プロパティとして書き込まれます。

  • Label="" は、プロパティが ItemDefinition メタデータとして書き込まれるときに、親 ItemDefinitionGroup のラベルが空になることを示しますます (すべての MSBuild 要素がラベルを持つことができます)。 Visual Studio 2017 以降では、ラベルの付いたグループを使用して、.vcxproj プロジェクト ファイルを移動します。 ほとんどの Rule のプロパティを含むグループは、空の文字列をラベルとして持ちます。

  • HasConfigurationCondition="true" は、現在のプロジェクト構成に対してのみ有効になるように、値に構成条件を添えるようにプロジェクト システムに指示します (条件は、親グループまたは値そのものに添えることができます)。 たとえば、プロジェクト ノードのプロパティ ページを開き、[構成プロパティ] > [C/C++ の全般] の下でプロパティ Treat Warnings As Error の値を "Yes" に設定します。 次の値がプロジェクト ファイルに書き込まれます。 親 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 のもう 1 つの属性は PersistedName です。 この属性を使用すると、別の名前を使用しているプロジェクト ファイル内のプロパティを表すことができます。 既定では、この属性はプロパティの Name に設定されています。

  個々のプロパティは、その親 Rule の DataSource をオーバーライドできます。 その場合、そのプロパティの値の場所は、Rule 内の他のプロパティとは異なる場所になります。

• Description と SupportsFileBatching を含む Rule の他の属性は、ここには示されていません。 Rule またはその他の要素に適用可能な属性の完全なセットは、これらの型のドキュメントを参照することで取得できます。 または、Microsoft.Build.Framework.dll アセンブリ内の Microsoft.Build.Framework.XamlTypes 名前空間内の型でパブリック プロパティを調べることもできます。

• DisplayName、PageTemplate、および Order は、ここに存在している UI 関連のプロパティか、そうでない場合は、UI に依存しないデータ モデルです。 これらのプロパティは、プロパティ ページを表示するために使用される任意の UI でほぼ確実に使用されます。 DisplayName および Description の 2 つのプロパティは、XML ファイル内のほぼすべての要素に存在します。 また、これら 2 つのプロパティは、ローカライズされる唯一のプロパティです。

カテゴリ要素

1 つの Rule で複数の Category 要素を持つことができます。 XML ファイル内でカテゴリが表示される順序は、カテゴリを同じ順序で表示するための UI への提案です。 たとえば、UI に表示される 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、EnumProperty、IntProperty、StringProperty、StringListProperty の基本フレームワークに示されている 5 つの可能な型のいずれかを指定できます。 ファイルに、これらの型の一部しか含めないこともできます。 プロパティに、詳細に説明できるように多くの属性を持たせることもできます。 以下に 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: このプロパティが該当するカテゴリ。 UI 内の [出力ファイル] カテゴリの下で、このプロパティの検索を試みます。

• Switch: 規則がコンパイラ ツールなどのツールを表す場合、Rule のほとんどのプロパティがビルド時にツールの実行可能ファイルにスイッチとして渡されます。 この属性の値は、使用されるスイッチ リテラルを示します。 <StringProperty> の例では、そのスイッチが Fo にする必要があることが指定されています。 親 Rule の SwitchPrefix 属性と組み合わせると、このプロパティは実行可能ファイルに /Fo"Debug\" として渡されます。 これは、プロパティ ページ UI の C/C++ のコマンド ラインに表示されます。

  その他のプロパティの属性は次のとおりです。

• Visible: プロパティをプロパティ ページに表示せずに、ビルド時に使用できるようにするには、この属性を false に設定します。

• ReadOnly:プロパティ ページで、このプロパティの値の読み取り専用ビューを提供する場合は、この属性を true に設定します。

• IncludeInCommandLine: ビルド時に、ツールがプロパティの一部を必要としない場合があります。 特定のプロパティが渡されないようにするには、この属性を false に設定します。