Microsoft’s new Razor HTML Rendering Engine that
is currently shipping with ASP.NET MVC previews can be used outside of ASP.NET. Razor
is an alternative view engine that can be used instead of
the ASP.NET Page engine that currently works with ASP.NET WebForms
and MVC. It provides a simpler
and more readable markup syntax
and is much more light weight
in terms of functionality than
the full blown WebForms Page engine, focusing only on features that are more along
the lines of a pure view engine (or classic ASP!) with focus on expression
and code rendering rather than a complex control/object model. Like
the Page engine though,
the parser understands .NET code syntax which can be embedded into templates,
and behind
the scenes
the engine compiles markup
and script code into an executing piece of .NET code
in an assembly. Although it ships as part of
the ASP.NET MVC
and WebMatrix
the Razor Engine itself
is not directly dependent on ASP.NET or IIS or HTTP
in any way.
And although there are some markup
and rendering features that are optimized for HTML based output generation, Razor
is essentially a free standing template engine.
And what’s really nice
is that unlike
the ASP.NET Runtime, Razor
is fairly easy to host inside of your own non-Web applications to provide templating functionality. Templating
in non-Web Applications? Yes please! So why might you host a template engine
in your non-Web application? Template rendering
is useful
in many places
and I have a number of applications that make heavy use of it. One of my applications – West Wind Html Help Builder - exclusively uses template based rendering to merge user supplied help text content into customizable
and executable HTML markup templates that provide HTML output for CHM style HTML Help. This
is an older product
and it’s not actually using .NET at
the moment –
and this
is one reason I’m looking at Razor for script hosting at
the moment. For a few .NET applications though I’ve actually used
the ASP.NET Runtime hosting to provide templating
and mail merge style functionality
and while that works reasonably well it’s a very heavy handed approach. It’s very resource intensive
and has potential issues with versioning
in various different versions of .NET.
The generic implementation I created
in the article above requires a lot of fix up to mimic an HTTP request
in a non-HTTP environment
and there are a lot of little things that have to happen to ensure that
the ASP.NET runtime works properly most of it having nothing to do with
the templating aspect but just satisfying ASP.NET’s requirements.
The Razor Engine on
the other hand
is fairly light weight
and completely decoupled from
the ASP.NET runtime
and the HTTP processing. Rather it’s a pure template engine whose sole purpose
is to render text templates. Hosting this engine
in your own applications can be accomplished with a reasonable amount of code (actually just a few lines with
the tools I’m about to describe)
and without having to fake HTTP requests. It’s also much lighter on resource usage
and you can easily attach custom properties to your base template implementation to easily pass context from
the parent application into templates all of which was rather complicated with ASP.NET runtime hosting. Installing
the Razor Template Engine You can get Razor as part of
the MVC 3 (RC
and later) or Web Matrix. Both are available as downloadable components from
the Web Platform Installer Version 3.0 (!important – V2 doesn’t show these components). If you already have that version of
the WPI installed just fire it up. You can get
the latest version of
the Web Platform Installer from here: http://www.microsoft.com/web/gallery/install.aspx Once
the platform Installer 3.0
is installed install either MVC 3 or ASP.NET Web Pages. Once installed you’ll find a System.Web.Razor assembly
in C:\Program Files\Microsoft ASP.NET\ASP.NET Web Pages\v1.0\Assemblies\System.Web.Razor.dll which you can add as a reference to your project. Creating a Wrapper
The basic Razor Hosting API
is pretty simple
and you can host Razor with a (large-ish) handful of lines of code. I’ll show
the basics of it later
in this article. However, if you want to customize
the rendering
and handle assembly
and namespace includes for
the markup as well as deal with text
and file inputs as well as forcing Razor to run
in a separate AppDomain so you can unload
the code-generated assemblies
and deal with assembly caching for re-used templates little more work
is required to create something that
is more easily reusable. For this reason I created a Razor Hosting wrapper project that combines a bunch of this functionality into an easy to use hosting class, a hosting factory that can load
the engine
in a separate AppDomain
and a couple of hosting containers that provided folder based
and string based caching for templates for an easily embeddable
and reusable engine with easy to use syntax. If you just want
the code
and play with
the samples
and source go grab
the latest code from
the Subversion Repository at: http://www.west-wind.com:8080/svn/articles/trunk/RazorHosting/ or a snapshot from: http://www.west-wind.com/files/tools/RazorHosting.zip Getting Started Before I get into how hosting with Razor works, let’s take a look at how you can get up
and running quickly with
the wrapper classes provided. It only takes a few lines of code.
The easiest way to use these Razor Hosting Wrappers
is to use one of
the two HostContainers provided. One
is for hosting Razor scripts
in a directory
and rendering them as relative paths from these script files on disk.
The other HostContainer serves razor scripts from
string templates… Let’s start with a very simple template that displays some simple expressions, some code blocks
and demonstrates rendering some data from contextual data that you pass to
the template
in the form of a ‘context’. Here’s a simple Razor template: @using System.Reflection
Hello @Context.FirstName! Your entry was entered on: @Context.Entered
@{
// Code block: Update
the host Windows Form passed
in through
the context
Context.WinForm.Text = "Hello World from Razor at " + DateTime.Now.ToString();
}
AppDomain Id:
@AppDomain.CurrentDomain.FriendlyName
Assembly:
@Assembly.GetExecutingAssembly().FullName
Code based output:
@{
// Write output with Response object from code
string output =
string.Empty;
for (int i = 0; i < 10; i++)
{
output += i.ToString() + " ";
}
Response.Write(output);
}
Pretty easy to see what’s going on here.
The only unusual thing
in this code
is the Context object which
is an arbitrary object I’m passing from
the host to
the template by way of
the template base class. I’m also displaying
the current AppDomain
and the executing Assembly name so you can see how compiling
and running a template actually loads up new assemblies. Also note that as part of my context I’m passing a reference to
the current Windows Form down to
the template
and changing
the title from within
the script. It’s a silly example, but it demonstrates two-way communication
between host
and template
and back which can be very powerful.
The easiest way to quickly render this template
is to use
the RazorEngine<TTemplateBase> class.
The generic parameter specifies a template base class type that
is used by Razor internally to generate
the class it generates from a template.
The default implementation provided
in my RazorHosting wrapper
is RazorTemplateBase.
Here’s a simple one that renders from a
string and outputs a string:
var engine = new RazorEngine<RazorTemplateBase>();
// we can pass any object as context - here create a custom context
var context = new CustomContext()
{
WinForm = this, FirstName = "Rick", Entered = DateTime.Now.AddDays(-10)
};
string output = engine.RenderTemplate(this.txtSource.Text new string[] { "System.Windows.Forms.dll" }, context);
if (output == null)
this.txtResult.Text = "*** ERROR:\r\n" + engine.ErrorMessage;
else
this.txtResult.Text = output;
Simple enough. This code renders a template from a
string input
and returns a result back as a
string. It creates a custom context
and passes that to
the template which can then access
the Context’s properties. Note that anything passed as ‘context’ must be serializable (or MarshalByRefObject) – otherwise you get an exception when passing
the reference over AppDomain boundaries (discussed later). Passing a context
is optional, but
is a key feature
in being able to share data
between the host application
and the template. Note that we use
the Context object to access FirstName, Entered
and even
the host Windows Form object which
is used
in the template to change
the Window caption from within
the script!
In the code above all
the work happens
in the RenderTemplate method which provide a variety of overloads to read
and write to
and from strings, files
and TextReaders/Writers. Here’s another example that renders from a file input using a TextReader:
using (reader = new StreamReader("templates\\simple.csHtml", true))
{
result = host.RenderTemplate(reader, new string[] { "System.Windows.Forms.dll" }, this.CustomContext);
}
RenderTemplate()
is fairly high level
and it handles loading of
the runtime, compiling into an assembly
and rendering of
the template. If you want more control you can use
the lower level methods to control each step of
the way which
is important for
the HostContainers I’ll discuss later. Basically for those scenarios you want to separate out loading of
the engine, compiling into an assembly
and then rendering
the template from
the assembly. Why? So we can keep assemblies cached.
In the code above a new assembly
is created for each template rendered which
is inefficient
and uses up resources. Depending on
the size of your templates
and how often you fire them you can chew through memory very quickly.
This slighter lower level approach
is only a couple of extra steps:
// we can pass any object as context - here create a custom context
var context = new CustomContext()
{
WinForm = this, FirstName = "Rick",
Entered = DateTime.Now.AddDays(-10)
};
var engine = new RazorEngine<RazorTemplateBase>();
string assId = null;
using (StringReader reader = new StringReader(this.txtSource.Text))
{
assId = engine.ParseAndCompileTemplate(new string[] { "System.Windows.Forms.dll" }, reader);
}
string output = engine.RenderTemplateFromAssembly(assId, context);
if (output == null)
this.txtResult.Text = "*** ERROR:\r\n" + engine.ErrorMessage;
else
this.txtResult.Text = output;
The difference here
is that you can capture
the assembly – or rather an Id to it –
and potentially hold on to it to render again later assuming
the template hasn’t changed.
The HostContainers take advantage of this feature to cache
the assemblies based on certain criteria like a filename
and file time step or a
string hash that if not change indicate that an assembly can be reused.
Note that ParseAndCompileTemplate returns an assembly Id rather than
the assembly itself. This
is done so that that
the assembly always stays
in the host’s AppDomain
and is not passed across AppDomain boundaries which would cause load failures. We’ll talk more about this
in a minute but for now just realize that assemblies references are stored
in a list
and are accessible by this ID to allow locating
and re-executing of
the assembly based on that id. Reuse of
the assembly avoids recompilation overhead
and creation of yet another assembly that loads into
the current AppDomain.
You can play around with several different versions of
the above code
in the main sample form:
Using Hosting Containers for more Control
and Caching
The above examples simply render templates into assemblies each
and every time they are executed. While this works
and is even reasonably fast, it’s not terribly efficient. If you render templates more than once it would be nice if you could cache
the generated assemblies for example to avoid re-compiling
and creating of a new assembly each time. Additionally it would be nice to load template assemblies into a separate AppDomain optionally to be able to be able to unload assembli es
and also to protect your host application from scripting attacks with malicious template code. Hosting containers provide also provide a wrapper around
the RazorEngine<T> instance, a factory (which allows creation
in separate AppDomains)
and an easy way to start
and stop
the container ‘runtime’.
The Razor Hosting samples provide two hosting containers: RazorFolderHostContainer
and StringHostContainer.
The folder host provides a simple runtime environment for a folder structure similar
in the way that
the ASP.NET runtime handles a virtual directory as it’s ‘application' root. Templates are loaded from disk
in relative paths
and the resulting assemblies are cached unless
the template on disk
is changed.
The string host also caches templates based on
string hashes – if
the same
string is passed a second time a cached version of
the assembly
is used.
Here’s how HostContainers work. I’ll use
the FolderHostContainer because it’s likely
the most common way you’d use templates – from disk based templates that can be easily edited
and maintained on disk.
The first step
is to create an instance of it
and keep it around somewhere (in
the example it’s attached as a property to
the Form):
RazorFolderHostContainer Host = new RazorFolderHostContainer();
public RazorFolderHostForm()
{
InitializeComponent();
//
The base path for templates - templates are rendered with relative paths
// based on this path.
Host.TemplatePath = Path.Combine(Environment.CurrentDirectory, TemplateBaseFolder);
// Add any assemblies you want reference
in your templates
Host.ReferencedAssemblies.Add("System.Windows.Forms.dll");
// Start up
the host container
Host.Start();
}
Next anytime you want to render a template you can use simple code like this:
private void RenderTemplate(string fileName)
{
// Pass
the template path via
the Context
var relativePath = Utilities.GetRelativePath(fileName, Host.TemplatePath);
if (!Host.RenderTemplate(relativePath, this.Context, Host.RenderingOutputFile))
{
MessageBox.Show("Error: " + Host.ErrorMessage);
return;
}
this.webBrowser1.Navigate("file://" + Host.RenderingOutputFile);
}
You can also render
the output to a
string instead of to a file:
string result = Host.RenderTemplateToString(relativePath,context);
Finally if you want to release
the engine
and shut down
the hosting AppDomain you can simply do:
Host.Stop();
Stopping
the AppDomain
and restarting it (ie. calling Stop(); followed by Start())
is also a nice way to release all resources
in the AppDomain.
The FolderBased domain also supports partial Rendering based on root path based relative paths with
the same caching characteristics as
the main templates. From within a template you can call out to a partial like this:
@RenderPartial(@"partials\PartialRendering.cshtml", Context)
where partials\PartialRendering.cshtml
is a relative to
the template root folder.
The folder host example lets you load up templates from disk
and display
the result
in a Web Browser control which demonstrates using Razor HTML output from templates that contain HTML syntax which happens to me my target scenario for Html Help Builder.
The Razor Engine Wrapper Project
The project I created to wrap Razor hosting has a fair bit of code
and a number of classes associated with it. Most of
the components are internally used
and as you can see using
the final RazorEngine<T>
and HostContainer classes
is pretty easy.
The classes are extensible
and I suspect developers will want to build more customized host containers for their applications. Host containers are
the key to wrapping up all functionality – Engine, BaseTemplate, AppDomain Hosting, Caching etc
in a logical piece that
is ready to be plugged into an application.
When looking at
the code there are a couple of core features provided:
Core Razor Engine Hosting
This
is the core Razor hosting which provides
the basics of loading a template, compiling it into an assembly
and executing it. This
is fairly straightforward, but without a host container that can cache assemblies based on some criteria templates are recompiled
and re-created each time which
is inefficient (although pretty fast).
The base engine wrapper implementation also supports hosting
the Razor runtime
in a separate AppDomain for security
and the ability to unload it on demand.
Host Containers
The engine hosting itself doesn’t provide any sort of ‘runtime’ service like picking up files from disk, caching assemblies
and so forth. So my implementation provides two HostContainers: RazorFolderHostContainer
and RazorStringHostContainer.
The FolderHost works off a base directory
and loads templates based on relative paths (sort of like
the ASP.NET runtime does off a virtual).
The HostContainers also deal with caching of template assemblies – for
the folder host
the file date
is tracked
and checked for updates
and unless
the template
is changed a cached assembly
is reused.
The StringHostContainer similiarily checks
string hashes to figure out whether a particular
string template was previously compiled
and executed.
The HostContainers also act as a simple startup environment
and a single reference to easily store
and reuse
in an application.
TemplateBase Classes
The template base classes are
the base classes that from which
the Razor engine generates .NET code. A template
is parsed into a class with an Execute() method
and the class
is based on this template type you can specify. RazorEngine<TBaseTemplate> can receive this type
and the HostContainers default to specific templates
in their base implementations. Template classes are customizable to allow you to create templates that provide application specific features
and interaction from
the template to your host application.
How does
the RazorEngine wrapper work?
You can browse
the source code
in the links above or
in the repository or download
the source, but I’ll highlight some key features here. Here’s part of
the RazorEngine implementation that can be used to host
the runtime
and that demonstrates
the key code required to host
the Razor runtime.
The RazorEngine class
is implemented as a generic class to reflect
the Template base class type:
public class RazorEngine<TBaseTemplateType> : MarshalByRefObject
where TBaseTemplateType : RazorTemplateBase
The generic type
is used to internally provide easier access to
the template type
and assignments on it as part of
the template processing.
The class also inherits MarshalByRefObject to allow execution over AppDomain boundaries – something that all
the classes discussed here need to do since there
is much interaction
between the host
and the template.
The first two key methods deal with creating a template assembly:
/// <summary>
/// Creates an instance of
the RazorHost with various options applied.
/// Applies basic namespace imports
and the name of
the class to generate
/// </summary>
/// <param name="generatedNamespace"></param>
/// <param name="generatedClass"></param>
/// <returns></returns>
protected RazorTemplateEngine CreateHost(string generatedNamespace,
string generatedClass)
{
Type baseClassType = typeof(TBaseTemplateType);
RazorEngineHost host = new RazorEngineHost(new CSharpRazorCodeLanguage());
host.DefaultBaseClass = baseClassType.FullName;
host.DefaultClassName = generatedClass;
host.DefaultNamespace = generatedNamespace;
host.NamespaceImports.Add("System");
host.NamespaceImports.Add("System.Text");
host.NamespaceImports.Add("System.Collections.Generic");
host.NamespaceImports.Add("System.Linq");
host.NamespaceImports.Add("System.IO");
return new RazorTemplateEngine(host);
}
/// <summary>
/// Parses
and compiles a markup template into an assembly
and returns
/// an assembly name.
The name
is an ID that can be passed to
/// ExecuteTemplateByAssembly which picks up a cached instance of
the
/// loaded assembly.
///
/// </summary>
/// <param name="namespaceOfGeneratedClass">The namespace of
the class to generate from
the template</param>
/// <param name="generatedClassName">The name of
the class to generate from
the template</param>
/// <param name="ReferencedAssemblies">Any referenced assemblies by dll name only. Assemblies must be
in execution path of host or
in GAC.</param>
/// <param name="templateSourceReader">Textreader that loads
the template</param>
/// <remarks>
///
The actual assembly isn't returned here to allow for cross-AppDomain
/// operation. If
the assembly was returned it would fail for cross-AppDomain
/// calls.
/// </remarks>
/// <returns>An assembly Id.
The Assembly
is cached
in memory
and can be used with RenderFromAssembly.</returns>
public
string ParseAndCompileTemplate(
string namespaceOfGeneratedClass,
string generatedClassName,
string[] ReferencedAssemblies,
TextReader templateSourceReader)
{
RazorTemplateEngine engine = CreateHost(namespaceOfGeneratedClass, generatedClassName);
// Generate
the template class as CodeDom
GeneratorResults razorResults = engine.GenerateCode(templateSourceReader);
// Create code from
the codeDom
and compile
CSharpCodeProvider codeProvider = new CSharpCodeProvider();
CodeGeneratorOptions options = new CodeGeneratorOptions();
// Capture Code Generated as a
string for error info
//
and debugging
LastGeneratedCode = null;
using (StringWriter writer = new StringWriter())
{
codeProvider.GenerateCodeFromCompileUnit(razorResults.GeneratedCode, writer, options);
LastGeneratedCode = writer.ToString();
}
CompilerParameters compilerParameters = new CompilerParameters(ReferencedAssemblies);
// Standard Assembly References
compilerParameters.ReferencedAssemblies.Add("System.dll");
compilerParameters.ReferencedAssemblies.Add("System.Core.dll");
compilerParameters.ReferencedAssemblies.Add("Microsoft.CSharp.dll"); // dynamic support!
// Also add
the current assembly so RazorTemplateBase
is available
compilerParameters.ReferencedAssemblies.Add(Assembly.GetExecutingAssembly().CodeBase.Substring(8));
compilerParameters.GenerateInMemory = Configuration.CompileToMemory;
if (!Configuration.CompileToMemory)
compilerParameters.OutputAssembly = Path.Combine(Configuration.TempAssemblyPath, "_" + Guid.NewGuid().ToString("n") + ".dll");
CompilerResults compilerResults = codeProvider.CompileAssemblyFromDom(compilerParameters, razorResults.GeneratedCode);
if (compilerResults.Errors.Count > 0)
{
var compileErrors = new StringBuilder();
foreach (System.CodeDom.Compiler.CompilerError compileError
in compilerResults.Errors)
compileErrors.Append(String.Format(Resources.LineX0TColX1TErrorX2RN, compileError.Line, compileError.Column, compileError.ErrorText));
this.SetError(compileErrors.ToString() + "\r\n" + LastGeneratedCode);
return null;
}
AssemblyCache.Add(compilerResults.CompiledAssembly.FullName, compilerResults.CompiledAssembly);
return compilerResults.CompiledAssembly.FullName;
}
Think of
the internal CreateHost() method as setting up
the assembly generated from each template. Each template compiles into a separate assembly. It sets up namespaces,
and assembly references,
the base class used
and the name
and namespace for
the generated class. ParseAndCompileTemplate() then calls
the CreateHost() method to receive
the template engine generator which effectively generates a CodeDom from
the template –
the template
is turned into .NET code.
The code generated from our earlier example looks something like this:
//------------------------------------------------------------------------------
// <auto-generated>
// This code was generated by a tool.
// Runtime Version:4.0.30319.1
//
// Changes to this file may cause incorrect behavior
and will be lost if
//
the code
is regenerated.
// </auto-generated>
//------------------------------------------------------------------------------
namespace RazorTest
{
using System;
using System.Text;
using System.Collections.Generic;
using System.Linq;
using System.IO;
using System.Reflection;
public class RazorTemplate : RazorHosting.RazorTemplateBase
{
#line hidden
public RazorTemplate()
{
}
public override void Execute()
{
WriteLiteral("Hello ");
Write(Context.FirstName);
WriteLiteral("! Your entry was entered on: ");
Write(Context.Entered);
WriteLiteral("\r\n\r\n");
// Code block: Update
the host Windows Form passed
in through
the context
Context.WinForm.Text = "Hello World from Razor at " + DateTime.Now.ToString();
WriteLiteral("\r\nAppDomain Id:\r\n ");
Write(AppDomain.CurrentDomain.FriendlyName);
WriteLiteral("\r\n \r\nAssembly:\r\n ");
Write(Assembly.GetExecutingAssembly().FullName);
WriteLiteral("\r\n\r\nCode based output: \r\n");
// Write output with Response object from code
string output =
string.Empty;
for (int i = 0; i < 10; i++)
{
output += i.ToString() + " ";
}
}
}
}
Basically
the template’s body
is turned into code
in an Execute method that
is called. Internally
the template’s Write method
is fired to actually generate
the output. Note that
the class inherits from RazorTemplateBase which
is the generic parameter I used to specify
the base class when creating an instance
in my RazorEngine host:
var engine = new RazorEngine<RazorTemplateBase>();
This template class must be provided
and it must implement an Execute()
and Write() method. Beyond that you can create any class you chose
and attach your own properties. My RazorTemplateBase class implementation
is very simple:
public class RazorTemplateBase : MarshalByRefObject, IDisposable
{
/// <summary>
/// You can pass
in a generic context object
/// to use
in your template code
/// </summary>
public dynamic Context { get; set; }
/// <summary>
/// Class that generates output. Currently ultra simple
/// with only Response.Write() implementation.
/// </summary>
public RazorResponse Response { get; set; }
public object HostContainer {get; set; }
public object Engine { get; set; }
public RazorTemplateBase()
{
Response = new RazorResponse();
}
public virtual void Write(object value)
{
Response.Write(value);
}
public virtual void WriteLiteral(object value)
{
Response.Write(value);
}
/// <summary>
/// Razor Parser implements this method
/// </summary>
public virtual void Execute() {}
public virtual void Dispose()
{
if (Response != null)
{
Response.Dispose();
Response = null;
}
}
}
Razor fills
in the Execute method when it generates its subclass
and uses
the Write() method to output content. As you can see I use a RazorResponse() class here to generate output. This isn’t necessary really, as you could use a StringBuilder or StringWriter() directly, but I prefer using Response object so I can extend
the Response behavior as needed.
The RazorResponse class
is also very simple
and merely acts as a wrapper around a TextWriter:
public class RazorResponse : IDisposable
{
/// <summary>
/// Internal text writer - default to StringWriter()
/// </summary>
public TextWriter Writer = new StringWriter();
public virtual void Write(object value)
{
Writer.Write(value);
}
public virtual void WriteLine(object value)
{
Write(value);
Write("\r\n");
}
public virtual void WriteFormat(string format, params object[] args)
{
Write(string.Format(format, args));
}
public override
string ToString()
{
return Writer.ToString();
}
public virtual void Dispose()
{
Writer.Close();
}
public virtual void SetTextWriter(TextWriter writer)
{
// Close original writer
if (Writer != null)
Writer.Close();
Writer = writer;
}
}
The Rendering Methods of RazorEngine
At this point I’ve talked about
the assembly generation logic
and the template implementation itself. What’s left
is that once you’ve generated
the assembly
is to execute it.
The code to do this
is handled
in the various RenderXXX methods of
the RazorEngine class. Let’s look at
the lowest level one of these which
is RenderTemplateFromAssembly()
and a couple of internal support methods that handle instantiating
and invoking of
the generated template method:
public
string RenderTemplateFromAssembly(
string assemblyId,
string generatedNamespace,
string generatedClass,
object context,
TextWriter outputWriter)
{
this.SetError();
Assembly generatedAssembly = AssemblyCache[assemblyId];
if (generatedAssembly == null)
{
this.SetError(Resources.PreviouslyCompiledAssemblyNotFound);
return null;
}
string className = generatedNamespace + "." + generatedClass;
Type type;
try
{
type = generatedAssembly.GetType(className);
}
catch (Exception ex)
{
this.SetError(Resources.UnableToCreateType + className + ": " + ex.Message);
return null;
}
// Start with empty non-error response (if we use a writer)
string result =
string.Empty;
using(TBaseTemplateType instance = InstantiateTemplateClass(type))
{
if (instance == null)
return null;
if (outputWriter != null)
instance.Response.SetTextWriter(outputWriter);
if (!InvokeTemplateInstance(instance, context))
return null;
// Capture
string output if implemented
and return
// otherwise null
is returned
if (outputWriter == null)
result = instance.Response.ToString();
}
return result;
}
protected virtual TBaseTemplateType InstantiateTemplateClass(Type type)
{
TBaseTemplateType instance = Activator.CreateInstance(type) as TBaseTemplateType;
if (instance == null)
{
SetError(Resources.CouldnTActivateTypeInstance + type.FullName);
return null;
}
instance.Engine = this;
// If a HostContainer was set pass that to
the template too
instance.HostContainer = this.HostContainer;
return instance;
}
/// <summary>
/// Internally executes an instance of
the template,
/// captures errors on execution
and returns true or false
/// </summary>
/// <param name="instance">An instance of
the generated template</param>
/// <returns>true or false - check ErrorMessage for errors</returns>
protected virtual bool InvokeTemplateInstance(TBaseTemplateType instance, object context)
{
try
{
instance.Context = context;
instance.Execute();
}
catch (Exception ex)
{
this.SetError(Resources.TemplateExecutionError + ex.Message);
return false;
}
finally
{
// Must make sure Response
is closed
instance.Response.Dispose();
}
return true;
}
The RenderTemplateFromAssembly method basically requires
the namespace
and class to instantate
and creates an instance of
the class using InstantiateTemplateClass(). It then invokes
the method with InvokeTemplateInstance(). These two methods are broken out because they are re-used by various other rendering methods
and also to allow subclassing
and providing additional configuration tasks to set properties
and pass values to templates at execution time.
In the default mode instantiation sets
the Engine
and HostContainer (discussed later) so
the template can call back into
the template engine,
and the context
is set when
the template method
is invoked.
The various RenderXXX methods use similar code although they create
the assemblies first. If you’re after potentially cashing assemblies
the method
is the one to call
and that’s exactly
what the two HostContainer classes do. More on that
in a minute, but before we get into HostContainers let’s talk about AppDomain hosting
and the like.
Running Templates
in their own AppDomain
With
the RazorEngine class above, when a template
is parsed into an assembly
and executed
the assembly
is created (in memory or on disk – you can configure that)
and cached
in the current AppDomain.
In .NET once an assembly has been loaded it can never be unloaded so if you’re loading lots of templates
and at some time you want to release them there’s no way to do so. If however you load
the assemblies
in a separate AppDomain that new AppDomain can be unloaded
and the assemblies loaded
in it with it.
In order to host
the templates
in a separate AppDomain
the easiest thing to do
is to run
the entire RazorEngine
in a separate AppDomain. Then all interaction occurs
in the other AppDomain
and no further changes have to be made. To facilitate this there
is a RazorEngineFactory which has methods that can instantiate
the RazorHost
in a separate AppDomain as well as
in the local AppDomain.
The host creates
the remote instance
and then hangs on to it to keep it alive as well as providing methods to shut down
the AppDomain
and reload
the engine.
Sounds complicated but cross-AppDomain invocation
is actually fairly easy to implement. Here’s some of
the relevant code from
the RazorEngineFactory class. Like
the RazorEngine this class
is generic
and requires a template base type
in the generic class name:
public class RazorEngineFactory<TBaseTemplateType>
where TBaseTemplateType : RazorTemplateBase
Here are
the key methods of interest:
/// <summary>
/// Creates an instance of
the RazorHost
in a new AppDomain. This
/// version creates a static singleton that that
is cached
and you
/// can call UnloadRazorHostInAppDomain to unload it.
/// </summary>
/// <returns></returns>
public static RazorEngine<TBaseTemplateType> CreateRazorHostInAppDomain()
{
if (Current == null)
Current = new RazorEngineFactory<TBaseTemplateType>();
return Current.GetRazorHostInAppDomain();
}
public static void UnloadRazorHostInAppDomain()
{
if (Current != null)
Current.UnloadHost();
Current = null;
}
/// <summary>
/// Instance method that creates a RazorHost
in a new AppDomain.
/// This method requires that you keep
the Factory around
in
/// order to keep
the AppDomain alive
and be able to unload it.
/// </summary>
/// <returns></returns>
public RazorEngine<TBaseTemplateType> GetRazorHostInAppDomain()
{
LocalAppDomain = CreateAppDomain(null);
if (LocalAppDomain == null)
return null;
/// Create
the instance inside of
the new AppDomain
/// Note: remote domain uses local EXE's AppBasePath!!!
RazorEngine<TBaseTemplateType> host = null;
try
{
Assembly ass = Assembly.GetExecutingAssembly();
string AssemblyPath = ass.Location;
host = (RazorEngine<TBaseTemplateType>) LocalAppDomain.CreateInstanceFrom(AssemblyPath,
typeof(RazorEngine<TBaseTemplateType>).FullName).Unwrap();
}
catch (Exception ex)
{
ErrorMessage = ex.Message;
return null;
}
return host;
}
/// <summary>
/// Internally creates a new AppDomain
in which Razor templates can
/// be run.
/// </summary>
/// <param name="appDomainName"></param>
/// <returns></returns>
private AppDomain CreateAppDomain(string appDomainName)
{
if (appDomainName == null)
appDomainName = "RazorHost_" + Guid.NewGuid().ToString("n");
AppDomainSetup setup = new AppDomainSetup();
// *** Point at current directory
setup.ApplicationBase = AppDomain.CurrentDomain.BaseDirectory;
AppDomain localDomain = AppDomain.CreateDomain(appDomainName, null, setup);
return localDomain;
}
/// <summary>
/// Allow unloading of
the created AppDomain to release resources
/// All internal resources
in the AppDomain are released including
///
in memory compiled Razor assemblies.
/// </summary>
public void UnloadHost()
{
if (this.LocalAppDomain != null)
{
AppDomain.Unload(this.LocalAppDomain);
this.LocalAppDomain = null;
}
}
The static CreateRazorHostInAppDomain()
is the key method that startup code usually calls. It uses a Current singleton instance to an instance of itself that
is created cross AppDomain
and is kept alive because it’s static. GetRazorHostInAppDomain actually creates a cross-AppDomain instance which first creates a new AppDomain
and then loads
the RazorEngine into it.
The remote Proxy instance
is returned as a result to
the method
and can be used
the same as a local instance.
The code to run with a remote AppDomain
is simple:
private RazorEngine<RazorTemplateBase> CreateHost()
{
if (this.Host != null)
return this.Host;
// Use Static Methods - no error message if host doesn't load
this.Host = RazorEngineFactory<RazorTemplateBase>.CreateRazorHostInAppDomain();
if (this.Host == null)
{
MessageBox.Show("Unable to load Razor Template Host",
"Razor Hosting", MessageBoxButtons.OK, MessageBoxIcon.Exclamation);
}
return this.Host;
}
This code relies on a local reference of
the Host which
is kept around for
the duration of
the app (in this case a form reference). To use this you’d simply do:
this.Host = CreateHost();
if (host == null)
return;
string result = host.RenderTemplate(
this.txtSource.Text,
new string[] { "System.Windows.Forms.dll", "Westwind.Utilities.dll" },
this.CustomContext);
if (result == null)
{
MessageBox.Show(host.ErrorMessage, "Template Execution Error", MessageBoxButtons.OK, MessageBoxIcon.Exclamation);
return;
}
this.txtResult.Text = result;
Now all templates run
in a remote AppDomain
and can be unloaded with simple code like this:
RazorEngineFactory<RazorTemplateBase>.UnloadRazorHostInAppDomain();
this.Host = null;
One Step further – Providing a caching ‘Runtime’
Once we can load templates
in a remote AppDomain we can add some additional functionality like assembly caching based on application specific features. One of my typical scenarios
is to render templates out of a scripts folder. So all templates live
in a folder
and they change infrequently. So a Folder based host that can compile these templates once
and then only recompile them if something changes would be ideal.
Enter host containers which are basically wrappers around
the RazorEngine<t>
and RazorEngineFactory<t>. They provide additional logic for things like file caching based on changes on disk or
string hashes for
string based template inputs.
The folder host also provides for partial rendering logic through a custom template base implementation.
There’s a base implementation
in RazorBaseHostContainer, which provides
the basics for hosting a RazorEngine, which includes
the ability to start
and stop
the engine, cache assemblies
and add references:
public abstract class RazorBaseHostContainer<TBaseTemplateType> : MarshalByRefObject
where TBaseTemplateType : RazorTemplateBase, new()
{
public RazorBaseHostContainer()
{
UseAppDomain = true;
GeneratedNamespace = "__RazorHost";
}
/// <summary>
/// Determines whether
the Container hosts Razor
///
in a separate AppDomain. Seperate AppDomain
/// hosting allows unloading
and releasing of
/// resources.
/// </summary>
public bool UseAppDomain { get; set; }
/// <summary>
/// Base folder location where
the AppDomain
///
is hosted. By default uses
the same folder
/// as
the host application.
///
/// Determines where binary dependencies are
/// found for assembly references.
/// </summary>
public
string BaseBinaryFolder { get; set; }
/// <summary>
/// List of referenced assemblies as
string values.
/// Must be
in GAC or
in the current folder of
the host app/
/// base BinaryFolder
/// </summary>
public List<string> ReferencedAssemblies = new List<string>();
/// <summary>
/// Name of
the generated namespace for template classes
/// </summary>
public
string GeneratedNamespace {get; set; }
/// <summary>
/// Any error messages
/// </summary>
public
string ErrorMessage { get; set; }
/// <summary>
/// Cached instance of
the Host. Required to keep
the
/// reference to
the host alive for multiple uses.
/// </summary>
public RazorEngine<TBaseTemplateType> Engine;
/// <summary>
/// Cached instance of
the Host Factory - so we can unload
///
the host
and its associated AppDomain.
/// </summary>
protected RazorEngineFactory<TBaseTemplateType> EngineFactory;
/// <summary>
/// Keep track of each compiled assembly
///
and when it was compiled.
///
/// Use a hash of
the string to identify
string
/// changes.
/// </summary>
protected Dictionary<int, CompiledAssemblyItem> LoadedAssemblies = new Dictionary<int, CompiledAssemblyItem>();
/// <summary>
/// Call to start
the Host running. Follow by a calls to RenderTemplate to
/// render individual templates. Call Stop when done.
/// </summary>
/// <returns>true or false - check ErrorMessage on false </returns>
public virtual bool Start()
{
if (Engine == null)
{
if (UseAppDomain)
Engine = RazorEngineFactory<TBaseTemplateType>.CreateRazorHostInAppDomain();
else
Engine = RazorEngineFactory<TBaseTemplateType>.CreateRazorHost();
Engine.Configuration.CompileToMemory = true;
Engine.HostContainer = this;
if (Engine == null)
{
this.ErrorMessage = EngineFactory.ErrorMessage;
return false;
}
}
return true;
}
/// <summary>
/// Stops
the Host
and releases
the host AppDomain
and cached
/// assemblies.
/// </summary>
/// <returns>true or false</returns>
public bool Stop()
{
this.LoadedAssemblies.Clear();
RazorEngineFactory<RazorTemplateBase>.UnloadRazorHostInAppDomain();
this.Engine = null;
return true;
}
…
}
This base class provides most of
the mechanics to host
the runtime, but no application specific implementation for rendering. There are rendering functions but they just call
the engine directly
and provide no caching – there’s no context to decide how to cache
and reuse templates.
The key methods are Start
and Stop
and their main purpose
is to start a new AppDomain (optionally)
and shut it down when requested.
The RazorFolderHostContainer – Folder Based Runtime Hosting
Let’s look at
the more application specific RazorFolderHostContainer implementation which
is defined like this:
public class RazorFolderHostContainer : RazorBaseHostContainer<RazorTemplateFolderHost>
Note that a customized RazorTemplateFolderHost class template
is used for this implementation that supports partial rendering
in form of a RenderPartial() method that’s available to templates.
The folder host’s features are:
Render templates based on a Template Base Path (a ‘virtual’ if you will)
Cache compiled assemblies based on
the relative path
and file time stamp
File changes on templates cause templates to be recompiled into new assemblies
Support for partial rendering using base folder relative pathing
As shown
in the startup examples earlier host containers require some startup code with a HostContainer tied to a persistent property (like a Form property):
//
The base path for templates - templates are rendered with relative paths
// based on this path.
HostContainer.TemplatePath = Path.Combine(Environment.CurrentDirectory, TemplateBaseFolder);
// Default output rendering disk location
HostContainer.RenderingOutputFile = Path.Combine(HostContainer.TemplatePath, "__Preview.htm");
// Add any assemblies you want reference
in your templates
HostContainer.ReferencedAssemblies.Add("System.Windows.Forms.dll");
// Start up
the host container
HostContainer.Start();
Once that’s done, you can render templates with
the host container:
// Pass
the template path for full filename seleted with OpenFile Dialog // relativepath is: subdir\file.cshtml or file.cshtml or ..\file.cshtml
var relativePath = Utilities.GetRelativePath(fileName, HostContainer.TemplatePath);
if (!HostContainer.RenderTemplate(relativePath, Context, HostContainer.RenderingOutputFile))
{
MessageBox.Show("Error: " + HostContainer.ErrorMessage);
return;
}
webBrowser1.Navigate("file://" + HostContainer.RenderingOutputFile);
The most critical task of
the RazorFolderHostContainer implementation
is to retrieve a template from disk, compile
and cache it
and then deal with deciding whether subsequent requests need to re-compile
the template or simply use a cached version. Internally
the GetAssemblyFromFileAndCache() handles this task:
/// <summary>
/// Internally checks if a cached assembly exists
and if it does uses it
/// else creates
and compiles one. Returns an assembly Id to be
/// used with
the LoadedAssembly list.
/// </summary>
/// <param name="relativePath"></param>
/// <param name="context"></param>
/// <returns></returns>
protected virtual CompiledAssemblyItem GetAssemblyFromFileAndCache(string relativePath)
{
string fileName = Path.Combine(TemplatePath, relativePath).ToLower();
int fileNameHash = fileName.GetHashCode();
if (!File.Exists(fileName))
{
this.SetError(Resources.TemplateFileDoesnTExist + fileName);
return null;
}
CompiledAssemblyItem item = null;
this.LoadedAssemblies.TryGetValue(fileNameHash, out item);
string assemblyId = null;
// Check for cached instance
if (item != null)
{
var fileTime = File.GetLastWriteTimeUtc(fileName);
if (fileTime <= item.CompileTimeUtc)
assemblyId = item.AssemblyId;
}
else
item = new CompiledAssemblyItem();
// No cached instance - create assembly
and cache
if (assemblyId == null)
{
string safeClassName = GetSafeClassName(fileName);
StreamReader reader = null;
try
{
reader = new StreamReader(fileName, true);
}
catch (Exception ex)
{
this.SetError(Resources.ErrorReadingTemplateFile + fileName);
return null;
}
assemblyId = Engine.ParseAndCompileTemplate(this.ReferencedAssemblies.ToArray(), reader);
// need to ensure reader
is closed
if (reader != null)
reader.Close();
if (assemblyId == null)
{
this.SetError(Engine.ErrorMessage);
return null;
}
item.AssemblyId = assemblyId;
item.CompileTimeUtc = DateTime.UtcNow;
item.FileName = fileName;
item.SafeClassName = safeClassName;
this.LoadedAssemblies[fileNameHash] = item;
}
return item;
}
This code uses a LoadedAssembly dictionary which
is comprised of a structure that holds a reference to a compiled assembly, a full filename
and file timestamp
and an assembly id. LoadedAssemblies (defined on
the base class shown earlier)
is essentially a cache for compiled assemblies
and they are identified by a hash id.
In the case of files
the hash
is a GetHashCode() from
the full filename of
the template.
The template
is checked for
in the cache
and if not found
the file stamp
is checked. If that’s newer than
the cache’s compilation date
the template
is recompiled otherwise
the version
in the cache
is used. All
the core work defers to a RazorEngine<T> instance to ParseAndCompileTemplate().
The three rendering specific methods then are rather simple implementations with just a few lines of code dealing with parameter
and return value parsing:
/// <summary>
/// Renders a template to a TextWriter. Useful to write output into a stream or
///
the Response object. Used for partial rendering.
/// </summary>
/// <param name="relativePath">Relative path to
the file
in the folder structure</param>
/// <param name="context">Optional context object or null</param>
/// <param name="writer">The textwriter to write output into</param>
/// <returns></returns>
public bool RenderTemplate(string relativePath, object context, TextWriter writer)
{
// Set configuration data that
is to be passed to
the template (any object)
Engine.TemplatePerRequestConfigurationData = new RazorFolderHostTemplateConfiguration()
{
TemplatePath = Path.Combine(this.TemplatePath, relativePath),
TemplateRelativePath = relativePath,
};
CompiledAssemblyItem item = GetAssemblyFromFileAndCache(relativePath);
if (item == null)
{
writer.Close();
return false;
}
try
{
//
String result will be empty as output will be rendered into
the
// Response object's stream output. However a null result denotes
// an error
string result = Engine.RenderTemplateFromAssembly(item.AssemblyId, context, writer);
if (result == null)
{
this.SetError(Engine.ErrorMessage);
return false;
}
}
catch (Exception ex)
{
this.SetError(ex.Message);
return false;
}
finally
{
writer.Close();
}
return true;
}
/// <summary>
/// Render a template from a source file on disk to a specified outputfile.
/// </summary>
/// <param name="relativePath">Relative path off
the template root folder. Format: path/filename.cshtml</param>
/// <param name="context">Any object that will be available
in the template as a dynamic of this.Context</param>
/// <param name="outputFile">Optional - output file where output
is written to. If not specified
the
/// RenderingOutputFile property
is used instead
/// </param>
/// <returns>true if rendering succeeds, false on failure - check ErrorMessage</returns>
public bool RenderTemplate(string relativePath, object context,
string outputFile)
{
if (outputFile == null)
outputFile = RenderingOutputFile;
try
{
using (StreamWriter writer = new StreamWriter(outputFile, false,
Engine.Configuration.OutputEncoding,
Engine.Configuration.StreamBufferSize))
{
return RenderTemplate(relativePath, context, writer);
}
}
catch (Exception ex)
{
this.SetError(ex.Message);
return false;
}
return true;
}
/// <summary>
/// Renders a template to
string. Useful for RenderTemplate
/// </summary>
/// <param name="relativePath"></param>
/// <param name="context"></param>
/// <returns></returns>
public
string RenderTemplateToString(string relativePath, object context)
{
string result =
string.Empty;
try
{
using (StringWriter writer = new StringWriter())
{
//
String result will be empty as output will be rendered into
the
// Response object's stream output. However a null result denotes
// an error
if (!RenderTemplate(relativePath, context, writer))
{
this.SetError(Engine.ErrorMessage);
return null;
}
result = writer.ToString();
}
}
catch (Exception ex)
{
this.SetError(ex.Message);
return null;
}
return result;
}
The idea
is that you can create custom host container implementations that do exactly
what you want fairly easily. Take a look at both
the RazorFolderHostContainer
and RazorStringHostContainer classes for
the basic concepts you can use to create custom implementations.
Notice also that you can set
the engine’s PerRequestConfigurationData() from
the host container:
// Set configuration data that
is to be passed to
the template (any object)
Engine.TemplatePerRequestConfigurationData = new RazorFolderHostTemplateConfiguration()
{
TemplatePath = Path.Combine(this.TemplatePath, relativePath),
TemplateRelativePath = relativePath,
};
which when set to a non-null value
is passed to
the Template’s InitializeTemplate() method. This method receives an object parameter which you can cast as needed:
public override void InitializeTemplate(object configurationData)
{
// Pick up configuration data
and stuff into Request object
RazorFolderHostTemplateConfiguration config = configurationData as RazorFolderHostTemplateConfiguration;
this.Request.TemplatePath = config.TemplatePath;
this.Request.TemplateRelativePath = config.TemplateRelativePath;
}
With this data you can then configure any custom properties or objects on your main template class. It’s an easy way to pass data from
the HostContainer all
the way down into
the template.
The type you use
is of type object so you have to cast it yourself,
and it must be serializable since it will likely run
in a separate AppDomain.
This might seem like an ugly way to pass data around – normally I’d use an event delegate to call back from
the engine to
the host, but since this
is running over AppDomain boundaries events get really tricky
and passing a template instance back up into
the host over AppDomain boundaries doesn’t work due to serialization issues. So it’s easier to pass
the data from
the host down into
the template using this rather clumsy approach of set
and forward. It’s ugly, but it’s something that can be hidden
in the host container implementation as I’ve done here. It’s also not something you have to do
in every implementation so this
is kind of an edge case, but I know I’ll need to pass a bunch of data
in some of my applications
and this will be
the easiest way to do so.
Summing Up
Hosting
the Razor runtime
is something I got jazzed up about quite a bit because I have an immediate need for this type of templating/merging/scripting capability
in an application I’m working on. I’ve also been using templating
in many apps
and it’s always been a pain to deal with.
The Razor engine makes this whole experience a lot cleaner
and more light weight
and with these wrappers I can now plug .NET based templating into my code literally with a few lines of code. That’s something to cheer about… I hope some of you will find this useful as well…
Resources
The examples
and code require that you download
the Razor runtimes. Projects are for Visual Studio 2010 running on .NET 4.0
Platform Installer 3.0 (install WebMatrix or MVC 3 for Razor Runtimes)
Latest Code
in Subversion Repository
Download Snapshot of
the Code
Documentation (CHM Help File)
© Rick Strahl, West Wind Technologies, 2005-2010Posted
in ASP.NET .NET
