Where does MailMergeOptions live in the IronWord API?

MailMergeOptions is a class in the IronWord.Models.MailMerge namespace, shipped in IronWord.dll, with base type System.Object. Reach an instance through the Options property of a MailMerge and adjust it before calling Execute.

How do you keep unused merge fields in an IronWord document?

Set MailMerge.Options.RemoveUnusedFields to false; unused fields default to being removed. Use NullValueReplacement to substitute text for null data values, and RemoveUnusedRegions to control whether empty TableStart/TableEnd regions are dropped.

Class MailMergeOptions

Configures how a mail merge operation handles unmatched fields, missing values, and unused regions.

Inheritance

System.Object

MailMergeOptions

Namespace: IronWord.Models.MailMerge

Assembly: IronWord.dll

Syntax

public class MailMergeOptions : Object

Controlling how a mail merge treats fields the data does not cover runs through MailMergeOptions. It collects the settings that decide what happens to merge fields with no matching value, what replaces a null, and whether unused fields and table regions stay in the finished document. The defaults match Microsoft Word's behaviour, so an unconfigured merge produces a clean result without any setup.

Reach the settings through the Options property of a MailMerge, which exposes a MailMergeOptions to adjust before running Execute. CaseInsensitiveFieldNames (default true) controls whether field-name lookups ignore case. NullValueReplacement (default an empty string) is the text substituted when the data source supplies a null. RemoveUnusedFields (default true) drops fields whose names never appear in the data, and RemoveUnusedRegions (default true) removes TableStart/TableEnd regions for which no rows were supplied. Set these before the merge so the result reflects the chosen handling. The replace words how-to covers replacing field text in a document.

mailMerge.Options.NullValueReplacement = "N/A";
mailMerge.Options.RemoveUnusedFields = false;

Constructors

MailMergeOptions()

Declaration

public MailMergeOptions()

Properties

CaseInsensitiveFieldNames

Gets or sets a value indicating whether merge field name lookups should be case-insensitive. Defaults to true to match Microsoft Word's behaviour.

Declaration

public bool CaseInsensitiveFieldNames { get; set; }

Property Value

Type	Description
System.Boolean

NullValueReplacement

Gets or sets the value used to substitute a merge field when the data source supplies a null value for it. Defaults to an empty string.

Declaration

public string NullValueReplacement { get; set; }

Property Value

Type	Description
System.String

RemoveUnusedFields

Gets or sets a value indicating whether merge fields whose names do not appear in the supplied data source should be removed from the document. Defaults to true.

Declaration

public bool RemoveUnusedFields { get; set; }

Property Value

Type	Description
System.Boolean

RemoveUnusedRegions

Gets or sets a value indicating whether TableStart/TableEnd regions for which no data was supplied should be removed from the document. Defaults to true.

Declaration

public bool RemoveUnusedRegions { get; set; }

Property Value

Type	Description
System.Boolean