生成过程中的代码生成

项目
08/12/2011

可以在 Visual Studio 解决方案生成过程中调用文本转换。可以借此来确定编译前从模板生成的文件是最新的。这样可以避免出现用户在生成项目或签入代码之前忘记单击**“转换所有模板”**这种情况。文本转换任务可以由 Visual Studio 或 MSBuild 在生成服务器上执行。

在项目文件中包含文本转换任务

安装可视化和建模 SDK

若要在开发计算机上启用生成任务，请安装 Visual Studio Visualization and Modeling SDK（Visual Studio 可视化和建模 SDK）。

若要在生成服务器上启用生成任务，请参见生成服务器上的文本转换。

编辑项目文件

若要调用文本转换，必须对定义项目的文件进行编辑。无法在项目属性编辑器中编辑这些属性。因此您必须关闭项目，将其作为文本文件进行编辑。

编辑项目文件的文本

在解决方案资源管理器中，右击项目，然后单击**“卸载项目”**。
再次右击项目，然后单击**“编辑项目”**。

项目文件的文本会出现在 XML 编辑器中。

在完成编辑时重新打开项目

关闭 XML 编辑器。
在解决方案资源管理器中，右击项目，然后单击**“重新加载项目”**。

导入文本转换目标

文本转换生成任务在一个文件中定义。必须在标准 C# 或 Visual Basic 目标之后导入该文件。

导入文本转换目标

在文件中搜索与以下这些行之一类似的一行：

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

- 或 -

<Import Project="$(MSBuildToolsPath)\Microsoft.VisualBasic.targets" />
在该行之后插入文本模板化导入：

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

设置属性以控制生成的执行方式

在项目文件中插入以下文本。有关可在此属性组中插入的其他属性，请参见以下各节。

<PropertyGroup>
 <TransformOnBuild>true</TransformOnBuild>
 <!-- Other properties can be inserted here -->
</PropertyGroup>

TransformOnBuild 会导致在生成项目时执行项目中的所有模板。

调用转换

在项目生成中转换所有模板

如果在项目文件中包括以下属性，则无论何时生成项目，都会按增量生成功能执行项目中的所有文本模板。

通过在 Visual Studio 中按 F5，或使用 MSBuild，均可调用转换。例如：

msbuild myproject.csproj

如果省略 TransformOnBuild 或将其设置为 false，则不会在项目生成中自动转换模板。

添加引用路径

可以添加到宿主在其中查找模板中引用的程序集的路径集。例如：

<ItemGroup>
    <!-- Add VS\...\PublicAssemblies to the list of places
         to look for assemblies used by templates. -->
    <T4ReferencePath Include="$(VsIdePath)PublicAssemblies\" />
</ItemGroup>

转换特定模板

通过使用 msbuild 实用工具调用 Transform 任务，可以转换指定文件。此任务不依赖于 TransformOnBuild 属性，也不编译项目文件。必须按上节所述导入文本模板化目标文件。

例如，转换特定文件：

msbuild myproj.proj /t:Transform /p:TransformFile=MyTemplate.tt

也可以在 TransformFile 参数中使用通配符。例如，此命令可对 GeneratedCode 文件夹下的所有 .tt 文件进行转换：

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

增量编译

默认情况下，如果生成管理器的输出文件是最新的，则该管理器会尝试避免执行模板。为此，该管理器会监视文件系统，以了解模板代码读取哪些文件。随后，会将这些文件的修改日期与输出文件的日期进行比较。如果有任何文件的修改日期早于输出文件，则会执行模板。此外，如果不存在有关此模板的以前执行情况的信息，也会执行模板。

因此如果输出文件早于以下任何文件，则会重新生成输出文件：

文本模板文件
<#@include#> 指令中指定的文件。
由模板中的代码读取的文件
由模板中使用的指令处理器包括或读取的文件。

如果要确保在每次生成中执行所有模板，请插入此属性：

<TransformOutOfDateOnly>false</TransformOutOfDateOnly>

源代码管理

没有针对源代码管理系统的特定内置集成。但是，可以添加自己的扩展，例如签出和签入生成的文件。

默认情况下，文本转换任务可避免覆盖标记为只读的文件，当遇到这类文件时，会在 Visual Studio 错误列表中记录错误，任务会失败。

若要指定应覆盖只读文件，请插入此属性：

除非自定义后续处理步骤，否则会在覆盖文件时，在错误列表中记录相应的警告。

自定义生成过程

可以自定义生成过程，例如签出已覆盖的文件。提供了两个自定义点，会在转换之前和之后调用这两个自定义点。

若要定义这些点，请定义属性 $(BeforeTransform) 和 $(AfterTransform)。

例如：

<PropertyGroup>
    <BeforeTransform>CustomPreTransform</BeforeTransform>
    <AfterTransform>CustomPostTransform;$(AfterTransform)</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 - 未覆盖的只读文件的列表。

例如，使用这些列表可以签出被覆盖的文件。

生成服务器上的文本转换

如果生成服务器在未安装 Visual Studio 的计算机上运行，则应从安装了 Visual Studio SDK 的计算机将下列文件复制到该生成计算机：

\Program Files\Microsoft Visual Studio 2010 SDK\VisualStudioIntegration\Common\Assemblies\v4.0\
- Microsoft.VisualStudio.TextTemplating.10.0.dll
- Microsoft.VisualStudio.TextTemplating.Interfaces.10.0.dll
- Microsoft.VisualStudio.TextTemplating.Vshost.10.0.dll
\Program Files\MSBuild\Microsoft\VisualStudio\TextTemplating\v10.0\
- Microsoft.VisualStudio.TextTemplating.Sdk.Host.10.0.dll
\Program Files\Microsoft Visual Studio 10.0\Common7\IDE\PublicAssemblies\
- Microsoft.VisualStudio.TextTemplating.Modeling.10.0.dll

有关更多信息，请参见创建和使用生成控制器。

请参见

其他资源

Visual Studio Visualization and Modeling SDK