How to Work with Fields in .NET

Step 1: Get the Library

Clone the repository and build Aspose.Words.sln in Release configuration, then add a project reference to Aspose.Words.csproj from your own .NET project, as described in the Installation guide. Add using Aspose.Words; and using Aspose.Words.Fields; at the top of any file that works with fields.

Step 2: Insert a Field and Read Its Result

DocumentBuilder.InsertField() inserts a new field at the cursor, with overloads that either update the field’s result immediately or leave it for a later update pass. Every field is a Field instance made of three marker nodes — FieldStart, Separator, and FieldEnd, exposed as Field.Start / Field.Separator / Field.End. Field.Type identifies which FieldType it represents, Field.Result and Field.DisplayResult hold the last-calculated value, Field.Format holds any format switches attached to the code, and Field.GetFieldCode() returns the raw field code text.

Step 3: Update Fields After a Programmatic Edit

Aspose.Words FOSS does not recalculate fields when the document loads or saves. After an edit that should change a field’s result, call Range.UpdateFields() to recalculate every field in that range — use Document.Range.UpdateFields() for the whole document — or Field.Update() for a single field. Range.UnlinkFields() converts every field in the range to static text in one call, and Range.NormalizeFieldTypes() reconciles a field’s stored type code against its actual field code after a manual edit.

Step 4: Configure Field Update Behavior with FieldOptions

Document.FieldOptions (a FieldOptions instance) governs how the whole document’s fields behave during an update: CurrentUser (a UserInformation instance — Name, Initials, Address) supplies the identity that author- and user-name-related fields read from, DefaultDocumentAuthor seeds author-related results, and LegacyNumberFormat / UseInvariantCultureNumberFormat / PreProcessCulture / FieldUpdateCultureSource control number and date formatting. For unattended pipelines, assign FieldOptions.UserPromptRespondent (an IFieldUserPromptRespondent) so prompt-driven fields like ASK and FILLIN don’t block waiting for interactive input, and assign a custom IFieldDatabaseProvider to FieldOptions.FieldDatabaseProvider to supply the DATABASE field’s rows from your own data source instead of a real database connection.

Step 5: Track Field Updates with a Callback

Implement IFieldUpdatingCallback (FieldUpdating and FieldUpdated) and assign it to FieldOptions to run code immediately before and after every field recalculates — useful for auditing exactly which fields changed in a batch job. For progress reporting across a large document, implement IFieldUpdatingProgressCallback (Notify), which receives a FieldUpdatingProgressArgs exposing TotalFieldsCount, UpdatedFieldsCount, and UpdateCompleted.

Step 6: Convert or Remove a Field

Field.Unlink() replaces the field with its last-calculated result as ordinary static text, discarding the underlying field code — use it when you want the value baked into the document permanently. Field.Remove() deletes the FieldStart, Separator, and FieldEnd nodes together with the field’s code and result, removing the field entirely. Prefer these two methods over deleting the marker nodes directly, since manually removing only part of a field’s structure can leave the document tree inconsistent.