HtmlForgeX

Native AOT & Trimming

HtmlForgeX is designed to stay usable in trimmed and Native AOT scenarios without giving up the nicer reflective conveniences that remain valuable on normal JIT runtimes.

Centralized JSON

HtmlForgeX uses a source-generated JSON context:

  • HtmlForgeX.Serialization.HtmlForgeJsonContext

That context is used for hot serialization paths such as DataTables, SmartWizard/SmartTab, ApexCharts, VisNetwork DTOs, and FullCalendar-related output.

var json = HtmlForgeX.Serialization.Json.SerializeMin(
    options,
    HtmlForgeX.Serialization.HtmlForgeJsonContext.Default.DataTablesOptions);

JIT Versus Native AOT

  • JIT runtimes keep the reflective conveniences used for table summaries and similar helpers
  • Native AOT paths avoid those dynamic code paths when runtime code generation is not available
  • The result is a cleaner publish story for AOT without forcing the rest of the library into lowest-common-denominator ergonomics

Prefer Labelers Over Reflection

If you want rich labels in AOT scenarios, register them explicitly:

table.Settings(s => s.LabelerForType<Owner>(o => o.Name));
table.Settings(s => s.LabelerForProperty("Owners", v => v is Owner o ? o.Name : v?.ToString() ?? ""));

These labelers run before the normal heuristics and work in both AOT and non-AOT builds.

Publish Probe

The repo includes an optional probe project:

  • samples/HtmlForgeX.AOTProbe

Linux publish example:

dotnet publish samples/HtmlForgeX.AOTProbe -c Release -r linux-x64 \
  -p:PublishAot=true -p:StripSymbols=true -p:IlcOptimizationPreference=Size

Windows publish example:

dotnet publish samples/HtmlForgeX.AOTProbe -c Release -r win-x64 \
  -p:PublishAot=true -p:StripSymbols=true -p:IlcOptimizationPreference=Size

Practical Guidance

  • Favor explicit labelers instead of inferred labels for complex objects
  • Test representative documents with PublishAot=true before promising support for a scenario
  • Keep custom serialization on the same source-generated HtmlForgeJsonContext path when possible