Building Fields with FieldBuilder

Building Fields with FieldBuilder

This guide shows how to construct a Word field from scratch in Aspose.Words FOSS for .NET using FieldBuilder and FieldArgumentBuilder, instead of working with a field that already exists in a document. For reading, updating, or removing existing fields, see the Working with Fields guide.

Creating a Field with FieldBuilder

FieldBuilder builds a field from field code tokens — arguments and switches. Construct one with new FieldBuilder(fieldType), passing the FieldType of the field you want to build. Add arguments with the overloaded AddArgument(argument) method, which accepts a string, int, double, a nested FieldBuilder, or a FieldArgumentBuilder. Add switches with the overloaded AddSwitch(switchName), AddSwitch(switchName, switchArgument) (string), or AddSwitch(switchName, switchArgument) (int/double) methods.

Inserting the Built Field

Once a FieldBuilder has its arguments and switches, call BuildAndInsert(refNode) to insert it into the document — one overload accepts an Inline node and inserts the field before it, and another accepts a Paragraph and inserts the field at the end of that paragraph.

Composing Complex Arguments with FieldArgumentBuilder

FieldArgumentBuilder builds a complex field argument made up of fields, nodes, and plain text, for cases where a single argument needs more than a plain string. Construct one with new FieldArgumentBuilder(), then call AddText(text) to add plain text, AddNode(node) to add an Inline node, or AddField(fieldBuilder) to nest another field (built with its own FieldBuilder) inside the argument. Pass the completed FieldArgumentBuilder to FieldBuilder.AddArgument(argument) to use it as one of the outer field’s arguments.

Tips and Best Practices

• Use FieldBuilder when constructing a field type that isn’t backed by one of the dedicated field classes (such as FieldDate or FieldSymbol), or when generating field codes programmatically from data rather than hand-authoring them.
• Nest a child field inside an outer field’s argument with FieldBuilder.AddArgument(FieldBuilder) for a simple case, or build a mixed argument of text, nodes, and nested fields with FieldArgumentBuilder when the argument is more than a single field.
• Pick the BuildAndInsert(refNode) overload that matches where you want the field to land — before a specific Inline node, or at the end of a Paragraph.
• After BuildAndInsert, treat the result like any other field in the tree — for example, call Update() on it if the field type requires an explicit recalculation.

Common Issues

FAQ

When should I use FieldBuilder instead of inserting a pre-formed field code?

Use FieldBuilder when you need explicit control over a field’s arguments and switches as you construct them programmatically, rather than inserting a pre-formed field code string.

How do I add more than one argument to a field?

Call AddArgument once per argument — it’s overloaded for string, int, double, a nested FieldBuilder, and FieldArgumentBuilder.

Can I build a field whose argument contains a mix of text and another field?

Yes — use FieldArgumentBuilder, calling AddText, AddNode, and AddField as needed, then pass it to FieldBuilder.AddArgument.

How do I actually put the built field into the document?

Call BuildAndInsert(refNode), passing either an Inline node (inserts before it) or a Paragraph (inserts at its end).

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation