Template Studio 模板开发入门 Lpt templates Development
作为一款优秀的ORM工具，一直享受着LLBL Gen快速代码生成的好处，却很少钻研它的原理，趁项目不忙，研究下LLBL Gen 3.x的模板开发方法。如果不熟悉基础的配置和步骤，请参考文章《优秀的基于模板的代码生成工具Template Studio》。LLBL Gen提供的ORM框架是免费的，源代码也可以从官网获取，ORM设计器需要商业许可。
既然是入门，肯定不能太复杂，参考Code Smith的入门资料的例子，生成下面的文件，作为模板代码生成的入门例子。
using System;
namespace <%=NameSpace %>
{
/// <summary>
/// Summary description for <%=ClassName %>.
/// </summary>
public class <%=ClassName %>
{
public <%=ClassName %>()
{
//
// TODO: Add constructor logic here
//
}
}
}
打开LLBL Gen的设计器，加载一个项目，点击菜单Windows->Show Template Bindings Viewer，调出Template Studio。注意，LLBL Gen 2.x的模板工具是独立的程序，称作Template Studio,LLBL Gen 3.x将模板工具直接集成到LLBL Gen设计器中，方便使用。新建立一个Template Bindings,界面如下图所示
添加两个模板Entity和EntityProperty，放在ISLTemplate目录下面，书写模板和模板生成的代码的语言都是C#。
CTRL+E，编辑模板Entity，因为是新增加的模板，会提示是否创建模板文件，选择Yes,Template Sutdio会创建模板文件，并打开它，供编辑模板，请添加如下的模板代码
<%
Project currentProject = _executingGenerator.ProjectDefinition;
EntityDefinition currentEntity = (EntityDefinition)_activeObject;
%>
using System;
using System.Data;
using <%=_executingGenerator.RootNamespaceToUse%>;
namespace <%=_executingGenerator.RootNamespaceToUse%>
{
/// <summary>
/// Summary description for <%=currentEntity.Name%>.
/// </summary>
public class <%=currentEntity.Name%>
{
public <%=currentEntity.Name%>()
{
//
// TODO: Add constructor logic here
//
}
}
}
如果有写过T4或是Code Smith模板的经验，这些经验仍然可以派上用场。不同的模板生成工具，不同的方面是获取元数据的方法，先在Visual Studio中写好最终需要的代码，然后把变化的部分用元数据替换。
<% 和 %> 包括的部分是代码片段，在运行时会执行。_executingGenerator是Template Studio内置的变量，在运行时动态传入值，它的类型是IGenerator，定义于程序集SD.LLBLGen.Pro.GeneratorCore中。还有两个变量
_parameters, 类型是Dictionary(String, TaskParameter) ,存放当前task的参数
_activeObject, 如果emitType=allEntites，则它代表当前的实体对象
这样解释感觉不太明朗，没有说透。以Entity模板为例子，模板引擎会为它生成一个类型，代码如下
public class Entity : ITemplateClass {
private StreamWriter __outputWriter;
private IGenerator _executingGenerator;
private Dictionary<string, TaskParameter> _parameters;
private object _activeObject;
public Entity() {
__outputWriter=null;_executingGenerator=null;_parameters=null;_activeObject=null;
}
private void __ScriptCode() {
Project currentProject = _executingGenerator.ProjectDefinition;
EntityDefinition currentEntity = (EntityDefinition)_activeObject;
__outputWriter.Write("\r\nusing System;\r\nusing System.Data;\r\n");
__outputWriter.Write("using ");
__outputWriter.Write(_executingGenerator.RootNamespaceToUse);
__outputWriter.Write(";\r\n\r\nnamespace ");
__outputWriter.Write(_executingGenerator.RootNamespaceToUse);
__outputWriter.Write("\r\n{\r\n /// <summary>\r\n /// Summary description for ");
__outputWriter.Write(currentEntity.Name);
__outputWriter.Write(".\r\n /// </summary>\r\n public class ");
__outputWriter.Write(currentEntity.Name);
__outputWriter.Write("\r\n {\r\n public ");
__outputWriter.Write(currentEntity.Name);
__outputWriter.Write("()\r\n {\r\n //\r\n // TODO: Add constructor logichere\r\n //\r\n }\r\n \r\n");
__outputWriter.Write("\r\n\r\n ");
__outputWriter.Write("\r\n\r\n");
__outputWriter.Write("\r\n//");
__outputWriter.Write("\r\n\r\n\r\n");
__outputWriter.Write("\r\n }\r\n}");
}
public void ___RUN(IGenerator executingGenerator, Dictionary<string, TaskParameter> parameters, StreamWriter outputWriter, object activeObject) {
__outputWriter = outputWriter;
_parameters = parameters;
_executingGenerator=executingGenerator;
_activeObject = activeObject;
__ScriptCode();
}
}
模板引擎会运行生成的___RUN方法，传放当前的项目信息(executingGenerator包含项目信息），和task的参数，如果是多次执行,将当前的对象赋给activeObject ，一并传入lpt模板。模板引擎分析lpt模板时，如果是字符串则直接用变量__outputWriter输出，如果是变量,比如<%=currentEntity.Name%>，则取它的值。
做基于LLBL Gen的代码生成器，所需要元数据就都在以上这四个变量中，如果不熟悉它的属性，可以用Reflector查看。
Entity模板设计好后，还需要设计它的传入参数。因为是自定义的模板，点击Add Tasks，添加ConsumeLptTemplate
再来配置它的几个参数。destinationFolder是存放模板的路径，相对于在General settings中设定的Destination root目录，可以使用DOS命令中的..和./表示当前目录或上一层目录，也可以放空，表示Destination root目录。如果它的值不为空，比如为GUI或是默认的值FolderName，则要添加一个DirectoryCreator任务，先产生目录，再来生成代码。
设置emitType=allEntities，因为这里是要为所有的实体生成一个类型文件，如果只为部分实体生成类型文件，请依照下图，来勾选需要生成代码的类型。
emitType的其它几个值，allTypedLists是所有的类型列表，allTypedViews所有视图，actionSPCalls所有命令存储过程，retrievalSPCalls所有查询存储过程，generic只执行一次
templateID设置为Entity，以表示当前任务，要使用的模板名称。filenameFormat默认为[elementName].[extension]，可不作修改，elementName是实体，extension依据当前要生成代码的项目类型，可以是VB或CS。
其它的选项可不作修改，最终的配置效果如图所示
点击 Start generator，就会在Destination root目录中生成代码，对每一个实体，生成一个类型文件。
前面已经提到过，要加入一些代码，作出逻辑判断，可以用<%和%>包括起来，这种情形用于修改元数据的值。
和ASP.NET相似，<%和%>括起工代码片段，，<%=%>，中间的部分是表达式，返回字符串
比如元数据提供的类型名称是Employee，而我需要的字符串是IEmployee，则可以用这种方法
public class I<%=currentEntity.Name%> { }
C#或VB代码片段的例子如下
<%
for(int i=0;i<_executingGenerator.ProjectDefinition.Entities.Count;i++)
{
%> some text which will end up Count times in the output <%
}
%>
如果做过LLBL Gen的开发，对__LLBLGENPRO_USER_CODE_REGION不会陌生。代码生成器在重新生成代码时，会保留这个标记符号中间的代码，而不会出现代码丢失。所以，要修改代码生成器生成的代码，增加一些业务逻辑，也应该遵守这个规则，把代码放到这两个符号级中间
// __LLBLGENPRO_USER_CODE_REGION_START Entity Property
// __LLBLGENPRO_USER_CODE_REGION_END
要生成这种符号标记，应该用这样的代码
<%=DotNetTemplateEngine.GetUserCodeRegion("Entity Property", "//")%>
LLBL Gen的模板允许嵌套，也就是一个模板文件中，可以嵌套定义多个子模板。以开头的两个模板Entity和EntityProperty模板为例子，要将EntityProperty模板嵌入到Entity模板中，应该这样写
<# EntityProperty #>
这令我想起了ASP和ASP.NET时代的页面嵌套，很相似。
使用<%和%>包括起来的代码片段部分，也可以包含方法定义，然后再在合适的地方，调用方法，请参考如下例子
<~
public string GetObjectName()
{
if(_activeObject==null)
{
return "no active object";
}
EntityDefinition e = _activeObject as EntityDefinition;
if(e!=null)
{
return e.Name;
}
TypedListDefinition tl = _activeObject as TypedListDefinition;
if(tl!=null)
{
return tl.Name;
}
TypedViewDefinition tv = _activeObject as TypedViewDefinition;
if(tv!=null)
{
return tv.Name;
}
SPCallDefinition sc = _activeObject as SPCallDefinition;
if(sc!=null)
{
return sc.Name;
}
// unknown object
return "Unknown";
}
~>
//<%=GetObjectName()%>
如果方法定义于一个外部程序集中，可以用这种方法引用外部程序集，用<[和]>括起来，例子如下
<[ System.Data.SqlClient ]>
如果要输出ASP.NET的类型变量，比如输出Foo，用C#是这样写:Response.Write("Foo");
转换成LLBL Gen模板语法：<%%=Response.Write("Foo");%%>
如果需要调试模板，参数设置debugBuild=true,在模板的开头添加<[ System.Diagnostics ]>，然后在需要停下来的地方，添加代码<% // Debugger.Break(); %>，这样在运行模板时，生调出窗口，选择调试器，以让调试器跟踪到生成的代码中去。不过，这种方法测试过多次，也没有成功调试。
LLBL Gen的模板编辑器，没有智能提示功能，只是个语法高亮的文本编辑器，LLBL Gen 3.x也没有提供对模板的编译和语法检查，2.x有语法检查功能，确实不好用。我想到的办法是，用Visual Studio来写模板代码，然后拷贝到Template Bindings Viewer编辑器中，对于错误模板的诊断和分析，只有靠经验来判断，这会令我无限的怀恋Visual Studio的功能，边写代码，后台自动检测语法错误。也许这是一个契机，开发一款灵活好用的LLBL Gen的模板编辑器
