HtmlBuilder.Create() is a factory, not a singleton. It returns a new builder pre-loaded with the built-in pipes on every call. Capture one instance — var builder = HtmlBuilder.Create(); — then register and render on that same instance; registering on one builder and rendering on another loses the registration.

Output is verbatim. Rendering emits your template's whitespace exactly as written — newlines and indentation included, and correctly inside <pre> / <textarea>. There is no minifier pass: what you write is what ships.

Object identity is path-dependent. A == A on the same object node holds for CLR models (live-reference identity) but not across separately-resolved JsonElement nodes — compare scalar values, not object nodes, when the model comes from JSON.

<script> / <style> are raw text. Their content is preserved verbatim and interpolations inside them render unescaped — {{ AccentColor }} in a stylesheet stays CSS, not HTML entities. Only bind values you trust there.

Pipes use the current culture — or the one you pass per render. date, number, currency, titlecase and largeNumber format with the thread's CultureInfo. To serve multiple locales from one process, set TemplateOptions.Culture on any BuildFromTemplate call or on CompiledTemplate.Render.

The engine swaps CurrentCulture/CurrentUICulture around the render and restores them in a finally — thread-local, so concurrent renders elsewhere are unaffected; null keeps the ambient culture.

The sample outputs on this page are en-US. Two culture-proof exceptions, the json pipe and bare interpolations in text mode, write invariant machine literals.

The expression language is small but real. Paths, safe-navigation ?., indices, .Count / .Length, literals, comparisons == != < > <= >=, logical && / || / !, arithmetic + - * / % (+ also concatenates strings), ternary and pipes.

No method calls; ordering comparisons are numeric. Test existence with a comparison — @if (Items.Count > 0), not @if (Items).

Truthiness is strict; misses are silent. Only a real boolean is truthy, and a path that doesn't resolve renders empty rather than throwing. Empty templates and unknown pipes do throw.

Rendering is synchronous. Rendering is CPU-bound — there is nothing to await and no async overload at all: BuildFromTemplate returns the rendered string directly (or use Compile(template).Render(model) for parse-once / render-many).

Components use reflection. Unlike pipes and directives, component [prop] binding is reflection-based — RegisterComponent<T>() carries the trimmer annotations, so the component's constructor and properties are preserved automatically under trimming / Native AOT. And a component's Render() output is trusted raw HTML, injected verbatim like [html] — escape user data inside the component (WebUtility.HtmlEncode).

Two caveats: complex-typed properties bound from a JsonElement model deserialize through reflection-based System.Text.Json (under trimming, enable JsonSerializerIsReflectionEnabledByDefault and keep the element types rooted — annotations aren't transitive), and a binding that can't convert sets nothing, silently. Components also receive CLR model objects by live reference, and any public settable property is bindable (case-insensitive) — treat bound objects as read-only.

FromJson reads lazily. The JsonElement path reads your document in place — keep its JsonDocument undisposed for the life of the render, or pass json.Clone() if it may be disposed first.

Creates a new builder pre-loaded with the built-in pipes (date, number, currency, largeNumber, upper, lower, titlecase, default, truncate, join, pad, image, json). Register your extensions on the instance you keep.

Same, with the builder's strict default set once: every Build/Compile on the builder is strict without repeating the flag. An explicit TemplateOptions.Strict in a call's options still overrides it (call wins over builder) — see strict mode & validation.

Renders a template against a model — synchronously, the real path (rendering is CPU-bound). The object overload reads it directly via reflection (honors [JsonPropertyName]/[JsonIgnore], not custom converters); the JsonElement overload is reflection-free with full System.Text.Json fidelity (AOT / trim); the NgElement overload is the hot-path opt-in.

Each takes one optional TemplateOptions carrying everything tunable: Mode (TemplateMode.Text renders non-HTML output raw — see Text mode; omitted or null means TemplateMode.Html), Strict (fail loud — see strict mode), Culture (swapped and restored around the render; null keeps the ambient culture) and Limits (opt-in resource caps for untrusted templates). Null options mean all defaults.

Parses and folds the template once and returns a reusable CompiledTemplate (parse-once / render-many). options.Mode is baked into the result (default TemplateMode.Html). With Strict = true the compile throws on Validate errors and every render throws on a path missing from the model; Strict left null inherits the builder's Create(strict:) default — see strict mode & validation. options.Culture / options.Limits are memorized as the compiled template's render defaults, overridable per render.

Reports every problem the lenient renderer would swallow silently — unclosed {{, unparsable expressions, @for (x in …), unclosed blocks, orphan [else], malformed pipes, and (as warnings) unregistered pipes, dashed tags not registered as components, statically always-false conditions and literal division by zero — without throwing, each with a source position. Empty list = clean template; made for CI. See strict mode & validation.

Registers a pipe / component / directive. Each T is instantiated via its parameterless constructor.

Instance registrations — the DI-friendly path for extensions with constructor-injected configuration. Pipe/directive instances are shared across renders (must be thread-safe, ideally immutable). A component instance is a prototype: each render still activates a fresh T via its public parameterless constructor, so constructor state does not flow into renders.

The registered extensions, keyed by name.

Renders the compiled template against a model — same three model kinds as BuildFromTemplate. The options' Culture, Limits and Strict override the defaults memorized at compile time (one compiled template serves multiple locales); a Mode contradicting the compiled dialect throws — the dialect was baked in at compile. Omitted options keep the compile-time defaults; no limits means nothing is enforced and nothing is paid.

Renders into a TextWriter sink — same three model kinds, same options. Nothing reaches the writer until the render has fully succeeded: a throwing render (strict miss, exceeded cap) writes zero characters (atomic). What the sink saves is the final output string.

The honest async form: the walk is CPU-bound and synchronous; the await is the write to your writer (real I/O). Same atomicity as the sync sink — a throwing render writes zero characters, and an already-canceled token throws before anything is rendered or written.

The dialect the template was compiled with (TemplateMode.Html / TemplateMode.Text) — captured at Compile time; a contradicting mode in Render options throws.

True when compiled with Strict = true (or from a strict builder): every render throws NgSharpException on a path missing from the model, instead of rendering empty (present-but-null still renders empty; ?.-guarded paths never throw) — see strict mode & validation.

Compile-time. The dialect the template is parsed in; null defaults to TemplateMode.Html. A CompiledTemplate bakes it in — a contradicting mode in Render options throws.

Both times. At compile it gates the template through Validate (any error throws); at render a missing model path, a non-boolean non-null condition and a division/modulo by zero throw. Null inherits the builder's Create(strict:) default — or, on CompiledTemplate.Render, the compiled Strict; an explicit true/false always wins.

Render-time. Swapped in around the render, restored afterwards; null keeps the ambient culture. Given to Compile, it becomes the compiled template's default culture, overridable per render.

Render-time. Opt-in resource caps for untrusted templates; null enforces nothing. Given to Compile, they become the compiled template's default caps, overridable per render.

The canonical empty options — every property null. Passing Default, null, or nothing at all are equivalent.

FromJson is reflection-free (AOT / trim safe) and reads the JsonElement lazily — keep its JsonDocument undisposed while you render, or pass json.Clone(). FromObject reads a CLR object in place via reflection — no JSON round-trip, no copy.

Scalar factories, both reflection-free. Parse coerces a template literal — null / true / false and culture-invariant numbers become their types, anything else stays a string. FromStringLiteral wraps the text with no coercion at all: "42" stays the string "42".

Resolves a path — property names, dotted paths, array indices ("Items[0].Name"), and the computed .Count / .Length.

Typed accessors for the leaf value (also GetLong, GetDecimal, GetFloat); each returns null when not convertible.

The scalar value and kind, the child/property collections, and the computed Count / Length. Key always returns string.Empty in 3.0 — lazy nodes don't record their position in the parent; enumerate Properties when you need the names.

A value transform for {{ value | pipeName }}.

Mutates a host element via [directive]="expr". DirectiveElement exposes TagName, GetAttribute, SetAttribute, RemoveAttribute.

A server component for <component-name>; its writable properties are bound from [prop] attributes. Its Render() output is trusted raw HTML — injected verbatim, like [html]: escape user data inside the component (WebUtility.HtmlEncode).

date · number · currency (ISO-pinned symbol) · largeNumber · upper · lower · titlecase · default (null/blank fallback) · truncate · join · pad · image · json (recursive — objects and arrays serialize whole). Register your own with RegisterPipe<T>().

The image pipe reads an ImageData-shaped value — FileName, whose extension gives the MIME type, and FileContent, the raw bytes (base64 in a JSON model) — and emits a data URI without ever decoding the content.

On an <img> it emits the bare URI — [src]="Logo | image" → data:image/png;base64,…. On any other element it wraps it for CSS — [style.background-image]="Logo | image" → url(data:…). A null value or empty content renders as an empty string.

Severity is Error (blocks a strict compile) or Warning (probable mistake). Position is the character offset in the template source — exact for structural findings; for a finding inside an expression it points at the expression's first occurrence. ToString() gives the log-friendly Error [position 23]: … line.

Deliberately generous defaults — roomy for any legitimate document, fatal for a runaway one. Each cap must be positive.

MaxOutputChars bounds the rendered output's length; MaxLoopIterations bounds a single @for/[for] loop (per loop, checked against the collection's count before iterating); MaxRenderDepth bounds @render fragment nesting — it generalizes the engine's built-in depth-50 guard and throws instead of silently truncating. None is the zero-cost default.

HTML templates. Colorizes {{ }} interpolations end to end — pipes, operators, $index and friends, literals — plus [if]/[for]/[else-if]/[else]/[not-empty] as control-flow keywords, the [attr.x]/[class.x]/[style.x]/[html] and bare [prop] bindings (the quoted value is tokenized as an expression, not left as a string), the @if/@else/@for/@render blocks, and <ng-template #x>/<ng-container>.

Text templates. An ngsharp-text language for text-mode templates — plain-text emails, JSON, CSV. Files named *.ngt or *.ng.txt are picked up automatically; any other .txt can be switched via Change Language Mode. Interpolations and blocks highlight on raw text; tags stay plain characters, exactly like the engine treats them.

Snippets. ngfor, ngif, ngifelse, the [if]/[for]/[else-if] attribute forms, ng-template + @render, ng-container and a server-component tag — in HTML mode; block and pipe snippets in text mode.

Install. Not on the marketplace yet — package it from the repo and install the .vsix:

HtmlBuilder.Default is removed. It was a factory disguised as a singleton: every access returned a new builder, so registrations made on one access were silently lost on the next. Replace it with HtmlBuilder.Create() and keep the instance you register on.

HtmlBuilder.MinifyHtml is removed. Rendering now emits your template verbatim, and the opt-in minifier went with it. It was a four-line Regex utility — trivial to copy into your own code if you still want it.

HtmlBuilder.Token is removed. It resolved a path against a context, falling back to parsing the token as a literal. Compose the two calls it wrapped yourself: content.SelectToken(path), then NgElement.Parse(literal) when the result's IsUndefined is true.

BuildFromTemplateAsync is removed. Rendering is CPU-bound and completes synchronously — the wrappers only returned Task.FromResult. Replace await builder.BuildFromTemplateAsync(...) with builder.BuildFromTemplate(...) (drop the await).

FromObject / FromJson lose their parent / key parameters. The engine never used them — delete the extra arguments and the calls compile again.

FromJson reads the JsonElement lazily. There is no document store anymore: rendering reads your JsonDocument in place. Keep it undisposed for the life of the render — or pass json.Clone() if it may be disposed first.

NgElement.Key always returns string.Empty. Lazy nodes no longer record their position in the parent. If you need property names, enumerate Properties — its keys are the names.

The built-in pipes are sealed (DatePipe, NumberPipe, UpperPipe, LargeNumberPipe, ImagePipe). Inheriting to tweak one no longer compiles — register your own pipe under a different name, or wrap a built-in instance by composition and delegate to it.

3.x is stable. No breaking change to the public API without a major version bump — semver, applied literally.

Deprecate before delete. Anything scheduled for removal ships [Obsolete] first, with a message naming its replacement, for at least one minor release before a major removes it.

Output is part of the contract. Rendered bytes only change behind an explicit opt-in or a major — the golden-locked test suite is what holds that line.

The boundary is drawn. Streaming output (TextWriter sinks) and honest async are delivered — in the one form that keeps the output contract: the walk renders fully, then the writer receives the final output in a single awaited write. A throwing render writes nothing (atomic). What stays excluded is incremental rendering — flushing mid-walk, while the tree is still being evaluated — because it would sacrifice exactly that atomicity: a failing render would leave half a document in your sink. No version is promised for it.

“Can't replace an empty html template”. The template string handed to the builder is null or empty — usually a file read that produced nothing. Check the template's path and the read, not the engine.

“Unknown pipe 'x'. Register it with RegisterPipe<T>() before rendering.” The template uses a pipe this builder doesn't know. Call RegisterPipe<T>() before rendering — on the same builder instance you render with.

Output is silently empty where a value should be. A path that doesn't resolve renders empty by design — no exception. Check the property path and its casing against the model: {{ user.name }} finds nothing when the model says User.Name. To hunt these down, run builder.Validate(template) for parse-level mistakes, or render with TemplateOptions.Strict = true — a missing path then throws NgSharpException naming it (see strict mode & validation).

A component tag renders as plain markup. Component names are read at parse time: call RegisterComponent<T>() before Compile or the first render, on the builder doing the compiling.

A registration “disappears”. HtmlBuilder.Create() returns a fresh builder on every call. Capture it once — var builder = HtmlBuilder.Create(); — then register and render on that same instance.