基于T4模板引擎生成静态网站(CMS)

缘由

用Net技术生成纯静态网站目前市面上的技术貌似不是很多，要么就是一些大公司的项目。相比于Php语言来说，基于Php语言的CMS系统就有很多了，并且模板解析技术也已经比较成熟了。模板解析引擎一直是一个核心的问题，曾经我也尝试了好多种办法来间接的实现模板解析，但都不能完美的解决面临的问题，相信很多使用Net做网站的朋友也希望有一套像Php那样的CMS系统。直到有一天公司组织微软的专家过来培训让我了解到了VS10在代码生成方面所呈现出的优越表现，让我联想到了这套引擎能不能用于其他的方面应用。。。。(写此文的目的为记录日志，所以大牛的话可以飘过了。)

一、所需准备：

1. 本文介绍的实现方法将以C#语言为实现。
2. 实验环境是VS10+sp1+VSsdk
3. 需要引入程序集：Microsoft.VisualStudio.TextTemplating.10.0.dll  和 Microsoft.VisualStudio.TextTemplating.Interfaces.10.0.dll
4. 所需的Net framework平台是 4，还在用2  || 3  ||  3.5的朋友赶紧的更新一下吧！

下载地址(vssdk)：http://www.microsoft.com/en-us/download/details.aspx?id=2680

已知问题：如果你的VS已经打过了SP1，那么安装VSSDK时会出现一个错误，需要手工更改一下注册表，需要将注册表中的某个键值1更改为0。具体的详细设置办法Google一下就有答案了。

二、技术实现

2.1实现思路

用T4做为模板文件的解析引擎，将数据、解析引擎、静态文件模板、控制器分别单独出来，这样的话程序员只用写一套框架程序就行了，框架写好之后剩下的就是写静态文件模板了。关于T4模板解析引擎功能的强大之处，可以参考MSDN的官方资料。（）像这些问题如：模板嵌套子模板、可编程等问题，早已被T4完美的解决了。

2.2实现代码

要实现我们的自定义主机解析引擎，首先要添加一个实现了ITextTemplatingEngineHost 和  ITextTemplatingSessionHost  接口的类，代码如下（时间长了，我也忘记是从哪里Copy过来的代码了，应该是MSDN吧）：

首先创建一个CustomCmdLineHost类，添加如下应用：

using System.IO;
using System.CodeDom.Compiler;
using Microsoft.VisualStudio.TextTemplating;

然后实现ITextTemplatingEngineHost 和  ITextTemplatingSessionHost  接口，代码如下：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.IO;
using System.CodeDom.Compiler;
using Microsoft.VisualStudio.TextTemplating;

namespace Smart.TextTemplating
{
    public class CustomCmdLineHost : ITextTemplatingEngineHost, ITextTemplatingSessionHost
    {
        //the path and file name of the text template that is being processed
        //---------------------------------------------------------------------
        public string TemplateFileValue;
        public string TemplateFile
        {
            get { return TemplateFileValue; }
        }
        //This will be the extension of the generated text output file.
        //The host can provide a default by setting the value of the field here.
        //The engine can change this value based on the optional output directive
        //if the user specifies it in the text template.
        //---------------------------------------------------------------------
        private string fileExtensionValue = ".txt";
        public string FileExtension
        {
            get { return fileExtensionValue; }
        }
        //This will be the encoding of the generated text output file.
        //The host can provide a default by setting the value of the field here.
        //The engine can change this value based on the optional output directive
        //if the user specifies it in the text template.
        //---------------------------------------------------------------------
        private Encoding fileEncodingValue = Encoding.UTF8;
        public Encoding FileEncoding
        {
            get { return fileEncodingValue; }
        }
        //These are the errors that occur when the engine processes a template.
        //The engine passes the errors to the host when it is done processing,
        //and the host can decide how to display them. For example, the host
        //can display the errors in the UI or write them to a file.
        //---------------------------------------------------------------------
        private CompilerErrorCollection errorsValue;
        public CompilerErrorCollection Errors
        {
            get { return errorsValue; }
        }
        //The host can provide standard assembly references.
        //The engine will use these references when compiling and
        //executing the generated transformation class.
        //--------------------------------------------------------------
        public IList<string> StandardAssemblyReferences
        {
            get
            {
                return new string[]
                {
                    //If this host searches standard paths and the GAC,
                    //we can specify the assembly name like this.
                    //---------------------------------------------------------
                    //"System"

                    //Because this host only resolves assemblies from the
                    //fully qualified path and name of the assembly,
                    //this is a quick way to get the code to give us the
                    //fully qualified path and name of the System assembly.
                    //---------------------------------------------------------
                    typeof(System.Uri).Assembly.Location
                };
            }
        }
        //The host can provide standard imports or using statements.
        //The engine will add these statements to the generated
        //transformation class.
        //--------------------------------------------------------------
        public IList<string> StandardImports
        {
            get
            {
                return new string[]
                {
                    "System"
                };
            }
        }
        //The engine calls this method based on the optional include directive
        //if the user has specified it in the text template.
        //This method can be called 0, 1, or more times.
        //---------------------------------------------------------------------
        //The included text is returned in the context parameter.
        //If the host searches the registry for the location of include files,
        //or if the host searches multiple locations by default, the host can
        //return the final path of the include file in the location parameter.
        //---------------------------------------------------------------------
        public bool LoadIncludeText(string requestFileName, out string content, out string location)
        {
            content = System.String.Empty;
            location = System.String.Empty;

            //If the argument is the fully qualified path of an existing file,
            //then we are done.
            //----------------------------------------------------------------
            if (File.Exists(requestFileName))
            {
                content = File.ReadAllText(requestFileName);
                return true;
            }
            //This can be customized to search specific paths for the file.
            //This can be customized to accept paths to search as command line
            //arguments.
            //----------------------------------------------------------------
            else
            {
                return false;
            }
        }
        //Called by the Engine to enquire about
        //the processing options you require.
        //If you recognize that option, return an
        //appropriate value.
        //Otherwise, pass back NULL.
        //--------------------------------------------------------------------
        public object GetHostOption(string optionName)
        {
            object returnObject;
            switch (optionName)
            {
                case "CacheAssemblies":
                    returnObject = true;
                    break;
                default:
                    returnObject = null;
                    break;
            }
            return returnObject;
        }
        //The engine calls this method to resolve assembly references used in
        //the generated transformation class project and for the optional
        //assembly directive if the user has specified it in the text template.
        //This method can be called 0, 1, or more times.
        //---------------------------------------------------------------------
        public string ResolveAssemblyReference(string assemblyReference)
        {
            //If the argument is the fully qualified path of an existing file,
            //then we are done. (This does not do any work.)
            //----------------------------------------------------------------
            if (File.Exists(assemblyReference))
            {
                return assemblyReference;
            }
            //Maybe the assembly is in the same folder as the text template that
            //called the directive.
            //----------------------------------------------------------------
            string candidate = Path.Combine(Path.GetDirectoryName(this.TemplateFile), assemblyReference);
            if (File.Exists(candidate))
            {
                return candidate;
            }
            //This can be customized to search specific paths for the file
            //or to search the GAC.
            //----------------------------------------------------------------
            //This can be customized to accept paths to search as command line
            //arguments.
            //----------------------------------------------------------------
            //If we cannot do better, return the original file name.
            return "";
        }
        //The engine calls this method based on the directives the user has
        //specified in the text template.
        //This method can be called 0, 1, or more times.
        //---------------------------------------------------------------------
        public Type ResolveDirectiveProcessor(string processorName)
        {
            //This host will not resolve any specific processors.
            //Check the processor name, and if it is the name of a processor the
            //host wants to support, return the type of the processor.
            //---------------------------------------------------------------------
            if (string.Compare(processorName, "XYZ", StringComparison.OrdinalIgnoreCase) == 0)
            {
                //return typeof();
            }
            //This can be customized to search specific paths for the file
            //or to search the GAC
            //If the directive processor cannot be found, throw an error.
            throw new Exception("Directive Processor not found");
        }
        //A directive processor can call this method if a file name does not
        //have a path.
        //The host can attempt to provide path information by searching
        //specific paths for the file and returning the file and path if found.
        //This method can be called 0, 1, or more times.
        //---------------------------------------------------------------------
        public string ResolvePath(string fileName)
        {
            if (fileName == null)
            {
                throw new ArgumentNullException("the file name cannot be null");
            }
            //If the argument is the fully qualified path of an existing file,
            //then we are done
            //----------------------------------------------------------------
            if (File.Exists(fileName))
            {
                return fileName;
            }
            //Maybe the file is in the same folder as the text template that
            //called the directive.
            //----------------------------------------------------------------
            string candidate = Path.Combine(Path.GetDirectoryName(this.TemplateFile), fileName);
            if (File.Exists(candidate))
            {
                return candidate;
            }
            //Look more places.
            //----------------------------------------------------------------
            //More code can go here...
            //If we cannot do better, return the original file name.
            return fileName;
        }
        //If a call to a directive in a text template does not provide a value
        //for a required parameter, the directive processor can try to get it
        //from the host by calling this method.
        //This method can be called 0, 1, or more times.
        //---------------------------------------------------------------------
        public string ResolveParameterValue(string directiveId, string processorName, string parameterName)
        {
            if (directiveId == null)
            {
                throw new ArgumentNullException("the directiveId cannot be null");
            }
            if (processorName == null)
            {
                throw new ArgumentNullException("the processorName cannot be null");
            }
            if (parameterName == null)
            {
                throw new ArgumentNullException("the parameterName cannot be null");
            }
            //Code to provide "hard-coded" parameter values goes here.
            //This code depends on the directive processors this host will interact with.
            //If we cannot do better, return the empty string.
            return String.Empty;
        }
        //The engine calls this method to change the extension of the
        //generated text output file based on the optional output directive
        //if the user specifies it in the text template.
        //---------------------------------------------------------------------
        public void SetFileExtension(string extension)
        {
            //The parameter extension has a '.' in front of it already.
            //--------------------------------------------------------
            fileExtensionValue = extension;
        }
        //The engine calls this method to change the encoding of the
        //generated text output file based on the optional output directive
        //if the user specifies it in the text template.
        //----------------------------------------------------------------------
        public void SetOutputEncoding(System.Text.Encoding encoding, bool fromOutputDirective)
        {
            fileEncodingValue = encoding;
        }
        //The engine calls this method when it is done processing a text
        //template to pass any errors that occurred to the host.
        //The host can decide how to display them.
        //---------------------------------------------------------------------
        public void LogErrors(CompilerErrorCollection errors)
        {
            errorsValue = errors;
        }
        //This is the application domain that is used to compile and run
        //the generated transformation class to create the generated text output.
        //----------------------------------------------------------------------
        public AppDomain ProvideTemplatingAppDomain(string content)
        {
            //This host will provide a new application domain each time the
            //engine processes a text template.
            //-------------------------------------------------------------
            return AppDomain.CreateDomain("Generation App Domain");
            //This could be changed to return the current appdomain, but new
            //assemblies are loaded into this AppDomain on a regular basis.
            //If the AppDomain lasts too long, it will grow indefintely,
            //which might be regarded as a leak.
            //This could be customized to cache the application domain for
            //a certain number of text template generations (for example, 10).
            //This could be customized based on the contents of the text
            //template, which are provided as a parameter for that purpose.
        }

        public ITextTemplatingSession CreateSession()
        {
            return Session;
        }

        public ITextTemplatingSession Session
        {
            get;
            set;
        }
    }
}

ITextTemplatingEngineHost  毫无疑问是模板解析引擎的主机；实现ITextTemplatingSessionHost  接口可以让我们往模板中传递变量，它采用了asp.net 中的Session概念。如果我们不需要往模板中传递Session数据话，可以不实现这个接口。

调用实例一：

Smart.TextTemplating.CustomCmdLineHost host = new Smart.TextTemplating.CustomCmdLineHost();
            Engine engine = new Engine();
            host.Session = new TextTemplatingSession();
            host.Session["count"] = 5;
            host.TemplateFileValue = "tmp.tt";
            string input = File.ReadAllText(host.TemplateFileValue);
            string output = engine.ProcessTemplate(input, host);
            File.WriteAllText(host.TemplateFileValue + ".txt", output);

模板文件内容(tmp.tt)：

<#@ template debug="true" #>
<#@ parameter name="data" type="System.Object" #>

<#
   int count = Convert.ToInt32(data);
   for (int i=0; i<count; i++)
   {
       WriteLine(i.ToString());
   }
#>

调用实例二：

此种方法我封装了一个单独的类，加入了我的代码收藏夹，实现了多文件生成，向模板文件传递数据等：

调用示例：

List<object> data = new List<object>();
            for (int i = 0; i < 5; i++)
            {
                data.Add(i.ToString());
            }

            Smart.TextTemplating.ParseTextTemplating parse = new Smart.TextTemplating.ParseTextTemplating(
                "",
                "view_",
                ".txt",
                data,
                "tmp.tt");
            parse.Parse();

我封装的代码(以后想用了直接调用就可以了)：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.CodeDom.Compiler;
using System.IO;
using Microsoft.VisualStudio.TextTemplating;

namespace Smart.TextTemplating
{
    public class ParseTextTemplating
    {
        #region 私有变量
        private string _templateContent;
        private string _saveRootPath;
        private string _startFlag;
        private string _extension;
        private List<object> _data = new List<object>();
        #endregion

        public ParseTextTemplating(string saveRootPath, string startFlag, string extension, List<object> data, string templatefilePath)
        {
            this._saveRootPath = saveRootPath;
            this._startFlag = startFlag;
            this._extension = extension;
            this._data = data;

            if (string.IsNullOrEmpty(_saveRootPath))
            {
                _saveRootPath = AppDomain.CurrentDomain.BaseDirectory;
            }
            if (string.IsNullOrEmpty(_extension))
            {
                _extension = ".html";
            }
            if (string.IsNullOrEmpty(templatefilePath) || !File.Exists(templatefilePath))
            {
                this._templateContent = "";
            }
            else
            {
                this._templateContent = File.ReadAllText(templatefilePath);
            }
        }

        public void Parse()
        {
            foreach (object key in _data)
            {
                SmartTextTemplatingEngineHost host = new SmartTextTemplatingEngineHost();
                host.Session = new TextTemplatingSession();
                host.Session["data"] = key;
                Engine engine = new Engine();
                string content = engine.ProcessTemplate(_templateContent, host);
                if (!string.IsNullOrEmpty(content) && host.Errors.Count == 0)
                {
                    string filePath = string.Format("{0}{1}{2}{3}",
                        _saveRootPath,
                        _startFlag,
                        DateTime.Now.ToString("yyyyMMddHHmmss") + DateTime.Now.Millisecond.ToString("d4"),
                        _extension);
                    File.WriteAllText(filePath, content, Encoding.UTF8);
                }

                foreach (CompilerError er in host.Errors)
                {
                    File.AppendAllText(_saveRootPath + "error.txt",
                        er.ToString() + "\r\n\r\n",
                        Encoding.UTF8);
                }
            }
        }
    }
}

模板文件传递变量：<#@ parameter name="data" type="System.Object" #> 可以接口主程序传递过来的onject类型的变量数据。

2.3运行结果

生成的结果文件：

文件内容：

三、总结和展望

T4模板引擎是非常强大的，至于功能都强大到何处还需要我们深入的仔细了解。细心的同学可能已经发现了，T4模板引擎虽然强大，但是写模板时却没有一个像VS那样的带智能感知的代码提示工具啊？放心吧！这个问题已经不是问题了，安装一个VS扩展就行了，看截图：

下载地址我就不贴了，文件名字是“tangibleT4EditorPlusModellingToolsSetup.msi”，相信有了Google和文件的名字找到官方网站的主页和下载地址对你已经不是问题了，如果从VS扩展管理器安装的话，名字是（推荐了2个）：t4 editor 和visual t4。

什么？T4模板的语法太古怪！写起来太麻烦!！写起来太累！程序员对代码总是这么苛刻，好吧，满足你的苛刻要求，不过要下次才能向你介绍了：

下次向你介绍的基于Net的模板解析引擎名字是：Razor

调用示例：

http://www.codeplex.com/上有个项目，名字是：RazorEngine 地址：http://razorengine.codeplex.com/

Razor的语法预览：

Razor语法详细介绍：http://weblogs.asp.net/scottgu/archive/2010/07/02/introducing-razor.aspx