ビルド処理でのテキスト変換の呼び出しInvoke text transformation in the build process

テキスト変換は、Visual Studio ソリューションのビルド処理の一部として呼び出すことができます。Text transformation can be invoked as part of the build process of a Visual Studio solution. テキスト変換に特化したビルド タスクがあります。There are build tasks that are specialized for text transformation. T4 ビルド タスクはデザイン時テキスト テンプレートを実行し、また、実行時 (前処理済み) テキスト テンプレートをコンパイルします。The T4 build tasks run design-time text templates, and they also compile run-time (preprocessed) text templates.

使用するビルド エンジンに応じて、ビルド タスクができることには違いが生じます。There are some differences in what the build tasks can do, depending on which build engine you use. Visual Studio でソリューションをビルドすると、hostspecific の属性が"true"に設定されている場合、テキストテンプレートから VISUAL studio API (EnvDTE) にアクセスできるようになります。When you build the solution in Visual Studio, a text template can access the Visual Studio API (EnvDTE) if the hostspecific="true" attribute is set. ただし、これは、コマンドラインからソリューションをビルドする場合、または Visual Studio を使用してサーバービルドを開始する場合には当てはまりません。But that isn't true when you build the solution from the command line or when you initiate a server build through Visual Studio. このような場合、ビルドは MSBuild によって実行され、別の T4 ホストが使用されます。In those cases, the build is performed by MSBuild and a different T4 host is used. これは、MSBuild を使用してテキストテンプレートを作成する場合と同じ方法でプロジェクトファイル名のようなものにアクセスできないことを意味します。This means that you can't access things like project file names in the same way when you build a text template using MSBuild. ただし、ビルドパラメーターを使用して、環境情報をテキストテンプレートおよびディレクティブプロセッサに渡すことができます。However, you can pass environment information into text templates and directive processors by using build parameters.

コンピューターを構成するConfigure your machines

開発用コンピューターでビルドタスクを有効にするには、モデリング SDK for Visual Studio をインストールします。To enable build tasks on your development computer, install Modeling SDK for Visual Studio.

Note

テキスト テンプレート変換コンポーネントがの一部として自動的にインストールされている、 Visual Studio 拡張機能の開発ワークロード。The Text Template Transformation component is automatically installed as part of the Visual Studio extension development workload. インストールすることも、個々 のコンポーネントVisual Studio インストーラーのタブで、 Sdk、ライブラリ、およびフレームワークカテゴリ。You can also install it from the Individual components tab of Visual Studio Installer, under the SDKs, libraries, and frameworks category. インストール、 Modeling SDKコンポーネントから、個々 のコンポーネントタブ。Install the Modeling SDK component from the Individual components tab.

Visual Studio がインストールされていないコンピューターでビルドサーバーを実行する場合は、開発用コンピューターからビルドコンピューターに次のファイルをコピーします。If your build server runs on a computer that doesn't have Visual Studio installed, copy the following files to the build computer from your development machine:

  • % ProgramFiles (x86)% \ Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VisualStudio\v16.0\TextTemplating%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VisualStudio\v16.0\TextTemplating

    • VisualStudio. 15.0. .dll....Microsoft.VisualStudio.TextTemplating.Sdk.Host.15.0.dll
    • Microsoft.TextTemplating.Build.Tasks.dllMicrosoft.TextTemplating.Build.Tasks.dll
    • Microsoft.TextTemplating.targetsMicrosoft.TextTemplating.targets
  • % ProgramFiles (x86)% \ Microsoft Visual Studio\2019\Community\VSSDK\VisualStudioIntegration\Common\Assemblies\v4.0%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\VSSDK\VisualStudioIntegration\Common\Assemblies\v4.0

    • VisualStudio. 15.0 (.dll)Microsoft.VisualStudio.TextTemplating.15.0.dll
    • VisualStudio. 15.0. .dll...Microsoft.VisualStudio.TextTemplating.Interfaces.15.0.dll
    • VisualStudio. Vshost.exe. 15.0.Microsoft.VisualStudio.TextTemplating.VSHost.15.0.dll
  • % ProgramFiles (x86)% \ Microsoft Visual Studio\2019\Community\Common7\IDE\PublicAssemblies%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\Common7\IDE\PublicAssemblies

    • VisualStudio. 15.0... テンプレート.Microsoft.VisualStudio.TextTemplating.Modeling.15.0.dll

Tip

ビルドサーバーで TextTemplating ビルドターゲットを実行するときに、Microsoft CodeAnalysis メソッドの MissingMethodException を取得した場合は、Roslyn アセンブリが、ビルド実行可能ファイルと同じディレクトリにあるroslynという名前のディレクトリにあることを確認してください (たとえば、 msbuild.exe)。If you get a MissingMethodException for a Microsoft.CodeAnalysis method when running TextTemplating build targets on a build server, make sure the Roslyn assemblies are in a directory named Roslyn that's in the same directory as the build executable (for example, msbuild.exe).

プロジェクト ファイルを編集するEdit the project file

プロジェクトファイルを編集して、MSBuild の一部の機能を構成します。たとえば、テキスト変換ターゲットをインポートします。Edit your project file to configure some of the features in MSBuild, for example, importing the text transformation targets.

ソリューションエクスプローラーで、プロジェクトの右クリックメニューから [アンロード] を選択します。In Solution Explorer, choose Unload from the right-click menu of your project. これにより XML エディターで .csproj または .vbproj ファイルを編集できるようになります。That allows you to edit the .csproj or .vbproj file in the XML editor. 編集が完了したら、 [再読み込み] を選択します。When you've finished editing, choose Reload.

テキスト変換ターゲットをインポートするImport the text transformation targets

.vbproj ファイルまたは .csproj ファイルで、次のような行を探します。In the .vbproj or .csproj file, find a line like this:

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

- または- or -

<Import Project="$(MSBuildToolsPath)\Microsoft.VisualBasic.targets" />

この行の後に、テキスト テンプレートのインポートを挿入します。After that line, insert the Text Templating import:

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

ビルド内のテンプレートの変換Transform templates in a build

プロジェクト ファイルに挿入して変換タスクを制御できるプロパティがいくつかあります。There are some properties that you can insert into your project file to control the transformation task:

  • すべてのビルドの開始時に変換タスクを実行します。Run the Transform task at the start of every build:

    <PropertyGroup>
        <TransformOnBuild>true</TransformOnBuild>
    </PropertyGroup>
    
  • ファイルがチェックアウトされていないためなど、読み取り専用のファイルを上書きします。Overwrite files that are read-only, for example, because they are not checked out:

    <PropertyGroup>
        <OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>
    </PropertyGroup>
    
  • 毎回、すべてのテンプレートを変換します。Transform every template every time:

    <PropertyGroup>
        <TransformOutOfDateOnly>false</TransformOutOfDateOnly>
    </PropertyGroup>
    

    既定では、次の値より古い場合、T4 MSBuild タスクによって出力ファイルが再生成されます。By default, the T4 MSBuild task regenerates an output file if it's older than:

    • そのテンプレートファイルits template file
    • 含まれているすべてのファイルany files that are included
    • 以前にテンプレートまたは使用するディレクティブプロセッサによって読み取られたファイルany files that have previously been read by the template or by a directive processor that it uses

    これは、Visual Studio の [すべてのテンプレートの変換] コマンドで使用されるよりも強力な依存関係テストであり、テンプレートと出力ファイルの日付のみを比較します。This is a more powerful dependency test than is used by the Transform All Templates command in Visual Studio, which only compares the dates of the template and output file.

プロジェクトでテキスト変換だけを実行するには、TransformAll タスクを呼び出します。To perform just the text transformations in your project, invoke the TransformAll task:

msbuild myProject.csproj /t:TransformAll

特定のテキスト テンプレートを変換するには、次のように実行します。To transform a specific text template:

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

TransformFile ではワイルドカードを使用できます。You can use wildcards in TransformFile:

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

ソース管理Source control

ソース管理システムと連携するような専用の機能は組み込まれていません。There is no specific built-in integration with a source control system. ただし、たとえば、独自の拡張機能を追加して、生成されたファイルをチェックアウトしてチェックインすることもできます。However, you can add your own extensions, for example, to check out and check in a generated file. 既定では、テキスト変換タスクは、読み取り専用としてマークされているファイルの上書きを回避します。By default, the text transform task avoids overwriting a file that is marked as read-only. このようなファイルが検出されると、Visual Studio エラー一覧にエラーが記録され、タスクは失敗します。When such a file is encountered, an error is logged in the Visual Studio Error List, and the task fails.

読み取り専用ファイルを上書きするには、次のプロパティを挿入します。To specify that read-only files should be overwritten, insert this property:

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

後処理の手順をカスタマイズしない限り、ファイルが上書きされたときにエラー一覧に警告が記録されます。Unless you customize the postprocessing step, a warning will be logged in the Error List when a file is overwritten.

ビルドプロセスをカスタマイズするCustomize the build process

テキスト変換は、ビルド処理で他のタスクよりも前に実行されます。Text transformation happens before other tasks in the build process. $(BeforeTransform) プロパティと $(AfterTransform) プロパティを設定して、変換の前後に呼び出すタスクを定義できます。You can define tasks that are invoked before and after transformation, by setting the properties $(BeforeTransform) and $(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 では、ファイルのリストを参照できます。In AfterTransform, you can reference lists of files:

  • GeneratedFiles: 処理中に出力されたファイルのリスト。GeneratedFiles - a list of files written by the process. 既存の読み取り専用ファイルを上書きしたファイルについては、%(GeneratedFiles.ReadOnlyFileOverwritten) は true になります。For those files that overwrote existing read-only files, %(GeneratedFiles.ReadOnlyFileOverwritten) will be true. これらのファイルは、ソース管理からチェックアウトできます。These files can be checked out of source control.

  • NonGeneratedFiles: 上書きされなかった読み取り専用ファイルのリスト。NonGeneratedFiles - a list of read-only files that were not overwritten.

たとえば、GeneratedFiles をチェックアウトするタスクを定義します。For example, you define a task to check out GeneratedFiles.

OutputFilePath と OutputFileNameOutputFilePath and OutputFileName

これらのプロパティを使用するのは MSBuild だけです。These properties are used only by MSBuild. Visual Studio のコード生成には影響しません。They do not affect code generation in Visual Studio. これらは生成された出力ファイルを別のフォルダーまたはファイルにリダイレクトします。They redirect the generated output file to a different folder or file. 対象となるフォルダーが既に存在する必要があります。The target folder must already exist.

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

リダイレクト先として便利なフォルダーは $(IntermediateOutputPath) です。A useful folder to redirect to is $(IntermediateOutputPath).

出力ファイル名を指定した場合は、テンプレートの output ディレクティブで指定されている拡張子よりも優先されます。If you specify an output filename, it takes precedence over the extension specified in the output directive in the templates.

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

OutputFileName または OutputFilePath を指定することは、Visual Studio 内で すべて変換する (1 つのファイルジェネレーター) を使用してテンプレートを変換する場合には推奨されません。Specifying an OutputFileName or OutputFilePath isn't recommended if you are also transforming templates inside Visual Studio using Transform All or running the single file generator. 変換のトリガー方法によっては、ファイルパスが異なる場合があります。You'll end up with different file paths depending on how you triggered the transformation. これは混乱する可能性があります。This can be confusing.

参照パスとインクルードパスの追加Add reference and include paths

ホストには、テンプレートで参照されているアセンブリを検索する既定のパス セットがあります。The host has a default set of paths where it searches for assemblies referenced in templates. このパス セットを追加するには、次のように指定します。To add to this set:

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

インクルード ファイルを検索するフォルダーを設定するには、セミコロン区切りのリストを指定します。To set the folders that will be searched for include files, provide a semicolon-separated list. 通常は、既存のフォルダー リストに追加します。Usually you add to the existing folder list.

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

ビルドコンテキストデータをテンプレートに渡すPass build context data into the templates

プロジェクト ファイルでパラメーター値を設定できます。You can set parameter values in the project file. たとえば、ビルドプロパティと環境変数を渡すことができます。For example, you can pass build properties and environment variables:

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

テキスト テンプレートでは、template ディレクティブで hostspecific を設定します。In a text template, set hostspecific in the template directive. 値を取得するには、 parameterディレクティブを使用します。Use the parameter directive to get values:

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

ディレクティブプロセッサでは、ITextTemplatingEngineHost を呼び出すことができますIn a directive processor, you can call ITextTemplatingEngineHost.ResolveParameterValue:

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

Note

ResolveParameterValue は、MSBuild を使用する場合に限り、T4ParameterValues からデータを取得します。ResolveParameterValue gets data from T4ParameterValues only when you use MSBuild. Visual Studio を使用してテンプレートを変換すると、パラメーターには既定値が設定されます。When you transform the template using Visual Studio, the parameters have default values.

アセンブリおよびインクルードディレクティブでのプロジェクトプロパティの使用Use project properties in assembly and include directives

$ (Solutiondir) などの Visual Studio マクロは、MSBuild では動作しません。Visual Studio macros like $(SolutionDir) don't work in MSBuild. その代わりに、プロジェクト プロパティを使用できます。You can use project properties instead.

.Csprojファイルまたは .vbprojファイルを編集して、プロジェクトのプロパティを定義します。Edit your .csproj or .vbproj file to define a project property. この例では、 Mylibfolderという名前のプロパティを定義します。This example defines a property named 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 ディレクティブおよび include ディレクティブでプロジェクト プロパティを使用できます。Now you can use your project property in assembly and include directives:

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

これらのディレクティブは、MSBuild ホストおよび Visual Studio ホストの両方で T4parameterValues から値を取得します。These directives get values from T4parameterValues both in MSBuild and in Visual Studio hosts.

Q & AQ & A

ビルドサーバーでテンプレートを変換する理由コードをチェックインする前に、Visual Studio で既にテンプレートを変換しました。Why would I want to transform templates in the build server? I already transformed templates in Visual Studio before I checked in my code.

インクルードファイルまたはテンプレートによって読み取られた別のファイルを更新すると、Visual Studio はファイルを自動的に変換しません。If you update an included file or another file read by the template, Visual Studio doesn't transform the file automatically. ビルドの一部としてテンプレートを変換すると、すべてが最新であることが保証されます。Transforming templates as part of the build makes sure that everything's up to date.

テキストテンプレートを変換するためのオプションは他にありますか。What other options are there for transforming text templates?

関連項目See also

  • @No__t_0 の T4 MSbuild テンプレートには、適切なガイダンスがあります。There's good guidance in the T4 MSbuild template at %ProgramFiles(x86)%\Microsoft Visual Studio\2017\Enterprise\msbuild\Microsoft\VisualStudio\v15.0\TextTemplating\Microsoft.TextTemplating.targets
  • @No__t_0 の T4 MSbuild テンプレートには、適切なガイダンスがあります。There's good guidance in the T4 MSbuild template at %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\msbuild\Microsoft\VisualStudio\v16.0\TextTemplating\Microsoft.TextTemplating.targets