Transitional Fields

This guide shows how to work with transitional field types — legacy barcode and compatibility fields — in Aspose.Words FOSS for .NET.

Aspose.Words FOSS for .NET represents certain older Word field types through a dedicated set of classes in the Aspose.Words.Fields namespace, informally called transitional fields. These are fields that predate later Open XML field equivalents but remain valid inside .docx documents opened from legacy sources. Each transitional field type has its own strongly-typed class deriving from Field, alongside the generic Field object exposed by Document.Range.Fields.

Barcode Fields

Three field classes generate or display barcode data inside a document: FieldBarcode (the BARCODE field — a legacy postal barcode with its own PostalAddress, IsBookmark, FacingIdentificationMark, and IsUSPostalAddress properties), FieldDisplayBarcode (the DISPLAYBARCODE field), and FieldMergeBarcode (the MERGEBARCODE field, which also implements IMergeFieldSurrogate for use during mail merge). FieldDisplayBarcode and FieldMergeBarcode share the same general-purpose barcode configuration properties — BarcodeType, BarcodeValue, SymbolHeight, SymbolRotation, ScalingFactor, ForegroundColor, BackgroundColor, PosCodeStyle, CaseCodeStyle, ErrorCorrectionLevel, DisplayText, AddStartStopChar, and FixCheckDigit — properties that FieldBarcode does not have.

The BarcodeParameters class is a pass-through container exposing the union of both property sets (the postal-address properties and the general barcode-configuration properties), used to hand settings to a barcode renderer, and IBarcodeGenerator is the interface a custom renderer implements, exposing GetBarcodeImage(parameters) and the legacy GetOldBarcodeImage(parameters). Iterate Document.Range.Fields and check Field.Type against FieldType.FieldBarcode, FieldType.FieldDisplayBarcode, or FieldType.FieldMergeBarcode to locate these fields, then cast to the specific field class — BarcodeValue and BarcodeType are only available after casting to FieldDisplayBarcode or FieldMergeBarcode, not FieldBarcode.

Legacy Compatibility Fields

Four additional field classes cover older Word field codes that are less common in newly authored documents but still appear in legacy .docx files: FieldBidiOutline (the BIDIOUTLINE field, for right-to-left outline numbering), FieldEQ (the EQ equation field, which also exposes AsOfficeMath() to convert its content to an OfficeMath object), FieldFootnoteRef (the FOOTNOTEREF field, which cross-references a footnote or endnote mark), and FieldInfo (the INFO field, which reads or writes a document summary-information property via its InfoType and NewValue properties).

Every one of these field classes inherits the same Field surface: GetFieldCode() returns the field’s underlying code text, Update() re-evaluates the field’s result, Unlink() replaces the field with its last calculated result, and Remove() deletes the field from the document. IFieldCodeTokenInfoProvider is implemented by FieldBarcode, FieldDisplayBarcode, FieldMergeBarcode, and FieldInfo, since their field codes carry structured switches beyond a plain instruction string.

Tips and Best Practices

Always check Field.Type before casting a generic Field to one of the transitional field classes — an incorrect cast throws an InvalidCastException.
Call Update() after changing a barcode field’s properties so Result reflects the new configuration before the document is saved.
FieldEQ.AsOfficeMath() only succeeds when the EQ field actually encodes an equation; verify the field’s Result looks like a formula before calling it.
Use Unlink() when you want to freeze a field’s current value as static text, discarding the ability to recalculate it later.
Barcode field classes only carry data — this FOSS edition does not include the barcode rendering engine, so GetBarcodeImage() output depends on the IBarcodeGenerator implementation you supply.

Common Issues

Issue	Cause	Fix
`InvalidCastException` when casting a `Field`	Wrong `FieldType` assumed	Check `Field.Type` against the matching `FieldType` constant first
`FieldEQ.AsOfficeMath()` returns unexpected results	Field does not contain a valid equation instruction	Inspect `GetFieldCode()` output before conversion
Barcode field has no rendered image	No `IBarcodeGenerator` implementation supplied	Provide a custom generator that implements `GetBarcodeImage()`
`FieldInfo` value not updated after `NewValue` change	Field not refreshed	Call `Update()` on the field after modifying `NewValue`

FAQ

What does “transitional” mean for these field types?

It is not official Word terminology — it groups field classes in this edition’s Aspose.Words.Fields namespace that implement older field codes (barcode and pre-Open-XML compatibility fields) through their own strongly-typed classes rather than being handled only through the generic Field object.

Does this edition render barcode images?

No. FieldBarcode, FieldDisplayBarcode, and FieldMergeBarcode hold barcode data and expose the IBarcodeGenerator interface, but no built-in barcode rendering engine ships in this edition — you supply your own IBarcodeGenerator implementation.

Can I convert an EQ field to an OfficeMath equation?

Yes, via FieldEQ.AsOfficeMath(), provided the field’s code actually encodes an equation.

How do I find all transitional fields in a document?

Enumerate Document.Range.Fields and compare each Field.Type to the relevant FieldType constants (FieldBarcode, FieldDisplayBarcode, FieldMergeBarcode, FieldBidiOutline, FieldEQ, FieldFootnoteRef, FieldInfo).

API Reference Summary

Class / Method	Description
`FieldBarcode`	Implements the `BARCODE` field
`FieldDisplayBarcode`	Implements the `DISPLAYBARCODE` field
`FieldMergeBarcode`	Implements the `MERGEBARCODE` mail-merge barcode field
`BarcodeParameters`	Container for barcode settings passed to a generator
`IBarcodeGenerator`	Interface for a custom barcode image renderer
`FieldBidiOutline`	Implements the `BIDIOUTLINE` field
`FieldEQ`	Implements the `EQ` equation field; `AsOfficeMath()` converts to `OfficeMath`
`FieldFootnoteRef`	Implements the `FOOTNOTEREF` field
`FieldInfo`	Implements the `INFO` document-property field

Transitional Fields