How to Work with Structured Document Tags in .NET

Step 1: Install the Package

Aspose.Words FOSS for .NET does not yet publish a NuGet package – build the library from source instead. Clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, then build Aspose.Words.sln in Release configuration with the .NET SDK and reference the resulting Aspose.Words assembly from your project. The library targets .NET Standard 2.0, so it runs on .NET Framework 4.6.2+ and .NET 6/8/10.

Step 2: Import Required Classes

Add a using Aspose.Words; directive for Document and DocumentBuilder, and a using Aspose.Words.Markup; directive for StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping, and the other content-control classes this guide covers.

Step 3: Check Which Content-Control Types You Can Insert

Before inserting, check whether the target SdtType is one of the seven types accepted by DocumentBuilder.InsertStructuredDocumentTag(SdtType): PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, and Date. RepeatingSection and RepeatingSectionItem cannot be inserted at a text cursor with this method – they wrap entire paragraphs or table rows instead. The remaining SdtType values that can appear in a Word file but are not present in the Word UI as insertable types – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group, and EntityPicker – are not accepted by this insertion method at all.

Step 4: Insert a Content Control at the Cursor

Call DocumentBuilder.InsertStructuredDocumentTag(SdtType) with one of the seven supported types to insert a new control at the builder’s current cursor position; the call returns the new StructuredDocumentTag. Set Tag and Title on the returned control to give it the identifying strings authors see in Word, and set PlaceholderName (backed by a Placeholder BuildingBlock) for the prompt text Word shows while the control is empty – IsShowingPlaceholderText reports whether that prompt is currently displayed.

Step 5: Configure Type-Specific Content

For a checkbox control, read or set StructuredDocumentTag.Checked, and call SetCheckedSymbol() / SetUncheckedSymbol() to customize the glyphs shown for each state. For a date control, set FullDate, with DateDisplayFormat and DateDisplayLocale controlling how it renders, DateStorageFormat (SdtDateStorageFormat) controlling how it is stored when bound to XML data, and CalendarType (SdtCalendarType) selecting the calendar system. For a drop-down list or combo box, populate ListItems – an SdtListItemCollection of SdtListItem (DisplayText, Value) – before setting SelectedValue to pick the active choice. For a plain-text control, Multiline is a bool property on StructuredDocumentTag that can be set to configure the control.

Step 6: Control Appearance and Locking

Set Appearance (SdtAppearance) to control how the control is visually delimited in Word, and Color to set its highlight color. ContentsFont and EndCharacterFont control the font applied to the control’s contents and its trailing end character. LockContentControl and LockContents are independent switches – set LockContentControl to block deletion of the control itself, and LockContents to block editing of what is inside it, without affecting the other.

Step 7: Find and Remove Content Controls

Read Range.StructuredDocumentTags – a StructuredDocumentTagCollection scoped to that range – and call GetById(), GetByTag(), or GetByTitle() to locate a specific control, or Remove() / RemoveAt() on the collection to remove one by reference or index. On an individual control, call Remove() to delete the control together with its contents, RemoveSelfOnly() to delete only the wrapper while keeping its contents in the document, or Clear() to empty its contents while keeping the control itself in place.

Step 8: Bind a Control to Custom XML Data

Read StructuredDocumentTag.XmlMapping – an XmlMapping instance – and call SetMapping(customXmlPart, xPath, prefixMapping) to bind the control to an existing custom XML part already present in the document’s custom XML data store, using an XPath expression to select the bound element. XmlMapping.IsMapped reports whether a binding is currently active, CustomXmlPart and StoreItemId identify the bound data part, and Delete() removes the mapping.

Step 9: Handle Content Controls That Span Multiple Sections

A content control spanning more than one document section – reported by IsMultiSection – is represented not by a single StructuredDocumentTag node but by a StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd pair, connected through StructuredDocumentTagRangeStart.RangeEnd. Program against the shared IStructuredDocumentTag interface (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()) when code needs to handle both the single-node and ranged forms uniformly, rather than branching on the concrete type.