API Reference


Plugins are a nice way to extend templates with customized functionality which can encapsulate any number of blocks, filters, preferred configuration and dependencies by implementing the ITemplatePlugin interface.

The MarkdownTemplatePlugin is a good example of this which registers a markdown Page format, Filter, Filter Transformer and markdown Block:

public class MarkdownTemplatePlugin : ITemplatePlugin
    public bool RegisterPageFormat { get; set; } = true;

    public void Register(TemplateContext context)
        if (RegisterPageFormat)
            context.PageFormats.Add(new MarkdownPageFormat());
        context.FilterTransformers["markdown"] = MarkdownPageFormat.TransformToHtml;
        context.TemplateFilters.Add(new MarkdownTemplateFilter());

        context.TemplateBlocks.Add(new TemplateMarkdownBlock());

The MarkdownTemplatePlugin is pre-registered when using the ServiceStack Templates View Engine, for all other contexts it can be registered and customized with:

var context = new TemplateContext {
    Plugins = { new MarkdownTemplatePlugin { RegisterPageFormat = false } }

Removing Plugins

When needed any default plugins can be removed with the RemovePlugins() API:

var context = new TemplateContext()
    .RemovePlugins(x => x is DefaultScriptBlocks) // Remove default blocks
    .RemovePlugins(x => x is HtmlScriptBlocks)    // Remove all html blocks

Or you can use the OnAfterPlugins callback to remove any individual blocks or filters that were added by any plugin.

E.g. the capture block can be removed with:

var context = new TemplateContext {
        OnAfterPlugins = ctx => ctx.RemoveBlocks(x => x.Name == "capture")

Advanced plugin registration

For greater control over the registration and execution of plugins, they can implement ITemplatePluginBefore to have custom logic executed before plugins are registered or implement ITemplatePluginAfter for executing any logic after.


The TemplateContext is the sandbox where all templates are executed within that can be customized with the available APIs below:

Preconfigured defaults

Some default filters when called without arguments will use the default configuration shown below that can be overridden by replacing their default value in the TemplateContext's Args collection:

var context = new TemplateContext { 
    Args = {
        [TemplateConstants.MaxQuota] = 10000,
        [TemplateConstants.DefaultCulture] = CultureInfo.CurrentCulture,
        [TemplateConstants.DefaultDateFormat] = "yyyy-MM-dd",
        [TemplateConstants.DefaultDateTimeFormat] = "u",
        [TemplateConstants.DefaultTimeFormat] = "h\\:mm\\:ss",
        [TemplateConstants.DefaultFileCacheExpiry] = TimeSpan.FromMinutes(1),
        [TemplateConstants.DefaultUrlCacheExpiry] = TimeSpan.FromMinutes(1),
        [TemplateConstants.DefaultIndent] = "\t",
        [TemplateConstants.DefaultNewLine] = Environment.NewLine,
        [TemplateConstants.DefaultJsConfig] = "excludetypeinfo",
        [TemplateConstants.DefaultStringComparison] = StringComparison.Ordinal,
        [TemplateConstants.DefaultTableClassName] = "table",
        [TemplateConstants.DefaultErrorClassName] = "alert alert-danger",


TemplateContext Arguments can be used to define global variables available to every template, partial, filter, etc:

Virtual Files

Templates only have access to Pages available from its configured VirtualFiles which uses an empty MemoryVirtualFiles. To make pages available to your TemplateContext instance you can choose to either programatically populate the VirtualFiles collection from an external source, e.g:

var fs = new FileSystemVirtualFiles("~/template-files".MapProjectPath());
foreach (var file in fs.GetAllMatchingFiles("*.html"))
    if (!MyAllowFile(file)) continue;
    using (var stream = file.OpenRead())
        context.VirtualFiles.WriteFile(file.VirtualPath, stream);

Alternatively if you want to enable access to an entire sub directory you can replace the Virtual Files with a FileSystem VFS at the directory you want to make the root directory:

context.VirtualFiles = new FileSystemVirtualFiles("~/template-files".MapProjectPath());


DebugMode is used to control whether full Exception details like StackTrace is displayed. In TemplatePageFeature it defaults to the AppHost DebugMode, otherwise it's true by default.


Specify a TemplateFilter or TemplateCodePage to auto register.


Specify assemblies that should be scanned to find TemplateFilter's and TemplateCodePage's to auto register. In TemplatePageFeature the AppHost's Service Assemblies are included by default.


Register additional instances of filters you want templates to have access to.


Register instances of code pages you want templates to have access to.


The IOC Container used by the TemplateContext to register and resolve dependencies, filters and Code Pages. Uses SimpleContainer by default.


Specify an optional App Settings provider that templates can access with the {{ key | appSetting }} default filter.


Whether to check for modified pages by default when not in DebugMode, defaults to true. Note: if DebugMode is true it will always check for changes.


If provided will specify how long to wait before checking if backing files of pages have changed and to reload them if they have. Note: if DebugMode is true it will always check for changes.


Whether to Render Expression Exceptions in-line (default = false).


The PageResult is the rendering context used to render templates whose output can be customized with the APIs below:


Override the layout used for the page by specifying a layout name:

new PageResult(page) { Layout = "custom-layout" }


Override the layout used for the page by specifying a Layout page:

new PageResult(page) { LayoutPage = Request.GetPage("custom-layout") }


Override existing or specify additional arguments in the Template's scope:

new PageResult(page) { 
    Args = { 
        ["myArg"] = "argValue",


Make additional filters available to the Template:

new PageResult(page) { 
    TemplateFilters = { new MyFilters() }


Transform the entire Template's Output before rendering to the OutputStream:

new PageResult(page) {
    ContentType = MimeTypes.Html,
    OutputTransformers = { MarkdownPageFormat.TransformToHtml },


Transform just the Page's Output before rendering to the OutputStream:

new PageResult(page) {
    ContentType = MimeTypes.Html,
    PageTransformers = { MarkdownPageFormat.TransformToHtml },


Specify additional Filter Transformers available to the Template:

new PageResult(page) {
    FilterTransformers = {
        ["markdown"] = MarkdownPageFormat.TransformToHtml


Disable access to the specified registered filters:

new PageResult(page) {
    ExcludeFiltersNamed = { "partial", "selectPartial" }


Return additional HTTP Response Headers when rendering to a HTTP Response:

new PageResult(page) {
    Options = { 
        ["X-Powered-By"] = "ServiceStack Templates"


Specify the HTTP Content-Type when rendering to a HTTP Response:

new PageResult(page) {
    ContentType = "text/plain"

made with by ServiceStack