Fill Word’s content controls, or mapped fields, from data stored in custom XML.
dotnet add package RecursiveAI.OneDocument.Documents dotnet add package RecursiveAI.OneDocument
Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using RecursiveAI.OneDocument.Documents; using var doc = Document.Open("bound-template.docx"); doc.BindContentControls( new Dictionary<string, string> { ["Customer"] = "Ada" }); doc.SaveAs("bound.docx");
Writes bound.docx. The input bound-template.docx is in the example; its customer control maps to /order[1]/customer[1].
Unzip the example, then dotnet run.
The full program
The self-made template contains this custom XML:
<order><customer>Original</customer></order>Two plain-text controls initially display “Original”. The customer control binds to that node using store ID {11111111-1111-1111-1111-111111111111}. The missing control uses the same path but an absent store ID, {00000000-0000-0000-0000-000000000000}.
The full example uses a typed record. [TemplateModel] and partial let the source generator in the directly referenced RecursiveAI.OneDocument package implement the data adapter. Both package references in the project are pinned to 1.0.0.
using RecursiveAI.OneDocument.Templating; using RecursiveAI.OneDocument.Documents; using var doc = Document.Open("bound-template.docx"); var report = doc.BindContentControls(new CustomerData("Ada")); foreach (var warning in report.Warnings) Console.WriteLine(warning.Code); var customer = doc.ContentControls().Single(c => c.Tag == "customer"); Console.WriteLine($"Bound: {customer.Text}"); customer.SetText("Grace"); Console.WriteLine($"Before push: {customer.EvaluateBinding().Value}"); doc.PushContentControls(); Console.WriteLine($"After push: {customer.EvaluateBinding().Value}"); doc.RefreshContentControls(); Console.WriteLine($"Refreshed: {customer.Text}"); Console.WriteLine($"Missing: {doc.ContentControls().Single(c => c.Tag == "missing").EvaluateBinding().Status}"); doc.SaveAs("bound.docx"); Console.WriteLine("Wrote bound.docx"); [TemplateModel] public partial record CustomerData(string Customer);
binding.store-not-found Bound: Ada Before push: Ada After push: Grace Refreshed: Grace Missing: StoreNotFound Wrote bound.docx
A missing store produces binding.store-not-found in the report’s warnings and leaves that control’s text unchanged.
Variations
Refresh without changing the stored data. Run this against bound-template.docx from the zip:
using RecursiveAI.OneDocument.Documents; using var doc = Document.Open("bound-template.docx"); doc.RefreshContentControls(); Console.WriteLine(doc.ContentControls() .Single(c => c.Tag == "customer").Text);
OriginalRelated recipes
The short answer
Use Document.BindContentControls(data) when a DOCX already contains content controls with w:dataBinding mappings. It writes values into the custom XML part and updates the visible controls. Use RefreshContentControls() to display the values already stored in the part. Use PushContentControls() after editing the controls when the custom XML must receive those edits.
This is different from replacing placeholder text. A content control has a persistent mapping: a store item ID, an XPath and, when necessary, namespace mappings. The binding documentation describes how each control type is read and written.
How do you map Word content controls to custom XML?
A mapping identifies a store with w:storeItemID and a node with w:xpath. The store ID is matched case-insensitively against the custom XML part’s properties. The example uses no-namespace XML, so its path has no prefixes. For namespaced XML, prefixes come from w:prefixMappings; an unprefixed name does not match an element in a default namespace.
When binding an object, the path is also interpreted as a path into that data. The root element’s name is not matched, property names are matched ignoring case, and an index such as [1] selects the first list item. Thus the record’s Customer property supplies the value for the template’s customer node. A missing node can be created; a missing custom XML store is instead a warning.
The top snippet uses a dictionary, so it needs no generated model. The full program demonstrates a record with generated binding. An ordinary class without the generated adapter is not read by reflection and throws OfficeUnsupportedException. JSON, dictionaries and XML are other documented inputs.
How do you link content controls in Word?
Controls can refer to the same XML node. Treat the stored value as shared data, not as a live event connection in your C# process. SetText changes the selected control but does not push that edit to its XML node. The full program prints “Ada” before the explicit push and “Grace” afterward. A refresh then reads the stored value back into the controls.
Choose the direction deliberately: bind application data, refresh from XML, or push control edits into XML. Refreshing after a local edit without pushing first replaces the displayed edit with the stored value. Save the document after the desired synchronization step; this example writes a new DOCX rather than overwriting the template.
How do mapped content controls work with repeating data?
A repeating section bound to a repeated node uses its first item as the pattern. Binding copies or trims items to the number of nodes and re-indexes the paths inside them. Nested repeating sections are supported. A section without a template item reports binding.no-template-item; it cannot invent a layout for the repeated content.
EvaluateBinding() is a read-only way to inspect a mapping. Its status distinguishes Resolved, NoMatch, StoreNotFound, UnsupportedPath and Invalid. It supports an XPath 1.0 subset, not arbitrary XPath: child and descendant steps, attributes, text nodes, positional predicates and the comparisons and functions listed in the docs. Unsupported axes or functions do not silently evaluate as a valid empty value. Check the returned status and the binding report’s warnings before deciding that an empty field means empty source data.