Forms and content controls
Word has two kinds of form control: modern content controls (Developer tab › Controls) and legacy form fields. DocWright reads and fills both. You don't need to render anything: load, fill and save.
See what a form contains
using DocWright;
using DocWright.Dom;
using DocWright.Dom.ContentControls;
using DocWright.Dom.Forms;
using FileStream input = File.OpenRead("forms.docx");
using WordDocument document = converter.Load(input);
// Content controls (Developer tab › Controls): body, headers, footers and notes.
foreach (ContentControl control in document.FindContentControls())
{
Console.WriteLine($"control {control.Kind,-14} tag={control.Tag ?? "-",-10} value={control.GetValue()}");
}
// Legacy form fields (the Word 97 ones).
foreach (FormField field in document.FindFormFields())
{
Console.WriteLine($"field {field.Kind,-14} name={field.Name ?? "-",-10} value={field.GetValue()}");
}
Output (this step, and the refusal further down)
control PlainText tag=name value=Ada Lovelace
control RichText tag=summary value=Rich text keeps its own run formatting.
control CheckBox tag=agreeYes value=true
control CheckBox tag=agreeNo value=false
control DropDownList tag=dept value=ENG
control ComboBox tag=office value=WLG
control DatePicker tag=signed value=6 August 2026
control BuildingBlockGallery tag=block value=Quick part placeholder.
control Group tag=group value=Grouped content is locked as a unit.
control RepeatingSection tag=lines value=First line item.
Second line item.
control RepeatingSectionItem tag=- value=First line item.
control RepeatingSectionItem tag=- value=Second line item.
control PlainText tag=signer value=Grace Hopper
field Text name=FullName value=Katherine Johnson
field CheckBox name=Agree value=true
field DropDown name=Dept value=Engineering
ContentControlEditException: 'Not an option' is not one of the drop-down list's entries, and a drop-down list accepts nothing else. Add the entry first, or use a combo box.
Fill it
using DocWright.Dom.ContentControls;
using DocWright.Dom.Forms;
foreach (ContentControl control in document.FindContentControls())
{
switch (control.Kind)
{
case ContentControlKind.PlainText:
case ContentControlKind.RichText:
control.SetValue("Filled by DocWright");
break;
case ContentControlKind.CheckBox:
control.SetValue("true"); // also repaints the check glyph
break;
case ContentControlKind.DatePicker:
control.SetDate(new DateTimeOffset(2026, 10, 1, 0, 0, 0, TimeSpan.Zero));
break;
case ContentControlKind.DropDownList:
case ContentControlKind.ComboBox:
control.SetValue(control.ListItems[^1].DisplayText); // pick the last entry
break;
}
}
foreach (FormField field in document.FindFormFields())
{
if (field.Kind == FormFieldKind.CheckBox)
{
field.IsChecked = true;
}
else if (field.Kind == FormFieldKind.Text)
{
field.SetValue("Katherine Johnson"); // truncated to the field's max length
}
}
Before
After| Content control kind | Set it with |
|---|---|
PlainText, RichText |
SetValue(text) |
CheckBox |
SetValue("true"), or IsChecked = true. The check glyph is repainted too. |
DropDownList |
SetValue(value or display text). It must be one of the entries. |
ComboBox |
SetValue(anything). Free text is allowed. |
DatePicker |
SetDate(DateTimeOffset, culture?). The control's date format is applied. |
RepeatingSection |
AddRepeatingItem(), MoveRepeatingItem(item, index), RemoveRepeatingItem(item) |
Find controls with FindContentControls(), FindContentControls(kind) or FindContentControlsByTag(tag). Tags are the reliable handle: set them in Word's control properties.
Invalid values are refused
A drop-down only accepts its own entries, as in Word. An edit DocWright can't make with certainty throws and changes nothing:
using DocWright.Dom.ContentControls;
using DocWright.Core;
// A drop-down only accepts one of its own entries, as in Word.
ContentControl? dropDown = document.FindContentControls(ContentControlKind.DropDownList).FirstOrDefault();
try
{
dropDown?.SetValue("Not an option");
}
catch (DocWrightException ex)
{
Console.WriteLine($"{ex.GetType().Name}: {ex.Message}");
}
Legacy form fields
FindFormFields() and FindFormField(name) return FormField objects. Set IsChecked on check boxes, SelectedIndex on drop-downs, and SetValue(text) on text fields. Text is cut to the field's maximum length. A check box shows CheckedState ?? IsCheckedByDefault: its stated state if there is one, otherwise its default.
Flatten before sending
To send a filled form to someone who shouldn't edit it, replace each field with what it shows:
using DocWright.Dom.Forms;
// For a recipient with no interactive fields: keep what is shown, drop the field.
foreach (FormField field in document.FindFormFields().ToList())
{
field.Flatten();
}
Reading changes nothing
Reading a control's properties never modifies the document. A control you only inspect saves byte-for-byte, and properties DocWright doesn't model are preserved even when you edit others.
Protection is not security
document.Settings.Protection tells you what the author restricted, for example forms-only editing, and it is preserved on save, including the password hash. DocWright does not enforce it. Every editing API works on a protected document. Treat protection as the author's intent, not as a security control.
Custom XML data binding
A content control can be bound to a node in a custom XML part stored inside the document. Word treats the XML as the source of truth. CustomXmlDataStore.Open(document) gives you the parts:
| Call | Does |
|---|---|
store.RefreshBoundControls() |
Copies the XML values into the bound controls. |
store.SetBoundValue(control, value) |
Updates both the control and its XML node. |
store.ReadValue(binding), store.WriteValue(binding, value) |
Reads or writes the XML only. |
store.Flush() |
Writes changed parts back to the document before you save. |
The document's own properties are bound the same way: Word binds docProps/core.xml (title, subject, author, ...) as
store {6C3C8BC8-F283-45AE-878A-BAB7291924A1} and docProps/app.xml (company, manager) as
{6668398D-A668-4E3E-A5EB-62B293D839F1}, and the store resolves both.
Typing into a plain-text control
A plain-text content control takes typed text through the ordinary edits, as Word's do: InsertText, DeleteRange and
ReplaceRange with both ends in the control change its value. Tabs go in; line endings are dropped in a single-line
control and become line breaks in a multi-line one; SplitParagraph (Enter) is refused. Typing over the placeholder
replaces all of it, and deleting the last character puts it back. FormatText with an end in the control formats the
whole control. A bound control writes its value through to its node, and every control bound to that node shows it;
SetCoreProperties and SetExtendedProperties update the controls bound to what they change. Each is one undo step.
ContentControl title = document.FindContentControlsByTag("title").Single(); // bound to dc:title
Paragraph paragraph = title.Node is SdtBlock block ? (Paragraph)block.Blocks[0] : (Paragraph)title.Node.Parent!;
document.InsertText(DocumentPosition.EndOf(paragraph), " (draft)");
string? written = document.ReadCoreProperties().Title; // ends with " (draft)"
Bindings use the XPath Word generates: absolute element paths with optional positions and an optional final attribute. Anything else throws ContentControlBindingException, naming the unsupported construct, instead of resolving the wrong node.