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

Remarks

Use MailMerge to access mail merge operations for a document.

Merge fields within the document are automatically detected, whether they were created using Microsoft Word or another compatible library.

Call GetFieldNames() to retrieve all available merge field names. Then use one of the Execute overloads to populate those fields with data.

For repeating regions, use ExecuteWithRegions(DataSet) with fields marked by TableStart:Region and TableEnd:Region.

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>