SlusserLabs.AnglePlates 1.2.0-ci.37

AnglePlates

AnglePlates is a .NET source generator for rendering templates. Think of it like T4 templates for modern .NET.

Templates are created at compile time, do not require reflection, are AOT friendly, yield excellent performance, and you get to use the C# skills you already know instead of learning a specific template language. The compiled templates write synchronously to a TextWriter or an IBufferWriter<byte>. For asynchronous UTF-8 streaming, render to a PipeWriter, such as an HTTP response body.

Quick start

Add the package:

dotnet package add SlusserLabs.AnglePlates

Create a model (or use an object you already have):

namespace MyApp;

public sealed record GreetingModel
{
    public string Name { get; init; } = default!;
    public string? Message { get; init; }
}

Make a template, e.g. Templates/greeting.html:

#model MyApp.GreetingModel

[* A greeting with an optional message. *]

<h1>Hello, [[ model.Name ]]!</h1>

[% if (!string.IsNullOrEmpty(model.Message)) { %]
<p>[[ model.Message ]]</p>
[% } %]

Build, then render the generated class. In a project whose RootNamespace is MyApp, the source generator will have created a type named MyApp.Templates.GreetingTextTemplate with a default instance for you to pass your model to and render:

using MyApp;
using MyApp.Templates;
using SlusserLabs.AnglePlates;

var model = new GreetingModel { Name = "Ada & Grace", Message = "Welcome!" };
string html = GreetingTextTemplate.Default.RenderToString(model);

Output (blank lines omitted):

<h1>Hello, Ada &amp; Grace!</h1>
<p>Welcome!</p>

Rendering and options

Each template generates a *TextTemplate class for TextWriter and a *Utf8Template class for IBufferWriter<byte>. The UTF-8 class also has RenderAsync for easy PipeWriter usage, including ASP.NET Core's HttpResponse.BodyWriter.

Use the static Default for a shared instance, or pass options to the constructor:

var email = new GreetingTextTemplate(new TemplateOptions { Encoder = null });
var german = new GreetingTextTemplate(new TemplateOptions
{
    Culture = System.Globalization.CultureInfo.GetCultureInfo("de-DE")
});

• TemplateOptions.Encoder controls the encoder to use for text output; the default is HtmlEncoder.Default; null turns encoding off.
• TemplateOptions.Culture controls the culture used when the renderer is converting objects to string; the default is CultureInfo.InvariantCulture.
• TemplateOptions.NullVariable controls what is rendered when a variable evaluates to null; the default is nothing.

Samples

Both samples are small runnable .NET 10 programs. Each has a README with a run command and expected output:

• HelloWorld: render a Markdown greeting and numbered task list with conditions and a loop.
• HelloWorldApi: stream a UTF-8 HTML page with nested models, a child template, and default encoding.

Learn more

• Template reference: directives, syntax, child templates, rendering, and MSBuild settings.
• Glossary: template terminology, generation, and rendering.
• Diagnostics: build errors and their fixes.
• Contributing and development: build, test, and release commands.

AI Disclosure

This project was built with the help of AI. As with any tool I use for coding, I am fully responsible for the end result and only put forward this project with full confidence that I have reviewed every line. Whether a line of code in this project was fully AI generated, AI assisted, or entirely from my own Muppet fingers on the keyboard, it is held to the same expectations.

License

AnglePlates is released under the MIT License.