How to Work with Transitional Fields in .NET

Step 1: Find Transitional Fields in a Document

Enumerate Document.Range.Fields and compare each field’s Type (a FieldType value) against the relevant constants — FieldBarcode, FieldDisplayBarcode, FieldMergeBarcode, FieldBidiOutline, FieldEQ, FieldFootnoteRef, or FieldInfo — then cast the generic Field to the matching class to access its specific properties. Always check Type before casting: casting to the wrong field class throws an InvalidCastException.

Step 2: Configure a DISPLAYBARCODE or MERGEBARCODE Field

FieldDisplayBarcode (the DISPLAYBARCODE field) and FieldMergeBarcode (the MERGEBARCODE field, which also implements IMergeFieldSurrogate for mail merge) share the same set of barcode-configuration properties: BarcodeType, BarcodeValue, SymbolHeight, SymbolRotation, ScalingFactor, ForegroundColor, BackgroundColor, PosCodeStyle, CaseCodeStyle, ErrorCorrectionLevel, DisplayText, AddStartStopChar, and FixCheckDigit. Set these on the field instance, then call Update() so Result reflects the new configuration before the document is saved.

Step 3: Read Legacy BARCODE (Postal) Field Data

FieldBarcode implements the older BARCODE field, which is specifically a US postal barcode (POSTNET) field rather than a general-purpose barcode — it does not share the BarcodeType/BarcodeValue properties from Step 2. Instead it exposes PostalAddress (the address the barcode encodes), FacingIdentificationMark, IsUSPostalAddress, and IsBookmark. Check Field.Type against FieldType.FieldBarcode specifically before reading these properties, since casting a DISPLAYBARCODE or MERGEBARCODE field to FieldBarcode would not expose the properties you expect.

Step 4: Render Barcode Images with a Custom Generator

This FOSS edition carries barcode field data but does not include a barcode rendering engine. BarcodeParameters is the pass-through container that consolidates settings from either barcode-field family — the DISPLAYBARCODE/MERGEBARCODE properties from Step 2 and the postal properties from Step 3 — into a single object handed to a renderer. Implement IBarcodeGenerator, exposing GetBarcodeImage(parameters) and the legacy GetOldBarcodeImage(parameters), to supply the actual image rendering; without a supplied implementation, barcode fields carry configuration data only.

Step 5: Work with Legacy Compatibility Fields

Four other classes cover older field codes still found in legacy .docx files. FieldBidiOutline implements the BIDIOUTLINE field for right-to-left outline numbering and exposes no properties beyond the common Field surface. FieldEQ implements the EQ equation field and additionally exposes AsOfficeMath() to convert its content to an OfficeMath object — this only succeeds when the field actually encodes an equation. FieldFootnoteRef implements the FOOTNOTEREF field, which cross-references a footnote or endnote mark, and also exposes no properties beyond the common Field surface. FieldInfo implements the INFO field, reading or writing a document summary-information property through its InfoType and NewValue properties.

Step 6: Update or Freeze a Transitional Field’s Value

Every transitional field class inherits GetFieldCode() (the field’s underlying code text), Update() (re-evaluates the result), Unlink() (replaces the field with its last calculated result as static text), and Remove() (deletes the field). Call Update() after changing any field’s configuration so Result reflects the change, and use Unlink() when a field’s current value should be frozen rather than remaining recalculable.