Rick Strahl's Web Log

Putting the Westwind.Scripting C# Templating Library to work, Part 2

Rick Strahl — Fri, 24 Apr 2026 02:04:43 GMT

This is a two part series that discusses the Westwind.Scripting Template library

Part 1: Revisiting C# Scripting with the Westwind.Scripting Templating Library

Part 2: Real world integration for a Local Rendering and Web Site Generation (this post)

In part 1 of this series I introduced the Westwind.Scripting library, how it works and how you can use it and integrate it into your applications. In part 2, I'm going over implementation details of hosting a scripting engine for a specific scenario that generates local static Html output for a for a project based solution that requires both local preview and local Web site generation. As part of that process I'll point out a number of issues that you likely have to consider in this somewhat common scenario.

If you haven't already, I'd recommend you read Part 1 so you have a good idea what the library provides and how it works. While not required, this post will make a lot more sense with that context in place.

Revisiting Westwind.Script Template Scripting Library, Part 1

Putting Templating to use in a Real World Scenario

The ScriptParser class in the Westwind.Scripting library allows you to execute C# based, Handlebars-like templates that merge template text with model data that can be embedded into the template with Handlebars style {{ expression }} and {{% code block }} directives. You can use both string based templates and templates from files that can also include references to partials and layout pages. All of that was covered in Part 1.

While using the ScriptParser for demos and single template output is easy enough, using it to integrate into a larger application, interacting with host application features and content, and especially generating many document Web site output with related dependencies, requires a bit more work.

I'm using my Documentation Monster application as an example here as it's been my dog-fooding project to put the ScriptParser to real world use. It's a project based documentation solution that statically produces Web Site Html output. It generates Html output in two ways in an offline desktop application:

Renders a single topic for Live Preview as you type topic content
Renders many topics in a documentation project into a full self-contained Web site

DM uses script templates to render each topic with a specific topic type - Topic, Header, ClassHeader, ClassMethod, ClassProperty, WhatsNew, ExternalLink etc. - each representing a separate Html template in an Html file (ie. Topic.html) on disk which are the templates I'm passing into the ScriptParser class for execution. The model then feeds specific a specific model that contains the topic, project and other support data and some application logic.

These topic templates templates are similar but all have overlapping content: All of them have a header and topic body, but they also have customized areas to them: For example, ClassHeader has a class member table, inheritance list, lists assembly and namespace, ClassProperty/ClassMethod/ClassField member templates have syntax and exception settings, ExternalLink displays an Html page during development but redirects to a Url in a published output file etc. In other words, each topic type has some unique things going on with it that the template script reflects. If a topic has a type that can't map to a template, the default template which in this case is the Topic template is used via fallback.

Templates are user customizable, so they are sensitive to changes and are recompiled whenever changes are detected in the generated code.

The raw Html rendering of topics is simple enough - the template is executed as is and produces Html output. But once you introduce document dependencies like images, scripts, css etc. and you create output that may end up in nested folders, pathing becomes a concern in statically generated content. The reason is, the 'hosting' environment can't be determined at render time and the content may be hosted locally via file system (for individual preview in this case), a root Web site, or in a sub-folder of a Web site.

So then the question is what's a relative path based on? What's a root path (/) based on? The rendered output has to be self-contained, and templates are responsible for properly making paths natural to use for a specific output environment.

This means some or all Urls may have to be fixed up and in some cases a <base> has to be provided in the Html content for each page. None of that can happen automatically so this is a manual post-processing step that is application specific.

In addition, when rendering topics a few things that need to be considered:

When and how to render using the ScriptParser
Where to store the Templates consistently
Ensure that rendered output can be referenced relatively
Ensure there's consistent BasePath to reference root and project wide Urls (ie. / or ~/)

Let's walk through what template rendering looks like inside of an application.

Create a TemplateHost

In projects that use template rendering I like to create a TemplateHost class that encapsulates all tasks related to executing the scripting engine. This simplifies configuration of the template engine in one place and provides a few easily accessible methods for rendering templates - in the case of DM rendering topics to string and to file.

ScriptParser Configuration - References and Namespaces

Adding of dependent references and namespaces is one of the most frustrating things of doing runtime compilation of code and so that step needs to be consolidated into a single place.

Here's the base implementation of the TemplateHost with the CreateScriptParser() method implementation from DM:

public class TemplateHost
{
    public ScriptParser Script
    {
        get
        {
            if (field == null)
                field = CreateScriptParser();
            return field;
        }
        set;
    }

    public static ScriptParser CreateScriptParser()
    {
        var script = new ScriptParser();            
        
        // Good chunk of .NET Default libs
        script.ScriptEngine.AddDefaultReferencesAndNamespaces();
        
        // Any library in Host app that's been loaded up to this point
        // In DM everything required actually is loaded through this
        script.ScriptEngine.AddLoadedReferences();
        
        // explicit assemblies not or not yet used by host
        //script.ScriptEngine.AddAssembly("privatebin/Westwind.Ai.dll");
        //script.ScriptEngine.AddAssembly(typeof(Westwind.Utilities.StringUtils));

        script.ScriptEngine.AddNamespace("Westwind.Utilities");
        script.ScriptEngine.AddNamespace("DocMonster");
        script.ScriptEngine.AddNamespace("DocMonster.Model");            
        script.ScriptEngine.AddNamespace("DocMonster.Templates");
        script.ScriptEngine.AddNamespace("MarkdownMonster");
        script.ScriptEngine.AddNamespace("MarkdownMonster.Utilities");

        script.ScriptEngine.SaveGeneratedCode = true;
        script.ScriptEngine.CompileWithDebug = true;            

        // {{ expr }} is Html encoded - {{! expr }} required for raw Html output
        script.ScriptingDelimiters.HtmlEncodeExpressionsByDefault = true;            

		// custom props that expose in the template without Model. prefix
        script.AdditionalMethodHeaderCode =
            """
            DocTopic Topic = Model.Topic;
            var Project = Model.Project;
            var Configuration = Model.Configuration;
            var Helpers = Model.Helpers;                
            var DocMonsterModel = Model.DocMonsterModel;
            var AppModel = MarkdownMonster.mmApp.Model;
            
            var BasePath = new Uri(FileUtils.NormalizePath( Project.ProjectDirectory + "\\") );

            """;            
        return script;
    }
    
    // render methods below
}

In DM the TemplateHost is created on first access of a Project.TemplateHost property and then persists for the lifetime of the project, unless explicitly recreated. There is some overhead in creating the script parser environment and we might be generating a lot of documents very quickly when generating Web site output so a cached instance is preferred.

get
{
    if (field == null)
        field = CreateScriptParser();
    return field;
}

Notice that the parser is set up with common default and all loaded assembly references from the host. I then add all the specific libraries that may not have been loaded yet, and any custom namespaces that are used by the various application specific components that are used in the templates. This is perhaps the main reason to use a TemplateHost like wrapper: To hide away all this application specific configuration for a one time config and then can be forgotten about - you don't want to be doing this sort of thing in your application or business logic code.

In DM I'm lucky enough that all application dependencies live in a couple of assemblies that are already loaded by the time the parser is activated so I can rely on script.ScriptEngine.AddLoadedReferences() to bring in all of my dependencies. If your application is broken out into many small dependencies that may not work as some assemblies may not have loaded yet in which case you have to ensure you manually use script.AddAssemblyReference() to pull in explicit assemblies preferrably using the Type overload.

Another thing of note in this particual usage scenario: The AdditionalMethodHeaderCode property is used to expose various objects as top level objects to the template script. So rather than having to specify {{ Model.Topic.Title }} we can just use {{ Topic.Title }} and {{ Helpers.ChildTopicsList() }} for example. Shortcuts are useful, and you can stuff anything you want to expose in the script beyond the model here.

Since the templates in DM are accessible to end-users for editing, making the template expressions simpler makes for a more user friendly experience. Highly recommended.

Rendering

The actual render code is pretty straight forward by calling RenderTemplateFile() which renders a template from file:

public string RenderTemplateFile(string templateFile, RenderTemplateModel model)
{
    ErrorMessage = null;

    Script.ScriptEngine.ObjectInstance = null; // make sure we don't cache
    
    // explicitly turn these off for live output
	Script.ScriptEngine.SaveGeneratedCode = false;
	Script.ScriptEngine.CompileWithDebug = false;
	Script.ScriptEngine.DisableAssemblyCaching = false;
    
    string basePath = model.Project.ProjectDirectory;
    model.PageBasePath = System.IO.Path.GetDirectoryName(model.Topic.RenderTopicFilename);

    string result = Script.ExecuteScriptFile(templateFile, model, basePath: basePath);

    if (Script.Error)
	{
	    // run again this time with debugging options on
	    Script.ScriptEngine.SaveGeneratedCode = true;
	    Script.ScriptEngine.CompileWithDebug = true;
	    Script.ScriptEngine.DisableAssemblyCaching = true;  // force a recompile
	
	    Script.ExecuteScriptFile(templateFile, model, basePath: basePath);
	
	    Script.ScriptEngine.SaveGeneratedCode = false;
	    Script.ScriptEngine.CompileWithDebug = false;
	    Script.ScriptEngine.DisableAssemblyCaching = false;
	
	    // render the error page
	    result = ErrorHtml(model);
	    ErrorMessage = Script.ErrorMessage + "\n\n" + Script.GeneratedClassCodeWithLineNumbers;
	}

    return result;
}

This is the basic raw template execution logic that produces direct generated output - in this case Html.

Note that the processing checks for template errors which captures either compilation or runtime errors. If an error occurs, the current render process is re-run with all the debug options turned on so I can get additional error information to display on the error page.

I'll talk more about the error display in a minute.

Template Layout

I haven't talked about what the templates look like: DM uses relatively small topic templates, with a more complex Layout page that provides for the Web site's page chrome. The actual project output renders both the content the headers and footers and there's a bunch of logic to pull in the table of contents and handle navigation to new topics efficiently. The preview renders the same content but some of the aspects like the table of content are visually hidden in that mode.

All of that logic is encapsulated in the layout page and the supporting JavaScript scripts.

At the core re the Html/Handlebars topic templates. As mentioned, each topic type is a template that is rendered. Topic, Header, ExternalLink, WhatsNew, ClassHeader, ClassProperty, ClassMethod etc. each with their own custom formats. Each of the templates then references the same layout page (you could have several different one however if you chose)

Here's an example Content Page:

topic.html Template

{{%
    Script.Layout = "_layout.html";
}}

<h2 class="content-title">
    <img src="/_docmonster/icons/{{ Model.Topic.DisplayType }}.png">
    {{ Model.Topic.Title }}
</h2>

<div class="content-body" id="body">
    {{% if (Topic.IsLink && Topic.Body.Trim().StartsWith("http")) { }}
        <ul>
        <li>
            <a href="{{! Model.Topic.Body }}" target="_blank">{{ Model.Topic.Title }}</a>
            <a href="{{! Model.Topic.Body }}" target="_blank"><i class="fa-solid fa-up-right-from-square" style="font-size: 0.7em; vertical-align: super;"></i></a>
        </li>
        </ul>

        <blockquote style="font-size: 0.8em;"><i>In rendered output this link opens in a new browser window.
            For preview purposes, the link is displayed in this generic page.
            You can click the link to open the browser with the link which is the behavior you see when rendered.</i>
        </blockquote>
    {{% } else { }}
        {{ Model.Helpers.Markdown(Model.Topic.Body) }}
    {{% } }}
    
</div>

{{% if (!string.IsNullOrEmpty(Model.Topic.Remarks)) {  }}
    <h3 class="outdent" id="remarks">Remarks</h3>
    {{ Helpers.Markdown(ModelTopic.Remarks) }}
{{% } }}


{{% if (!string.IsNullOrEmpty(Topic.Example))  {  }}
    <h3 class="outdent" id="example">Example</h3>
    {{ Helpers.Markdown(Topic.Example) }}
{{% } }}

{{% if (!string.IsNullOrEmpty(Topic.SeeAlso)) { }}
    <h4 class="outdent" id="seealso">See also</h4>
    <div class="see-also-container">
        {{ Helpers.FixupSeeAlsoLinks(Topic.SeeAlso) }}
    </div>
{{% } }}

For demonstration purposes I'm showing both the Model.Topic and the custom header based direct binding to Topic via script.AdditionalMethodHeaderCode I showed earlier. Both point at the same value.

Note also the code block at the top that pulls in the Layout page:

{{%
    Script.Layout = "_layout.html";
}}

The layout page then looks like this:

_Layout.html

<!DOCTYPE html>
<html>
<head>
    {{%
     var theme = Project.Settings.RenderTheme;
     if(Topic.TopicState.IsPreview) { }}
    <base href="{{ Model.PageBasePath }}" />
    {{% } }}

    <meta charset="utf-8" />
    <title>{{ Topic.Title }} - {{ Project.Title }}</title>

    {{% if (!string.IsNullOrEmpty(Topic.Keywords)) { }}
    <meta name="keywords" content="{{ Topic.Keywords.Replace(" \n",", ") }}" />
    {{% } }}
    {{% if(!string.IsNullOrEmpty(Topic.Abstract)) { }}
    <meta name="description" content="{{! Topic.Abstract }}" />
    {{% } }}
    <meta name="viewport" content="width=device-width, initial-scale=1,maximum-scale=1" />
    <link rel="stylesheet" type="text/css" href="~/_docmonster/themes/scripts/bootstrap/bootstrap.min.css" />
    <link rel="stylesheet" type="text/css" href="~/_docmonster/themes/scripts/fontawesome/css/font-awesome.min.css" />
    <link id="AppCss" rel="stylesheet" type="text/css" href="~/_docmonster/themes/{{ theme }}/docmonster.css" />

    <script src="~/_docmonster/themes/scripts/highlightjs/highlight.pack.js"></script>
    <script src="~/_docmonster/themes/scripts/highlightjs-badge.min.js"></script>
    <link href="~/_docmonster/themes/scripts/highlightjs/styles/vs2015.css" rel="stylesheet" />
    <script src="~/_docmonster/themes/scripts/bootstrap/bootstrap.bundle.min.js" async></script>
    <script src="~/_docmonster/themes/scripts/lunr/lunr.min.js"></script>
    <script>
        window.page = {};
        window.page.basePath = "{{ Project.Settings.RelativeBaseUrl }}";
        window.renderTheme="{{ Project.Settings.RenderThemeMode }}";
    </script>
    <script src="~/_docmonster/themes/scripts/docmonster.js"></script>

    {{% if(Topic.TopicState.IsPreview) { }}
    <!-- Preview Navigation and Syncing -->
    <script src="~/_docmonster/themes/scripts/preview.js"></script>
    {{% } }}

</head>
<body>
    <!-- Markdown Monster Content -->
    <div class="flex-master">
        <div class="banner">
            <div class="float-end">
                <button id="themeToggleBtn" type="button" onclick="toggleTheme()"
                        class="btn btn-sm btn-secondary theme-toggle"
                        title="Toggle Light/Dark Theme">
                    <i id="themeToggleIcon"
                       class="fa fa-moon text-warning">
                    </i>
                </button>
            </div>

            <div class="float-start sidebar-toggle">
                <i class="fa fa-bars"
                   title="Show or hide the topics list"></i>
            </div>

			{{% if (Topic.Incomplete) { }}
               <div class="float-end mt-2 " title="This topic is under construction.">
                   <i class="fa-duotone fa-triangle-person-digging fa-lg fa-beat"
                   style="--fa-primary-color: #333; --fa-secondary-color: goldenrod; --fa-secondary-opacity: 1; --fa-animation-duration: 3s;"></i>
	           </div>
		    {{% } }}

            <img src="~/images/logo.png" class="banner-logo" />
            <div class="projectname"> {{ Project.Title }}</div>

            <div class="byline">
                <img src="~/_docmonster/icons/{{ Topic.DisplayType }}.png">
                {{ Topic.Title }}
            </div>
        </div>
        <div class="page-content">
            <div id="toc-container" class="sidebar-left toc-content">
                <nav class="visually-hidden">
                    <a href="~/tableofcontents.html">Table of Contents</a>
                </nav>
            </div>

            <div class="splitter">
            </div>

            <nav class="topic-outline">
                <div class="topic-outline-header">On this page:</div>
                <div class="topic-outline-content"></div>
            </nav>

            <div id="MainContent" class="main-content">
                <!-- Rendered Content -->

                <article class="content-pane">
                    {{ Script.RenderContent() }}
                </article>

                <div class="footer">

                    <div class="float-start">
                        &copy; {{ Project.Owner }}, {{ DateTime.Now.Year }} &bull;
                        updated: {{ Topic.Updated.ToString("MMM dd, yyyy") }}
                        <br />
                        {{%
                            string mailBody = $"Project: {Project.Title}\nTopic: {Topic.Title}\n\nUrl:\n{ Project.Settings.WebSiteBaseUrl?.TrimEnd('/') + Project.Settings.RelativeBaseUrl }{ Topic.Id }.html";
                            mailBody = WebUtility.UrlEncode(mailBody).Replace("+", "%20");
                        }}
                        <a href="mailto:{{ Project.Settings.SupportEmail }}?subject=Support: {{ Project.Title }} - {{ Topic.Title }}&body={{ mailBody }}">Comment or report problem with topic</a>
                    </div>

                    <div class="float-end">
                        <a href="https://documentationmonster.com" target="_blank"><img src="~/_docmonster/images/docmonster.png" style="height: 3.8em"/></a>
                    </div>
                </div>
                <!-- End Rendered Content -->
            </div> <!-- End MainContent -->
        </div> <!-- End page-content -->
    </div>   <!-- End flex-master -->
    
    <!-- End Markdown Monster Content -->
</body>
</html>

The full rendered site output looks something like this for a topic:

Figure 1 - Documentation Monster Rendered site output

The rendered topic content is in the middle panel of the display - all the rest is both static and dynamically rendered Html that is controlled through the Layout page. Both the table of contents and the document outline on the right are rendered using dynamic loading via JavaScript, while the header and footer are static with some minor embedded expressions.

With a Layout page this is easy to set up and maintain as there's a single page that handles that logic and it's easily referenced from each of the topic templates with a single layout page reference.

Behind the scenes, the parser looks for a Layout page directive in the content page requested by the ScriptParser, and if it finds one combines the layout page and content page into a single page that is executed. Essentially the Script.Layout command in the content page causes the referenced Layout page to be loaded, and the {{ Script.RenderContent() }} tag then is replaced with the content page content resulting in a single Html/Handlebars template. This combined content is then compiled and executed to produce the final merged output.

So far things are pretty straight forward relying on the core features of the scripting engine: We're pointing at template and a layout page and it produces Html in various forms depending on the type of template that we are dealing with.

That still leaves the task fixing up paths to make sure they work in the final 'hosting' environment.

Base Path Handling - PageBaseFolder and BaseFolder

When rendering Html output that depends on other resources like images CSS and scripts that referenced either as relative or site rooted paths, it's important that the page context can find these resources based on natural relative and absolute page path resolution.

There are two concerns:

Page Base Path for page relative links
Project Base Path for site root paths

Page Base Path for Relative Linking

Page base path refers to resolving relative paths in the document. For example from the current page referencing an image as SomeImage.png (same folder) or ../images/SomeFolder (relative path). In order for these relative paths to work the page has to be either running directly from the folder or the page has to be mapped into that page context.

In the context of a Web site that's simple as you have a natural page path that always applies. However, for previewing pages that are often rendered to a temporary file in an external location, which is then displayed in a WebView for preview. In that scenario relative path needs to be fixed up so it can find resolve links.

This scenario can be handled by explicitly forcing the page's <base> path to reflect the current page's path:

{{%
    if(Topic.TopicState.IsPreview)  { }}
       <base href="{{ Model.PageBasePath }}" />
{{%  }  }}

Note that I'm only applying the <base> tag in Preview mode. In Preview the Html is rendered into a temp location, so I map back to the actual location where relative content is expected and that makes relative links work.

Here's what that looks like:

Figure 2 - Providing a Page Base path when rendering to a temp location is crucial to ensure relative resources like images can be found!

Without the <base> path in the document, the page would look for the image in the rendered output location - in the TMP folder - and of course would not find the image there.

For final rendered output running in a Web Browser, this is not necessary as the page naturally runs out of the appropriate folder and no <base> path is applied.

Why not just render local output into the 'correct relative location' where relative content can be found?
For local preview that's often impractical due to permissions or simply for cluttering up folders with temporary render files. Generated files can wreak havoc with source control or Dropbox and permissions unless explicit exceptions are set up. I recommend that local WebView content that has dependencies should always be rendered to a temporary location and then be back-linked via <base> paths to ensure that relative paths can resolve.

Root Paths In Temporary Location

The other more important issue has to do with resolving the root path. This is especially important when rendering to a temporary file, but it can even be an issue if you create a 'site' that sits off a Web root.

For example, most of my documentation 'sites' live in a /docs folder off the main Web site rather than at the / root.

For example:

Markdown Monster Documentation

In this site, any links that reference / and intend to go back to the documentation root, are going to jump back to the main Web site root instead. From a project perspective I want / to mean the project root, but I don't want to have to figure out while I'm working on the content whether I have to use /docs/ or /. In fact, I never want to hard code a reference to /docs/ in my templates or in user content, but expect to reference the project root as /.

In DM this is very relevant when the site is generated. We can then specify a root folder / by default or /docs/ explicitly as shown here entered for my specific site:

Figure 3 - When rendering to a non-root location it has to be generated at Html generation time.

Here's what this looks like in the template (you can use either ~/ or /):

<link id="AppCss" rel="stylesheet" type="text/css" 
      href="~/_docmonster/themes/{{ theme }}/docmonster.css" />

and here is the rendered output with the /docs/ path for any / or ~/ starting Urls:

<link id="AppCss" rel="stylesheet" type="text/css" 
      href="/docs/_docmonster/themes/Dharkan/docmonster.css" />

This fixup applies to any Url generated both from the templates and from user generated topic content so the fixup has to occur post rendering - it's not something that can be fixed via the template.

This fixup also happens in Preview mode where the full path is prefixed which produces these nasty looking paths:

<link id="AppCss" rel="stylesheet" type="text/css" 
      href="C:/Users/rstrahl/Documents/Documentation Monster/MarkdownMonster/_docmonster/themes/Dharkan/docmonster.css" />

This means that the root path need to be fixed up depending on the root path environment. There are several scenarios:

Root is root / rendered into root of site for final Html Site output - no replacements required.
Root is a subfolder (ie. /docs/) - / is replaced with /docs/ in all paths
Root is the project folder from Temp location - / is replaced with a folder file location or WebView virtual host name root

This is something that is not part of the ScriptParser class, but rather has to be handled at the application layer post fix up, and it's fairly specific to the Html based generation that takes place. In my template based applications I always have do one form or another of this sort of fix up.

Here's what this looks like in DM:

string html = Project.TemplateHost.RenderTemplateFile(templateFile, model);

...

// Fix up any locally linked .md extensions to .html
string basePath = null;
if (renderMode == TopicRenderModes.Html)
{
 	 // fix up DM specific `dm-XXX` links like topic refs, .md file links etc.
     html = FixupHtmlLinks(html, renderMode);  

     // Specified value in dialog ('/docs/` or `/`)
     basePath = Project.Settings.RelativeBaseUrl;  // 
}            
else if (renderMode == TopicRenderModes.Preview || renderMode == TopicRenderModes.Chm)
{
	// special `dm-XXX` links are handled via click handlers
	
	// Project directory is our base folder
    basePath = Path.TrimEndingDirectorySeparator(Project.ProjectDirectory).Replace("\\", "/") + "/";
}

html = html
           .Replace("=\"/", "=\"" + basePath)
           .Replace("=\"~/", "=\"" + basePath)
           // UrlEncoded
           .Replace("=\"%7E/", "=\"" + basePath)
           // Escaped
          .Replace("=\"\\/", "=\"/")
          .Replace("=\"~\\/", "=\"/");
          
if(renderMode == TopicRenderModes.Preview ||
   renderMode == TopicRenderModes.Print || 
   renderMode == TopicRenderModes.Chm)
{
   // explicitly specify local page path
   var path = Path.GetDirectoryName(topic.GetExternalFilename()).Replace("\\","/") + "/";
   html = html.Replace("=\"./", "=\"" + path)
              .Replace("=\"../", "=\"" + path + "../");
}

OnAfterRender(html, renderMode);

return html;

The key piece is the Html fix up block that takes any / or ~/ links - including some variations - and explicitly replaces the actual base path that's specified.

Another issue is addressed in the following block that deals with print and local pages: Relative links don't resolve in print and PDF output, so they have to be explicitly specfied as part of the link. Apparently the WebView print engine ignores <basePath> for many things and so even relative links have to be fixed up with an explicit prefix even if the page is in the correct location.

So yeah - path handling is a pain in the ass! 🤣 But hopefully this section gives you the information you need to fix up your paths as needed.

Error Handling

When a template is run there is a possibility that it can fail. Typically it fails because there's an error in the template itself, which tends to generate compilation errors, or you can also run into runtime errors when code execution fails.

The ScriptParser automatically captures error information for both compilation and runtime errors are provides convenient members to access them. There's ErrorMessage and `` If an error occurs, DM checks for it and then generates an error page:

if (Script.Error)
{
    result = ErrorHtml();
    ErrorMessage = Script.ErrorMessage + "\n\n" + Script.GeneratedClassCodeWithLineNumbers;
}

where ErrorHtml() is the method that creates the error.

You can keep this real simple and just render the error message and optionally the code:

public string ErrorHtml(string errorMessage = null, string code = null)
{            
    if (string.IsNullOrEmpty(errorMessage))
        errorMessage = Script.ErrorMessage;
    if (string.IsNullOrEmpty(code))
        code = Script.GeneratedClassCodeWithLineNumbers;

    string result =
            "<style>" +
            "body { background: white; color; black; font-family: sans;}" +
            "</style>" +
            "<h1>Template Rendering Error</h3>\r\n<hr/>\r\n" +
            "<pre style='font-weight: 600;margin-bottom: 2em;'>" + WebUtility.HtmlEncode(errorMessage) + "</pre>\n\n" +
            "<pre>" + WebUtility.HtmlEncode(code) + "</pre>";                   

    return result;
}

Or you can present a nicer error page that itself is rendered through a template. This is the error page that is used in DM.

Figure 4 - Displaying render error information for debugging purposes

The code for this implementation is more complex.

public string ErrorHtml(RenderTemplateModel model, string errorMessage = null, string code = null)
  {
      if (string.IsNullOrEmpty(errorMessage))
          errorMessage = Script.ErrorMessage;
      if (string.IsNullOrEmpty(code))
          code = Script.GeneratedClassCodeWithLineNumbers;

      var origTemplateFile = model.Topic.GetRenderTemplatePath(model.Project.Settings.RenderTheme);            
      var templateFile = Path.Combine(Path.GetDirectoryName(origTemplateFile), "ErrorPage.html");
      string errorOutput = null;

      if (File.Exists(templateFile))
      {
      	  // render the error template
          var lastException = Script.ScriptEngine.LastException;
          model?.TemplateError = new TemplateError
          {
              Message = errorMessage,
              GeneratedCode = code,
              TemplateFile = origTemplateFile,
              CodeErrorMessage = errorMessage,
              CodeLineError = string.Empty,
              Exception = lastException
          };
          model.TemplateError.Message = model.TemplateError.WrapCompilerErrors(model.TemplateError.Message);
          model.TemplateError.ParseCompilerError();

          // Try to execute ErrorPage.html template

          bool generateScript = Script.SaveGeneratedClassCode;
          Script.SaveGeneratedClassCode = false;

          errorOutput = Script.ExecuteScriptFile(templateFile, model, basePath: model.Project.ProjectDirectory);

          Script.SaveGeneratedClassCode = generateScript;
      }

	  // if template doesn't exist or FAILs render a basic error page
      if (string.IsNullOrEmpty(errorOutput))
      {
          if (Script.ErrorMessage.Contains(" CS") && Script.ErrorMessage.Contains("):"))
          {
              errorOutput =
                      "<style>" +
                      "body { background: white; color: black; font-family: sans-serif; }" +
                      "</style>" +
                      "<h1>Template Compilation Error</h3>\r\n<hr/>\r\n" +
                      "<p style='margin-bottom: 2em; '>" + HtmlUtils.DisplayMemo(model.TemplateError.WrapCompilerErrors(errorMessage)) + "</pre>\n\n" +
                      (model.Topic.TopicState.TopicRenderMode == TopicRenderModes.Preview
                          ? "<pre>" + WebUtility.HtmlEncode(code) + "</pre>"
                          : "");
          }
          else
          {
              errorOutput =
                  "<style>" +
                  "body { background: white; color: black; font-family: sans-serif;}" +
                  "</style>" +
                  "<h1>Template Rendering Error</h3>\r\n<hr/>\r\n" +
                   "<p style='font-weight: 600;margin-bottom: 2em; '>" + WebUtility.HtmlEncode(errorMessage) + "</p>\n\n" +
                   (model.Topic.TopicState.TopicRenderMode == TopicRenderModes.Preview
                       ? "<hr/><pre>" + WebUtility.HtmlEncode(code) + "</pre>"
                       : "");
          }
      }

      return errorOutput;
  }

Summary

And that brings us to the end of this two-part post series. In this second part I've given a look behind the scenes of what's involved in running a scripting engine for site generation and local preview. As you can tell this is a little more involved than the basics of running a script template using the ScriptParser class as described in part one of this series.

Pathing is the main thing that can give you headaches - especially if there are multi-use cases of where your output is rendered. In the case of Documentation Monster, output can both be rendered into a final output Web site, or be used locally for previewing content from the file system and also be used for generating PDF and Print output which have additional specific requirements for pathing. The issues involved depend to some degrees on how you set up your application, but for me at least, I spent a lot of time getting the pathing to work correctly across all the output avenues. I hope that what I covered here will be of help in figuring out what needs to be considered, if not solving the issues directly.

I've been very happy with how using ScriptParser with its new features of Layout/Sections support works for this project. Given that I've been sitting in analysis paralysis for so long prior fighting with Razor, the results I've gotten are a huge relief, both in terms of features and functionality and performance. Hopefully the Westwind.Scripting library and the Script Templating will be useful to some of you as well.

Resources

Posted in .NET C#

Revisiting C# Scripting with the Westwind.Scripting Templating Library, Part 1

Rick Strahl — Wed, 01 Apr 2026 20:35:37 GMT

This is a two part series that discusses the Westwind.Scripting Template library

Part 1: An introduction to Template Scripting and how it works (this post)

Part 2: Real world integration for Local Rendering and Web Site Generation

Recently I updated my C# template scripting engine that uses a ScriptParser class in Westwind.Scripting by adding support for Layout Pages and Sections.

ScriptParser is a small, self-contained C# based template rendering engine that merges a text document with embedded expressions and code. It uses Handlebars-like syntax mixed with a simple mechanism for raw C# code expressions and code blocks. The scripting engine turns templates into executable .NET code that runs at native .NET speeds for fast template rendering.

Similar in concept to Razor, which also compiles templates down to runnable code, ScriptParser lets you use raw C# code as the 'markup language' in your templates using familiar Handlebars syntax. Raw C# is used for all language and structure constructs, so unlike some other Handlebars scripting solutions, there are no weird 'scripting language constructs' involved; the scripting language is just raw C#.

There are two main features to the Westwind.Scripting library:

C# Script Execution Engine
This is the core execution engine that allows you to compile and run C# code from source at runtime. You can execute code by providing a standalone snippet, a complete method, or an entire class definition to be loaded and accessed dynamically. The engine manages the full lifecycle of the script: generating the necessary wrapper code, compiling it via Roslyn, loading dependencies, caching the resulting assemblies for performance, and executing the compiled code. All of this including how it works is covered in a previous article.
Template Scripting Engine
The template scripting engine and the focus of this post series, leverages the execution engine by first parsing a Handlebars-style template into C# code, then compiling and executing the generated code. Templates use Handlebars-style syntax with {{ expression }} and {{% codeBlock }} tags to embed C# expressions and blocks within text using a model object passed in as the execution context. Expressions and code blocks can then access the model's data and methods to expand into the output. Templates can be executed from strings or files, with the model merged into the template as its data context. Because templates can contain code blocks, they can (but probably shouldn't) express complex logic.

In this post I'm only focusing on the latter Template Scripting Engine via ScriptParser, although that component uses the C# Script Execution after parsing.

ScriptParser isn't new and it has undergone a number of changes over its lifetime, but I realize now that I never mentioned it outside of the documentation. Since I spent a bit of time recently adding new features that add Layout Pages and Sections, this is as good a time as any to write about what it is and how it's been very useful to me.

Here's an overview of the template features:

Handlebars-like syntax using raw C# code
String based template execution
File based script execution
Support for Partials loaded from disk (both string and file scripts)
Support for Layout and Section directives (file scripts only)
Expressions and code blocks use raw C# syntax
Support for latest C# syntax
Uses native C# language constructs - no pseudo scripting language
Familiar Handlebars syntax with C# code:
- {{ C# expression }}
- {{% C# code block }}
- {{: html encoded Expression }}
- {{! raw expression }}
- {{@ commented block @}}
Code blocks can be used for:
- self contained code blocks
- Any C# structured statements (for, while, if, using etc.)
  can split across multiple code blocks with literal text, expressions and code blocks
  in between. It's all raw C# code!
Script parses to plain C# code at runtime
Compiled template generation code is very fast
- Expressions and Codeblocks execute directly (no Reflection or Expressions)
- Compiled code is very efficient
  - Code is compiled on first execution
  - First run is slightly slower
  - Subsequent invocation is faster
  - Code is cached to avoid re-compilation and startup cost on subsequent execution
Error Handling Support
- Captures Compilation and Runtime errors
- Compilation errors capture line numbers and source reference
- Runtime Errors can provide stack info
- Compiled source can be captured

Why Build?

So why not use Razor and build something completely from scratch? I built ScriptParser originally after I started several desktop and non-Web projects with Razor for templating using first an internal and then a third party Razor library, and eventually ran into walls with both of them.

Razor is great in full ASP.NET Web applications when you use it with integrated tooling in Visual Studio or Rider. For pure Web applications Razor is awesome! But when used elsewhere, between the complexity of running it outside of ASP.NET, the differences in behavior, the Html based formatting oddities for plain text use cases, the required ASP.NET runtime requirements and potential for runtime compilation going away, the crappy Razor language and terrible 'syntax highlighting' support in non .NET editors, plus the constant churn of the engine internals made me eventually give up trying to run Razor outside of ASP.NET Web applications.

I went back and forth between continuing on with Razor (and several other libraries like DotLiquid and Fluid) and building a custom engine, resulting in long stretch of analysis paralysis which made me put off going forward with several projects for some time!

At some point I decided I had enough and just build exactly what I needed! Since I had built script engines before (as far back as FoxPro in the early 90's no less) and decided it would be more efficient and flexible to do something similar in .NET. Turns out that was the right call: Even the original very limited version of ScriptParser I built ended up being a very small easily re-usable scripting engine that uses raw C# code and runs very fast at compiled speeds. The syntax isn't as fancy as Razor's neat C# syntax integration in HTML, but it also doesn't require fancy tooling in editors to be still readable in any Html or plain text editor which is actually quite important for non-ASP.NET applications. And almost any Html editor does a decent job with Handlebars syntax these days. And as a bonus the Handlebars syntax is generally more familiar and easier to understand than Razor syntax outside of .NET circles.

I also like the idea of having a fully self-contained, .NET-based scripting solution that is easily embeddable, and not dependent on the whims of some big and constantly shifting scripting environment. The ScriptParser implementation is simple and unlikely to change, as it's merely a parser plus raw C# code that generates output. If C# changes, the existing parser can accommodate that simply by adding the latest Roslyn libraries. There's nothing magic there. And for me personally that's a huge bonus!

Show me the Money!

If you want to jump to code and examples for the runtime compilation or C# Handlebars style scripting, head on over to the GitHub repo. The repo has all the info you need to get started quickly, and if you want you can look at the source code or check out the tests that demonstrate much of the functionality.

If you want to read more about the dynamic compilation features which are also used by this library to actually compile and run the templates, look at the previous blog post for the base Westwind.Scripting features:

Deep Dive on the Westwind.Scripting inner C# Compilation Workings (original release blog post)

Keep reading if you want to learn more about the template scripting and the new Layout/Section features.

A bit of Background on Westwind.Scripting and ScriptParser

The Westwind.Scripting library was originally created as a C# runtime source-code based compilation library, but it also includes the ScriptParser Template Engine. The template engine provides C# Handlebars-style templating that uses embedded raw C# code expressions and code blocks to compile templates into executable .NET code.

I originally created Westwind.Scripting almost 20 years ago, and it has gone through many behind the scenes iterations as compiler technology in .NET has changed. The latest incarnation a few years back updated the library to support the latest Roslyn compilation APIs At that time I also added the ScriptParser class for Handlebars-like script template parsing and execution using .NET expressions and code snippets.

My primary use cases have been for template snippet expansions with embedded expressions and logic in Markdown Monster and Html generation templates in several text-based documentation generation tools. The templating has been a great addition for those scenarios.

Installing the NuGet Package

To get started with the runtime compilation and/or the Template Scripting you can install a single NuGet package:

dotnet add package Westwind.Scripting

This installs the actual Westwind.Scripting library and also the .NET Roslyn compiler libraries required to handle runtime code compilation.

Rosyln Runtime Dependency

Unfortunately the Roslyn runtime compilation library Microsoft.CodeAnalysis.CSharp is not part of the distributed .NET Runtime, so this library has to be added explicitly, and it adds several MBs of Roslyn dependency DLLs to your application's distribution.

It's a small price to pay for the ability to dynamically compile code at runtime, but something to keep in mind.

Running Template Script Expansion

To give you a quick idea how ScriptParser class works with Handlebars {{ expression }} and {{% code block }} syntax and uses raw C# code here are is a short overview.

Expanding Expressions and Code Blocks

There are really just two constructs that make up template logic:

Expressions {{ expr }}

<i>{{ DateTime.Now.ToString("d") }}</i>

Code Blocks {{% C# code }}

{{% for(int x; x<10; x++  { }}     
    <div>{{ x }}. Hello World</div>
{{% } }}

{{%
     // declare variables
     var album = new Album() {
       Title = "Album Title",
       Band = "Rocka Rolla"
     }
     
     var message = "Rock on Garth.";
}}

<!--  use declared variables -->
<div>
{{ album.title }} by {{ album.band }}
</div>
<div>
	{{ message }}
</div>

You can also pass in a model parameter to the various script execution methods, which then become available as Model. in the script code.

Scripts compile to Class Methods

You can think of a template script as a method in a class where the majority of the template's text is treated as literal text that's written out with .Write() method, with the embedded expressions and codeblocks directly injected as raw C# method body code as is. This means variables declared are visible to expressions and code blocks below, along with the Model. property if a model was passed. The whole thing is combined into a C# class wrapper, that is then compiled on the fly, and optionally cached and executed.

One way to execute script templates in C# code with a passed in model looks like this:

var model = new TestModel {Name = "rick", DateTime = DateTime.Now.AddDays(-10)};

string script = @"
Hello World. Date is: {{ Model.DateTime.ToString(""d"") }}!
{{% for(int x=1; x<3; x++) 
{ }}
    {{ x }}. Hello World {{Model.Name}}
{{% } }}

And we're done with this!
";

var scriptParser = new ScriptParser();

// add dependencies - sets on .ScriptEngine instance
scriptParser.AddAssembly(typeof(ScriptParserTests));
scriptParser.AddNamespace("Westwind.Scripting.Test");

// Execute the script
string result = scriptParser.ExecuteScript(script, model);

Console.WriteLine(result);

Console.WriteLine(scriptParser.ScriptEngine.GeneratedClassCodeWithLineNumbers);
Console.WriteLine(scriptParser.ErrorType);  // if there's an error

As you can see in the script template string, the C# code expressions are just raw C# code wrapped into Handlebars blocks. Scripts are parsed into C# code, compiled at runtime into executable IL code, and then executed using standard .NET runtime execution. Output can be saved to assembly or executed immediately. Compiled code is automatically cached by default, so execution is very fast after the initial, one-time compilation step. If you re-run the same script or file template on the same script parser instance the cached assembly code is used.

All of the latest C# features are automatically supported in embedded expressions and code blocks matching the latest version support of the dependent Roslyn compiler assembly.

Adding Layout Pages and Sections

Basic script operation is useful, but often you need to componentize templates into re-usable sub-pages or master pages that simplify more complex site based setups like a documentation project.

To that effect, the initial implementation of ScriptParser until recently only supported {{ Script.RenderPartial("./partial.html") }} to pull in external templates. This allows pulling in of external code or files and executing them separately. While that works, use of Script.RenderPartial() can get very repetitive in larger projects if you need to simulate many pages that have similar high level layout and common document sections.

To that effect, the latest release of ScriptParser adds support for Layout Pages and Sections. Layout pages allow you to create a 'Master' page that is referenced from a 'Content' page. You can then have many Content pages that reference the same Master page to provide common UI Chrome that is common to all of those pages. The most common use case when creating a Web site/project, the common UI Chrome holds the main site layout (main panels, headers, footers, sidebars, logins etc.), but it could also be document headers for text generation for reports for example, or class wrappers for method code generations for example. Layouts can be super useful for a variety of use cases.

Figure 1 - Many Content pages request a shared Layout page into which content is loaded

Layout pages work only with files on disk so you point at a base basePath location for the template files. Based on that related files like Layout files and partials can be located based on relative or site root paths.

The process works like this.

Start by setting up and calling the script parser and calling ExecuteScriptFile() (or ExecuteScriptFileAsync()):

[TestMethod]
public void LayoutFileScriptTest()
{
    var scriptParser = new ScriptParser();
    
    // auto-encode {{ expr }}
    scriptParser.ScriptingDelimiters.HtmlEncodeExpressionsByDefault = true; 

    var result = scriptParser.ExecuteScriptFile("website/Views/Detail.html",
                        new TestModel { Name = "Rick" },
                        basePath: "website/Views/");

    Console.WriteLine(result);
    Console.WriteLine(scriptParser.ScriptEngine.GeneratedClassCodeWithLineNumbers);

    Assert.IsNotNull(result, scriptParser.ErrorMessage);
}

Next you specify:

The Template Script file to 'execute'
Provide a model to pass in (exposed a Model in the script)
Provide a root path for the templates
This allows paths that start with / or ~/ to find related scripts. Defaults the template's path so if everything is in the same path you don't need to pass this.

It's important that basePath resolves only for Layout and RenderPartial(). It doesn't automagically resolve other document Urls. We'll discuss how that can be handled towards the end of this post.

Next you'll have the Detail.html content page that is loaded from ExecuteScriptFile() call:

{{ Script.Section("StartDocument") }}
{{%
    // Script.Layout page is PARSED out of the document not executed
    // it supports  bracketed expressions from the script Model optionally.
    // Paths resolve as: Absolute, Relative to Script, ~ Base Path Relative or Base Path Relative without ~
    Script.Layout = "Layout.html";

    // this is explicitly projected into the Layout page
    // A better approach is to make anything you need in the Layout page 
    // part of the model, but for hard overrides this works.
    string title = "My Great Detail with Layout Page";
    Script.Title = title;
}}
{{ Script.EndSection("StartDocument") }}
<div>
    <!-- dynamic type cast from an Anonymous type: THIS FAILS! -->
    <h1>Welcome back, {{ Model.Name }}</h1>

    {{ Script.RenderPartial("Partial.html", Model) }}

    <p>This is the detail page content {{ DateTime.Now.ToString("t") }}</p>

    {{% 
        for(var i = 1; i <= 5; i++) {  
        // any C# code
        Model.Name = "Name " + i;
    }}       
    {{% } }}

    <h3>Inline Methods</h3>
    {{ Add(8,10)}}        
    {{%
        // Example of an inline function
        int Add(int a, int b)
        {
           return a + b;
        }
        writer.WriteLine(Add(5, 10));        
    }} 
  
    {{%
        var text = "This is & text requires \"escaping\".";
    }}

    Encoded:  
    {{: text }}

    Unencoded: 
    {{! text }}

    default (depends on ScriptDelimiters.HtmlEncodeExpressionsByDefault):
    {{ text }}

    {{%
        // write from within code blocks
        writer.WriteLine("Hello world, " + Model.Name);  // unencoded
        
        // write with HtmlEncoding
        writer.WriteHtmlEncoded( $"this text is basic {Model.Name}, but \"encoded\".\n" );
    }}
</div>

{{ Script.Section("Headers") }}
<style>
    body {
        background-color: lightblue;
    }
    <script> 
        var viewMode = { Name:"{{ Model.Name }}" };
    </script>
</style>
{{ Script.EndSection("Headers") }}

{{ Script.Section("Scripts") }}
<script src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
{{ Script.EndSection("Scripts") }}

This Html page is the entry point, but it's not what starts rendering the document since it references a Script.Layout = "Layout.html"; I could also have used "/Laytout.html" since we declared a base path in the C# code which points back to current folder.

The rest of the page then uses the passed in Model and shows a few examples of using expressions and script blocks.

Also notice that there are several Sections like this one:

{{ Script.Section("Headers") }}
<style>
    body {
        background-color: lightblue;
    }
    <script> 
        var viewMode = { Name:"{{ Model.Name }}" };
    </script>
</style>
{{ Script.EndSection("Headers") }}

This syntax refers to a Section defined in the Layout page into which the section's content is embedded.

To keep things simple, the Layout Page in this test scenario here is not very practical and simply shows a header, but it shows the different areas that are being filled in. In real application, this page likely would contain a top level Html layout with headers and footers, sidebars etc.

The key item below is the {{ Script.RenderContent() }} block that pulls in the content page:

{{ Script.RenderSection("StartDocument") }}
<!DOCTYPE html>

<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <title>{{ Model.Name }}</title>
   
        {{ Script.RenderSection("Headers") }}
    </head>
    <body>
        <header>This is a Site header</header>
        
        <!-- Merges in the Content Page's script before parsing and compiling -->
        {{ Script.RenderContent() }}

        <footer>
            <hr/>
            Site Footer here &copy; {{ DateTime.Now.Year}}
        </footer>


        {{ Script.RenderSection("Scripts") }}
    </body>
</html>

Content and Layout Merge into a Single Class Method

Layout and Content page using ScriptParser are combined into a single block of generated code at parse time. The Layout page renders first and merges the content from the Content page at the {{ Script RenderContent() }} block. The combined content is then parsed compiled and executed.

This means that any change to the Layout page requires rebuilding all the content pages that use that Layout page.

Notice also the sections that are declared in the Layout page and implemented in the Content page. Sections are pulled from the Content page and injected into the generated code at the defined section boundaries so they execute in order based on the location of the section definition in the layout page.

Here's another look at Content, Layout and Partials in single view in relation to each other.

Figure 2 - A test example that demonstrates Content, Partials, Layout and Sections in templates using Handlebars syntax. All files are .html files to facilitate editor syntax support.

I've needed this functionality for some time on several projects and finally after building it had the chance to put it into a production system that replaced the previous incomplete Razor engine that was holding up the project. The results in this documentation solution worked out great with fast performance and lots of flexibility for custom rendering and providing for customized rendering by combining both the Template Scripting and the underlying C# code generation to customize the exposed script API surface in scripts.

Eating my own Dogfood

So let me give a few examples how I've been using the Template Scripting features in various ways both with and without the new Layout Page features. Templating is not a common application scenario, but when you need it, you really need it and there are not a ton of options.

Here are a few scenarios where I'm using this templating engine now in production:

Markdown Monster Snippet Engine

Markdown Monster has a dynamic execution feature in the Markdown Monster for the Snippet Template Expansions and Commander Scripting Addin both of which allow Markdown Monster's functionality with dynamic code. Snippets uses dynamic text expansions in the markdown text editor, and Commander allows for application automation. The Snippets expansion uses the ScriptParser template expansion to mix text with C# expressions and code to produce embeddable text. The latter use pure code execution to perform automation tasks and has built-in support for text generation through the scripting engine.

Here's an example of the Snippets Addin in Markdown Monster, running user provided snippets:

Figure 3 - Snippet Expansion in Markdown Monster uses template expansions with C# code

Documentation Monster Topic Generation

I also use the ScriptParser to generate output for my documentation solution Documentation Monster which creates a self-contained Web site for documentation (Examples: here (product) and here (product) and here (generated class reference)). Html is generated from Templates for live previews in real time as you type and for final bulk output generation of the entire Documentation project. The process is blazing fast: 2.5k+ Html topics generated in ~10 seconds in one project.

Figure 4 - Documentation Monster renders topics in the previewer and eventually in a fully generated Web site of Html pages using various topic templates merged with topic content

Bulk E-Mail Generation for Notifications

I also use the script engine for creating a simple mail merge engine that runs against my customer and order database. I create mailing documents with embedded data that comes from various internal databases driven through a set of business objects. Code snippets at the top of templates drive the controller code, and the template expressions do the view rendering. In this case it's a background service console app that gets called every few days to check for renewals and sends out various generated and mail merged notifications on a regular schedule.

Code Generation

Recently I also upgraded an ancient legacy application that uses a SQL to entity generator tool for creating custom entities based on various structure code templates, that merge together multiple templates into code files. The old T3 templating was getting to be a pain in the ass to use and maintain so I switched out to a small console app using ScriptParser with mostly string based processing. The end result was much cleaner code that was more flexible as we could mix application logic with the template generation bits.

In short, this templating engine has proven very useful to me for a whole host of uses cases.

A look under the Hood of Westwind.Scripting and ScriptParser

We already looked at template rendering but let's look a little deeper at what gets generated and run, and at configuration and things you have to provide in order for code to compile.

So again, the simplest Script Rendering you can do is the following:

string script = @"
Hello World. Date is: {{ DateTime.Now.ToString(""d"") }}!

{{% for(int x=1; x<3; x++) { }}
{{ x }}. Hello World
{{% } }}

DONE!
";
var scriptParser = new ScriptParser();
var result = scriptParser.ExecuteScript(script, null);

// merged content as a string
Console.WriteLine(result);  

// Generated Class Code with Line Numbers
Console.WriteLine(scriptParser.ScriptEngine.GeneratedClassCodeWithLineNumbers);

// Error Information is available on the .ScriptEngine property
// which captures compilation and runtime errors
// ErrorType, ErrorMessage, ErrorException are available
Assert.IsNotNull(result, scriptParser.ScriptEngine.ErrorMessage);

The output from this is:

Hello World. Date is: 3/31/2025!

1. Hello World
2. Hello World

DONE!

Pretty straight forward and simple. In this case I'm not passing in a model, so the code just uses base C# and library code - it's using core .NET runtime features so there are no extra assemblies that need to be loaded.

By default the compiler and parser load a good chunk of common runtime libraries which works for core language features, but if you need additional types - like a model or runtime features not included - you have to explicitly reference them.

Here I have to add the model's type because the compiler doesn't know about it as it's contained in an external library (Westwind.Utilities):

var model = new TestModel { Name = "Rick", Date = DateTime.Now.AddDays(-10) };

string script = """
{{%
using Westwind.Utilities;
}}
Hello {{ Model.Name }}.
Date is: {{ Model.Date.ToString("d") }}!

{{% for(int x=1; x<4; x++) { }}
{{ x }}. {{ StringUtils.Replicate("Hello World ",x) }}
{{% } }}

And we're done with this!
""";

var scriptParser = new ScriptParser();

// Referenced types and required assemblies
scriptParser.AddAssembly(typeof(Westwind.Utilities.StringUtils));  // include a library
scriptParser.AddAssembly(typeof(TestModel));                       // include model/executing assembly

// Execute and pass the model
string result = scriptParser.ExecuteScript(script, model);

Console.WriteLine(result);

Console.WriteLine(scriptParser.ScriptEngine.GeneratedClassCodeWithLineNumbers);
Assert.IsNotNull(result, scriptParser.ScriptEngine.ErrorMessage);

Notice the .AddAssembly() calls. The relevant assemblies have to be present in the current execution path of the current (host) environment.

This template produces the following text:

Hello Rick.
Date: 2/5/2026!

1. Hello World 
2. Hello World Hello World 
3. Hello World Hello World Hello World 

And we're done with this!

There is also ExecuteScriptAsync() which allows for executing async code to execute in the script. Both ExecuteScript() and ExecuteScriptAsync() have several overloads that deal with how the model or parameters are handled.

In this example the model is passed in generically and parsed as a dynamic value that is passed to the template code. If you'd rather pass the model using a fixed type you can use the ExecuteScript<TModelType>() overload. If you know the type at execution time, the generic version is preferred as it gets around weird edge cases where dynamic might misinterpret types or null values, plus it's slightly faster.

If you look at the template code you see the {{ expression }} and {{% codeBlock }} tags.

To make it a little clearer what happens here's the for loop with some indentation and comments:

{{% 
	for(int x=1; x<3; x++) 
	{
	    var output = x + ". Hello World";
}}  
	<!-- End of top code block -->
	
	<!-- literal text with expression expansions -->
	<div>{{ output }}</div>
	
{{% 
    // You can add additional code here before closing tag
    Console.WriteLine(output);  
} }}
<!-- End of for loop -->

Expressions expand inline and simply replace the expression value for the tag. They are expanded as string values - by default rendering using ToString().

Code blocks are raw snippets C# code and they expand as-is into the generated code. They also strip off the linefeed at the end of the code block so generated text doesn't end up with extra line breaks.

Code Blocks can be single line blocks as shown in the first example, or multi-line code blocks that combine multiple operations as shown in the second example. When creating structured blocks (ie. if or for statements) with markup text between the start and end statements you need two code blocks for each part separated by additional markup in between. The markup in between can contain additional literal text, or nested expressions and code blocks.

Bottom line: Expressions and Code blocks are simply embedded as-is into the generated code with any text between embedded the markup writing out string literals and generate into raw C# code.

To give you an idea of a more real world example of a template here's one of my Documentation Monster topic templates in VS Code:

Figure 5 - A real world example of a template that renders a documentation topic for a Class Header.

You can see there's a mixture of expressions and code blocks and nested code blocks. Generally the template inline code is kept very simple. While it's possible to write complex C# logic in the template, personally I prefer code helpers for complex operations. For example, generating a Child Topics List as a list, or creating a list of members for a Class Header is much better done in code than an enormouse code block inline of the template. You can do that if you want to, but it's preferred to externalize complex logic to helpers on the model. The advantage is that you get to write your code in your development IDE with all the editor tooling and completions, and you can independently test the logic. Just as importantly: You can re-use the functionality in multiple templates.

Here's what this rendered template ClassHeader looks like:

Figure 6 - The rendered template has complex page elements that are rendered in external library code rather than embedding complex code into the template

References and Namespaces

In the first examples, I have to explicitly add references to the model type and utility library.

Because code gets compiled, the compiler needs to know all references that are used in the code you are executing. The current application's environment and loaded assemblies are not used by the compiler so everything has to be explicitly declared.

The script engine by default adds commonly used .NET Core base assemblies so it works with common base .NET base libraries. But if you use less common libraries or reference your own support assemblies and types including model types, you'll have to explicitly add those assemblies and also the namespaces - either in code or via the template. Regardless of whether they might already be loaded in your application as the compiler doesn't know about any of that.

.NET Core made this more complex due to its highly granular assembly usage. To help make it easier to add references there are a few high level helpers methods in the C# Execution engine and Script Parser:

Common .NET Runtime base libraries (default)
AddCommonDefaultReferences()
Common plus forward all loaded assemblies from the host application
AddLoadedReferences().
Note that assemblies have to be actually loaded at the time of compilation to be picked up, not just referenced by the application!
Explicitly add assemblies from types or from disk
AddAssembly() AddAssemblies()
Explicitly adding assemblies is usually easiest with typeof() unless the type is not used by the host:
```
  scriptParser.AddAssembly(typeof(ScriptParserTests));  // from type
```
Add all assemblies from a .NET Runtime Meta Reference Library
AddAssemblies()
This guarantees that all runtime libraries are loaded, but these meta libraries are large and add several megabytes of disk footprint to your application.

Here's how you add references and namespaces so the compiler can resolve your script code:

var scriptParser = new ScriptParser();

// Explicit references
scriptParser.AddAssembly(typeof(ScriptParserTests));  // from type
scriptParser.AddAssembly("./Westwind.Utilities.dll"); // from file

// Loaded References from Host (current assembly context)  
// be careful here: Not all referenced assemblies may be loaded when you call this
script.ScriptEngine.AddLoadedReferences();               

// If you add a Meta Data Reference Assembly to your project
scriptParser.AddAssemblies(metaAssemblies: Basic.Reference.Assemblies.Net100.References.All.ToArray());

// Add namespaces your code needs explicitly            
scriptParser.AddNamespace("Westwind.Scripting.Test");

Namespaces can also be added in code:

string script = """
{{%
using Westwind.Utilities;
}}
Hello {{ Model.Name }}.
Date: {{ Model.Date.ToString("d") }}!

{{% for(int x=1; x<4; x++) { }}
{{ x }}. {{ StringUtils.Replicate("Hello World ",x) }}
{{% } }}

And we're done with this!
""";

Assembly loading and explicit namespace requirements can be one of the more tricky things to get right when using the compilation and templating tools especially if you are integrating with a complex application and are exposing a broad application model to templates.

Take a look at Generated Code - no really!

The easiest way to understand how Literals, Expressions and Code Blocks work in templates is to look at the generated code from the script template above. The generated class source code can be captured via script.ScriptEngine.GeneratedClassCode or .GeneratedClassCodeWithLineNumbers which shows the entire generated class:

 1. using System;
 2. using System.Text;
 3. using System.Reflection;
 4. using System.IO;
 5. using System.Net;
 6. using System.Net.Http;
 7. using System.Collections;
 8. using System.Collections.Generic;
 9. using System.Collections.Concurrent;
1. using System.Text.RegularExpressions;
2. using System.Threading.Tasks;
3. using System.Linq;
4. using Westwind.Scripting;
5. using Westwind.Utilities;
6. 
7. namespace __ScriptExecution {
8. 
9. public class _yzf2irai
10. { 
11. 
12. 
13. public System.String ExecuteCode(Westwind.Scripting.Test.TestModel Model)
14. {
15. ScriptHelper Script = new ScriptHelper() { BasePath = null };
16. 
17. 
18. using( var writer = new ScriptWriter())
19. {
20. 
21. // using Westwind.Utilities;
22. 
23. writer.Write("Hello ");
24. writer.Write(  Model.Name  );
25. writer.Write(".\r\nDate: ");
26. writer.Write(  Model.Date.ToString("d")  );
27. writer.Write("!\r\n\r\n");
28. for(int x=1; x<4; x++) { 
29. writer.Write(  x  );
30. writer.Write(". ");
31. writer.Write(  StringUtils.Replicate("Hello World ",x)  );
32. writer.Write("\r\n");
33. } 
34. writer.Write("\r\nAnd we're done with this!");
35. return writer.ToString();
36. 
37. } // using ScriptWriter
38. 
39. }
40. 
41. 
42. } 
43. }

You can see that actual template script, is broken down into:

Class Header
This is basically a shell that wraps the code and includes all the added namespaces and class wrapper. This code is static and entirely generated by the CSharpScriptExecution class. The only thing that changes there is typically the class name and namespace.
Literal text
All non code text outside of the {{ }} tags is treated as a literal. In the generated code literals are parsed and formatted and then written out as properly encoded C# string literals which is why you see line breaks and other encoded text.
Expressions
Expressions are parsed and embedded - as-is - and written straight out as string values into writer.Write(). Non-string values are auto-converted using .ToString() on any non string value.
Code Blocks
Similar to expressions any code block code is written out as is but does not generate a writer.Write() since it's literally raw code. There's some additional logic that cleans up line breaks after code blocks to avoid extra line breaks introduced by the code tags (as Razor maddeningly does).

From a coding perspective the hardest part about all of this is the literal text parsing - finding all the places and special cases where literals get too long and have to be broken up and require special encoding or formatting.

There are also different tag prefixes that need to be parsed:

{{: expression }} - Explicitly Html Encoded
{{! expression }} - Always parsed as Raw Text - no encoding

Note that there's an option to automatically Html Encode all expression tags:

scriptParser.ScriptingDelimiters.HtmlEncodeExpressionsByDefault = true;

which makes the {{: expr }} syntax redundant but you may be required to use {{! expr }} occasionally to get raw Html or text rendered. If you're generating Html you'll want this set to true, but if you're generating text for code, scripts or other plain text output, you'll want to leave it at its false default.

Caching

Each template 'executed' compiled into an assembly that is eventually executed. Many templates means also many assemblies loaded into the current process.

The script engine by default caches generated template assemblies based on the generated code used as input. If you execute the same template multiple times, the previously cached assembly will be used instead, for much faster execution.

This means the very first time you run your template it might take a second or two as the Roslyn compiler is loaded for the first time. If you re-run the same template again it will be much, much faster. Compiling another template after the initial cold start will be significantly faster than the very first compile, but still slower than cached operation. Compilation even of moderately sized templates tends to be very quick, but ideally you'll want to compile once, and run many times to achieve best performance.

In most application situations templates get reused frequently. For example, in Documentation Monster I have 15 different topic templates of which 8 are actively used. Some of my help files contain a couple of thousand topics. So essentially I compile 8 templates once as they are first accessed, but I may generate two thousand topics from these 8 cached assemblies. When a script or layout page changes, the cache busts and the templates that require it automatically recompile - once - and then are reused many times more to render the other topics that use the same template. Using cached compilation I can compile my nearly 3500 topic documentation site to disk in less than 15 seconds.

Assembly caching uses a static object collection. Assemblies are loaded into the host process and by default can't be unloaded, hence the static collection. However, if you're adventurous you can create and provide your own AassemblyLoadContext to implement unload behavior on your own.

Error Handling

Error handling for templates is critical as you may run into compilation errors as you're creating your templates:

Figure 7 - A template compilation error shows code, so that you can cross reference back into your original template

Errors are captured on the ScriptEngine's ErrorMessage property. There are two scriptParser.ScriptEngine.ErrorType values:

Compilation
Runtime

If compilation errors occur in the generated code the scriptParser.ScriptEngine.ErrorMessage has error information pointing at specific line numbers into the generated code as shown in Figure 99 above. This can be super useful for scripting solutions: In Markdown Monster's Command Scripting Addin the errors and generated code are displayed so you can glance at the generated code and glean where the error occurred - in there I adjust the line numbers so they match up with the user provided code. It ain't exactly Visual Studios Error Pane but it's pretty good for a generic template solution to pinpoint the line of generated code where the error occurred that you can translate into whatever line that matches in your script.

Runtime errors provide less specific error information - you generally just get the exception and message returned. For runtime errors you likely want to catch the exception around the template execution block and either display the error message or handle it in some generic way via a custom method that generates formatted error output. The exception is preserved and passed forward so you can decide what to do with it - it's essentially up to your application how to display the error. More on that in part 2.

File Template Rendering and Layout and Sections

String rendering works for simple things, but if you're building more complex projects that involve multiple pages you're likely to use files to hold your templates. Unlike string based templates, file templates support Layout Pages and Sections.

If you want to render templates from disk, the base features work the same as with templates except you use ExecuteScriptFile().

If you're calling a single self contained template it works exactly the same as ExecuteScript()

var scriptParser = new ScriptParser();
var result = scriptParser.ExecuteScriptFile("website/Views/SelfContained.html", 
             new TestModel { Name = "Rick" });

Console.WriteLine(result);
Console.WriteLine(scriptParser.ScriptEngine.GeneratedClassCodeWithLineNumbers);
Assert.IsNotNull(result, scriptParser.ErrorMessage);

The template in this case is a self-contained Html page:

{{%
  Script.Title = "Self Contained Page";
}}
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <title>{{ Script.Title }}</title>
</head>
<body>
  <h1>This is a self contained page!</h1>

  <p>Hello, {{ Model.Name }}</p>

  <p>This page is self contained and doesn't require any external resources to render.</p>

  {{ DateTime.Now.ToString("d") }}
</body>
</html>

If you have a folder hierarchy for your templates you might need to explicitly specify a base path that acts as a root folder for the project. This is so that files can resolve the root folder as in /path/subpath/file in code for things like a referenced Layout or Partial pages.

Layout and Content Page in MultiPage Layouts

But it gets more interesting if you are working with multi-page layouts where you have multiple pages that use a common theme layout. You can separate out Content pages and Layout pages the latter of which provide the site chrome that can potentially be customized through the model that is passed to it.

In this scenario you have:

A Content Page that holds the current Page Content
A Layout Page that is referenced from the Content Page
Partial Pages loaded from either Content or Layout Pages

Let's start with the Content page. This page contains the relevant content that holds the current information to display. So in my documentation example, each topic renders as a Content page. The content page is the top level page that is referenced by the code that invokes the Template. The template then can optionally link a Layout page that provides the base layout which is then merged into the Content template as it's rendered and compiled.

var scriptParser = new ScriptParser();
scriptParser.ScriptingDelimiters.HtmlEncodeExpressionsByDefault = true;

var result = scriptParser.ExecuteScriptFile("website/Views/Detail.html",
                    new TestModel { Name = "Rick" },
                    basePath: "website/Views/");

Console.WriteLine(result);
Console.WriteLine(scriptParser.ScriptEngine.GeneratedClassCodeWithLineNumbers);

Assert.IsNotNull(result, scriptParser.ErrorMessage);

Here's the Detail.html content page - notice the Script.Layout = "detail.html" at the top that links in the Layout page. The page demonstrates a lot of the different features of the templates all of which should look familiar if you've used Razor/Blazor or ASP.NET Pages.

{{%
    // This code will execute at the top of the Layout page
    Script.Layout = "Layout.html";
}}
<div>
    <h1>Welcome back, {{ Model.Name }}</h1>

    
    {{ Script.RenderPartial("Partial.html", Model) }}

    <p>This is the detail page content {{ DateTime.Now.ToString("t") }}</p>

    {{% 
        string display = string.Empty;
        for(var i = 1; i <= 5; i++) {  
            // any C# code
            display = "Name " + i;
    }}
    {{ i }}. {{ display }}
    {{% } }}

    <h3>Inline Methods</h3>
    {{ Add(8,10)}}        
    {{%
        // Example of an inline function
        int Add(int a, int b)
        {
           return a + b;
        }
        writer.WriteLine(Add(5, 10));        
    }} 
  
    {{%
        var text = "This is & text requires \"escaping\".";
    }}

    Encoded: {{: text }}
    Unencoded: {{! text }}
    Default: {{ text }}

    {{%
        // write from within code blocks
        writer.WriteLine("Hello world, " + Model.Name);  // unencoded
        
        // write with HtmlEncoding
        writer.WriteHtmlEncoded( $"this text is basic {Model.Name}, but \"encoded\".\n" );
    }}
</div>

{{ Script.Section("Headers") }}
<style>
    body {
        background-color: lightblue;
    }
    <script> 
        var viewMode = { Name:"{{ Model.Name }}" };
    </script>
</style>
{{ Script.EndSection("Headers") }}

{{ Script.Section("Scripts") }}
<script src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
{{ Script.EndSection("Scripts") }}

Layout Page

The Layout page is loaded via a code reference to Script.Layout = "Layout.html";. This code can appear anywhere in code in the template. The page is referenced relative to the page it's called from - in this case in the same folder.

The Layout Page and the Content page are merged into a single text document before the code is parsed into code. This means the Layout page is passed the same model that the main content page has access to. This usually means that content pages need to use a common base model that has the data for the Content page and the Layout page. That means things like Title, Project Name etc. company info for the footer etc. Essentially the model contains both data for the content page and the layout page.

The content page is the entry point that references the layout page, but the layout page renders first and the {{ Script.RenderContent() }} section pulls the Content Page into the layout. Both are combined into a single C# program that is then compiled and executed.

Keep in mind that any code that runs in the Content Page runs after the top of the Layout page code has run.

IOW, by the time the first code inside of the Content page is executed, the Html header has already been rendered and any code blocks and expressions in the top of the Layout page have already run. This means for example that you can't set the title after the fact from the content page. You can use the model to hold the values you want to set, or you can use Sections to force content from the Content Page into the layout page at designated Section locations.

In the layout page you declare sections using {{ Script.RenderSection("StartDocument") }} which 'pulls' the content from the content page:

<!-- inject code here so it's available/set above Script.RenderContent() -->
{{ Script.RenderSection("StartDocument") }}
<!DOCTYPE html>

<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <title>{{ Model.Name }}</title>
   
        {{ Script.RenderSection("Headers") }}
    </head>
    <body>
        <header>This is a Site header</header>
        
        <!-- main content goes here -->
        {{ Script.RenderContent() }}

        <footer>
            <hr/>
            Site Footer here &copy; {{ DateTime.Now.Year}}
        </footer>

        {{ Script.RenderSection("Scripts") }}
    </body>
</html>

Sections

You've seen sections referenced in the previous snippet in the Layout page.

Sections are defined in a Layout page as a placeholder via {{ Script.RenderSection("SectionName") }} and implemented in Content pages via {{ Script.Section("SectionName") }} and {{ Script.EndSection("SectionName") }}. Any content between the two - literal text, expressions and code blocks are then embedded in the Layout page at the section placeholder location.

Layout Page

<head>
    <title>{{ Script.Title }}</title>
    {{ Script.RenderSection("Headers") }}
</head>

Content Page

{{ Script.Section("Headers") }}
<style>
    body {
        background-color: lightblue;
    }
    <script> 
        var viewMode = { Name:"{{ Model.Name }}" };
    </script>
</style>
{{ Script.EndSection("Headers") }}

The Layout page's RenderSection() pulls the markup from between the Content Page's section and embeds it into the template during the parsing phase as part of the process of creating a single executable file from the content and layout page.

Partials

Unlike Layout and Content pages (and Sections) which merge into a single template before parsing, partials are rendered like a standalone page based on a file on disk. For Html rendering Partials are typically Html fragments for a page sub-component.

<h3>
    This is some Partial Content, {{ Model.Name }} 
    at {{ DateTime.Now.ToString("HH:mm:ss") }}
</h3>

Partials can be called from Content Pages, Layout Pages and other Partial pages using the following syntax:

<hr />
    {{ Script.RenderPartial("Partial.html", Model) }}
<hr />

Note that you pass a model to the partial explicitly - typically you'll just pass forward the existing content page model but you can also pass something completely different here if it makes sense.

Using Layout pages and Sections is a key feature and I'm glad that functionality finally part of the ScriptParser class. It's made a big difference for several projects that previously suffered with lots of .RenderPartial() embeddings.

Summary

This brings us to the end of part 1 of this series.

In this post I've reviewed the core features of the Westwind.Scripting templating features and how you can use both string based and file template based scripting to quickly merge text with data using its simple Handlebars C# syntax and provided some insight how the template engine works behind the scenes.

In Part 2, I'll expand on usage in a real-world scenario for Html output generation from a desktop application, which involves a few extra steps to ensure that content generated locally works in Web environments. It'll demonstrate how to pass in application level data, format paths, handle site base paths in Web scenarios and a few other issues like dealing with dependency references.

Until then give this library a try and see where it might fit for your use cases.

Resources

Posted in .NET C#

Using .NET Native AOT to build Windows WinAPI Dlls

Rick Strahl — Sat, 21 Mar 2026 21:47:13 GMT

Here's something that I didn't know you could do: You can create AOT compiled DLLs that compile down to platform specific native DLLs. For example, on Windows you can compile an AOT library to a Standard Calling Convention type DLL that you can be called from any tool that can access WinApi-style dlls. C-Style DLLs are also supported but in this post I look at StandardCall (WinAPI style) DLLs for Windows.

I'm specifically looking at this for some Windows DLLs that I created eons ago using the Visual Studio C++ compiler to build the DLLs. Moving those into .NET and C# certainly would make a number of things easier including not having to install the Visual Studio C++ compiler and all its crazy Windows dependencies (C++ SDK, ATL etc.) and dealing with the constant version update hassles in Visual Studio when the compiler version revs and screws up dependencies.

My specific use case involves some very old FoxPro x86 code on the calling end, so I'll use FoxPro for my calling examples here. But the same applies for any application that can call into DLLs using either WinAPI standard call or optionally standard C calling syntax.

Setting up an AOT Project for native Windows DLL Compilation

So here's what you need to create an .NET AOT DLL for use as a Windows API (Standard Call) style DLL:

Create a new Class Library .NET 10+ project
Set it up for AOT compilation
Create a class with static methods with specific attributes to specify native Exports
Use dotnet publish to build the native DLL for each target platform

Let's start with the project file. To build a DLL you'll use a standard Class Library project and then add a couple of explicit tags:

<Project Sdk="Microsoft.NET.Sdk">
	<PropertyGroup>
		<TargetFramework>net10.0</TargetFramework>
		<ImplicitUsings>enable</ImplicitUsings>
		
		<!-- These are the critical settings -->
		<PublishAot>true</PublishAot>
		<NativeLib>Shared</NativeLib>
		<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
	</PropertyGroup>
</Project>

PublishAot and NativeLib are the keys for creating a DLL library. AllowUnsafeBlocks is optional but likely needed if you do any sort of P/Invoke code which is likely if you end up pushing reference values in and out of the DLL.

Next create a class and add the appropriate attributes to static methods that make up the exports:

public static class Exports
{    
    [UnmanagedCallersOnly(
        EntryPoint = "Add",
        CallConvs = new[] { typeof(CallConvStdcall) })]
    public static int Add(int a, int b)
    {
        return a + b;
    }
}

The key bit here are the [UnmanagedCallersOnly] attribute which marks the method for external access. For Windows Standard Call or 'WinApi' style DLLs you can specify the CallConvStdcall type which is required in order to generate the DLL export, so the exported function becomes visible.

Next you need to build the project. A plain dotnet build just builds a .NET DLL not an AOT DLL. In order to create the native DLL you have to use dotnet publish.

Open a terminal in the project folder and then use:

dotnet publish -c Release -r win-x64 /p:PublishAot=true
dotnet publish -c Release -r win-x86 /p:PublishAot=true

You should publish for each of the platforms you want to target.

the /p:PublishAot is technically not required since we specify it in the project file, but if you don't, this is how you can override the project value for AOT compilation explicitly at build time.

To call the generated DLL externally - using FoxPro in my case - I can do the following:

lcDll = FullPath("wwDotnetBridge_Loader.dll")

DECLARE integer Add;
     in (lcDll) ;
     as DotnetAdd ;
     integer a, integer b 
     
? DotNetAdd(1,5)

Et voila: You now have a Windows compatible DLL that you can call from another application.

The file is 850k - not exactly tiny but considering it's .NET code that's not bad. As you add .NET features though, the size of the DLL gets bigger and fast. Obviously the code above does very little and relies only on core language features and no library calls, so that's about as small as the DLL you can get. From here any dependencies used increase the size of the DLL. Any library you reference or call, AOT will pull out the code you are using (if it's compatible even) and include it in the AOT DLL. So the more diverse code you call - the bigger the library gets.

For reference, for the entire samples I show in this post (which are all very minimal!) the size will end up at about 1.5mb.

It's .NET but it's different

Although you're building your code with .NET, a Windows native DLL that is called using external non-.NET code has to behave more like a C/C++ method than what you're used to in a .NET interface. While you can easily pass primitive parameters like the integers I passed above for just about anything else you have to fall back to C style calling conventions. This means using pointers for strings and objects, ints for boolean values and so on. The only straight through values pretty much are number primitive types (int, long, double, single).

This makes passing parameters in and out a lot more tedious especially in a client that doesn't have explicit support for structured fixed-sized types.

Here's an example of passing strings in and out:

[UnmanagedCallersOnly(
    EntryPoint = "StringInStringOut",
    CallConvs = new[] { typeof(CallConvStdcall) })]
public static int StringInStringOut(IntPtr input, IntPtr output)
{
    // retrieve the input buffer        
    string inputStr = Marshal.PtrToStringAnsi(input) ?? string.Empty;


    // get the empty buffer for size
    string outputStr = Marshal.PtrToStringAnsi(output) ?? string.Empty;
    if (outputStr.Length < 1)
        return 0; // output buffer too small

    var result = inputStr + " !!!"; // "Echoing back your message:\r\n\r\n" + inputStr;

    WriteAnsiString(output, outputStr?.Length  ?? 0 , result);
    return outputStr.Length;  // success
}

In typical Windows API style string output is passed in as a buffer address that is filled by the method. Input too comes in as a pointer that has to be dereferenced back into a string first.

To call this from FoxPro looks like any other Windows API call and requires passing in a pre-allocated buffer by reference for the return value:

DECLARE integer StringInStringOut ;
     in (lcDll) ;
     string input, string@ output

lcOutput = SPACE(255)
? StringInStringOut("Hello World. Time is: " + TIME(), @lcOutput)
? lcOutput

It's also possible to pass back a generated string, but then your calling code will be responsible for releasing the memory allocated for the string which is even more of a pain than passing in a pre-allocated buffer.

None of this is new or different than calling Windows APIs or most StdCall DLLs. While you can use .NET code to write your method logic, the call and return interface is still tightly bound to the very low level DLL calling standard and accordingly more verbose than simple parameter and result value passing.

Objects? Yes but no Thanks!

Object passing is even more painful especially when you work with a non-structured client like FoxPro that can't easily construct a fixed structure. For objects, the best way is to use Structures with fixed layouts that can be filled and read by the client.

Here's an example of passing data in via a structure, updating it and passing it back:

[StructLayout(LayoutKind.Sequential, Pack = 1, CharSet = CharSet.Ansi)]
public struct PersonInfo
{
    public int Id;
    public double Amount;
    [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 64)]
    public string Name;
}

[UnmanagedCallersOnly(
    EntryPoint = "ProcessPerson",
    CallConvs = new[] { typeof(CallConvStdcall) })]
public static int ProcessPerson(IntPtr personPtr)
{
    if (personPtr == IntPtr.Zero)
        return -1;

    // read the structure from the VFP buffer
    var person = Marshal.PtrToStructure<PersonInfo>(personPtr);

    var id = person.Id; // return val        
    
    // Update fields
    person.Id += 100;
    person.Amount += 10.00;
    person.Name = "Updated from .NET";

    // Write updated struct back into same VFP buffer
    Marshal.StructureToPtr(person, personPtr, false);

    return id;
}

From FoxPro this code is ugly as you have to create the binary layout via string construction. Here's what that looks like:

lcStruct = ;
    BINTOC(11, "4RS") + ;        && int Id
    BINTOC(99.95, "8B") + ;       && double Amount - verify format
    PADR("Rick", 64, CHR(0))      && fixed char[64]
? lcStruct

DECLARE INTEGER ProcessPerson IN (lcDll) STRING@ person

lnResult = ProcessPerson(@lcStruct)
? lnResult  && 11

***  retrive the data back out
lnId = CTOBIN(SUBSTR(lcStruct, 1, 4), "4RS")  
lnAmount = CTOBIN(SUBSTR(lcStruct, 5, 8), "8B")
lcName = SUBSTR(lcStruct, 13, 64)
lcName = LEFT(lcName, AT(CHR(0), lcName + CHR(0)) - 1)

? lnId    && 111
? lnAmount
? lcName

Yeah that's not pretty, but it gives you the idea of how to pass complex data in and out using StdCall DLL interface. This isn't any better than standard C/C++ because we're building a native DLL.

There are FoxPro libraries that can help with structure conversions (Vfp2C32) but even then this process is tedious and error prone especially if structures change.

When does this make Sense?

I was pretty excited about using C# to create DLL interfaces and replace some of my ancient, nearly unmaintainable native DLLs. Using C/C++ for critical components is a PITA, and it requires installing the C compiler plus a pile of dependencies that seem to break every time the compiler or Windows SDK revs. So yes, replacing C with C# and AOT compilation sounds like a great idea.

But... there are issues. I use .NET interop a lot from different applications, and one thing that has always bugged me is the loader DLL that spins up the .NET Runtime Host. For one, that code is incredibly dense, and difficult to understand and horribly under documented by Microsoft. So much so that even with the help of LLMs, I've gotten this wrong many times before ending up on a shakey foundation that worked but that I don't 100% understand. I was hoping by bootstrapping through .NET that would be easier, but unfortunately, COM wrapper interfaces aren't part of AOT so there's no 'built-in' mechanism to pass back a .NET reference from without re-constructing the COM wrapper infrastructure. And even if it would be available, startup would likely bloat into multi-megabyte territory, which is unacceptable.

On top of that the reality is that to do anything productive with this tech, you still have to use the same awkward calling syntax that makes C-style DLL code painful outside of C code in the first place. AOT doesn't change that. And if you need serious C# functionality with runtime dependencies, you'll likely end up with a fairly large DLL anyway.

For any environment that has access to COM, I'd recommend sticking with traditional ways to call into .NET via COM interop or something like wwDotnetBridge to bootstrap and then communicate over COM with the .NET object. Yes, that's not native code, but you get a much cleaner calling interface, and performance is only slightly slower for call overhead, and first time JIT compilation. After that, I wouldn't expect any meaningful performance difference of JIT compiled code versus native AOT compilation.

I can still see this being useful in a few places. I may still end up using it for my wwDotnetBridge bootstrapping DLL although it'll end up being a bit more work than I'd hoped. Even though I can't use runtime libraries directly to get the .NET Runtime hosted, I might be able to make it work with P/Invoke calls. The main benefit for me would be dropping the C compiler from my build pipeline, which would be a win.

That leaves environments that have good native C interfaces like Python or no easy COM interfaces. Basically any scenario where you'd opt to use C/C++, the .NET AOT route might be an option.

Summary

In the end using AOT to create native DLLs is a very niche feature that has a very narrow optimal usage range that probably benefits only certain bootstrapping scenarios. Almost everything else is probably better handled with full .NET interop with the same performance profile other than initial JIT compile overhead.

The only benefit I see here really is for people like me who dig out C++ every 5 years for some system level interface, only to take 2 weeks to create something that would take 10 seconds in .NET 😄 And with LLMs today that probably can compress down to 1 hour and some incomprehensible C/C++ code 😂.

However, if you find yourself with one of those very narrow use cases, I hope this post has given you the background for what you need to know to create your AOT DLLs...

Posted in .NET C# Windows

Azure Trusted Signing Revisited with Dotnet Sign

Rick Strahl — Mon, 02 Mar 2026 20:10:23 GMT

In this follow-up post to my previous guide on Azure Trusted Signing, I explore how the new `dotnet sign` tool significantly simplifies the code signing process compared to the traditional `SignTool` workflow. The post identifies `dotnet sign` using `artifact-signing` as a faster, more efficient alternative.

Don't use the Microsoft Timestamp Server for Signing

Rick Strahl — Thu, 26 Feb 2026 22:41:03 GMT

The default Microsoft timestamp server frequently causes intermittent failures during the code-signing process, particularly when processing many files or large binaries as part of a application distribution. These reliability issues can be resolved by replacing the Microsoft timestamp server with a more stable, compatible third-party alternative.

Reliably Refreshing the WebView2 Control

Rick Strahl — Thu, 05 Feb 2026 07:53:22 GMT

The WebView2 control lacks a direct `Reload(noCache)` overload that forces a browser hard reload of the current page. Instead content is loaded with a soft refresh that - hopefully - reloads the current page and its dependencies dependent on WebView environment and server cache policies. In this post we'll look at how to work around this limitation and force a hard refresh in several different ways.

What the heck is a `\\.\nul` path and why is it breaking my Directory Files Lookup?

Rick Strahl — Mon, 08 Dec 2025 23:15:18 GMT

I've been trying to track down an odd bug in my logs related to Null device failures in directory lookups which have been causing application level exceptions. In some odd scenarios these null mappings are showing up for files. In this post I take a look at what they are and how to work around them for this very edge case scenario.

Using the new WebView2 AllowHostInputProcessing Keyboard Mapping Feature

Rick Strahl — Thu, 21 Aug 2025 03:17:34 GMT

If you've used the WebVIew2 control for a UI interactive Hybrid active you've probably run into some odd keyboard behavior, where some keys cannot be captured properly in the host application or are not forwarded quite the way they normally behave. In the newer releases of the WebView SDK there's a new option called `AllowHostInputProcessing` that allows for forwarding keyboard events more aggressively to the host which fixes some Windows behaviors and introduces some new issues.

Fighting through Setting up Microsoft Trusted Signing

Rick Strahl — Mon, 21 Jul 2025 00:56:23 GMT

It's that time of year again to update my CodeSigning certificate, only to find out that the rules have changed since I last did this. Certs now require either a physical hardware key or a online service provides the non-exportable keys to sign binaries along with massive price increases for the privilege. So I decided to give Microsoft's new Trusted CodeSigning service a try, and while that entails all the joy of setting up Azure services, at the and of the day it works and is a considerably more economical way for CodeSigning to work. In this post I describe how to set this up hopefully to help you avoid some of the pain I went through.

Centering a WPF TreeViewItem in the TreeView ScrollViewer

Rick Strahl — Wed, 16 Jul 2025 04:23:03 GMT

One of the annoying features of the TreeView in WPF is the inability to easily select and make an item prominently visible. While there is `TreeView.BringIntoView()` it doesn't do a good job dropping the item that the very bottom (or top) of the viewport with no way to center. In this post I show a few helper methods that facilitate this process and a few related tasks with some useful TreeView helpers.

Unpacking Zip Folders into Windows Long File Paths

Rick Strahl — Sun, 22 Jun 2025 11:00:48 GMT

Ah, long file paths bit me again today - this time with `ZipFile.ExtractToDirectory()` not unzipping long path files, even when specifying long path syntax for the output folder. In this post I briefly review Windows long path issues again, and describe what doesn't work and how to work around this particular problem. While specific to `ExtractToDirectory()` a similar approach might apply to other batch file based operations.

Adding Runtime NuGet Package Loading to an Application

Rick Strahl — Tue, 10 Jun 2025 04:40:37 GMT

It's not a common use case, but if you need need to dynamically add external code at runtime, NuGet packages are the most familiar way for developers to add that functionality besides old-school direct assembly loading. In this post I look at my LiveReloadServer local Web Server tool and how I integrated both external assembly loading and NuGet package support to allow extensibility for the Razor (and Markdown) scripting functionality of LiveReloadServer.

Distinguished Name on FileZilla Server Self-Generated Certs

Rick Strahl — Fri, 06 Jun 2025 20:44:04 GMT

Renewing Filezilla certificates I've run into a 'huh?' moment a few times trying to renew the self-signed certificates for the Administration interface. Trying the obvious entries of putting in the DNS names results in an error that's not perplexingly is fixed by providing a full Common Name instead.

Configuring Microsoft.AI.Extensions with multiple providers

Rick Strahl — Sat, 31 May 2025 08:56:33 GMT

Microsoft.Extensions.AI is the new base library for creating AI clients in an abstracted way. While the library does a great job with the abstraction of the interfaces it works with, the provider interfaces that create the intial abstractions like IChatClient are a lot less user friendly with hard to discover syntax based on extension methods and different syntax for each provider. In this post I review three providers and how to get them instantiated along with a small streaming example to use them.

Lazy Loading the Mermaid Diagram Library

Rick Strahl — Sun, 11 May 2025 09:26:29 GMT

The Mermaid library is a large beast, and if you're using it selectively in your Web content you probably want to make sure you don't load it unless you actually need it, due to it's download footprint and load time. If you're loading Mermaid with server only code it's pretty straight forward, but if you use it on the client there you may want to delay loading the library until you actually need to display a diagram.

WebView2: Waiting for Document Loaded

Rick Strahl — Tue, 06 May 2025 21:50:16 GMT

WebBrowser loading is always async and the WebView2 control is no different - in fact it's more complex as there a number of events that need to be handled in order to properly handle loading the control. In this post I describe how you can create a simplified load checking routine, or use the Westwind.WebView library and WebViewHandler to wait on content and process document access using linear `await` syntax.

Avoiding WPF Image Control Local File Locking

Rick Strahl — Mon, 28 Apr 2025 22:01:46 GMT

WPF locks local images when referenced via a Source attribute. In this post I discuss why this might be a problem and how you can work around it using native XAML and custom binding converter that provides a consolidated approach that includes image caching for better performance of reused images.

The Strong ARM of .NET: Wrestling with x64 and Arm64 Desktop App Deployment

Rick Strahl — Sat, 19 Apr 2025 08:35:43 GMT

.NET works great for cross-platform development making it easy to build apps that are cross-platform and cross-architecture specifically for x64 and Arm64. However, building a distributable application that can install and run out of box on both of these platforms, that's a bit more effort. In this post I discuss some of the gotchas and how to work around them to distribute apps that run out of the gate on both platforms.

Using Windows.Media SpeechRecognition in WPF

Rick Strahl — Tue, 25 Mar 2025 04:33:00 GMT

Windows has a pretty capable SpeechRecognition engine built-in via Windows Media services. In .NET these features are accessible via the Windows SDK (WinSdk) that expose these Windows features to .NET applications. In this post I discuss how you can integrate these features into a WPF application, and discuss some of the pitfalls along the way that you have to watch out for related to the SDK integration 'features'.

Making Html Input Controls Truly ReadOnly

Rick Strahl — Fri, 14 Mar 2025 20:26:04 GMT

A discussion of how to show readonly controls in user interface and ensuring that they are not UI activated. This post discusses readonly and disabled behavior and how you can make readonly behave better if you choose to use it over disabled.

Accessing Windows Settings Dialogs from Code via Shell Commands

Rick Strahl — Thu, 13 Mar 2025 22:40:22 GMT

Windows has support for an `ms-setting:` Protocol Handler/Uri Scheme that allows you to directly open most Windows settings dialogs directly via simple Url based shell commands.

Resolving Paths To Server Relative Paths in .NET Code

Rick Strahl — Sun, 09 Mar 2025 06:39:18 GMT

ASP.NET Core has support for resolving Urls in Controllers and Razor Pages via embedded `~/` links in Views and via `Url.Content()`. But, these features are tied to Controllers or Razor Pages - what if you need to resolve Urls elsewhere, in middleware or even inside of business logic? In this post I describe how you can build a couple of helpers that are more flexible and also provide some additional functionality of resolving site root and relative paths to full site root paths.

Inline Confirmations in JavaScript UI

Rick Strahl — Thu, 27 Feb 2025 09:02:10 GMT

Confirmation dialogs or modal popups can be annoying in HTML applications. What if you could instead use an inline UI to confirm an operation? In this post I describe a simple way you can use an inline UI to confirm an operation that can be easily implemented with a few lines of code and a couple of binding directives.

Retrieving Images from the Clipboard Reliably in WPF Revisited

Rick Strahl — Sat, 22 Feb 2025 08:09:36 GMT

The WPF Clipboard is notoriously bad for retrieving image data, mainly because of the funky behavior of the ImageSource control into which clipboard data is loaded. WPF cuts a lot of corners when retrieving images and there are many scenarios where Clipboard.GetImage() either crashes or doesn't render the supposedly successfully retrieved image. In this post I review some of the challenges and how you can work around the retrieving an ImageSource with an intermediary load of a bitmap in between to provide reliable image retrieval from the clipboard in WPF.

Comparing Raw ASP.NET Request Throughput across Versions: 8.0 to 9.0 Edition

Rick Strahl — Sun, 19 Jan 2025 22:51:02 GMT

Once again I'm taking a look at the newish .NET release and how it compares to the previous release - this time .NET 9.0 from .NET 8.0. I'll run my simple load tests to compare performance and also discuss a number of anecdotes from running .NET 9.0 in production apps for the last couple of months.

Back to Basics: Using the Parallel Library to Massively Boost Loop Performance

Rick Strahl — Fri, 27 Dec 2024 23:37:19 GMT

I recently had another occasion to add Parallel.ForEachAsync() into an application to improve performance of an Http look up operation drastically. When I tweeted a note on X there was quite a bit of response, so I thought I follow up and discuss Parallel use in this use case and when it makes sense to use Parallel in applications.

Getting the Current TabItem when the Tab is not selected in WPF

Rick Strahl — Sat, 09 Nov 2024 09:10:44 GMT

There's no direct support in WPF to find the control that the mouse is hovering over in Items controls like the TabControl, so if you need to bring up context sensitive information like a context menu or tooltip it takes a little extra effort to get the correct item to work with in this case ContextMenuOpening.

Using SQL Server on Windows ARM

Rick Strahl — Thu, 24 Oct 2024 21:59:54 GMT

I recently got a SnapDragon X Elite ARM device to play with and while I've been impressed with all things that work very well on it, one thing did not install easily: SQL Server. There's no ARM version of SQL Server and the x64 versions don't run on ARM devices. Docker images are also amd64 so that didn't work well either. Turns out you can use LocalDb onin emulation mode, but setting it up is anything but intuitive. In this post I discuss how to get SQL Server to run on a Windows ARM device.

Getting the ASP.NET Core Server Hosting Urls at Startup and in Requests

Rick Strahl — Wed, 04 Sep 2024 09:31:35 GMT

Ever need to retrieve an ASP.NET application's hosting Urls? There are million ways to set these URLs but there's no easy fixed location where you can pick the addresses up from. Instead you have to go through a bit of a dance, and use one of two approaches depending on whether you need the addresses during startup or inside of a request.

Nuking Local Nuget Package Sources to show newly Published Packages

Rick Strahl — Sun, 04 Aug 2024 23:52:12 GMT

Every once in while when I publish a NuGet package and then try to use the published package in another project I end up with a situation where the new package simply is not recognized. Most of the time it shows up after a few minutes, but on more than a few occasions I've stuck waiting for quite a while waiting for the package cache to refresh. Luckily there's a way to nuke the cache and force Nuget to re-read local packages and while that is the nuclear option that requires downloading a lot of packages it works to make your project compile - right now!

Create a .NET PlantUML Markdown Render Extension

Rick Strahl — Mon, 29 Jul 2024 22:16:35 GMT

PlantUML is a Web based diagramming markup language that can be used to create diagrams using text descriptions that are rendered into images via a PlantUML server. In this post I describe how you can integrate PlantUML image rendering into your .NET application, specifically from a Markdown rendering perspective as Markdown documents are the most common mechanism that PlantUML output is delivered.

Back to Basics: Await a Task with a Timeout

Rick Strahl — Thu, 25 Jul 2024 21:48:00 GMT

Sometimes it's useful to call async methods and be able to stop waiting after a given timeout period. Unfortunately there's no native support on Task to provide this. In this short post I show how you can simulate timeouts and provide a couple of helper methods to make the process generically available.

Work around the WebView2 NavigateToString() 2mb Size Limit

Rick Strahl — Tue, 23 Jul 2024 07:53:44 GMT

The WebView2 control's NavigateToString() method has a limit for the string size of 2mb, which can be a problem especially for HTML pages with embedded content. In this post I'll describe how this problem can show up and show a couple of ways to work around the issue.

Dealing with Platform Specific Classes and Methods in CrossPlatform .NET

Rick Strahl — Fri, 19 Jul 2024 07:02:59 GMT

If you deal with old .NET library code that is sprinkled with some Windows specific code in places you've likely run into places where the Windows specific code is throwing up unwanted compiler warnings. Sometimes that matters, but often times these warnings are annoyances as these methods are highly unlikely to get called from x-platform code. In this post I describe some annoyances, how you can work around them and eventually fix the issues without throwing everything out the window.

C# Version String Formatting

Rick Strahl — Fri, 14 Jun 2024 06:12:37 GMT

I'm tired of trying to format versions for user facing interfaces after fumbling with it again and again. In this short post I show a small helper extension method that lets you configure how to form user friendly version strings to display to end users.

Mime Base64 is a Thing?

Rick Strahl — Mon, 27 May 2024 07:50:45 GMT

Ran into an old legacy application recently that required that attached data was preformatted to Mime Base64 which I never even heard of before. Turns out it's a 'url-safe' version of base64 that replaces certain characters that can be present in base64 with 'safe' characters. In this short post I show a small helper that handles several Base64 Mime operations.

Speed up your Start Menu by disabling Web Search

Rick Strahl — Sat, 04 May 2024 06:53:30 GMT

If you're like me, you've probably cursed the Windows Start menu from time to time, when it's either very slow to pop up, or in some instances fails to pop up at all when you press the Windows key. This simple tip can drastically improve performance of your Windows Start Menu by simply disabling Web search.

ASP.NET Core Hosting Module with Shadow Copy Not Starting: Separate your Shadow Copy Folders!

Rick Strahl — Mon, 29 Apr 2024 01:06:35 GMT

I recently ran into a major failure related to Shadow Copying for an ASP.NET Web app on IIS which was caused by corruption of the Shadow Copy directories. The app starts with the dreaded white ANCM Error page and event log entries that point at missing application folders. It turns out that this is caused by interference of multiple applications using the same shadow copy folder. In this post I describe the problem and how to work around it.

Programmatic Html to PDF Generation using the WebView2 Control with .NET

Rick Strahl — Wed, 27 Mar 2024 07:59:52 GMT

In this post I describe how to use the Microsoft WebView2 control to automate HTML to PDF generation generically for any kind of Windows application, including services. We'll look at the WebView and it's printing functionality and some of the intricacies that are involved in hosting the WebView control outside of a desktop application context to provide unattended mode even in service context.

Comparing Raw ASP.NET Request Throughput across Versions

Rick Strahl — Fri, 08 Mar 2024 10:21:08 GMT

When I set up a new machine I usually use a small ASP.NET test project to get a feel of performance of the machine and when that happens I also take a moment to compare performance across recent versions of .NET to see how things are improving - and improved they have. Both due to the new hardware I'm using but also ASP.NET continues to bump up performance in every new version that comes out. In this post I describe a simple project with minimal do nothing requests to test the ASP,.NET pipeline locally and how to test these request as well as discussing the results.

Reading Raw ASP.NET Request.Body Multiple Times

Rick Strahl — Tue, 20 Feb 2024 23:08:09 GMT

Some time ago I wrote about accessing raw request body content in ASP.NET Core which ended up being one of the most popular posts on this blog. But I failed to mention one major caveat: By default Request.Body can only be read once. In this post I discuss why frequently when you need raw Request.Body access you actually need to read the body more than once, and you can enable that functionality and deal with the caveats of doing so.

Sharing Tab Missing in Windows 11 Folder Properties

Rick Strahl — Wed, 10 Jan 2024 22:54:27 GMT

For some unfathomable reason, Windows 11 has removed the Sharing Tab on the Explorer Properties Context menu by default. The Sharing Tab allows you to shared folders and drives for remote access. In this post I discuss how to get the Sharing Tab back and also touch on how to make sure your machine can actually accept remote connections so you can share your folders and drives.

Working around the WPF ImageSource Blues

Rick Strahl — Thu, 04 Jan 2024 05:36:29 GMT

The WPF Image control and its ImageSource property can be problematic if you are loading a lot of images in a list. Depending on where you load images from, and how, you can very easily get bogged down with slow, blocking load operations, and memory leaks when the controls are released. In this post I describe a couple of specific problems I ran into loading a sizable list of images from files and show a few ways how to avoid the potential pitfalls related to ImageSource peculiarities.

Integrating OpenAI Image Generation into a .NET Application

Rick Strahl — Thu, 21 Dec 2023 22:22:07 GMT

Image Generation AIs are proving to be very good at creating images that can be used for all sorts of purposes. In this article I discuss how you can integrate image generation right into your own .NET applications using the OpenAI REST API. In addition I'll show how you can integrated this functionality into a larger application and discuss some general thoughts on image AI usage based on some of the experiences from a developer/non-designer user perspective.

Embedding a minimal ASP.NET Web Server into a Desktop Application

Rick Strahl — Tue, 28 Nov 2023 08:42:36 GMT

Did you ever need to embed a Web Server into a non-Web application? In this post I describe how you can use host ASP.NET in a non-Web application and specifically in a WPF desktop app. What do you need, how is it different and some of the issues that you need to consider if you want to use ASP.NET in your non-Web applications.

Save Files With Elevated Permissions on UnauthorizedAccessException

Rick Strahl — Fri, 03 Nov 2023 19:48:56 GMT

If you have an application that generically allows you to edit and save files, you might on rare occasions need to save files in locations that where a regular user account does not have permissions to save. Rather than failing wouldn't it be nice to let the user know and optionally allow saving with elevated permissions? In this post I describe the workflow and implementation on how to do just that.

Caching your WebView Environment to manage multiple WebView2 Controls

Rick Strahl — Tue, 31 Oct 2023 22:10:59 GMT

I've been struggling with rare WebView initialization errors in one of my applications, that have been difficult to debug and track down. After a lot of trial and error I discovered that the problem is related to WebView Environment instantiations that might be stepping on each other. In this post I describe the problem and a solution that involves creating a single WebView Environment and reusing it for all WebView initialization.

Rolling Forward to Major Versions in .NET

Rick Strahl — Tue, 03 Oct 2023 08:12:27 GMT

.NET Core has sophisticated policies that allows your applications that are compiled to specific versions of the .NET Runtime can roll forward to newer versions. You can specify what part of the version to roll forward and that generally works well, except for preview releases which require an extra step.

IIS Error 500.19 with ASP.NET Core Application

Rick Strahl — Tue, 19 Sep 2023 10:02:02 GMT

Running on IIS locally is pretty rare, but if for some odd reason you decide to run IIS locally on your dev machine you might find yourself getting a 500.19 error which relates to an issue in the web.config configuration. The solution is simple enough: Make sure the ASP.NET Core Hosting Module is installed. In this post I describe in more detail what the problem is and why you need a seemingly superfluous extra install to get IIS and ASP.NET Core to cooperate on local dev machine.

Dotnet Tool Component not found on the Mac

Rick Strahl — Tue, 12 Sep 2023 02:05:47 GMT

I've run into this problem a few times: I install a new Mac OS and then install the .NET SDK. A bit later I install a dotnet tool using `dotnet tool install -g` and then try to run it, only to find out that the SDK is not able find it. This post is a note to self on how to fix the pathing for .NET tools to be found correctly and to be able to run your dotnet tools.