Dijgrid.RazorLight 3.0.1

RazorLight

RazorLight is a generic C# text-template engine built on Razor. It compiles templates and renders them outside ASP.NET MVC, making Razor syntax useful for source generation, configuration files, messages, reports, prompts, and other structured or plain-text output.

The maintained release targets .NET 10 and is published as Dijgrid.RazorLight. HTML behavior is optional; the core library treats output as text.

Capabilities

• Render Razor templates from strings, files, embedded resources, databases, or custom projects.
• Use dynamic or strongly typed models, standard Razor expressions, imports, LINQ, layouts, sections, and partial templates.
• Compose templates with trusted ordinary C# helper files through AddCSharpSource or @compileSource.
• Cache compiled templates and invalidate dependent templates when project sources change.
• Cancel template lookup, compilation waits, rendering, layouts, and includes cooperatively.
• Precompile templates with the Dijgrid.RazorLight.Precompile command-line tool and render them in a compiler-free execution mode that never falls back to runtime compilation.
• Select plain-text output, optional HTML encoding, or a custom output encoder.
• Control namespaces, metadata references, dependency discovery, diagnostics, and integration with dependency injection.
• Run framework-dependent, self-contained, and extraction-based single-file deployments on Windows and Linux.

Install

dotnet add package Dijgrid.RazorLight --version 3.0.1

The historical RazorLight 2.3.1 package is the upstream release, not this continuation. Moving to the Dijgrid.RazorLight 3.x line is a framework and API migration. Read the 2.3.1-to-3.0 migration guide before upgrading.

Quick example

var engine = new RazorLightEngineBuilder()
    .UseMemoryCachingProvider()
    .Build();

string template = "Hello, @Model.Name. Welcome to RazorLight repository";
ViewModel model = new ViewModel { Name = "John Doe" };

string result = await engine.CompileRenderStringAsync("templateKey", template, model);

Each template key identifies a logical template and allows its compiled form to be reused. String templates work without a project; project-backed templates add file lookup, embedded resources, layouts, includes, and source change tracking.

For example, render a file relative to a configured template root:

var engine = new RazorLightEngineBuilder()
    .UseFileSystemProject("C:/Templates")
    .UseMemoryCachingProvider()
    .Build();

string result = await engine.CompileRenderAsync(
    "Reports/Summary.cshtml",
    new { Title = "Quarterly summary" });

The engine exposes cache administration without leaking compiled-page factories:

if (engine.IsTemplateCached("Reports/Summary.cshtml"))
{
    engine.InvalidateTemplate("Reports/Summary.cshtml");
}

Templates can also select ordinary C# helper code:

@compileSource "../Shared/ScenarioFunctions.cs"
@using ScenarioTemplates
@ScenarioFunctions.Quote(Model.Name)

See the RazorLight manual for installation details, template sources, models, composition, includes, caching, encoding, precompilation, deployment, and troubleshooting examples.

Output and trust model

The core package writes expression results as plain text. Install Dijgrid.RazorLight.Html and call UseHtmlEncoding() when producing HTML, or implement IOutputEncoder for another format.

Razor templates and imported C# sources are executable .NET code with the host process's permissions. RazorLight is intended for application-owned or otherwise trusted templates. It is not an in-process sandbox for untrusted authors; see the template security guide.

Compatibility

• Maintained projects, tests, samples, and generated code target .NET 10 and C# 14.
• Runtime compilation requires dynamic code and a preserved compilation context. Trimming and Native AOT are not supported by the runtime compiler.
• The generic core does not provide MVC tag helpers or built-in HTML contracts.
• Public compatibility, language behavior, and deployment expectations are recorded in the repository documentation rather than inferred from the historical package.

Documentation

• Manual
• Migrating from RazorLight 2.3.1
• Framework support and migration
• Template language compatibility
• Caching and invalidation
• Cancellation
• Deployment compatibility
• Template security
• Public API design
• Release process
• Changelog

Project maintenance

Read CONTRIBUTING.md before contributing, use the repository's GitHub issue forms for reproducible bugs and focused proposals, and report vulnerabilities according to SECURITY.md. Accepted roadmap work is tracked in .planfs.