An empty array, a null object or a field that stopped arriving will stop a document assembling,
even when the template guards against it. There are three ways to keep it running — a JSON
Schema, AllowMissingMembers and InlineErrorMessages — and picking the wrong one hides a real
problem instead of fixing it.
The report fills in perfectly on your machine. It runs for three weeks. Then one night it stops on
the third customer of a batch of two thousand, and the message is about a member of a DataRow.
The data was valid. The template was correct. What went wrong is the gap between them — and there are three different ways to close it, each right for a different reason.
The runnable version of everything below is on GitHub — data-safe-templates-net.
The data that breaks a working template
{ "Name": "Quayside Bistro", "Account": "00042", "Cards": [], "Loyalty": null }
A customer who has not added a payment card yet and is not in the loyalty programme. Nothing is malformed. And a template that handles both cases properly —
<<if [customer.Cards.Count() > 0]>>Card: <<[customer.Cards.First().Type]>><<else>>No payment card on file.<</if>>
— still does not assemble:
An error has been encountered at the end of expression 'customer.Cards.First().Type]>'.
Can not get the value of member 'Type' on type 'System.Data.DataRow'.
The branch never renders. The engine still has to resolve the expression, and an empty array has
no element type to resolve it against. The same reasoning turns "00042" into 42: with no
other information, a string of digits is a number.
1. A JSON Schema, when the shape is known
New in 26.11 — schema support for
JsonDataSource.
JsonDataSource dataSource = new JsonDataSource(
"data/Customer.json",
"data/Customer.schema.json");
new DocumentAssembler().AssembleDocument(
"templates/Json schema.docx",
"output/with-schema.docx",
new DataSourceInfo(dataSource, "customer"));
{
"type": "object",
"properties": {
"Name": { "type": "string" },
"Account": { "type": "string" },
"Cards": { "type": "array",
"items": { "type": "object", "properties": { "Type": { "type": "string" } } } },
"Loyalty": { "type": ["object", "null"], "properties": { "Level": { "type": "string" } } }
}
}
Now the element type of Cards is known whether or not any card is present, and Account is a
string because the schema says so. Both failures disappear, and nothing about the template changed.
Use this when the data comes from a system whose contract you know: an API, an export, or a language model you prompted with the same schema.
2. AllowMissingMembers, when the data is genuinely sparse
A member that is not in the data at all. By default that is an error. With the option it renders as an empty value:
DocumentAssembler assembler = new DocumentAssembler
{
Options = DocumentAssemblyOptions.AllowMissingMembers
};
This one deserves a moment of thought before you reach for it, because it is the easiest to misuse. It is right when a blank really is the correct output — an optional fax number, a middle name. It is wrong when a missing member means somebody renamed a field upstream and nobody noticed: with the option on, two thousand documents go out with a blank where the order total used to be, and nothing anywhere says so.
3. InlineErrorMessages, when the template is not yours
For templates edited by people outside your team. The error goes into the report, where the tag
was, and AssembleDocument returns false:
DocumentAssembler assembler = new DocumentAssembler
{
Options = DocumentAssemblyOptions.InlineErrorMessages
};
bool success = assembler.AssembleDocument(template, output, dataSourceInfo);
The batch finishes. The three documents that are wrong carry the reason in their own text, next to the tag that caused it, and you route those three to whoever owns the template instead of stopping the other 1,997.
Check the return value. A pile of documents with error text in them and nobody watching is worse than a crash.
Which one should you use?
| Situation | Use |
|---|---|
| The shape is known in advance; values may be empty, null or missing | a JSON Schema |
| The data is genuinely sparse and a blank is correct | AllowMissingMembers |
| Templates are edited outside your team | InlineErrorMessages, and check the return value |
| A missing member means something upstream broke | the default: let it throw |
They combine. A schema plus InlineErrorMessages is a reasonable default for a service that
assembles documents from data it does not own: the known shape is handled, and anything else is
visible rather than silent.
Questions people ask
How do I handle missing data in a Word template in C#?
Three ways, and they are not interchangeable: a JSON Schema when you know the shape in advance,
DocumentAssemblyOptions.AllowMissingMembers when the data is genuinely sparse, and
DocumentAssemblyOptions.InlineErrorMessages when the template is edited outside your team.
Why does an empty array break a template that guards it with <<if>>?
The branch does not have to render for the expression to be resolved, and an empty array carries no
element type to resolve .First().Type against. A JSON Schema supplies that type.
Why did my "00042" turn into 42?
Without a schema the engine infers types from the data, and a string of digits is read as a number.
Declaring "type": "string" keeps it.
Does AllowMissingMembers hide real problems?
It can, and that is the main reason to think before switching it on. If a member disappears because
somebody renamed a field upstream, the option turns that into blank space in every document and
nothing reports it.
Does AssembleDocument tell me a document came out wrong?
With InlineErrorMessages it returns false and puts the error into the document where the tag
was. Check the return value — a pile of documents with error text and nobody watching is worse than
an exception.
Try it
git clone https://github.com/groupdocs-assembly/data-safe-templates-net.git
cd data-safe-templates-net
dotnet run --project src/SafeTemplates -- all
It prints all four cases, including the two failures, so you can see exactly what each option changes.
The reference page is Templates for incomplete data.