---
title: "Bind Word content controls in C#"
url: https://recursiveai.org/onedocument/cookbook/bind-word-content-controls/
description: "Bind Word content controls to custom XML in C# with OneDocument for .NET 10. Download a runnable example with sample inputs and see its actual output."
version: "1.0.0"
---

# Bind Word content controls in C#

**OneDocument** is a free, open-source Word, Excel and PowerPoint document library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneDocument.Documents) · [GitHub](https://github.com/recursive-ai-oss/onedocument-csharp) · [Docs](https://recursiveai.org/onedocument/docs/) · [Download example (.zip)](https://recursiveai.org/onedocument/cookbook/bind-word-content-controls/bind-word-content-controls.zip)

Fill Word’s content controls, or mapped fields, from data stored in custom XML.

```shell
dotnet add package RecursiveAI.OneDocument.Documents
dotnet add package RecursiveAI.OneDocument
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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](https://recursiveai.org/onedocument/cookbook/bind-word-content-controls/bind-word-content-controls.zip), then `dotnet run`.

## The full program

The self-made template contains this custom XML:

```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.

```csharp
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);
```

```text
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:

```csharp
using RecursiveAI.OneDocument.Documents;
using var doc =
    Document.Open("bound-template.docx");
doc.RefreshContentControls();
Console.WriteLine(doc.ContentControls()
    .Single(c => c.Tag == "customer").Text);
```

```text
Original
```

## Related recipes

- [Fill a Word placeholder template](https://recursiveai.org/onedocument/cookbook/fill-word-template/)
- [Read a Word document](https://recursiveai.org/onedocument/cookbook/read-word-document/)

## 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](https://recursiveai.org/onedocument/docs/docx-content-controls/) 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.
