Template variable list

[Amberg]

Template Schema Inspection — GetTemplateSchema()

Adds a static analysis API that inspects a template without rendering it and returns the structural schema of the variables, collections and nested objects the template references. Callers can validate their model against the template's expectations up front, or generate a skeleton model to fill in.

Public API

using var template = DocxTemplate.Open("template.docx");

// Template: "Hello {{customer.Name}}" and "{{#items}}{{items.Price}}{{/items}}"
var schema = template.GetTemplateSchema();

schema.Roots["customer"].Properties["Name"].Kind;          // Scalar
schema.Roots["items"].Kind;                                // Collection
schema.Roots["items"].ItemSchema.Properties["Price"].Kind; // Scalar

Type	Description
DocxTemplate.GetTemplateSchema() → TemplateSchema	Returns the template's schema.
TemplateSchema	Roots = top-level models (case-insensitive), matching the BindModel prefixes.
TemplateSchemaNode	Name, Kind, Properties (objects), ItemSchema (collections).
TemplateNodeKind	Scalar | Object | Collection.

What is covered

The schema is collected from the block tree and covers:

• Variables & expressions ({{x}}, {{(a + b)}}) — expression operands parsed via SchemaExpressionParser.
• Loops / collections ({{#items}}…{{/items}}) including nested item schemas and references to outer models.
• Conditions (if/else), switch/case/default — reported as the union of all branches, so a caller must be prepared to bind anything reachable at runtime.
• Range loops, inline keywords, ignore blocks.

Each block type contributes through a new CollectSchema(SchemaBuilder) method (base in ContentBlock, overrides in LoopBlock, ConditionalBlock, SwitchBlock/CaseBlock, RangeLoopBlock, IgnoreBlock, InlineKeyWordBlock).

Schema and rendering on the same instance

GetTemplateSchema() builds the same block tree the renderer uses (which mutates the XML). To keep Process() working afterwards, the pipeline was split into two phases:

• BuildBlockTree — pre-process + marker isolation + loop expansion → model-independent.
• RenderNode — variable replacement + extensions + loop.Expand + cleanup → model-dependent.
• ProcessNode = BuildBlockTree + RenderNode (unchanged behaviour for existing callers).

GetTemplateSchema() caches the built block tree per node (header/body/footer) and the resulting TemplateSchema; Process() then renders from the cache instead of rebuilding the already-extracted tree. The previous "destructive — do not call Process afterwards, reopen the stream" contract is removed.

Guards / idempotency:

• A second GetTemplateSchema() call returns the cached result.
• Calling GetTemplateSchema() after Process() throws a clear exception.
• Process() without a prior schema call, or called twice, behaves as before.

Known limitations (documented on TemplateSchema)

• Sub-templates (:tmpl): the referenced sub-template is a runtime template string, invisible to static analysis.
• Dynamic tables (:dyntable): only the collection itself is reported, not its runtime-defined rows/columns.
• String-key indexing (props["key"]): the key is not statically known and is not reflected in the schema.

Tests

• New: TemplateSchemaTest, SchemaBuilderTest, SchemaExpressionParserTest.
• ComplexTemplateTest.ProcessComplexTemplate extended to call GetTemplateSchema() then Process() on the same instance.
• All schema tests (41/41) and ProcessComplexTemplate (3/3) pass on net8.0 / net9.0 / net10.0.

Docs

README gains a Template Schema Inspection section and a feature bullet.