Razor - 模板引擎 / 代码生成 - RazorEngine

创建时间:
2015-03-30 20:45
最近更新:
2018-09-21 12:58

Brief

Open source templating engine based on Microsoft's Razor parsing engine.

Authors

  • Matthew Abbott
  • Ben Dornis
  • Matthias Dittrich

Official Website

GitHub

CodePlex - obsolete

NuGet

Install-Package RazorEngine
Install-Package RazorEngine -Version 3.6.4
https://www.nuget.org/packages/RazorEngine/ - latest: RazorEngine 3.6.4, Friday, March 27 2015

Stack Overflow

API Reference

  • AddTemplate(): Adds a given template to the ITemplateManager as dynamic template.
  • GetKey(): Gets a given key from the ITemplateManager implementation. See ITemplateManager.GetKey.
  • IsTemplateCached(): Checks if a given template is already cached in the RazorEngine.Templating.ICachingProvider.
  • Compile(): Compiles the specified template and caches it.
  • Run(): Runs the given cached template.
  • RunCompile(): Runs the given cached template. When the cache does not contain the template it will be compiled and cached beforehand. Note: 2017-05-08 猜测此方法内封装了 IsTemplateCached()Compile()Run(),因此实际应用中 无需使用这 3 个被封装的方法、只需使用此方法。
  • Create: Creates a new IRazorEngineService instance.
  • Create: Creates a new IRazorEngineService instance with the given configuration.

RazorEngine 的原理 - 官方解释

There is often a confusion about where Razor sits in this set of technologies. Essentially Razor is the parsing framework that does the work to take your text template and convert it into a compilable class. In terms of MVC and WebPages, they both utilise this parsing engine to convert text templates (view/page files) into executable classes (views/pages). Often we are asked questions such as "Where is @Html, @Url", etc. These are not features provided by Razor itself, but implementation details of the MVC and WebPages frameworks.

RazorEngine is another consumer framework of the Razor parser. We wrap up the instantiation of the Razor parser and provide a common framework for using runtime template processing.

-- Razor vs. MVC vs. WebPages vs. RazorEngine

安装记录

总结

以下两次安装,均安装了 System.Web.Razor.dll & RazorEngine.dll 两个 DLL。

2016-07-31 - Installed into Net451Console via NuGet

------- 正在安装...RazorEngine 3.9.0 -------
正在尝试解析依赖项“Microsoft.AspNet.Razor (≥ 3.0.0)”。
正在安装“Microsoft.AspNet.Razor 3.0.0”。
已将文件“System.Web.Razor.dll”添加到文件夹“Microsoft.AspNet.Razor.3.0.0\lib\net45”。
已将文件“System.Web.Razor.xml”添加到文件夹“Microsoft.AspNet.Razor.3.0.0\lib\net45”。
已将文件“Microsoft.AspNet.Razor.3.0.0.nuspec”添加到文件夹“Microsoft.AspNet.Razor.3.0.0”。
已将文件“Microsoft.AspNet.Razor.3.0.0.nupkg”添加到文件夹“Microsoft.AspNet.Razor.3.0.0”。
已成功安装“Microsoft.AspNet.Razor 3.0.0”。
正在安装“RazorEngine 3.9.0”。
已将文件“RazorEngine.dll”添加到文件夹“RazorEngine.3.9.0\lib\net40”。
已将文件“RazorEngine.xml”添加到文件夹“RazorEngine.3.9.0\lib\net40”。
已将文件“RazorEngine.dll”添加到文件夹“RazorEngine.3.9.0\lib\net45”。
已将文件“RazorEngine.xml”添加到文件夹“RazorEngine.3.9.0\lib\net45”。
已将文件“LICENSE.md”添加到文件夹“RazorEngine.3.9.0”。
已将文件“RazorEngine.3.9.0.nuspec”添加到文件夹“RazorEngine.3.9.0”。
已将文件“RazorEngine.3.9.0.nupkg”添加到文件夹“RazorEngine.3.9.0”。
已成功安装“RazorEngine 3.9.0”。
正在将“Microsoft.AspNet.Razor 3.0.0”添加到 Console。
已将引用“System.Web.Razor”添加到项目“Console”
已添加文件“packages.config”。
已将文件“packages.config”添加到项目“Console”
已成功将“Microsoft.AspNet.Razor 3.0.0”添加到 Console。
正在将“RazorEngine 3.9.0”添加到 Console。
已将引用“RazorEngine”添加到项目“Console”
已添加文件“packages.config”。
已成功将“RazorEngine 3.9.0”添加到 Console。
==============================

2018-02-02 - Installed into project TonyLibrary via NuGet

入口: Visual Studio 2013 - 解决方案资源管理器 - 项目 TonyLibrary 右键菜单 "管理 NuGet 程序包" - 联机 - 全部 - 搜索 razorengine - 安装 RazorEngine

------- 正在安装...RazorEngine 3.10.0 -------
正在尝试解析依赖项“Microsoft.AspNet.Razor (= 2.0.30506)”。
正在安装“Microsoft.AspNet.Razor 2.0.30506.0”。
已将文件“System.Web.Razor.dll”添加到文件夹“Microsoft.AspNet.Razor.2.0.30506.0\lib\net40”。
已将文件“System.Web.Razor.xml”添加到文件夹“Microsoft.AspNet.Razor.2.0.30506.0\lib\net40”。
已将文件“Microsoft.AspNet.Razor.2.0.30506.0.nuspec”添加到文件夹“Microsoft.AspNet.Razor.2.0.30506.0”。
已将文件“Microsoft.AspNet.Razor.2.0.30506.0.nupkg”添加到文件夹“Microsoft.AspNet.Razor.2.0.30506.0”。
已成功安装“Microsoft.AspNet.Razor 2.0.30506.0”。
正在安装“RazorEngine 3.10.0”。
已将文件“RazorEngine.dll”添加到文件夹“RazorEngine.3.10.0\lib\net40”。
已将文件“RazorEngine.xml”添加到文件夹“RazorEngine.3.10.0\lib\net40”。
已将文件“RazorEngine.dll”添加到文件夹“RazorEngine.3.10.0\lib\net45”。
已将文件“RazorEngine.xml”添加到文件夹“RazorEngine.3.10.0\lib\net45”。
已将文件“LICENSE.md”添加到文件夹“RazorEngine.3.10.0”。
已将文件“RazorEngine.3.10.0.nuspec”添加到文件夹“RazorEngine.3.10.0”。
已将文件“RazorEngine.3.10.0.nupkg”添加到文件夹“RazorEngine.3.10.0”。
已成功安装“RazorEngine 3.10.0”。
正在将“Microsoft.AspNet.Razor 2.0.30506.0”添加到 TonyLibrary。
已将引用“System.Web.Razor”添加到项目“TonyLibrary”
已添加文件“packages.config”。
已成功将“Microsoft.AspNet.Razor 2.0.30506.0”添加到 TonyLibrary。
正在将“RazorEngine 3.10.0”添加到 TonyLibrary。
已将引用“RazorEngine”添加到项目“TonyLibrary”
已添加文件“packages.config”。
已成功将“RazorEngine 3.10.0”添加到 TonyLibrary。
==============================

Supported Syntax (默认实现支持的语法)

You can access several things when you use the default TemplateBase<> implementation:
* @using Custom.Namespace (see also the quick intro and assembly resolvers for custom references)
* @model ModelType
* @inherits HtmlSupportTemplateBase<ModelType> (see below)
* Set a layout (and @RenderBody() within the layout template): @{ Layout = "layout.cshtml"; }
* @Include("templateName", model = null, modelType = null) to include another template.
* Accessing the ViewBag: <h1>@ViewBag.Title</h1>
* Sections (@DefineSection, @RenderSection and @IsSectionDefined)

-- http://antaris.github.io/RazorEngine/TemplateBasics.html#Supported-syntax

测试记录 - can't cleanup temp files (不能清除临时文件)

TonyRemark:

  • 2017-05-08: Everything 搜索 RazorEngine_ 是定位 临时文件 的好办法。
  • 2018-02-13: CodeGen 项目中 RazorEngine 产生的 临时文件 在单元测试方法执行完毕后 自动清除了。

2015-10-19 Tony 在 .NET4.51 Console Application 中单步执行以下代码时弹出命令行窗口显示以下信息:

代码:

using RazorEngine;
using RazorEngine.Templating;

namespace Net451ConsoleApplication
{
    class Program
    {
        static void Main(string[] args)
        {
            // using RazorEngine.Templating; // Dont forget to include this.
            string template = "Hello @Model.Name, welcome to RazorEngine!";
            var result = Engine.Razor.RunCompile(template, "templateKey", null, new { Name = "World" });
        }
    }
}

信息:

RazorEngine: We can't cleanup temp files if you use RazorEngine on the default Appdomain.
Create a new AppDomain and use RazorEngine from there.
Read the quickstart or https://github.com/Antaris/RazorEngine/issues/244 for details!
You can ignore this and all following 'Please clean ... manually' messages if you are using DisableTempFileLocking, which is not recommended.
Please clean 'C:\Users\User0\AppData\Local\Temp\RazorEngine_********.***' manually!

每次单步执行 RazorEngine.Engine.Razor.RunCompile() 后,都会生成 1 个目录及该目录中的 6 个文件,该目录及其中的全部文件的名称都是随机的,例如:

  1. "C:\Users\User0\AppData\Local\Temp\RazorEngine_pv3sxecv.dyv\CompiledRazorTemplates.Dynamic.RazorEngine_290440367cc04e8c9d06a99a7a805d08.dll"
  2. "C:\Users\User0\AppData\Local\Temp\RazorEngine_pv3sxecv.dyv\filbbops.0.cs"
  3. "C:\Users\User0\AppData\Local\Temp\RazorEngine_pv3sxecv.dyv\filbbops.cmdline"
  4. "C:\Users\User0\AppData\Local\Temp\RazorEngine_pv3sxecv.dyv\filbbops.err"
  5. "C:\Users\User0\AppData\Local\Temp\RazorEngine_pv3sxecv.dyv\filbbops.out"
  6. "C:\Users\User0\AppData\Local\Temp\RazorEngine_pv3sxecv.dyv\filbbops.tmp"

单步执行完毕后 (Tony 理解为应用程序域已终止并释放),其它 5 个文件已自动移除,但 .dll 文件及该目录会残留。以下为 4 次单步执行后的残留:

  1. "C:\Users\User0\AppData\Local\Temp\RazorEngine_bmze52rx.ovb\CompiledRazorTemplates.Dynamic.RazorEngine_a291215db8fd497cae3e4a2bfcabe7b2.dll"
  2. "C:\Users\User0\AppData\Local\Temp\RazorEngine_tkidehx4.qay\CompiledRazorTemplates.Dynamic.RazorEngine_bd299256d8b94f64ba943c5a09014ed6.dll"
  3. "C:\Users\User0\AppData\Local\Temp\RazorEngine_a1anyws2.vvo\CompiledRazorTemplates.Dynamic.RazorEngine_f890b330f6104de19631e25ea528a6e8.dll"
  4. "C:\Users\User0\AppData\Local\Temp\RazorEngine_pv3sxecv.dyv\CompiledRazorTemplates.Dynamic.RazorEngine_290440367cc04e8c9d06a99a7a805d08.dll"

官网提供了上述问题的解决方案,2017-03-15 编写以下代码对该方案进行了测试,结论: 该方案在控制台程序中有效:

//Program.cs

using RazorEngine;
using RazorEngine.Templating;

namespace Net451Console
{
    class Program
    {
        //static void Main(string[] args)
        static int Main(string[] args)
        {
            bool isDefaultAppDomain = NewDomain.Switch();
            if(isDefaultAppDomain) {
                return 0;
            }

            #region test code:
            string template = "Hello @Model.Name, welcome to RazorEngine!";
            var result = Engine.Razor.RunCompile(template, "templateKey", null, new { Name = "World" });
            //执行上一行后创建了 "C:\Users\User0\AppData\Local\Temp\RazorEngine_tbr5ujmj.fju" 目录及其中的 6 个文件。
            var isTrue = result == "Hello World, welcome to RazorEngine!";
            #endregion test code.

            return 123;
        }
        //退出 Main() 后 "C:\Users\User0\AppData\Local\Temp\RazorEngine_tbr5ujmj.fju" 目录被删除。
    }
}
//NewDomain.cs

using System;
using System.Reflection;
using System.Security;
using System.Security.Permissions;
using System.Security.Policy;

namespace Net451Console
{
    class NewDomain
    {
        /// <summary>
        /// 如果 应用程序域 非 进程的默认应用程序域,则 不作任何处理、直接返回 false;
        /// 如果 应用程序域 是 进程的默认应用程序域,则 创建新的应用程序域、并在该域中执行当前程序集、接着卸载该域、并返回 true。
        /// </summary>
        public static bool Switch()
        {
            bool isDefaultAppDomain = AppDomain.CurrentDomain.IsDefaultAppDomain();
            if(!isDefaultAppDomain) {
                return false;
            }

            // RazorEngine cannot clean up from the default appdomain...
            Console.WriteLine("Switching to second AppDomain, for RazorEngine...");

            //2017-03-15 已测试证明以下两行代码无用:
            //AppDomainSetup adSetup = new AppDomainSetup();
            //adSetup.ApplicationBase = AppDomain.CurrentDomain.SetupInformation.ApplicationBase;
            //测试记录: 至此 adSetup.ApplicationBase 的值为 "D:\Test\Net451Console\branches\RazorEngine\Net451Console\bin\Debug\"。

            // You only need to add strongnames when your appdomain is not a full trust environment.
            AppDomain domain = AppDomain.CreateDomain(
                "MyMainDomain",
                null,
                AppDomain.CurrentDomain.SetupInformation,
                new PermissionSet(PermissionState.Unrestricted),
                new StrongName[0]
            );
            string location = Assembly.GetExecutingAssembly().Location;
            //测试记录: 至此 location 的值为 "D:\Test\Net451Console\branches\RazorEngine\Net451Console\bin\Debug\Net451Console.exe"。
            int exitCode = domain.ExecuteAssembly(location);
            //执行上一行的 domain.ExecuteAssembly() 导致重新执行 Main(),届时 isDefaultAppDomain 为 false,将跳过本方法主体转而执行 Mian() 中的剩余代码,Main() 的返回值将成为上一行的返回值并赋给 exitCode,接着执行下 2 行代码,最后退出本方法。
            // Note that you need to Unload the domain to trigger cleanup.
            // RazorEngine will cleanup.
            AppDomain.Unload(domain);
            //执行上一行后 "C:\Users\User0\AppData\Local\Temp\RazorEngine_tbr5ujmj.fju" 目录中的 6 个文件仅剩下 1 个 .dll 文件。
            return true;
        }
    }
}

测试记录 - 以上方案仅在控制台程序中有效、在 ASP.NET MVC 中无效

  1. 在 ASP.NET MVC 中 AppDomain.CurrentDomain.IsDefaultAppDomain() 总是返回 false
  2. 执行 Assembly.GetExecutingAssembly().Location 返回 C:\Users\User0\AppData\Local\Temp\Temporary ASP.NET Files\root\b54c3416\14425600\assembly\dl3\57a31749\d172b5e9_d29fd201\Net451MvcNoAuth.dll,接着执行下一行 domain.ExecuteAssembly(location) 报错 异常详细信息: System.MissingMethodException: 未在程序集“Net451MvcNoAuth, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null”中找到入口点。

测试记录 - Quick Start

以下测试代码整理自 http://antaris.github.io/RazorEngine/index.html#Quickstart:

using RazorEngine;
using RazorEngine.Templating; // 此行必须,否则扩展方法不可用。

namespace Net451Console
{
    class Program
    {
        //static void Main(string[] args)
        static int Main(string[] args)
        {
            bool isDefaultAppDomain = NewDomain.Switch();
            if(isDefaultAppDomain) {
                return 0;
            }

            #region test code:
            //All you need to do is use the static Engine class (the Engine.Razor instance) in the 'RazorEngine' namespace:
            string template = "Hello @Model.Name, welcome to RazorEngine!";
            string key = "templateKey";
            var result0 = Engine.Razor.RunCompile(template, key, null, new { Name = "World" });

            //The "templateKey" must be unique and after running the above example you can re-run the cached template with this key.
            var result1 = Engine.Razor.Run(key, null, new { Name = "Max" });

            //The null parameter is the modelType and null in this case means we use dynamic as the type of the model. You can use a static model as well by providing a type object.
            var result2 = Engine.Razor.RunCompile(key, typeof(Person), new Person { Name = "Max" });
            //Note that we now re-compile the model with a different type. When you do not run the same template a lot of times (like several 1000 times), compiling uses the most time. So the benefit you get from a static type will most likely not compensate the additional compile time. Therefore you should either stick to one type for a template (best of both worlds) or just use (the slower) dynamic (null). You can specify the modelType of a template with the @model directive. When you do this the modelType parameter is ignored, but you should use the same type instance (or null) on every call to prevent unnecessary re-compilations because of type mismatches in the caching layer.
            #endregion test code.

            return 123;
        }
    }
    public class Person
    {
        public string Name { get; set; }
    }
}

测试记录 - Configuration

以下测试代码整理自 http://antaris.github.io/RazorEngine/index.html#Configuration:

using RazorEngine;
using RazorEngine.Configuration;
using RazorEngine.Templating;
using RazorEngine.Text;

namespace Net451Console
{
    class Program
    {
        //static void Main(string[] args)
        static int Main(string[] args)
        {
            bool isDefaultAppDomain = NewDomain.Switch();
            if(isDefaultAppDomain) {
                return 0;
            }

            #region test code:
            //You can configure RazorEngine with the TemplateServiceConfiguration class.
            var config = new TemplateServiceConfiguration();

            // ... configure your instance

            //General Configuration
            //By default RazorEngine is configured to encode using Html. This supports the majority of users but with some configuration changes you can also set it to encode using Raw format which is better suited for templates that generate things like javascript, php, C# and others.
            config.Language = Language.CSharp; // C# as template language.
            config.EncodedStringFactory = new RawStringFactory(); // Raw string encoding.
            //config.EncodedStringFactory = new HtmlEncodedStringFactory(); // Html encoding.

            //One thing you might want to enable is the debugging feature:
            config.Debug = true;

            IRazorEngineService service = RazorEngineService.Create(config);

            //If you want to use the static Engine class with this new configuration:
            Engine.Razor = service;

            //When Debug is true you can straight up debug into the generated code. RazorEngine also supports debugging directly into the template files (normally .cshtml files). As as you might see in the above code there is no file to debug into. To provide RazorEngine with the necessary information you need to tell where the file can be found:
            string template = "Hello @Model.Name, welcome to RazorEngine!";
            string templateFile = "d:/mytemplate.cshtml";
            // Provide a non-null file to improve debugging
            var loadedTemplateSource = new LoadedTemplateSource(template, templateFile);
            var result = Engine.Razor.RunCompile(loadedTemplateSource, "templateKey", null, new { Name = "World" });
            //This time when debugging the template you will jump right into the template file.
            #endregion test code.

            return 123;
        }
    }
}

上述代码中的 d:/mytemplate.cshtml 的测试记录:

  • 该文件中的断点有效。
  • 该文件的内容与 template 的值无关。
  • 该文件的内容可为任意字符 (包括空文件)。
  • 该文件不能放在 Windows10 的 C 分区,否则会因为访问权限而报错。

测试记录 - 对比 3 种 Type 的 model 的语法

以下测试代码整理自 http://antaris.github.io/RazorEngine/TemplateBasics.html:

using RazorEngine;
using RazorEngine.Templating;
using System.Dynamic;

namespace Net451Console
{
    class Program
    {
        //static void Main(string[] args)
        static int Main(string[] args)
        {
            bool isDefaultAppDomain = NewDomain.Switch();
            if(isDefaultAppDomain) {
                return 0;
            }

            #region test code:
            string template = "<div>Hello @Model.Name</div>";

            var model0 = new Person { Name = "Matt" };  //statically type
            var model1 = new { Name = "Matt" };         //anonymous type
            dynamic model2 = new ExpandoObject();       //dynamic type
            model2.Name = "Matt";                       //dynamic type

            string result0 = Engine.Razor.RunCompile(template, "key0", typeof(Person), model0);  //statically type
            string result1 = Engine.Razor.RunCompile(template, "key1", null, model1);            //anonymous type
            string result2 = Engine.Razor.RunCompile(template, "key2", null, (object)model2);    //dynamic type
            //执行至此 result0-2 均为 "<div>Hello Matt</div>"。
            #endregion test code.

            return 123;
        }
    }

    public class Person
    {
        public string Name { get; set; }
    }
}

测试记录 - 扩展模板语法

以下测试代码整理自 http://antaris.github.io/RazorEngine/TemplateBasics.html#Extending-the-template-Syntax:

using RazorEngine.Configuration;
using RazorEngine.Templating;
using RazorEngine.Text;
using System;

namespace Net451Console
{
    class Program
    {
        //static void Main(string[] args)
        static int Main(string[] args)
        {
            bool isDefaultAppDomain = NewDomain.Switch();
            if(isDefaultAppDomain) {
                return 0;
            }

            #region test code:
            var config = new TemplateServiceConfiguration();
            // You can use the @inherits directive instead (this is the fallback if no @inherits is found).
            config.BaseTemplateType = typeof(HtmlSupportTemplateBase<>);
            using(var service = RazorEngineService.Create(config)) {
                string template0 = "@Model.Data";
                string template1 = "@Html.Raw(Model.Data)";
                string data = "My raw double quotes appears here \"hello!\"";
                var model = new { Data = data };

                string result0 = service.RunCompile(template0, "htmlRawTemplate0", null, model);
                string result1 = service.RunCompile(template1, "htmlRawTemplate1", null, model);

                if(result0 == "My raw double quotes appears here "hello!"") {
                    Console.WriteLine("* 默认行为: 引号被 HTML 实体编码。");
                }
                if(result1 == data) {
                    Console.WriteLine("* @Html.Raw() 原样输出。");
                }
            }
            #endregion test code.

            return 123;
        }
    }

    public class MyHtmlHelper
    {
        public IEncodedString Raw(string rawString)
        {
            return new RawString(rawString);
        }
    }

    public abstract class HtmlSupportTemplateBase<T> : TemplateBase<T>
    {
        //public MyClassImplementingTemplateBase()
        public HtmlSupportTemplateBase()
        {
            Html = new MyHtmlHelper();
        }
        public MyHtmlHelper Html { get; set; }
    }
}

测试记录 - Layout

以下测试代码整理自 http://antaris.github.io/RazorEngine/LayoutAndPartial.html#Layout-template:

using RazorEngine;
using RazorEngine.Templating;

namespace Net451Console
{
    class Program
    {
        //static void Main(string[] args)
        static int Main(string[] args)
        {
            bool isDefaultAppDomain = NewDomain.Switch();
            if(isDefaultAppDomain) {
                return 0;
            }

            #region test code:
            IRazorEngineService service = Engine.Razor;
            service.AddTemplate("Layout0", @"<html>@RenderBody()</html>");
            service.AddTemplate("Layout1", @"<body>@RenderBody()</body>@{ Layout = ""Layout0""; }");
            service.AddTemplate("Layout2", @"<div> @RenderBody()</div> @{ Layout = ""Layout1""; }");
            service.AddTemplate("templet", @"<h1>  content in h1</h1>  @{ Layout = ""Layout2""; }");
            service.Compile("templet");
            string result = service.Run("templet");
            bool isTrue = result == "<html><body><div> <h1>  content in h1</h1>  </div> </body></html>";
            #endregion test code.

            return 123;
        }
    }
}

测试记录 - Partial (@Include())

以下测试代码整理自 http://antaris.github.io/RazorEngine/LayoutAndPartial.html#Partial-templates:

using RazorEngine;
using RazorEngine.Templating;

namespace Net451Console
{
    class Program
    {
        //static void Main(string[] args)
        static int Main(string[] args)
        {
            bool isDefaultAppDomain = NewDomain.Switch();
            if(isDefaultAppDomain) {
                return 0;
            }

            #region test code:
            var service = Engine.Razor;
            service.AddTemplate("part", @"my template");
            // If you leave the second and third parameters out the current model will be used.
            // If you leave the third we assume the template can be used for multiple types and use "dynamic".
            // If the second parameter is null (which is default) the third parameter is ignored.
            // To workaround in the case you want to specify type "dynamic" without specifying a model use Include("p", new object(), null)
            service.AddTemplate("template", @"<h1>@Include(""part"", @Model.SubModel, typeof(Net451Console.SubModel))</h1>");
            service.Compile("template", typeof(MyModel));
            service.Compile("part", typeof(SubModel));
            var result = service.Run(
                "template",
                typeof(MyModel),
                new MyModel {
                    ModelProperty = "model",
                    SubModel = new SubModel { SubModelProperty = "submodel" }
                }
            );
            bool isTrue = result == "<h1>my template</h1>";
            #endregion test code.

            return 123;
        }
    }

    public class SubModel
    {
        public string SubModelProperty { get; set; }
    }

    public class MyModel
    {
        public string ModelProperty { get; set; }
        public SubModel SubModel { get; set; }
    }
}

测试发现很多参数都可省略:

using RazorEngine;
using RazorEngine.Templating;

namespace Net451Console
{
    class Program
    {
        //static void Main(string[] args)
        static int Main(string[] args)
        {
            bool isDefaultAppDomain = NewDomain.Switch();
            if(isDefaultAppDomain) {
                return 0;
            }

            #region test code:
            var service = Engine.Razor;
            service.AddTemplate("part", @"Text in the part.");
            service.AddTemplate("template", @"<h1>@Include(""part"")</h1>");
            service.Compile("template");
            service.Compile("part");
            var result = service.Run("template");
            bool isTrue = result == "<h1>Text in the part.</h1>";
            #endregion test code.

            return 123;
        }
    }
}

测试记录 - @ 转义失败、原因不明、已绕过

测试环境

2018-09-21
VM0
Windows 10
Visual Studio 2013
CodeGen

测试过程

模板完整内容:

<input type="hidden" id="Id" name="Id" value="@@SnowflakeApi.ToNSystem(Model.Id)" />

用上述模板生成时,RazorEngine 抛出以下异常:

RazorEngine.Templating.TemplateParsingException: (11:55) - “@”在代码块开头无效。只有标识符、关键字、注释、“(”和“{”才有效。

尝试对 <@ 进行各种转义,均不成功,最后包装在 @Raw() 内,绕过了此问题:

@Raw(@"<input type=""hidden"" id=""Id"" name=""Id"" value=""@SnowflakeApi.ToNSystem(Model.Id)"" />")

以下为 希望的、最终的 输出:

<input type="hidden" id="Id" name="Id" value="@SnowflakeApi.ToNSystem(Model.Id)" />

Encoding Values - @Raw()

总结

  • RazorEngine 原生支持 @Raw(),不支持 @Html.Raw(),使用前者即可。
  • 本文 "扩展模板语法" 小节 介绍了 使 RazorEngine 支持 @Html.Raw() 的方案。

Example

以下测试代码整理自 http://antaris.github.io/RazorEngine/Encoding.html:

using RazorEngine;
using RazorEngine.Templating;

namespace Net451Console
{
    class Program
    {
        //static void Main(string[] args)
        static int Main(string[] args)
        {
            bool isDefaultAppDomain = NewDomain.Switch();
            if(isDefaultAppDomain) {
                return 0;
            }

            #region test code:
            //By default RazorEngine is configured to encode as Html. This sometimes this presents problems were certain characters are encoded as Html but what you want is to output them as-is. To output something in raw format use the @Raw() built-in method as shown in the following example:
            string template0 = "@Model.Data";
            string template1 = "@Raw(Model.Data)";
            var model = new { Data = "My raw double quotes appears here \"hello!\"" };
            string result0 = Engine.Razor.RunCompile(template0, "templateKey0", null, model);
            string result1 = Engine.Razor.RunCompile(template1, "templateKey1", null, model);
            bool isTrue0 = result0 == @"My raw double quotes appears here "hello!"";
            bool isTrue1 = result1 == @"My raw double quotes appears here ""hello!""";
            #endregion test code.

            return 123;
        }
    }
}

测试记录 - 不支持 @Html.Raw()

执行 string test = Engine.Razor.RunCompile(@"@Html.Raw(""asdf"")", "key", null, string.Empty); 时抛出异常 "当前上下文中不存在名称“Html”"。

RazorEngine.Razor 已废弃,请改用 Engine.Razor

#region 程序集 RazorEngine.dll, v3.9.0.0
// D:\Test\Net451Console\branches\RazorEngine\packages\RazorEngine.3.9.0\lib\net45\RazorEngine.dll
#endregion

namespace RazorEngine
{
    [Obsolete("Please use the Engine.Razor instance instead.")]
    public static class Razor {
        public static void Compile(string razorTemplate, string name);
        ...
        public static ITemplate CreateTemplate(string razorTemplate);
        ...
        public static ITemplate GetTemplate(string razorTemplate, string name);
        ...
        public static string Parse(string razorTemplate);
        ...
        public static ITemplate Resolve(string name);
        ...
        public static string Run(string name);
        ...
        public static void SetTemplateService(ITemplateService service);
    }
}

缓存

  1. How are templates in RazorEngine cached?
  2. Antaris RazorEngine How to Recompile a template using the same Key?
  3. RazorEngine Memory Usage
  4. RazorEngine IsolatedTemplateService is not preventing growth of number of loaded assemblies
  5. Use external cache provider for RazorEngine
  6. Memcached Caching Provider and Serialization Issue #278

作者说: 无法稍毁缓存

When you change and recompile templates you have a memory leak, because you cannot unload loaded assemblies (which RazorEngine compiles and loads for you in the background).

The only way to really free the memory is to reload the AppDomain or restart the process.

-- http://stackoverflow.com/questions/14369614/razorengine-un-cache-compiled-templates

某网文代码

ASP.NET MVC 解析模板生成静态页一 (RazorEngine)》 全文共两部分: 1. 基本的单数据模型模板解析; 2. 面向接口的多数据模型模板解析。该网文仅涉及到 RazorEngine 最基础的 API,未展示 Hello World 之外的功能。以下为第一部分的原始代码 (未改动、仅格式化)。第二部分核心代码与第一部分完全相同,仅增加了 TemplateView 模型解析类中间件、Repository、泛型、面向接口、Spring 依赖注入、反射赋值,所有这些增加的部分都是面向对象与设计模式的半桶水套路,无作用无意义徒增坏味道,跳过。

public class Articles
{
    public int      Id          { get; set; }
    public string   Title       { get; set; }
    public string   Content     { get; set; }
    public string   Author      { get; set; }
    public DateTime CreateDate  { get; set; }
}
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <title>@Model.Title</title>
</head>
<body>
    <h1>@Model.Title</h1>
    <p>作者:@Model.Author - 发布时间:@Model.CreateDate</p>
    <p>@Raw(Model.Content)</p>
</body>
</html>
/// <summary>
/// 获取页面的Html代码
/// </summary>
/// <param name="url">模板页面路径</param>
/// <param name="encoding">页面编码</param>
public string GetHtml(string url, System.Text.Encoding encoding)
{
    byte[] buf = new WebClient().DownloadData(url);
    if(encoding != null){
        return encoding.GetString(buf);
    }
    string html = System.Text.Encoding.UTF8.GetString(buf);
    encoding = GetEncoding(html);
    if(encoding == null || encoding == System.Text.Encoding.UTF8){
        return html;
    }
    return encoding.GetString(buf);
}

/// <summary>
/// 获取页面的编码
/// </summary>
/// <param name="html">Html源码</param>
public System.Text.Encoding GetEncoding(string html)
{
    string pattern = @"(?i)/bcharset=(?<charset>[-a-zA-Z_0-9]+)";
    string charset = Regex.Match(html, pattern).Groups["charset"].Value;
    try{
        return System.Text.Encoding.GetEncoding(charset);
    }
    catch(ArgumentException){
        return null;
    }
}
 /// <summary>
/// 创建静态文件
/// </summary>
/// <param name="result">Html代码</param>
/// <param name="createpath">生成路径</param>
public bool CreateFileHtmlByTemp(string result, string createpath)
{
    if(!string.IsNullOrEmpty(result)) {
        if(string.IsNullOrEmpty(createpath)) {
            createpath = "/default.html";
        }
        string filepath = createpath.Substring(createpath.LastIndexOf(@"/"));
        createpath = createpath.Substring(0, createpath.LastIndexOf(@"/"));
        if (!Directory.Exists(createpath)) {
            Directory.CreateDirectory(createpath);
        }
        createpath = createpath + filepath;
        try {
            FileStream fs2 = new FileStream(createpath, FileMode.Create);
            StreamWriter sw = new StreamWriter(fs2, new System.Text.UTF8Encoding(false));//去除UTF-8 BOM
            sw.Write(result);
            sw.Close();
            fs2.Close();
            fs2.Dispose();
            return true;
        }
        catch { return false; }
    }
    return false;
}
/// <summary>
/// 解析模板生成静态页
/// </summary>
/// <param name="temppath">模板地址</param>
/// <param name="path">静态页地址</param>
/// <param name="t">数据模型</param>
public bool CreateStaticPage(string temppath, string path, Articles t)
{
    try {
        //获取模板Html
        string TemplateContent = GetHtml(temppath, System.Text.Encoding.UTF8);
        //解析模板生成静态页Html代码
        string result = Razor.Parse(TemplateContent, t);
        //创建静态文件
        return CreateFileHtmlByTemp(result, path);
    }
    catch (Exception e) {
        throw e;
    }
}

安全 - 只可能内部使用、不能让用户定义模板

  1. How dangerous is it to let users specify RazorEngine templates?
  2. RazorEngine for user templates - Security?
  3. ASP.NET Razor templates editable by users - remove @ for security reasons

Resource - Hello World

  1. 利用 RazorEngine 打造简单的泛用代码生成器 - 基于 ExpandoObject
  2. 利用 RazorEngine 更加直观的格式化字符串 - Note: 反射取值的 Regex.Replace() 有实用价值

Resource - Advanced

  1. 第四篇 基于 .NET 搭建热插拔式 Web 框架 (RazorEngine 实现)
  2. 用 Razor 語法寫範本 - RazorEngine 組件介紹
  3. 让 Windows2003 Server NET4.0 Frameworks 可以上使用 RazorEngine 程序集
  4. C# 模板引擎 RazorEngine 3.7 的简单使用
  5. RazorEngine 在非 MVC 下的使用,以及使用自定义模板
  6. .NET MVC Razor 也可以这样玩
  7. 在 ASP.NET WebAPI 中使用 Razor
  8. DIY RazorEngine 的程序集生成方式
  9. 抛弃 NVelocity,来玩玩 Razor - 文件嵌套、@Include()
  10. Razor Engine,实现代码生成器的又一件利器
  11. Razor 模板引擎使用 - 缓存源码?
  12. C# & SQlite 代码生成器 - 非 HTML 模板示例
  13. Razor 模板引擎 - 缓存测试 & 封装
  14. 使用 Razor 模板构建应用注意的细节

base or advanced

  1. 用 Razor 語法寫範本 - RazorEngine 組件介紹
  2. 用 Razor 語法寫範本 - RazorEngine 組件介紹
  3. 让 Windows2003 Server NET4.0 Frameworks 可以上使用 RazorEngine 程序集
  4. RazorEngine - @Html.LabelFor OK, @Html.EditorFor "not implemented exception" on Execute()
  5. Dynamic CSS using Razor Engine
  6. Razor Templating Engine
  7. 代码生成就用 Razor 模板
  8. C# 模板引擎 RazorEngine 3.7 的扩展 — 引入外部文件
  9. C# 模板引擎 RazorEngine 3.7 的扩展 — 引用布局页
  10. 在非网页程序里使用 Razor 模板引擎
  11. ASP.NET MVC 解析模板生成静态页一 (RazorEngine) - 详见本文 "某网文代码" 小节
  12. DIY RazorEngine 的程序集生成方式