Mail Merge

Mail Merge

This guide shows how to work with mail-merge field codes and mail-merge configuration data in Aspose.Words FOSS for .NET, and where the boundary with merge execution lies. Aspose.Words FOSS for .NET recognizes and updates the Word mail-merge field codes — ADDRESSBLOCK, DATABASE, GREETINGLINE, MERGEFIELD, NEXTIF, and SKIPIF — as part of its field evaluation engine, and can read the mail-merge configuration data (MailMergeSettings) persisted inside a document. Running an actual merge against an external data source to generate populated output documents — the MailMerge.Execute() workflow familiar from the commercial product — is not implemented in this edition; no MailMerge execution class exists in the current API surface.

MERGEFIELD — Reading and Modifying Merge Placeholders

FieldMergeField implements the MERGEFIELD field. FieldName and FieldNameNoPrefix return the underlying data-source column name the field is bound to, TextBefore/TextAfter hold literal text wrapped around the merged value, and IsMapped/IsVerticalFormatting report merge-field mapping and layout flags. Like every field type, it supports GetFieldCode(), Update(), Unlink(), and Remove().

ADDRESSBLOCK and GREETINGLINE

FieldAddressBlock implements the ADDRESSBLOCK field, with FormatAddressOnCountryOrRegion, IncludeCountryOrRegionName, ExcludedCountryOrRegionName, NameAndAddressFormat, and LanguageId controlling how the recipient’s address is formatted. FieldGreetingLine implements GREETINGLINE, with AlternateText, NameFormat, and LanguageId controlling the salutation text.

DATABASE Field

FieldDatabase implements the DATABASE field, exposing the connection details persisted in the field: Connection, FileName, Query, TableFormat, InsertHeadings, InsertOnceOnMailMerge, FirstRecord, and LastRecord. To supply query results when this field is updated, implement IFieldDatabaseProvider and its GetQueryResult(fileName, connection, query, field) method, then assign it to Document.FieldOptions.FieldDatabaseProvider before calling Update(). The Connection property must be set — without it, Update() has no data source to query.

Conditional Merge Fields — NEXTIF and SKIPIF

FieldNextIf and FieldSkipIf implement the NEXTIF and SKIPIF fields, each exposing LeftExpression, ComparisonOperator, and RightExpression for the conditional test. Document.FieldOptions.ComparisonExpressionEvaluator (an IComparisonExpressionEvaluator) can override how these conditional expressions are evaluated.

Picture Merge Field Sizing

MergeFieldImageDimension represents a width or height for an image inserted through a picture merge field, constructed as new MergeFieldImageDimension(value) (in points) or new MergeFieldImageDimension(value, unit) with an explicit MergeFieldImageDimensionUnit (Point or Percent). Its Value and Unit properties are both writable.

What’s In Scope, and What Isn’t

Document.MailMergeSettings returns a MailMergeSettings object that models the mail-merge configuration OOXML persists inside a document — DataSource, ConnectString, Query, MainDocumentType, DataType, Destination, CheckErrors, and the Office Data Source Object (ODSO) settings via OdsoFieldMapData/OdsoRecipientData collections. This is configuration data the document carries, not a live connection: reading and writing MailMergeSettings does not connect to a database, spreadsheet, or address list, and this edition has no MailMerge execution class to run a merge and produce populated output documents from it. What this edition does support is the field-level layer above: recognizing, reading, updating, and modifying the merge field codes themselves within a single document via the field evaluation engine.

Tips and Best Practices

• Treat MailMergeSettings as document metadata you can read and round-trip, not as an API for connecting to external data — there’s no execution engine behind it in this edition.
• Always set FieldDatabase.Connection before calling Update() on a DATABASE field, or the update has nothing to query.
• Implement IFieldDatabaseProvider once and assign it via Document.FieldOptions.FieldDatabaseProvider to centralize how all DATABASE fields in a document resolve their data.
• Use FieldMergeField.FieldName to read which data-source column a MERGEFIELD is bound to before deciding how to process it programmatically.

Common Issues

FAQ

Can I run a mail merge against a CSV or database in this edition?

No. This edition implements the mail-merge field codes and the MailMergeSettings configuration data model, but there’s no MailMerge execution class to connect to an external data source and generate populated documents.

What can I actually do with MERGEFIELD fields, then?

You can read and modify them directly — FieldMergeField.FieldName for the bound column name, TextBefore/TextAfter for surrounding literal text, and Update()/Unlink()/Remove() like any other field — within the current document.

Is MailMergeSettings useless without merge execution?

No — it’s still useful for reading or round-tripping a document’s stored mail-merge configuration, such as DataSource, Query, or MainDocumentType, even though this edition doesn’t act on that configuration to run a merge.

How do I supply data for a DATABASE field?

Implement IFieldDatabaseProvider.GetQueryResult(fileName, connection, query, field) and assign your implementation to Document.FieldOptions.FieldDatabaseProvider before calling Update().

How do I control the size of an image inserted by a picture merge field?

Use MergeFieldImageDimension, constructed with a point value or a value plus an explicit MergeFieldImageDimensionUnit (Point or Percent).

API Reference Summary

See Also

• Aspose.Words for .NET — Enterprise Documentation