ビルドプロセスでテキスト変換を呼び出す

テキスト変換は、Visual Studio ソリューションのビルドプロセスの一部として呼び出すことができます。テキスト変換に特化したビルドタスクがあります。 T4 ビルドタスクでは、デザイン時のテキストテンプレートが実行され、実行時 (前処理済み) テキストテンプレートもコンパイルされます。

使用するビルドエンジンに応じて、ビルドタスクで実行できる操作にはいくつかの違いがあります。 Visual Studio でソリューションをビルドするときに、 hostspecific="true" 属性が設定されている場合、テキストテンプレートは Visual Studio API (EnvDTE) にアクセスできます。ただし、これは、コマンドラインからソリューションをビルドするときや、Visual Studio を使用してサーバービルドを開始する場合には当てはまりません。このような場合、ビルドは MSBuild によって実行され、別の T4 ホストが使用されます。つまり、MSBuild を使用してテキストテンプレートを作成する場合、同じ方法でプロジェクトファイル名などにアクセスすることはできません。ただし、ビルドパラメーターを使用して、環境情報をテキストテンプレートとディレクティブプロセッサに渡すことができます。

マシンを構成する

開発用コンピューターでビルドタスクを有効にするには、Modeling SDK for Visual Studio をインストールします。

注

テキストテンプレート変換コンポーネントは、Visual Studio 拡張機能開発ワークロードの一部として自動的にインストールされます。 SDK、ライブラリ、フレームワーク カテゴリの下にある Visual Studio インストーラーの [個々のコンポーネント] タブからインストールすることもできます。 [個々のコンポーネント] タブから Modeling SDK コンポーネントをインストールします。

Visual Studio がインストールされていないコンピューターでビルドサーバーが実行されている場合は、開発用コンピューターからビルドコンピューターに次のファイルをコピーします。

%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VisualStudio\v16.0\TextTemplating
- Microsoft.VisualStudio.TextTemplating.Sdk.Host.15.0.dll
- Microsoft.TextTemplating.Build.Tasks.dll
- Microsoft.TextTemplating.targets
%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\VSSDK\VisualStudioIntegration\Common\Assemblies\v4.0
- Microsoft.VisualStudio.TextTemplating.15.0.dll
- Microsoft.VisualStudio.TextTemplating.Interfaces.15.0.dll
- Microsoft.VisualStudio.TextTemplating.VSHost.15.0.dll
%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\Common7\IDE\PublicAssemblies
- Microsoft.VisualStudio.TextTemplating.Modeling.15.0.dll

ヒント

ビルドサーバーで TextTemplating ビルドターゲットを実行するときに Microsoft.CodeAnalysis メソッドの MissingMethodException が得られる場合は、Roslyn アセンブリが、ビルド実行可能ファイルと同じディレクトリにある Roslyn という名前のディレクトリ ( たとえば、msbuild.exe) にあることを確認します。

プロジェクトファイルを編集する

プロジェクトファイルを編集して、MSBuild の一部の機能 (テキスト変換ターゲットのインポートなど) を構成します。

ソリューションエクスプローラーで、プロジェクトの右クリックメニューから [アンロード] を選択します。これにより、XML エディターで .csproj または .vbproj ファイルを編集できます。編集が完了したら、[ 再読み込み] を選択します。

テキスト変換ターゲットをインポートする

.vbproj または .csproj ファイルで、最後の Import Project 行を見つけます。

その行の後に、存在する場合は、テキストテンプレートのインポートを挿入します。

<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets" />

ビルド内のテンプレートを変換する

変換タスクを制御するためにプロジェクトファイルに挿入できるプロパティがいくつかあります。

すべてのビルドの開始時に Transform タスクを実行します。

<PropertyGroup>
    <TransformOnBuild>true</TransformOnBuild>
</PropertyGroup>

たとえば、チェックアウトされていないため、読み取り専用のファイルを上書きします。
```
<PropertyGroup>
    <OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>
</PropertyGroup>
```
すべてのテンプレートを毎回変換します。
```
<PropertyGroup>
    <TransformOutOfDateOnly>false</TransformOutOfDateOnly>
</PropertyGroup>
```
既定では、T4 MSBuild タスクは、次よりも古い場合に出力ファイルを再生成します。
- そのテンプレートファイル
- 含まれるすべてのファイル
- テンプレートまたはそのテンプレートで使用されるディレクティブプロセッサによって以前に読み取られたファイル
これは、テンプレートと出力ファイルの日付のみを比較する Visual Studio の [すべてのテンプレートの変換 ] コマンドで使用されるよりも強力な依存関係テストです。

プロジェクトでテキスト変換のみを実行するには、TransformAll タスクを呼び出します。

msbuild myProject.csproj /t:TransformAll

特定のテキストテンプレートを変換するには:

msbuild myProject.csproj /t:Transform /p:TransformFile="Template1.tt"

TransformFile ではワイルドカードを使用できます。

msbuild dsl.csproj /t:Transform /p:TransformFile="GeneratedCode\**\*.tt"

ソース管理

ソース管理システムとの特定の組み込み統合はありません。ただし、生成されたファイルをチェックアウトしてチェックインするなど、独自の拡張機能を追加できます。既定では、テキスト変換タスクは、読み取り専用としてマークされているファイルの上書きを回避します。このようなファイルが検出されると、Visual Studio のエラー一覧にエラーが記録され、タスクは失敗します。

読み取り専用ファイルを上書きするように指定するには、次のプロパティを挿入します。

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

後処理手順をカスタマイズしない限り、ファイルが上書きされたときにエラー一覧に警告が記録されます。

ビルドプロセスをカスタマイズする

テキスト変換は、ビルドプロセス内の他のタスクの前に行われます。変換の前後に呼び出されるタスクは、 $(BeforeTransform) および $(AfterTransform)プロパティを設定することで定義できます。

<PropertyGroup>
    <BeforeTransform>CustomPreTransform</BeforeTransform>
    <AfterTransform>CustomPostTransform</AfterTransform>
</PropertyGroup>
<Target Name="CustomPreTransform">
    <Message Text="In CustomPreTransform..." Importance="High" />
</Target>
<Target Name="CustomPostTransform">
    <Message Text="In CustomPostTransform..." Importance="High" />
</Target>

AfterTransformでは、ファイルの一覧を参照できます。

GeneratedFiles - プロセスによって書き込まれたファイルの一覧。既存の読み取り専用ファイルを上書きしたファイルの場合、 %(GeneratedFiles.ReadOnlyFileOverwritten) は true になります。これらのファイルは、ソース管理からチェックアウトできます。
NonGeneratedFiles - 上書きされなかった読み取り専用ファイルの一覧。

たとえば、GeneratedFiles をチェックアウトするタスクを定義します。

OutputFilePath と OutputFileName

これらのプロパティは、MSBuild でのみ使用されます。 Visual Studio でのコード生成には影響しません。生成された出力ファイルを別のフォルダーまたはファイルにリダイレクトします。ターゲットフォルダーが既に存在している必要があります。

<ItemGroup>
  <None Include="MyTemplate.tt">
    <Generator>TextTemplatingFileGenerator</Generator>
    <OutputFilePath>MyFolder</OutputFilePath>
    <LastGenOutput>MyTemplate.cs</LastGenOutput>
  </None>
</ItemGroup>

リダイレクト先の便利なフォルダーは $(IntermediateOutputPath)。

出力ファイル名を指定すると、テンプレートの出力ディレクティブで指定された拡張子よりも優先されます。

<ItemGroup>
  <None Include="MyTemplate.tt">
    <Generator>TextTemplatingFileGenerator</Generator>
    <OutputFileName>MyOutputFileName.cs</OutputFileName>
    <LastGenOutput>MyTemplate.cs</LastGenOutput>
  </None>
</ItemGroup>

Visual Studio 内でテンプレートを変換する際に、「Transform All」を使用するか、単一ファイルジェネレーターを実行する場合は、OutputFileName または OutputFilePath を指定することは推奨されません。最終的には、変換をトリガーした方法に応じて、異なるファイルパスが得られます。これは混乱を招く可能性があります。

参照パスとインクルードパスを追加する

ホストには、テンプレートで参照されるアセンブリを検索する既定のパスセットがあります。このセットに追加するには:

<ItemGroup>
    <T4ReferencePath Include="$(VsIdePath)PublicAssemblies\" />
    <!-- Add more T4ReferencePath items here -->
</ItemGroup>

インクルードファイルを検索するフォルダーを設定するには、セミコロンで区切られたリストを指定します。通常、既存のフォルダー一覧に追加します。

<PropertyGroup>
    <IncludeFolders>
$(IncludeFolders);$(MSBuildProjectDirectory)\Include;AnotherFolder;And\Another</IncludeFolders>
</PropertyGroup>

ビルドコンテキストデータをテンプレートに渡す

プロジェクトファイルでパラメーター値を設定できます。たとえば、ビルドプロパティと環境変数を渡すことができます。

<ItemGroup>
  <T4ParameterValues Include="ProjectFolder">
    <Value>$(ProjectDir)</Value>
    <Visible>false</Visible>
  </T4ParameterValues>
</ItemGroup>

テキストテンプレートで、テンプレートディレクティブhostspecificを設定します。パラメーターディレクティブを使用して値を取得します。

<#@template language="c#" hostspecific="true"#>
<#@ parameter type="System.String" name="ProjectFolder" #>
The project folder is: <#= ProjectFolder #>

ディレクティブプロセッサでは、 ITextTemplatingEngineHost.ResolveParameterValue を呼び出すことができます。

string value = Host.ResolveParameterValue("-", "-", "parameterName");

Dim value = Host.ResolveParameterValue("-", "-", "parameterName")

注

ResolveParameterValue は、MSBuild を使用する場合にのみ T4ParameterValues からデータを取得します。 Visual Studio を使用してテンプレートを変換する場合、パラメーターには既定値があります。

アセンブリやインクルードディレクティブでプロジェクトのプロパティを活用する

$(SolutionDir) などの Visual Studio マクロは MSBuild では機能しません。代わりにプロジェクトプロパティを使用できます。

.csproj または .vbproj ファイルを編集して、プロジェクトプロパティを定義します。この例では、 myLibFolder という名前のプロパティを定義します。

<!-- Define a project property, myLibFolder: -->
<PropertyGroup>
    <myLibFolder>$(MSBuildProjectDirectory)\..\libs</myLibFolder>
</PropertyGroup>

<!-- Tell the MSBuild T4 task to make the property available: -->
<ItemGroup>
    <T4ParameterValues Include="myLibFolder">
      <Value>$(myLibFolder)</Value>
    </T4ParameterValues>
  </ItemGroup>

これで、アセンブリでプロジェクトプロパティを使用し、ディレクティブを含めることができます。

<#@ assembly name="$(myLibFolder)\MyLib.dll" #>
<#@ include file="$(myLibFolder)\MyIncludeFile.t4" #>

これらのディレクティブは、MSBuild と Visual Studio ホストの両方で T4parameterValues から値を取得します。

Q&A(質疑応答)

ビルドサーバーでテンプレートを変換する理由コードをチェックインする前に、Visual Studio でテンプレートを既に変換しました。

テンプレートによって読み取られたインクルードファイルまたは別のファイルを更新した場合、Visual Studio はファイルを自動的に変換しません。ビルドの一部としてテンプレートを変換すると、すべてが最新の状態になります。

テキストテンプレートを変換するためのその他のオプションは何ですか?

TextTransform ユーティリティは、コマンドスクリプトで使用できます。ほとんどの場合、MSBuild を使用する方が簡単です。
Visual Studio 拡張機能でテキスト変換を呼び出す。
デザイン時のテキストテンプレートは、Visual Studio によって変換されます。
実行時テキストテンプレートは、アプリケーションの実行時に変換されます。

T4 MSbuild テンプレートには、優れたガイダンスが含まれています %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets。

T4 テキストテンプレートを作成する

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-12-12

次の方法で共有

ビルド プロセスでテキスト変換を呼び出す

マシンを構成する

プロジェクト ファイルを編集する