HtmlForgeX

Advanced Topics

This section covers the runtime and deployment topics that do not fit neatly into component-by-component docs: package loading modes, Native AOT, trimming, and running HtmlForgeX from hosted ASP.NET Core apps.

Library Modes

Online Mode

Links to CDN resources. Requires internet connectivity:

doc.LibraryMode = LibraryMode.Online;

Offline Mode

Embeds all CSS/JS inline for a fully self-contained HTML file:

doc.LibraryMode = LibraryMode.Offline;

OfflineWithFiles Mode

Creates separate CSS/JS files alongside the HTML:

doc.LibraryMode = LibraryMode.OfflineWithFiles;

Performance

Lazy Initialization

Defer component loading for large datasets:

table.EnableLazyInit();

Resource Deduplication

HtmlForgeX automatically deduplicates CSS/JS resources using HashSets. Each library is included only once regardless of how many components use it.

AOT Compilation

HtmlForgeX supports .NET 8 Native AOT with some considerations:

  • Use AOT-safe labelers for table columns
  • Avoid reflection-heavy patterns in AOT scenarios
  • Test with PublishAot=true to verify compatibility
// AOT-safe table column configuration
table.WithAotSafeLabeler<Employee>(labeler => {
    labeler.Label(e => e.Name, "Employee Name");
});

Thread Safety

HtmlForgeX uses ConcurrentDictionary for shared state, making it safe to generate documents from multiple threads simultaneously.

Custom Libraries

Add custom CSS/JS libraries:

doc.Head.AddStylesheet("https://example.com/custom.css");
doc.Head.AddScript("https://example.com/custom.js");