Scriban¶

Scriban template infrastructure for Roslyn incremental source generators.

Distribution

Deepstaging.Roslyn.Scriban is not published as a separate NuGet package — it ships inside Deepstaging.Roslyn.

Architecture¶

Generator
  │
  ├── TemplateName.ForGenerator<T>()     → Factory for template identifiers
  │
  ├── Template.RenderTemplate(name, model) → Load + parse + render (cached)
  │     └── RenderResult (Success | Failure)
  │
  ├── AddFromTemplate(ctx, name, model)  → Context extension (render + add source)
  │
  └── Customizable Templates
        ├── TemplateMap<TModel>          → Record which values are replaceable
        ├── CustomizableEmit             → Bridge default emit + user templates
        ├── UserTemplates                → Discover .scriban-cs from AdditionalTexts
        └── Scaffold                     → Auto-generate starter templates
              ├── ScaffoldEmitter        → Emit assembly metadata
              ├── ScaffoldAvailableAnalyzer → DSRK005 info diagnostic
              └── ScaffoldTemplateCodeFix   → Create template file

Quick Start¶

1. Create a template¶

Add a .scriban-cs file as an embedded resource:

// <auto-generated/>
#nullable enable

namespace {{ model.namespace }};

public partial class {{ model.name }}
{
{{~ for prop in model.properties ~}}
    public {{ prop.type }} {{ prop.name }} { get; set; }
{{~ end ~}}
}

2. Set up the template name factory¶

public class MyGenerator : IIncrementalGenerator
{
    private static readonly Func<string, TemplateName> Named =
        TemplateName.ForGenerator<MyGenerator>();
}

3. Render and add to output¶

context.AddFromTemplate(
    Named("MyTemplate.scriban-cs"),
    hintName: $"{model.Name}.g.cs",
    context: model);

Template Conventions¶

Convention	Value
File extension	`.scriban-cs`
Build action	`EmbeddedResource`
Directory	`Templates/` next to generator
Property access	snake_case (e.g., `FullName` → `{{ model.full_name }}`)

<ItemGroup>
    <EmbeddedResource Include="Templates\*.scriban-cs" />
</ItemGroup>

Diagnostics¶

ID	Severity	Description
`DEEPCORE001`	Error	Template parse or render error
`DSRK005`	Info	Customizable template available (code fix creates starter template)
`DSRK006`	Error	User template rendered invalid C#
`DSRK007`	Error	User template has Scriban parse or render errors

API Reference¶

Type	Description
TemplateName	Identifies an embedded template by resource name and assembly
Template / RenderResult	Load, parse, render with two-level caching
Context Extensions	AddFromTemplate, UserTemplatesProvider, ScribanExtension
Experimental	Customizable Templates, Scaffolding (⚠️ experimental)