Extrode.NativeWeb.Render 0.1.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Extrode.NativeWeb.Render --version 0.1.0
                    
NuGet\Install-Package Extrode.NativeWeb.Render -Version 0.1.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Extrode.NativeWeb.Render" Version="0.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Extrode.NativeWeb.Render" Version="0.1.0" />
                    
Directory.Packages.props
<PackageReference Include="Extrode.NativeWeb.Render" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Extrode.NativeWeb.Render --version 0.1.0
                    
#r "nuget: Extrode.NativeWeb.Render, 0.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Extrode.NativeWeb.Render@0.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Extrode.NativeWeb.Render&version=0.1.0
                    
Install as a Cake Addin
#tool nuget:?package=Extrode.NativeWeb.Render&version=0.1.0
                    
Install as a Cake Tool

nativeweb.render

HTML rendering for NativeWeb: a source-generated template system that writes UTF-8 into an IBufferWriter<byte> with no intermediate whole-page string, plus the locale catalogs and per-request negotiation those templates read from. This project is the runtime half. The build-time half is libs/nativeweb.render.generator, which turns a product's own templates/**/*.html and locales/*.json files into C#. A consumer references both:

<ProjectReference Include="..\..\libs\nativeweb.render\nativeweb.render.csproj" />
<ProjectReference Include="..\..\libs\nativeweb.render.generator\nativeweb.render.generator.csproj"
                  OutputItemType="Analyzer"
                  ReferenceOutputAssembly="false" />

Templates and locale catalogs are AdditionalFiles of the product project; the generator never reads disk, only what the compiler hands it.

The whole API

Entry point What it does
Html.Raw Marks a string as already-encoded markup: the one unencoded path for values
TemplateWriter The render target generated template code writes into
TemplateRender The delegate a template body compiles to
TemplateResults.Html Wraps a TemplateRender as an IResult: buffered, length declared, one write
TemplateResults.ToHtmlString Materialises the same body as a string, for e-mail and tests
FormatResults One IResult per text format: Text, Markdown, Json, Xml, Csv, Atom, Rss, Sitemap
Format A representation: extension, media type, and whether it takes a charset
Feed, FeedEntry, SitemapEntry The structured input Atom, Rss and Sitemap write
RequestBase.PublicBase The request's scheme and host as the base every relative link resolves against
LocaleCatalog One locale's fully resolved string table
LocaleNegotiation UseLocaleNegotiation middleware and the GetLocale reader
LocaleNegotiationOptions Configures that middleware

Encoding is decided by overload resolution on TemplateWriter, at compile time:

Overload Behaviour
Write(string?) HTML-encodes. Null renders nothing
Write(Html) Writes pre-encoded markup verbatim
Write on char, int, long No encoding; numbers cannot need it
WriteRaw Generated code only, hidden from editor completion

Write(string?) encodes the five HTML-significant characters (less-than, greater-than, ampersand, both quotes) and lets non-ASCII text through as UTF-8 bytes rather than numeric entities. A template expression of any other type fails to compile, which is the intended default for types nobody has made an encoding decision about.

LocaleCatalog exposes Locale (the lowercase id), Lang (BCP-47 for the html lang attribute), Dir ("ltr" or "rtl"), a string indexer, and placeholder substitution:

Format(string key, params ReadOnlySpan<(string Name, string? Value)> args)

Format makes a single left-to-right scan: placeholders occurring in a substituted value are never re-substituted, so argument order cannot splice one argument into another. Placeholders with no matching argument are left in place.

LocaleNegotiationOptions:

Property Meaning
SupportedLocales Lowercase locale ids the app ships catalogs for
DefaultLocale When nothing else matches; "en" by default
CookieName The override cookie; "locale" by default
UserPreference Signed-in user's stored preference (users.locale), consulted first

UseLocaleNegotiation chooses user preference, then cookie, then Accept-Language (ordered by descending q, "*" excluded), then the default, and parks the result in HttpContext.Items for GetLocale. Dialects fall back to their base language before the next candidate is tried: "en-gb" matches "en" when only "en" is shipped.

A page, a layout, and the endpoint that serves it

templates/shared/layout.html — a template containing a slot is a layout, and gets no class of its own:


<!doctype html>
<html lang="{{locale.Lang}}" dir="{{locale.Dir}}">
  <head>
    <meta charset="utf-8">
    <title>{{title}}</title>
  </head>
  <body>
    {{slot Main}}
  </body>
</html>

templates/articles/index.html:


<h1>{{t:articles.heading}}</h1>
{{featured}}
<ul>
{{for article in articles}}
  <li>{{article.Title}}</li>
{{/for}}
</ul>

locales/en.json — nested objects flatten to dot-joined keys, and every {{t:...}} key anywhere must exist in this root file:

{
  "articles": {
    "heading": "Articles"
  }
}

locales/ms.json — an override file refines root keys; fallthrough to English is resolved at build time, never walked at render time:

{
  "articles": {
    "heading": "Artikel"
  }
}

The generator emits a static class per page, each path segment Pascal-cased and nested under Templates, so the page above becomes Templates.Articles.Index. A page whose layout reads locale.Lang takes the resolved catalog as an implicit first parameter, layout parameters first and page parameters after:

app.UseLocaleNegotiation(new LocaleNegotiationOptions
{
    SupportedLocales = Locales.All,
    UserPreference = context => currentUser.LocalePreferenceAsync(context),
});

app.MapGet("/articles", async (HttpContext context, ArticleStore store) =>
{
    LocaleCatalog locale = Locales.Get(context.GetLocale());
    IReadOnlyList<Article> articles = await store.RecentAsync(20);
    return Templates.Articles.Index.Result(
        locale,
        featured: Html.Raw(store.FeaturedMarkup()),
        articles: articles);
});

Result returns the buffered IResult; ToHtmlString returns the same markup as a string for the paths that still compose one.

Other formats

The same buffered, length-declared, one-write shape as TemplateResults.Html, for everything that is not a page (spec 021):

app.MapGet("/export.csv", async (IPublishedArticles articles, CancellationToken ct) =>
{
    IReadOnlyList<PublishedArticle> rows = await articles.RecentAsync(100, ct);
    return FormatResults.Csv(
        ["id", "title", "author"],
        rows.Select(r => new[] { r.Id, r.Title, r.Author ?? "" }));
});

app.MapGet("/feed.atom", async (IPublishedArticles articles, HttpRequest request, CancellationToken ct) =>
{
    IReadOnlyList<PublishedArticle> rows = await articles.RecentAsync(20, ct);
    Feed feed = new(
        Id: new Uri(request.PublicBase(), "/feed").AbsoluteUri,
        Title: "Articles",
        Link: "/articles",
        Updated: rows.Count > 0 ? rows[0].CreatedAt : DateTimeOffset.UnixEpoch,
        Entries: rows.Select(r => new FeedEntry(
            Id: new Uri(request.PublicBase(), "/articles/" + r.Id).AbsoluteUri,
            Title: r.Title,
            Link: "/articles/" + r.Id,
            Updated: r.CreatedAt)).ToList());
    return FormatResults.Atom(feed, request);
});
Helper Emits
Text, Markdown text/plain and text/markdown, UTF-8, no BOM; Text takes a status code for refusals
Json<T> Through the JsonTypeInfo<T> the caller supplies, so nothing reflects and nothing trims away
Xml An XmlWriter over the buffer, declaration included; WriteRaw on it is the one unescaped path
Csv RFC 4180: CRLF, fields quoted when they hold a comma, quote or line break, quotes doubled
Atom, Rss RFC 4287 and RSS 2.0 from a Feed; RFC 3339 and RFC 822 dates in UTC
Sitemap sitemaps.org 0.9 from SitemapEntry values; priority outside 0..1 throws

Csv neutralises spreadsheet formulas: a cell whose first printable character is =, +, - or @ is prefixed with an apostrophe and quoted, unless the whole cell parses as a number, so -5 survives and =CMD() does not. Leading spaces and invisible characters are skipped before that test, which is where the known bypasses hide.

Feed and sitemap links are written relative and resolved against a base: the HttpRequest overloads take it from the request through PublicBase, after UseForwardedHeaders has corrected the scheme and host; the Uri overloads take it from the caller. Choosing a representation from the path or the Accept header is MapNegotiated in nativeweb.web.

The generator

RenderTemplateGenerator is an incremental generator. A consumer references it as an analyzer and never calls anything it defines, so it gets no README of its own. From each product's own files it emits:

Source Emission
templates/**/*.html A static class per page: Render into a TemplateWriter, plus ToHtmlString, Result, and InlineScriptCspHashes
locales/*.json The Locales class: one LocaleCatalog per locale id, Get, All

InlineScriptCspHashes lists 'sha256-…' script-src sources for the page's static inline scripts, taken over the bytes Render writes, so a cacheable response needs no per-response nonce. It is always emitted, empty included, so consumers can reference it unconditionally. Generated classes land under the project's root namespace (build_property.RootNamespace).

Every template mistake is a build error, not a runtime blank, and each diagnostic points at the line in the template file that wrote it:

Diagnostic What it rejects
NWT001 Malformed template header, including a layout that chains to another layout
NWT002 Unknown directive in the header; only @layout and @param exist
NWT003 @param that is not "@param <type> <name>"
NWT004 @layout naming no template file
NWT005 A partial naming no template file
NWT006 Partial arguments not matching the partial's @param list
NWT007 Slots and fills misused: duplicate fill, fill outside a layout, unfilled slot name
NWT008 Unbalanced {{if}}, {{for}} or {{fill}} blocks
NWT009 Two templates compiling to the same class name
NWT010 A parameter declared with different types in page and layout
NWT011 A required layout slot the page never fills
NWT012 An expression carrying ;, { or } — expressions are values, not statements
NWT013 A {{t:...}} key missing from locales/en.json
NWT014 A locale override for a key the English root never defined (typo)
NWT015 Malformed locale catalog: bad JSON, duplicate locale id, missing root, a _dir that is not ltr/rtl
NWT016 Interpolation inside a tag but outside a quoted attribute value

NWT016 is the check behind the writer's encoding contract: Write(string?) is safe in text and inside a quoted attribute value and nowhere else, because an unquoted value ends at a space and a space is not encoded. Quote the attribute value.

What this library does not do

No template is parsed at run time. There is no engine to load, no path resolution, no reflection over models; what is left at run time is generated C# writing bytes.

There is one unencoded path for values, Html.Raw, and the caller owns the claim that the markup is safe. Auditing raw output means grepping for Html.Raw in application code and WriteRaw in generated code. URL values from user data need scheme validation in the calling C#: no HTML encoder stops a javascript: href.

TemplateResults.Html is for pages. It renders into a private buffer, declares the length, and hands the body over in one write, because a chunked page costs 35% of its throughput for framing no page needs. Every FormatResults helper buffers the same way. A body that cannot know its length needs a different result type, one that streams.

FormatResults writes documents; it does not decide which one to write. Negotiation is nativeweb.web's, and what a sitemap lists is the application's.

LocaleCatalog lookup never throws mid-render: a miss returns the key itself. Keys are compile-checked against the English root, so a miss can only come from a hand-written C# key.

LocaleNegotiation picks a catalog id and nothing else. It does not set thread culture, format numbers or dates, and outside the middleware GetLocale returns "en".

RTL detection covers the shipped set (Arabic, Hebrew, Persian, Urdu and friends); a locale outside it declares _dir in its own file or stays ltr. Lang casing handles one- and two-subtag ids.

Proved by

tests/nativeweb.render.tests.unit: TemplateWriterTests (the encoding decisions), TemplateHtmlResultTests (the IResult path), LocalizationTests (catalogs, fallthrough, negotiation), GeneratedTemplateTests and FormattingTests (generated output), InlineScriptHashTests, FormatResultsTests, CsvTests and FeedTests (the other formats, the sitemap validated against the vendored sitemap.xsd), and GeneratorDiagnosticsTests with DiagnosticsReferenceTests over the NWT set above.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Extrode.NativeWeb.Render:

Package Downloads
Extrode.NativeWeb.Web

NativeWeb framework: the request pipeline — security headers, public-page output cache, error pages, static pages, flash, readiness, CSP reporting.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.1 110 11/3/2026
0.1.0 108 11/3/2026