Visual Studio C++ プロジェクトシステムの機能拡張とツールセットの統合

[アーティクル]
05/08/2023

Visual C++ プロジェクトシステムは、.vcxproj ファイルに使用されます。これは、Visual Studio Common Project System (CPS) に基づいており、新しいツールセット、ビルドアーキテクチャ、およびターゲットプラットフォームの統合を容易にするための追加の C++ 固有の機能拡張ポイントを提供します。

C++ MSBuild ターゲットの構造

すべての .vcxproj ファイルは、次のファイルをインポートします。

<Import Project="$(VCTargetsPath)\Microsoft.Cpp.Default.props" />
<Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
<Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />

これらのファイルが単独で定義されることはほとんどありません。代わりに、次のプロパティ値に基づいて他のファイルをインポートします。

$(ApplicationType)

例: Windows Store、Android、Linux
$(ApplicationTypeRevision)

major.minor[.build[.revision]] 形式の有効なバージョン文字列を指定する必要があります。

例: 1.0、10.0.0.0
$(Platform)

歴史的な理由で "プラットフォーム" の名前が付けられたビルドアーキテクチャ。

例: Win32、x86、x64、ARM
$(PlatformToolset)

例: v140、v141、v141_xp、llvm

これらのプロパティ値によって、$(VCTargetsPath) ルートフォルダーの下にフォルダー名が指定されます。

$(VCTargetsPath)\
    アプリケーションの種類\
        $(ApplicationType)\
            $(ApplicationTypeRevision)\
                プラットフォーム\
                    $(Platform)\
                        PlatformToolsets\
                            $(PlatformToolset)
    プラットフォーム\
        $(Platform)\
            PlatformToolsets\
                $(PlatformToolset)

$(VCTargetsPath)\Platforms\ フォルダーは、$(ApplicationType) が空のときに使用されます (Windows デスクトッププロジェクトの場合)。

新しいプラットフォームツールセットの追加

新しいツールセット (既存の Win32 プラットフォーム用の "MyToolset" など) を追加するには、$(VCTargetsPath)\Platforms\Win32\PlatformToolsets\ の下に MyToolset フォルダーを作成し、その中に Toolset.props および Toolset.targets ファイルを作成します。

PlatformToolsets の下にある各フォルダー名が、以下に示すように、指定したプラットフォームの使用可能なプラットフォームツールセットとして [プロジェクトのプロパティ] ダイアログに表示されます。

プロジェクトの [プロパティページ] ダイアログの [プラットフォームツールセット] プロパティ

このツールセットでサポートされている既存の各プラットフォームフォルダーに、同様の MyToolset フォルダーと Toolset.props および Toolset.targets ファイルを作成します。

新しいプラットフォームの追加

新しいプラットフォーム ("MyPlatform" など) を追加するには、$(VCTargetsPath)\Platforms\ の下に MyPlatform フォルダーを作成し、その中に Platform.default.props、Platform.props、Platform.targets の各ファイルを作成します。また、$(VCTargetsPath)\Platforms\MyPlatform\PlatformToolsets\ フォルダーを作成し、その中にツールセットを少なくとも 1 つ作成します。

各 $(ApplicationType) および $(ApplicationTypeRevision) の Platforms フォルダーの下にあるすべてのフォルダー名が、プロジェクトに使用できるプラットフォームの選択肢として IDE に表示されます。

[新しいプロジェクトプラットフォーム] ダイアログの [新しいプラットフォーム] の選択肢

新しいアプリケーションの種類の追加

新しいアプリケーションの種類を追加するには、$(VCTargetsPath)\Application Type\ の下に MyApplicationType フォルダーを作成し、その中に Defaults.props ファイルを作成します。アプリケーションの種類には少なくとも 1 つのリビジョンが必要であるため、$(VCTargetsPath)\Application Type\MyApplicationType\1.0 フォルダーも作成し、その中に Defaults.props ファイルを作成します。また、$(VCTargetsPath)\ApplicationType\MyApplicationType\1.0\Platforms フォルダーを作成し、その中にプラットフォームを少なくとも 1 つ作成する必要もあります。

$(ApplicationType) および $(ApplicationTypeRevision) プロパティは、ユーザーインターフェイスに表示されません。それらはプロジェクトテンプレート内に定義され、プロジェクトの作成後は変更できません。

.vcxproj インポートツリー

Microsoft C++ の props および targets ファイルの簡略化されたインポートツリーは次のようになります。

$(VCTargetsPath)\Microsoft.Cpp.Default.props
    $(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props
    $(VCTargetsPath)\ImportBefore\Default\*.props
    $(VCTargetsPath)\Application Type\$(ApplicationType)\Default.props
    $(VCTargetsPath)\Application Type\$(ApplicationType)\$(ApplicationTypeRevision)\Default.props
    $(VCTargetsPath)\Application Type\$(ApplicationType)\$(ApplicationTypeRevision)\Platforms\$(Platform)\Platform.default.props
    $(VCTargetsPath)\ImportAfter\Default\*.props

Windows デスクトッププロジェクトでは $(ApplicationType) を定義しないため、以下だけをインポートします

$(VCTargetsPath)\Microsoft.Cpp.Default.props
    $(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props
    $(VCTargetsPath)\ImportBefore\Default\*.props
    $(VCTargetsPath)\Platforms\$(Platform)\Platform.default.props
    $(VCTargetsPath)\ImportAfter\Default\*.props

$(Platform) プラットフォームフォルダーの場所を保持するには、$(_PlatformFolder) プロパティを使用します。このプロパティは、

$(VCTargetsPath)\プラットフォーム\$(Platform)

(Windows デスクトップアプリの場合)、または

$(VCTargetsPath)\Application Type\$(ApplicationType)\$(ApplicationTypeRevision)\Platforms\$(Platform)

(その他すべての場合) です。

props ファイルは、次の順序でインポートされます。

$(VCTargetsPath)\Microsoft.Cpp.props
    $(_PlatformFolder)\Platform.props
        $(VCTargetsPath)\Microsoft.Cpp.Platform.props
            $(_PlatformFolder)\ImportBefore\*.props
            $(_PlatformFolder)\PlatformToolsets\$(PlatformToolset)\Toolset.props
            $(_PlatformFolder)\ImportAfter\*.props

targets ファイルは、次の順序でインポートされます。

$(VCTargetsPath)\Microsoft.Cpp.targets
    $(VCTargetsPath)\Microsoft.Cpp.Current.targets
        $(_PlatformFolder)\Platform.targets
            $(VCTargetsPath)\Microsoft.Cpp.Platform.targets
                $(_PlatformFolder)\ImportBefore\*.targets
                $(_PlatformFolder)\PlatformToolsets\$(PlatformToolset)\Toolset.target
                $(_PlatformFolder)\ImportAfter\*.targets

お使いのツールセットに既定のプロパティをいくつか定義する必要がある場合は、適切な ImportBefore および ImportAfter フォルダーにファイルを追加できます。

Toolset.props および Toolset.targets ファイルの作成

Toolset.props および Toolset.targets ファイルは、このツールセットが使用されているビルド中に発生する処理を完全に制御します。また、使用可能なデバッガー、一部の IDE ユーザーインターフェイス ([プロパティページ] ダイアログの内容など)、およびプロジェクト動作の他の側面も制御できます。

ツールセットはビルドプロセス全体をオーバーライドできますが、通常はお使いのツールセットで一部のビルドステップを変更または追加したり、別のビルドツールを既存のビルドプロセスの一部として使用したりする必要があるだけです。この目標を達成するために、お使いのツールセットでインポートできる一般的な props および targets ファイルが多数あります。ツールセットで実行する処理に応じて、以下のファイルをインポートまたは例として使用すると便利な場合があります。

$(VCTargetsPath)\Microsoft.CppCommon.targets

このファイルでは、ネイティブビルドプロセスの主要部分を定義し、以下のインポートも行います。
- $(VCTargetsPath)\Microsoft.CppBuild.targets
- $(VCTargetsPath)\Microsoft.BuildSteps.targets
- $(MSBuildToolsPath)\Microsoft.Common.Targets
$(VCTargetsPath)\Microsoft.Cpp.Common.props

Microsoft コンパイラを使用し、Windows を対象とするツールセットの既定値を設定します。
$(VCTargetsPath)\Microsoft.Cpp.WindowsSDK.props

このファイルでは、Windows SDK の場所を決定し、Windows を対象とするアプリの重要なプロパティをいくつか定義します。

ツールセット固有のターゲットを既定の C++ ビルドプロセスと統合する

既定の C++ ビルドプロセスは、Microsoft.CppCommon.targets で定義されています。そこにあるターゲットは特定のビルドツールを呼び出しません。それらは主要なビルドステップ、その順序、依存関係を指定するものです。

C++ ビルドには、次のターゲットで表される 3 つの主要ステップがあります。

BuildGenerateSources
BuildCompile
BuildLink

各ビルドステップは個別に実行される可能性があるため、あるステップで実行されているターゲットが、別のステップの一部として実行されるターゲットで定義されている項目のグループやプロパティを利用することはできません。こうした区分により、特定のビルドパフォーマンスの最適化が可能になります。既定では使用されませんが、引き続きこうした区別を受け入れることをお勧めします。

各ステップ内で実行されるターゲットは、以下のプロパティによって制御されます。

$(BuildGenerateSourcesTargets)
$(BuildCompileTargets)
$(BeforeBuildLinkTargets)

各ステップには、Before および After プロパティもあります。

<Target
  Name="_BuildGenerateSourcesAction"
  DependsOnTargets="$(CommonBuildOnlyTargets);$(BeforeBuildGenerateSourcesTargets);$(BuildGenerateSourcesTargets);$(AfterBuildGenerateSourcesTargets)" />

<Target
  Name="\_BuildCompileAction"
  DependsOnTargets="$(CommonBuildOnlyTargets);$(BeforeBuildCompileTargets);$(BuildCompileTargets);$(AfterBuildCompileTargets)" />

<Target
  Name="\_BuildLinkAction"
  DependsOnTargets="$(CommonBuildOnlyTargets);$(BeforeBuildLinkTargets);$(BuildLinkTargets);$(AfterBuildLinkTargets)" />

各ステップに含まれているターゲットの例については、Microsoft.CppBuild.targets ファイルをご覧ください。

<BuildCompileTargets Condition="'$(ConfigurationType)'\!='Utility'">
  $(BuildCompileTargets);
  _ClCompile;
  _ResGen;
  _ResourceCompile;
  $(BuildLibTargets);
</BuildCompileTargets>

_ClCompile などのターゲットを確認すると、単独では何も行わず、その代わりに他のターゲット (ClCompile など) に依存していることがわかります。

<Target Name="_ClCompile"
  DependsOnTargets="$(BeforeClCompileTargets);$(ComputeCompileInputsTargets);MakeDirsForCl;ClCompile;$(AfterClCompileTargets)" >
</Target>

ClCompile とその他のビルドツール固有のターゲットは、Microsoft.CppBuild.targets で空のターゲットとして定義されます。

<Target Name="ClCompile"/>

ClCompile ターゲットは空であるため、ツールセットによってオーバーライドされない限り、実際のビルドアクションは実行されません。ツールセットのターゲットは ClCompile ターゲットをオーバーライドできます。つまり、Microsoft.CppBuild.targets のインポート後に、それらに別の ClCompile 定義を含めることができます。

<Target Name="ClCompile"
  Condition="'@(ClCompile)' != ''"
  DependsOnTargets="SelectClCompile">
  <!-- call some MSBuild tasks -->
</Target>

その名前 (Visual Studio でクロスプラットフォームのサポートを実装する前に作成されたもの) にもかかわらず、ClCompile ターゲットでは CL.exe を呼び出す必要がありません。また、適切な MSBuild タスクを使用して、Clang、gcc、またはその他のコンパイラを呼び出すこともできます。

ClCompile ターゲットには、SelectClCompile ターゲット (1 つのファイルコンパイルコマンドが IDE で動作するために必要なもの) 以外の依存関係を含めることはできません。

ツールセットのターゲット内で使用する MSBuild タスク

実際のビルドツールを呼び出すには、ターゲットで MSBuild タスクを呼び出す必要があります。実行するコマンドラインを指定できる基本的な Exec タスクがあります。ただし、ビルドツールには通常、インクリメンタルビルドに備えて追跡するオプション、入力、出力が多数あるため、それら専用のタスクを用意するほうが理にかなっています。たとえば、CL タスクでは MSBuild プロパティを CL.exe スイッチに変換して応答ファイルに書き込み、CL.exe を呼び出します。また、後でインクリメンタルビルドを行えるように、すべての入力および出力ファイルを追跡します。詳細については、「インクリメンタルビルドと最新状態チェック」をご覧ください。

Microsoft.Cpp.Common.Tasks.dll には、以下のタスクが実装されています。

BSCMake
CL
ClangCompile (clang-gcc スイッチ)
LIB
LINK
MIDL
Mt
RC
XDCMake
CustomBuild (Exec と同じですが、入力と出力の追跡が含まれます)
SetEnv
GetOutOfDateItems

既存のツールと同じアクションを実行するツールと、(clang-cl や CL で実行するような) 同様のコマンドラインスイッチを備えたツールがある場合は、両方に同じタスクを使用できます。

ビルドツール用の新しいタスクを作成する必要がある場合は、次のオプションから選択できます。

このタスクをめったに使用しない場合、またはお使いのビルドで数秒が問題にならない場合は、MSBuild の "インライン" タスクを使用できます。
- Xaml タスク (カスタムビルド規則)
  
  Xaml タスク宣言の一例については $(VCTargetsPath)\BuildCustomizations\masm.xml を、その使用法については $(VCTargetsPath)\BuildCustomizations\masm.targets をそれぞれご覧ください。
- Code タスク
タスクパフォーマンスを向上させたい場合、またはより複雑な機能を必要とするだけの場合は、通常の MSBuild タスクの作成プロセスを使用します。

CL、MIDL、RC の場合のように、ツールのすべての入力と出力がツールのコマンドラインに一覧表示されるとは限らない場合で、自動入力および出力ファイルの追跡と .tlog ファイルの作成が必要な場合は、使用するタスクを Microsoft.Build.CPPTasks.TrackedVCToolTask クラスから派生させます。現時点では、基底の ToolTask クラスに関するドキュメントはありますが、TrackedVCToolTask クラスの詳細についての例やドキュメントはありません。これについて特別な関心をお持ちの場合は、Developer Community のリクエストにご意見をお寄せください。

インクリメンタルビルドと最新状態チェック

MSBuild インクリメンタルビルドの既定のターゲットでは、Inputs および Outputs 属性を使用します。これらを指定すると、MSBuild では、いずれかの入力のタイムスタンプがすべての出力よりも新しい場合にのみターゲットを呼び出します。ソースファイルには他のファイルが含まれていたり、インポートされていたりすることが多く、またビルドツールではツールのオプションに応じてさまざまな出力が生成されるため、考えられるすべての入力と出力を MSBuild のターゲット内に指定することは困難です。

この問題を管理するために、C++ のビルドでは、インクリメンタルビルドをサポートする別の手法を使用します。ほとんどのターゲットでは入力と出力を指定せず、結果としてそれらは常にビルド中に実行されます。ターゲットによって呼び出されるタスクでは、すべての入力と出力に関する情報を、.tlog 拡張子を持つ tlog ファイルに書き込みます。この .tlog ファイルは、後のビルドで、変更されたものと再構築が必要なもの、最新のものを確認するために使用されます。また、.tlog ファイルは、IDE での既定のビルド最新状態チェックに使用される唯一のソースです。

すべての入力と出力を確認するために、ネイティブツールタスクでは tracker.exe と、MSBuild によって提供される FileTracker クラスを使用します。

Microsoft.Build.CPPTasks.Common.dll では、TrackedVCToolTask パブリック抽象基底クラスを定義します。ほとんどのネイティブツールタスクは、このクラスから派生します。

Visual Studio 2017 Update15.8 以降では、Microsoft.Cpp.Common.Tasks.dll に実装されている GetOutOfDateItems タスクを使用して、既知の入力と出力を含むカスタムターゲット用の .tlog ファイルを生成できます。あるいは、WriteLinesToFile タスクを使用してそれらを作成することもできます。 $(VCTargetsPath)\BuildCustomizations\masm.targets に含まれる _WriteMasmTlogs ターゲットを例としてご覧ください。

.tlog ファイル

.tlog ファイルには、"読み取り"、"書き込み"、"コマンドライン" の 3 つの種類があります。読み取りと書き込みの .tlog ファイルは、インクリメンタルビルドと IDE での最新状態チェックによって使用されます。コマンドラインの .tlog ファイルは、インクリメンタルビルドでのみ使用されます。

MSBuild では、読み取りと書き込みの .tlog ファイルに以下のヘルパークラスを提供します。

FlatTrackingData クラスを使用すると、読み取りと書き込みの両方の .tlog ファイルにアクセスして、出力より新しい入力を特定できます。出力がない場合は、最新状態チェックで使用されます。

コマンドラインの .tlog ファイルには、ビルドで使用されるコマンドラインに関する情報が含まれています。これらは、最新状態チェックではなく、インクリメンタルビルドにのみ使用されるため、それらを生成する MSBuild タスクによって内部形式が決定されます。

読み取りの .tlog の形式

"読み取り" の .tlog ファイル (*.read.*.tlog) には、ソースファイルとその依存関係に関する情報が含まれています。

行の先頭にあるキャレット (^) は、1 つ以上のソースを示します。同じ依存関係を共有するソースは、縦棒 (|) で区切られます。

依存関係ファイルは、ソースの後にそれぞれ独自の行で一覧表示されます。ファイル名はすべて完全なパスです。

たとえば、プロジェクトのソースが F:\test\ConsoleApplication1\ConsoleApplication1 にあるとします。ソースファイル (Class1.cpp) に以下の include が含まれている場合、

#include "stdafx.h" //precompiled header
#include "Class1.h"

CL.read.1.tlog ファイルにはソースファイルとその後にその依存関係が 2 つ含まれます。

^F:\TEST\CONSOLEAPPLICATION1\CONSOLEAPPLICATION1\CLASS1.CPP
F:\TEST\CONSOLEAPPLICATION1\CONSOLEAPPLICATION1\DEBUG\CONSOLEAPPLICATION1.PCH
F:\TEST\CONSOLEAPPLICATION1\CONSOLEAPPLICATION1\CLASS1.H

ファイル名を大文字で記述する必要はありませんが、一部のツールには便利です。

書き込みの .tlog の形式

"書き込み" の .tlog (*.write.*.tlog) ファイルは、ソースと出力を結び付けます。

行の先頭にあるキャレット (^) は、1 つ以上のソースを示します。複数のソースは、縦棒 (|) で区切られます。

ソースから作成された出力ファイルは、ソースの後にそれぞれ独自の行で一覧表示されます。ファイル名はすべて完全なパスである必要があります。

たとえば、追加のソースファイル Class1.cpp を持つ単純な ConsoleApplication プロジェクトの場合、link.write.1.tlog ファイルには以下が含まれている可能性があります。

^F:\TEST\CONSOLEAPPLICATION1\CONSOLEAPPLICATION1\DEBUG\CLASS1.OBJ|F:\TEST\CONSOLEAPPLICATION1\CONSOLEAPPLICATION1\DEBUG\CONSOLEAPPLICATION1.OBJ|F:\TEST\CONSOLEAPPLICATION1\CONSOLEAPPLICATION1\DEBUG\STDAFX.OBJ
F:\TEST\CONSOLEAPPLICATION1\DEBUG\CONSOLEAPPLICATION1.ILK
F:\TEST\CONSOLEAPPLICATION1\DEBUG\CONSOLEAPPLICATION1.EXE
F:\TEST\CONSOLEAPPLICATION1\DEBUG\CONSOLEAPPLICATION1.PDB

デザイン時のビルド

IDE では、.vcxproj プロジェクトは一連の MSBuild ターゲットを使用して、プロジェクトから追加情報を取得し、出力ファイルを再生成します。これらのターゲットの一部はデザイン時のビルドでのみ使用されますが、その多くは通常のビルドとデザイン時のビルドの両方で使用されます。

デザイン時のビルドに関する一般的な情報については、デザイン時のビルドの CPS ドキュメントをご覧ください。このドキュメントは、Visual C++ プロジェクトに部分的に適用されます。

デザイン時のビルドのドキュメントに記載されている CompileDesignTime および Compile ターゲットは、.vcxproj プロジェクトでは実行されません。 Visual C++ の .vcxproj プロジェクトでは、さまざまなデザイン時のターゲットを使用して、IntelliSense の情報を取得します。

IntelliSense の情報のためのデザイン時のターゲット

.vcxproj プロジェクトで使用されるデザイン時のターゲットは、$(VCTargetsPath)\Microsoft.Cpp.DesignTime.targets で定義されています。

GetClCommandLines ターゲットでは、IntelliSense のコンパイラオプションを収集します。

<Target
  Name="GetClCommandLines"
  Returns="@(ClCommandLines)"
  DependsOnTargets="$(DesignTimeBuildInitTargets);$(ComputeCompileInputsTargets)">

DesignTimeBuildInitTargets – デザイン時のビルドの初期化に必要な、デザイン時のみのターゲット。特に、これらのターゲットでは、パフォーマンスを向上させるために通常のビルド機能の一部を無効にします。
ComputeCompileInputsTargets – コンパイラのオプションと項目を変更する一連のターゲット。これらのターゲットは、デザイン時と通常の両方のビルドで実行されます。

このターゲットでは CLCommandLine タスクを呼び出して、IntelliSense に使用するコマンドラインを作成します。この場合も、その名前にかかわらず、CL オプションだけでなく、Clang や gcc オプションも処理できます。コンパイラスイッチの型は、ClangMode プロパティによって制御されます。

現在、CLCommandLine タスクによって生成されるコマンドラインでは、IntelliSense エンジンが解析しやすくなるように、常に (Clang モードでも) CL スイッチを使用しています。

コンパイル前に実行されるターゲットを追加する場合は、通常またはデザイン時のどちらであっても、それによってデザイン時のビルドが中断されたり、パフォーマンスに影響したりしないようにしてください。ターゲットをテストする最も簡単な方法は、開発者コマンドプロンプトを開き、以下のコマンドを実行することです。

msbuild /p:SolutionDir=*solution-directory-with-trailing-backslash*;Configuration=Debug;Platform=Win32;BuildingInsideVisualStudio=true;DesignTimebuild=true /t:\_PerfIntellisenseInfo /v:d /fl /fileloggerparameters:PerformanceSummary \*.vcxproj

このコマンドによって詳細なビルドログ (msbuild.log) が生成されます。これには、ターゲットとタスクのパフォーマンスの概要が最後に示されます。

デザイン時のビルドではなく、通常のビルドにのみ意味を持つすべての操作では必ず Condition ="'$(DesignTimeBuild)' != 'true'" を使用してください。

ソースを生成するデザイン時のターゲット

"この機能はデスクトップのネイティブプロジェクトでは既定で無効になっており、キャッシュされたプロジェクトでは現在サポートされていません。"

プロジェクト項目に GeneratorTarget メタデータが定義されている場合は、プロジェクトが読み込まれるときとソースファイルが変更されるときに、ターゲットが自動的に実行されます。

たとえば、.xaml ファイルから .cpp または .h ファイルを自動的に生成する場合は、$(VSInstallDir)\MSBuild\Microsoft\WindowsXaml\v16.0\*\Microsoft.Windows.UI.Xaml.CPP.Targets ファイルで以下のエンティティを定義します。

<ItemDefinitionGroup>
  <Page>
    <GeneratorTarget>DesignTimeMarkupCompilation</GeneratorTarget>
  </Page>
  <ApplicationDefinition>
    <GeneratorTarget>DesignTimeMarkupCompilation</GeneratorTarget>
  </ApplicationDefinition>
</ItemDefinitionGroup>
<Target Name="DesignTimeMarkupCompilation">
  <!-- BuildingProject is used in Managed builds (always true in Native) -->
  <!-- DesignTimeBuild is used in Native builds (always false in Managed) -->
  <CallTarget Condition="'$(BuildingProject)' != 'true' Or $(DesignTimeBuild) == 'true'" Targets="DesignTimeMarkupCompilationCT" />
</Target>

Task.HostObject を使用してソースファイルの未保存のコンテンツを取得するには、ターゲットとタスクを、指定されたプロジェクトの MsbuildHostObjects として pkgdef に登録する必要があります。

\[$RootKey$\\Projects\\{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}\\MSBuildHostObjects\]
\[$RootKey$\\Projects\\{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}\\MSBuildHostObjects\\DesignTimeMarkupCompilationCT;CompileXaml\]
@="{83046B3F-8984-444B-A5D2-8029DEE2DB70}"

Visual Studio IDE での Visual C++ プロジェクトの機能拡張

Visual C++ プロジェクトシステムは VS Project System に基づいており、その機能拡張ポイントが使用されます。ただし、プロジェクト階層の実装は Visual C++ に固有であり、CPS に基づくものではないため、階層の機能拡張はプロジェクト項目に限定されます。

[プロジェクトプロパティ] ページ

一般的な設計情報については、VC++ プロジェクト用のフレームワークのマルチターゲットに関するページをご覧ください。

簡単に言えば、C++ プロジェクトの [プロジェクトプロパティ] ダイアログに表示されるプロパティページは、"規則" ファイルによって定義されます。規則ファイルでは、プロパティページに表示する一連のプロパティ、およびそれらをプロジェクトファイル内に保存する方法と場所を指定します。規則ファイルは、Xaml 形式を使用する .xml ファイルです。それらをシリアル化するために使用される型については、Microsoft.Build.Framework.XamlTypes に関するページをご覧ください。プロジェクトでの規則ファイルの使用について詳しくは、「プロパティページの XML 規則ファイル」をご覧ください。

規則ファイルは、PropertyPageSchema 項目グループに追加する必要があります。

<ItemGroup>
  <PropertyPageSchema Include="$(VCTargetsPath)$(LangID)\general.xml;"/>
  <PropertyPageSchema Include="$(VCTargetsPath)$(LangID)\general_file.xml">
    <Context>File</Context>
  </PropertyPageSchema>
</ItemGroup>

Context メタデータは規則の可視性を制限し (規則の可視性は規則の種類によっても制御される)、これには以下の値のいずれかを指定できます。

Project | File | PropertySheet

CPS ではコンテキストの種類を表す他の値をサポートしていますが、Visual C++ プロジェクトでは使用されません。

規則が複数のコンテキストで表示されるようにする必要がある場合は、以下に示すように、コンテキスト値をセミコロン (;) で区切ります。

<PropertyPageSchema Include="$(MyFolder)\MyRule.xml">
  <Context>Project;PropertySheet</Context>
</PropertyPageSchema>

規則の形式と主な種類

規則形式は単純であるため、このセクションでは、ユーザーインターフェイスでの規則の表示方法に影響する属性についてのみ説明します。

<Rule
  Name="ConfigurationGeneral"
  DisplayName="General"
  PageTemplate="generic"
  Description="General"
  xmlns="http://schemas.microsoft.com/build/2009/properties">

PageTemplate 属性は、[プロパティページ] ダイアログでの規則の表示方法を定義します。この属性には、以下の値のいずれかを指定できます。

属性	説明
`generic`	すべてのプロパティが、カテゴリの見出しの下の 1 ページに表示されます。 `Project` および `PropertySheet` コンテキストでは規則を表示できますが、`File` では表示できません。例: `$(VCTargetsPath)`\1033\general.xml
`tool`	カテゴリがサブページとして表示されます。すべてのコンテキスト (`Project`、`PropertySheet`、`File`) で規則を表示できます。規則が [プロジェクトプロパティ] に表示されるのは、その規則名が `ProjectTools` 項目グループに含まれている場合を除いて、`Rule.DataSource` で定義された `ItemType` を持つ項目がプロジェクトにある場合のみです。例: `$(VCTargetsPath)`\1033\clang.xml
`debugger`	ページが、[デバッグ] ページの一部として表示されます。現在、カテゴリは無視されています。規則名は、デバッグランチャーの MEF オブジェクトの `ExportDebugger` 属性と一致している必要があります。例: `$(VCTargetsPath)`\1033\debuggerlocalwindows.xml
custom	カスタムテンプレート。テンプレートの名前は、`PropertyPageUIFactoryProvider` MEF オブジェクトの `ExportPropertyPageUIFactoryProvider` 属性と一致している必要があります。 Microsoft.VisualStudio.ProjectSystem.Designers.Properties.IPropertyPageUIFactoryProvider をご覧ください。例: `$(VCTargetsPath)`\1033\userMacros.xml

規則でプロパティグリッドベースのテンプレートの 1 つを使用している場合は、以下の機能拡張ポイントをそのプロパティに使用できます。

規則の拡張

既存の規則を使用したいが、いくつかのプロパティだけを追加または削除する必要がある場合は、拡張規則を作成できます。

規則のオーバーライド

お使いのツールセットで、プロジェクトの既定の規則のほとんどを使用するが、そのうちの 1 つまたは一部だけは置き換えたいと考える場合があります。たとえば、異なるコンパイラスイッチを表示するように C/C++ の規則のみを変更するとします。既存の規則と同じ名前と表示名を持つ新しい規則を指定し、既定の cpp ターゲットのインポート後にそれを PropertyPageSchema 項目グループに含めることができます。プロジェクトでは所定の名前を持つ規則が 1 つだけ使用され、PropertyPageSchema 項目グループに含められた最後のものが優先されます。

プロジェクト品目

ProjectItemsSchema.xml ファイルでは、プロジェクト項目として扱われる項目の ContentType および ItemType 値を定義し、新しいファイルの追加先となる項目グループを決定する FileExtension 要素を定義します。

既定の ProjectItemsSchema ファイルは $(VCTargetsPath)\1033\ProjectItemsSchema.xml にあります。それを拡張するには、新しい名前 (MyProjectItemsSchema.xml など) でスキーマファイルを作成する必要があります。

<ProjectSchemaDefinitions xmlns="http://schemas.microsoft.com/build/2009/properties">

  <ItemType Name="MyItemType" DisplayName="C/C++ compiler"/>

  <ContentType
    Name="MyItems"
    DisplayName="My items"
    ItemType=" MyItemType ">
  </ContentType>

  <FileExtension Name=".abc" ContentType=" MyItems"/>

</ProjectSchemaDefinitions>

次に、ターゲットファイルに以下を追加します。

<ItemGroup>
  <PropertyPageSchema Include="MyProjectItemsSchema.xml"/>
</ItemGroup>

例: $(VCTargetsPath)\BuildCustomizations\masm.xml

デバッガー

Visual Studio のデバッグサービスでは、デバッグエンジンの機能拡張をサポートしています。詳細については、以下のサンプルをご覧ください。

デバッグセッション用のデバッグエンジンとその他のプロパティを指定するには、デバッグランチャーの MEF コンポーネントを実装し、debugger 規則を追加する必要があります。例については、$(VCTargetsPath)\1033\debugger_local_windows.xml ファイルをご覧ください。

デプロイ

.vcxproj プロジェクトでは、デプロイプロバイダーに Visual Studio プロジェクトシステムの機能拡張を使用します。

ビルドの最新状態チェック

既定では、ビルドの最新状態チェックには、ビルド中に $(TlogLocation) フォルダーに作成される、すべてのビルド入力および出力用の読み取り .tlog および書き込み .tlog ファイルが必要です。

カスタムの最新状態チェックを使用するには:

Toolset.targets ファイルに NoVCDefaultBuildUpToDateCheckProvider 機能を追加して、既定の最新状態チェックを無効にします。
```
<ItemGroup>
  <ProjectCapability Include="NoVCDefaultBuildUpToDateCheckProvider" />
</ItemGroup>
```
独自の IBuildUpToDateCheckProvider を実装します。

プロジェクトのアップグレード

既定の .vcxproj プロジェクトアップグレードプログラム

既定の .vcxproj プロジェクトアップグレードプログラムでは、PlatformToolset、ApplicationTypeRevision、MSBuild ツールセットのバージョン、.NET Framework を変更します。最後の 2 つは常に Visual Studio バージョンの既定値に変更されますが、PlatformToolset と ApplicationTypeRevision は特別な MSBuild プロパティによって制御できます。

このアップグレードプログラムでは、以下の基準を使用して、プロジェクトをアップグレードできるかどうかを判断します。

ApplicationType と ApplicationTypeRevision を定義するプロジェクトの場合、リビジョン番号が現在のものよりも高いフォルダーが存在する。
現在のツールセットに _UpgradePlatformToolsetFor_<safe_toolset_name> プロパティが定義されており、その値が現在のツールセットと等しくない。

これらのプロパティ名で、<safe_toolset_name> は英数字以外のすべて文字がアンダースコア (_) で置き換えられたツールセット名を表します。

プロジェクトをアップグレードできる場合は、"ソリューションの再ターゲット" に加えられます。詳細については、IVsTrackProjectRetargeting2 に関するページをご覧ください。

プロジェクトで特定のツールセットを使用する場合にソリューションエクスプローラーでプロジェクト名を装飾するには、_PlatformToolsetShortNameFor_<safe_toolset_name> プロパティを定義します。

_UpgradePlatformToolsetFor_<safe_toolset_name> および _PlatformToolsetShortNameFor_<safe_toolset_name> プロパティの定義の例については、Microsoft.Cpp.Default.props ファイルをご覧ください。使用例については、$(VCTargetPath)\Microsoft.Cpp.Platform.targets ファイルをご覧ください。

カスタムのプロジェクトアップグレードプログラム

カスタムのプロジェクトアップグレードプログラムオブジェクトを使用するには、以下に示すように MEF コンポーネントを実装します。

/// </summary>
[Export("MyProjectUpgrader", typeof(IProjectRetargetHandler))]
[Export(typeof(IProjectRetargetHandler))]
[ExportMetadata("Name", "MyProjectUpgrader")]
[OrderPrecedence(20)]
[PartMetadata(ProjectCapabilities.Requires, ProjectCapabilities.VisualC)]

internal class MyProjectUpgrader: IProjectRetargetHandler
{
    // ...
}

コードでは、既定の .vcxproj アップグレードプログラムオブジェクトをインポートして呼び出すことができます。

// ...
[Import("VCDefaultProjectUpgrader")]
// ...
    IProjectRetargetHandler Lazy<IProjectRetargetHandler>
    VCDefaultProjectUpgrader { get; set; }
// ...

IProjectRetargetHandler は Microsoft.VisualStudio.ProjectSystem.VS.dll で定義され、IVsRetargetProjectAsync に似ています。

VCProjectUpgraderObjectName プロパティを定義して、プロジェクトシステムにカスタムのアップグレードプログラムオブジェクトを使用するよう指示します。

<PropertyGroup>
  <VCProjectUpgraderObjectName>MyProjectUpgrader</VCProjectUpgraderObjectName>
</PropertyGroup>

プロジェクトのアップグレードの無効化

プロジェクトのアップグレードを無効にするには、NoUpgrade 値を使用します。

<PropertyGroup>
  <VCProjectUpgraderObjectName>NoUpgrade</VCProjectUpgraderObjectName>
</PropertyGroup>

プロジェクトキャッシュと機能拡張

Visual Studio 2017 で大規模な C++ ソリューションを使用するときのパフォーマンスを向上させるために、プロジェクトキャッシュが導入されました。これは、プロジェクトデータを格納する SQLite データベースとして実装された後、MSBuild または CPS プロジェクトをメモリに読み込まずにプロジェクトを読み込むために使用されます。

キャッシュから読み込まれた .vcxproj プロジェクトには CPS オブジェクトが存在しないため、UnconfiguredProject または ConfiguredProject をインポートする、拡張機能の MEF コンポーネントは作成できません。機能拡張をサポートするため、プロジェクトで MEF 拡張機能が使用される (または使用される可能性がある) かどうかを Visual Studio で検出するときに、プロジェクトキャッシュは使用されません。

以下の種類のプロジェクトは常に完全に読み込まれ、メモリ内に CPS オブジェクトが存在するため、すべての MEF 拡張機能が作成されます。

スタートアッププロジェクト
カスタムのプロジェクトアップグレードプログラムを持つ (つまり、VCProjectUpgraderObjectName プロパティが定義されている) プロジェクト
Desktop Windows を対象としない (つまり、ApplicationType プロパティが定義されている) プロジェクト
共有項目プロジェクト (.vcxitems) と、.vcxitems プロジェクトのインポートによってそれらを参照するすべてのプロジェクト。

これらの条件がいずれも検出されない場合は、プロジェクトキャッシュが作成されます。このキャッシュには、VCProjectEngine インターフェイス上で get クエリに応答するために必要な MSBuild プロジェクトからのデータがすべて含まれています。これは、拡張機能によって実行される、MSBuild の props および targets ファイルレベルでの変更がすべて、キャッシュから読み込まれたプロジェクトでのみ機能する必要があることを意味します。

拡張機能の配布

VSIX ファイルを作成する方法については、「Visual Studio 拡張機能の配布」をご覧ください。特別なインストール場所にファイルを追加する (たとえば、$(VCTargetsPath) の下にファイルを追加する) 方法については、「拡張機能フォルダー外でのインストール」をご覧ください。

その他のリソース

Microsoft Build System (MSBuild) は、ビルドエンジンと拡張可能な XML ベースの形式をプロジェクトファイルに提供します。 Visual C++ プロジェクトシステムを拡張するためには、基本的な MSBuild の概念と Visual C++ 向け MSBuild のしくみを理解しておく必要があります。

Managed Extensibility Framework (MEF) には、CPS および Visual C++ プロジェクトシステムで使用される拡張機能 API が用意されています。 CPS による MEF の使用方法の概要については、VSProjectSystem での MEF の概要のページに記載されている CPS と MEF に関するセクションをご覧ください。

既存のビルドシステムをカスタマイズして、ビルドステップまたは新しいファイルの種類を追加できます。詳細については、MSBuild (Visual C++) の概要とプロジェクトプロパティの操作に関するそれぞれのページをご覧ください。

次の方法で共有

Visual Studio C++ プロジェクト システムの機能拡張とツールセットの統合

C++ MSBuild ターゲットの構造

新しいプラットフォーム ツールセットの追加

新しいプラットフォームの追加

新しいアプリケーションの種類の追加

.vcxproj インポート ツリー

Toolset.props および Toolset.targets ファイルの作成

ツールセット固有のターゲットを既定の C++ ビルド プロセスと統合する

ツールセットのターゲット内で使用する MSBuild タスク

インクリメンタル ビルドと最新状態チェック

.tlog ファイル

読み取りの .tlog の形式

書き込みの .tlog の形式

デザイン時のビルド

IntelliSense の情報のためのデザイン時のターゲット

ソースを生成するデザイン時のターゲット

Visual Studio IDE での Visual C++ プロジェクトの機能拡張

[プロジェクト プロパティ] ページ

規則の形式と主な種類

規則の拡張

規則のオーバーライド

プロジェクト品目

デバッガー

デプロイ

ビルドの最新状態チェック

プロジェクトのアップグレード

既定の .vcxproj プロジェクト アップグレード プログラム

カスタムのプロジェクト アップグレード プログラム

プロジェクトのアップグレードの無効化

プロジェクト キャッシュと機能拡張

拡張機能の配布

その他のリソース

その他のリソース

Visual Studio C++ プロジェクトシステムの機能拡張とツールセットの統合

新しいプラットフォームツールセットの追加

.vcxproj インポートツリー

ツールセット固有のターゲットを既定の C++ ビルドプロセスと統合する

インクリメンタルビルドと最新状態チェック

[プロジェクトプロパティ] ページ

既定の .vcxproj プロジェクトアップグレードプログラム

カスタムのプロジェクトアップグレードプログラム

プロジェクトキャッシュと機能拡張