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 IScriptPlugin interface.

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

public class MarkdownScriptPlugin : IScriptPlugin
    public bool RegisterPageFormat { get; set; } = true;

    public void Register(ScriptContext context)
        if (RegisterPageFormat)
            context.PageFormats.Add(new MarkdownPageFormat());
        context.FilterTransformers["markdown"] = MarkdownPageFormat.TransformToHtml;
        context.ScriptMethods.Add(new MarkdownScriptMethods());

        context.ScriptBlocks.Add(new MarkdownScriptBlock());

The MarkdownScriptPlugin is pre-registered when using the #Script Pages, for all other contexts it can be registered and customized with:

var context = new ScriptContext {
    Plugins = { new MarkdownScriptPlugin { RegisterPageFormat = false } }

Removing Plugins

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

var context = new ScriptContext()
    .RemovePlugins(x => x is DefaulScripttBlocks) // 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 ScriptContext {
        OnAfterPlugins = ctx => ctx.RemoveBlocks(x => x.Name == "capture")

Advanced plugin registration

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


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

Preconfigured defaults

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

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


ScriptContext 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 ScriptContext 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 SharpPagesFeature it defaults to the AppHost DebugMode, otherwise it's true by default.


Specify a ScriptMethods or SharpCodePage to auto register.


Specify assemblies that should be scanned to find ScriptMethods's and SharpCodePage's to auto register. In SharpPagesFeature 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 ScriptContext 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) { 
    ScriptMethods = { new MyScriptMethods() }


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"] = "#Script"


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

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

made with by ServiceStack