Class MailMerge

Provides mail merge functionality for a WordDocument.

Inheritance
System.Object
MailMerge
Namespace: IronWord.Models.MailMerge
Assembly: IronWord.dll
Syntax
public class MailMerge : Object

Populating a Word template with data, names on a batch of letters, line items on an invoice, rows in a report, runs through MailMerge. It detects the merge fields already in a document, whether they were authored in Microsoft Word or another compatible library, and fills them from the data a developer supplies. It is the type behind a "C# mail merge" search, and it sits alongside MergeField, the read-only record describing one discovered field, and MailMergeOptions, the settings that govern the run.

A document hands back its merge facade through the get-only WordDocument.MailMerge property, so there is no separate object to construct. From there the members fall into four groups. **Discovery**: GetFieldNames lists every merge field name, GetFields returns the richer MergeField records, and GetRegionNames reports the repeating-region names. **Flat merge**: the Execute overloads fill the fields once, accepting an IDictionary<string, string>, a parallel pair of IEnumerable<string> names and values, a DataRow, or a DataTable (whose first row supplies the values). **Region merge**: the ExecuteWithRegions overloads repeat a block of the template per data row, accepting a DataSet, a DataTable, or a region name paired with a DataTable, driven by fields marked TableStart:Region and TableEnd:Region. **Configuration**: the Options property exposes a MailMergeOptions for null handling and unused-field removal.

The usual sequence is to read the field names, build matching data, then call one Execute overload for a single record or ExecuteWithRegions for a repeating section. Configure Options first if the defaults need adjusting, then save the document as usual.

WordDocument document = new WordDocument("template.docx");
document.MailMerge.Execute(new Dictionary<string, string>
{
    ["FirstName"] = "Ada",
    ["Company"] = "Iron Software"
});
document.Save("letter.docx");

The replace words how-to covers replacing field text, the create word from text example builds a document to merge into, and the document element tutorial explains the document model around it.

Properties

Options

Gets the options that control how this MailMerge instance behaves.

Declaration
public MailMergeOptions Options { get; }
Property Value
Type Description
MailMergeOptions

Methods

Execute(IDictionary<String, String>)

Replaces every merge field whose name appears in data with the matching value. Fields that have no entry are removed (when RemoveUnusedFields is true) or left in place.

Declaration
public void Execute(IDictionary<string, string> data)
Parameters
Type Name Description
System.Collections.Generic.IDictionary<System.String, System.String> data

A dictionary keyed by merge field name.

Execute(IEnumerable<String>, IEnumerable<String>)

Replaces fields named in fieldNames with the corresponding entries in values.

Declaration
public void Execute(IEnumerable<string> fieldNames, IEnumerable<string> values)
Parameters
Type Name Description
System.Collections.Generic.IEnumerable<System.String> fieldNames
System.Collections.Generic.IEnumerable<System.String> values
Exceptions
Type Condition
System.ArgumentException

Thrown when fieldNames and values are different lengths.

Execute(DataRow)

Replaces fields using the column names of dataRow as field names.

Declaration
public void Execute(DataRow dataRow)
Parameters
Type Name Description
System.Data.DataRow dataRow

Execute(DataTable)

Replaces fields using the column names of dataTable as field names and the first row's values. Equivalent to calling Execute(DataRow) with dataTable.Rows[0].

Declaration
public void Execute(DataTable dataTable)
Parameters
Type Name Description
System.Data.DataTable dataTable

ExecuteWithRegions(DataSet)

Expands every TableStart/TableEnd region in the document by repeating its content once for each row of the matching table in dataSet.

Declaration
public void ExecuteWithRegions(DataSet dataSet)
Parameters
Type Name Description
System.Data.DataSet dataSet

A System.Data.DataSet containing tables that correspond to region names defined by TableStart:RegionName and TableEnd:RegionName fields.
Remarks

Tables are matched to regions by name.

Non-region merge fields are not populated by this method. To populate standard merge fields, call Execute(IDictionary<String, String>) after region expansion.

ExecuteWithRegions(DataTable)

Expands a single region using dataTable's System.Data.DataTable.TableName as the region name.

Declaration
public void ExecuteWithRegions(DataTable dataTable)
Parameters
Type Name Description
System.Data.DataTable dataTable

ExecuteWithRegions(String, DataTable)

Expands the named region with rows from dataTable.

Declaration
public void ExecuteWithRegions(string regionName, DataTable dataTable)
Parameters
Type Name Description
System.String regionName
System.Data.DataTable dataTable

GetFieldNames()

Gets the names of every value-style merge field declared in the document (in document order, deduplicated).

Declaration
public IReadOnlyList<string> GetFieldNames()
Returns
Type Description
System.Collections.Generic.IReadOnlyList<System.String>

GetFields()

Gets every merge field discovered in the document, including TableStart/TableEnd markers.

Declaration
public IReadOnlyList<MergeField> GetFields()
Returns
Type Description
System.Collections.Generic.IReadOnlyList<MergeField>

GetRegionNames()

Gets the names of every TableStart region declared in the document.

Declaration
public IReadOnlyList<string> GetRegionNames()
Returns
Type Description
System.Collections.Generic.IReadOnlyList<System.String>