Class MailMerge

Represents the mail merge functionality in the Word document.

Inheritance

System.Object

MailMerge

Namespace: Syncfusion.DocIO.DLS

Assembly: Syncfusion.DocIO.Portable.dll

Syntax

public class MailMerge : Object

Properties

ClearFields

Gets or sets a value indicating whether to remove empty mail merge fields from a document. The default is true.

Declaration

public bool ClearFields { get; set; }

Property Value

Type	Description
System.Boolean	Set true to remove empty mail merge fields from a document; otherwise, false.

Document

Gets the document.

Declaration

protected WordDocument Document { get; }

Property Value

Type	Description
WordDocument	The document.

InsertAsNewRow

Gets or sets a value indicating whether to insert a new row for every group in a table while performing mail merge. Default value is false.

Declaration

public bool InsertAsNewRow { get; set; }

Property Value

Type	Description
System.Boolean	Set True to insert a new row for every group in a table; otherwise, false.

Remarks

This property is valid only if the group start and group end fields present in the table row with single cell. (i.e., rows containing single cell)

Examples

//Opens the template document.
WordDocument document = new WordDocument("Template.docx", FormatType.Docx);
//Set "InsertAsNew" as true to insert a new row for every group when group start and end present in the same table cell.
document.MailMerge.InsertAsNewRow = true;
//Performs the mail merge.
document.MailMerge.ExecuteGroup(DataTable);
//Saves and closes the WordDocument instance.
document.Save("Sample.docx", FormatType.Docx);
document.Close();

'Opens the template document.
Dim document As New WordDocument("Template.docx", FormatType.Docx)
'Set "InsertAsNew" as true to insert a new row for every group when group start and end present in the same table cell.
document.MailMerge.InsertAsNewRow = True
'Performs the mail merge.
document.MailMerge.ExecuteGroup(DataTable)
'Saves and closes the WordDocument instance.
document.Save("Sample.docx", FormatType.Docx)
document.Close()

MappedFields

Gets the collection of mapped fields.

Declaration

public Dictionary<string, string> MappedFields { get; }

Property Value

Type	Description
System.Collections.Generic.Dictionary<System.String, System.String>	The mapped fields represent mapping between fields names in the data source and mail merge fields in the document. The keys of the collection are merge field names and the values are field names in the data source.

RemoveEmptyGroup

Gets or sets a value indicating whether to remove groups which contain empty merge fields.

Declaration

public bool RemoveEmptyGroup { get; set; }

Property Value

Type	Description
System.Boolean	Set to True to remove empty groups; otherwise, false.

RemoveEmptyParagraphs

Gets or sets a value indicating whether to remove paragraphs which contain empty merge fields.

Declaration

public bool RemoveEmptyParagraphs { get; set; }

Property Value

Type	Description
System.Boolean	Set to True to remove empty paragraphs; otherwise, false.

Settings

Gets the MailMerge settings

Declaration

public MailMergeSettings Settings { get; }

Property Value

Type	Description
MailMergeSettings

Examples

The following code example demonstrates change the datasource path in the mail merge setting in the document.

    //Load an existing Word document into WordDocument instance.
    WordDocument document = new WordDocument("Sample.docx", FormatType.Docx);
    //Change the datasource property of the mail merge settings in the word document.
    document.MailMerge.Settings.DataSource = "NewDataSource.txt";
    //Saves the specified document
    document.Save("Sample.docx", FormatType.Docx);
    //Close the WordDocument instance
    document.Close();

    'Load an existing Word document into WordDocument instance
    Dim document As New WordDocument("Sample.docx", FormatType.Docx)
    'Change the datasource property of the mail merge settings in the word document
    document.MailMerge.Settings.DataSource = "NewDataSource.txt"
    'Saves the specified document
    document.Save("Sample.docx", FormatType.Docx)
    'Close the WordDocument instance
    document.Close()

StartAtNewPage

Gets or sets a value that indicates whether to start a new page for each group of records. The default value is false.

Declaration

public bool StartAtNewPage { get; set; }

Property Value

Type	Description
System.Boolean	Set True to start a new page for each group of records during mail merge execution; otherwise, false.

Remarks

This property is valid for group mail merge and also that the corresponding group start and group end should be present in the text body of the Word document.

This property is not valid when the group start, and group end are present in the table, headers and footers.

Examples

 
//Load the template Word document. 
WordDocument document = new WordDocument("Template.docx"); 
//Data source. 
DataSet ds = new DataSet(); 
ds.Tables.Add(); 
//Define the columns 
ds.Tables[0].TableName = "Employee"; 
ds.Tables[0].Columns.Add("NAME"); 
ds.Tables[0].Columns.Add("DESC"); 
//Set the values. 
DataRow row; 
row = ds.Tables["Employee"].NewRow(); 
row["NAME"] = "AAA"; 
row["DESC"] = null; 
ds.Tables["Employee"].Rows.Add(row); 
row = ds.Tables["Employee"].NewRow(); 
row["NAME"] = "BBB"; 
row["DESC"] = ""; 
ds.Tables["Employee"].Rows.Add(row); 
row = ds.Tables["Employee"].NewRow(); 
row["NAME"] = "CCC"; 
row["DESC"] = "ccc"; 
ds.Tables["Employee"].Rows.Add(row); 
//Enable a flag to start a new page for each group of records. 
document.MailMerge.StartAtNewPage= true; 
//Execute mail merge. 
document.MailMerge.ExecuteGroup(ds.Tables["Employee"]); 
//Save the Word document. 
document.Save("Result.docx", FormatType.Docx); 
//Close the Word document. 
document.Close(); 

 
'Load the template Word document. 
Dim document As WordDocument = New WordDocument("Template.docx") 
'Data source. 
Dim ds As DataSet = New DataSet 
ds.Tables.Add 
'Define the columns. 
ds.Tables(0).TableName = "Employee" 
ds.Tables(0).Columns.Add("NAME") 
ds.Tables(0).Columns.Add("DESC") 
'Set values. 
Dim row As DataRow 
row = ds.Tables("Employee").NewRow 
row("NAME") = "AAA" 
row("DESC") = Nothing 
ds.Tables("Employee").Rows.Add(row) 
row = ds.Tables("Employee").NewRow 
row("NAME") = "BBB" 
row("DESC") = "" 
ds.Tables("Employee").Rows.Add(row) 
row = ds.Tables("Employee").NewRow 
row("NAME") = "CCC" 
row("DESC") = "ccc" 
ds.Tables("Employee").Rows.Add(row) 
'Enable a flag to start a new page for each group of records. 
document.MailMerge.StartAtNewPage= true 
'Execute mail merge. 
document.MailMerge.ExecuteGroup(ds.Tables("Employee")) 
'Save the Word document. 
document.Save("Result.docx", FormatType.Docx) 
'Close the Word document. 
document.Close 

Methods

add_BeforeClearField(BeforeClearFieldEventHandler)

Declaration

public void add_BeforeClearField(BeforeClearFieldEventHandler value)

Parameters

Type	Name	Description
BeforeClearFieldEventHandler	value

add_BeforeClearGroupField(BeforeClearGroupFieldEventHandler)

Declaration

public void add_BeforeClearGroupField(BeforeClearGroupFieldEventHandler value)

Parameters

Type	Name	Description
BeforeClearGroupFieldEventHandler	value

add_MergeField(MergeFieldEventHandler)

Declaration

public void add_MergeField(MergeFieldEventHandler value)

Parameters

Type	Name	Description
MergeFieldEventHandler	value

add_MergeImageField(MergeImageFieldEventHandler)

Declaration

public void add_MergeImageField(MergeImageFieldEventHandler value)

Parameters

Type	Name	Description
MergeImageFieldEventHandler	value

Execute(IEnumerable)

Performs the mail merge operation using a IEnumerable as data source.

Declaration

public void Execute(IEnumerable dataSource)

Parameters

Type	Name	Description
System.Collections.IEnumerable	dataSource	IEnumerable data source that contains the mail merge field names with corresponding values.

Execute(DataRow)

Performs the mail merge operation using a DataRow as data source.

Declaration

public void Execute(DataRow row)

Parameters

Type	Name	Description
System.Data.DataRow	row	The DataRow contains the data for performing mail merge operation.

Remarks

This method is not supported in Silverlight, WinRT, Windows Phone, Universal, Universal Windows Platform, MVC6 and Xamarin platforms.

Execute(DataTable)

Performs the mail merge operation using a DataTable as data source.

Declaration

public void Execute(DataTable table)

Parameters

Type	Name	Description
System.Data.DataTable	table	The DataTable contains the data for performing mail merge operation.

Remarks

This method is not supported in Silverlight, WinRT, Windows Phone, Universal, Universal Windows Platform, MVC6 and Xamarin platforms.

Execute(DataView)

Performs the mail merge operation using a DataView as data source.

Declaration

public void Execute(DataView dataView)

Parameters

Type	Name	Description
System.Data.DataView	dataView	The DataView contains the data for performing mail merge operation.

Remarks

This method is not supported in Silverlight, WinRT, Windows Phone, Universal, Universal Windows Platform, MVC6 and Xamarin platforms.

Execute(String[], String[])

Performs the mail merge operation using an array of field names with its values as data source.

Declaration

public void Execute(string[] fieldNames, string[] fieldValues)

Parameters

Type	Name	Description
System.String[]	fieldNames	The array of merge field names.
System.String[]	fieldValues	The array of merge field values.

ExecuteGroup(MailMergeDataTable)

Performs the mail merge operation for a specified region.

Declaration

public void ExecuteGroup(MailMergeDataTable dataSource)

Parameters

Type	Name	Description
MailMergeDataTable	dataSource	The MailMergeDataTable contains the data source for performing mail merge operation.

ExecuteGroup(DataTable)

Performs the mail merge operation for a specified region using DataTable as data source.

Declaration

public void ExecuteGroup(DataTable table)

Parameters

Type	Name	Description
System.Data.DataTable	table	The DataTable contains the data for performing mail merge operation.

Remarks

ExecuteGroup mail merge functionality performs the replacements of merge fields, in which field names match the table column names with the ///corresponding values of table cell. These replacements are performed for every row contained in the table of the specified region.

The region where the mail merge operations are to be performed must be marked by two MergeFields with the following names:

For Example, You have to insert three MergeFields in the document with the following field names:

This method is not supported in Silverlight, WinRT, Windows Phone, Universal, Universal Windows Platform, MVC6 and Xamarin platforms.

ExecuteGroup(DataView)

Performs the mail merge operation for a specified region using DataView as data source.

Declaration

public void ExecuteGroup(DataView dataView)

Parameters

Type	Name	Description
System.Data.DataView	dataView

Remarks

ExecuteGroup mail merge functionality performs the replacements of merge fields, in which field names match the table column names with the ///corresponding values of table cell. These replacements are performed for every row contained in the table of the specified region.

The region where the mail merge operations are to be performed must be marked by two MergeFields with the following names:

For Example, You have to insert three MergeFields in the document with the following field names:

This method is not supported in Silverlight, WinRT, Windows Phone, Universal, Universal Windows Platform, MVC6 and Xamarin platforms.

ExecuteNestedGroup(MailMergeDataSet, List<DictionaryEntry>)

Performs the nested mail merge operation for a specified region using the MailMergeDataSet as data source.

Declaration

public void ExecuteNestedGroup(MailMergeDataSet dataSource, List<DictionaryEntry> commands)

Parameters

Type	Name	Description
MailMergeDataSet	dataSource	The MailMergeDataSet contains the data source for performing mail merge operation.
System.Collections.Generic.List<System.Collections.DictionaryEntry>	commands	Commands list

ExecuteNestedGroup(MailMergeDataTable)

Performs the nested mail merge operation for a specified region using the MailMergeDataTable as data source.

Declaration

public void ExecuteNestedGroup(MailMergeDataTable dataTable)

Parameters

Type	Name	Description
MailMergeDataTable	dataTable	The MailMergeDataTable contains the data source for performing mail merge operation.

ExecuteNestedGroup(DataSet, ArrayList)

Performs the nested mail merge operation for a specified region using DataSet as data source.

Declaration

public void ExecuteNestedGroup(DataSet dataSet, ArrayList commands)

Parameters

Type	Name	Description
System.Data.DataSet	dataSet	The DataSet contains data for mail merge.
System.Collections.ArrayList	commands	The array of commands contains the queries to get the data from dataset.

Remarks

Nested mail merge for a region works when the group start and end is BeginGroup and EndGroup respectively.

Nested mail merge for a table works when the group start and end is TableStart and TableEnd respectively.

The commands list to retrieve the DataTable from the data source must be in the same order of Group which is preserved in the input WordDocument.

This method is not supported in Silverlight, WinRT, Windows Phone, Universal, Universal Windows Platform, MVC6 and Xamarin platforms.

GetMergeFieldNames()

Returns a collection of merge field names found in the document.

Declaration

public string[] GetMergeFieldNames()

Returns

Type	Description
System.String[]	The string array which contains the name of all the merge fields name in the document.

GetMergeFieldNames(String)

Gets a collections of merge field names in the specified group.

Declaration

public string[] GetMergeFieldNames(string groupName)

Parameters

Type	Name	Description
System.String	groupName	A String that represents the name of the group.

Returns

Type	Description
System.String[]	The string array which contains the name of all the merge fields name in the specified group.

GetMergeGroupNames()

Gets a collections of the merge field group names in the document.

Declaration

public string[] GetMergeGroupNames()

Returns

Type	Description
System.String[]	The string array which contains the name of all the merge fields group names in the document.

remove_BeforeClearField(BeforeClearFieldEventHandler)

Declaration

public void remove_BeforeClearField(BeforeClearFieldEventHandler value)

Parameters

Type	Name	Description
BeforeClearFieldEventHandler	value

remove_BeforeClearGroupField(BeforeClearGroupFieldEventHandler)

Declaration

public void remove_BeforeClearGroupField(BeforeClearGroupFieldEventHandler value)

Parameters

Type	Name	Description
BeforeClearGroupFieldEventHandler	value

remove_MergeField(MergeFieldEventHandler)

Declaration

public void remove_MergeField(MergeFieldEventHandler value)

Parameters

Type	Name	Description
MergeFieldEventHandler	value

remove_MergeImageField(MergeImageFieldEventHandler)

Declaration

public void remove_MergeImageField(MergeImageFieldEventHandler value)

Parameters

Type	Name	Description
MergeImageFieldEventHandler	value

SendMergeField(IWMergeField, Object, IRowsEnumerator)

Sends MergeField event.

Declaration

protected MergeFieldEventArgs SendMergeField(IWMergeField field, object value, IRowsEnumerator rowsEnum)

Parameters

Type	Name	Description
IWMergeField	field	The field.
System.Object	value	The value.
IRowsEnumerator	rowsEnum	The rows enum.

Returns

Type	Description
MergeFieldEventArgs

SendMergeImageField(IWMergeField, Object, IRowsEnumerator, MemoryStream)

Declaration

protected MergeImageFieldEventArgs SendMergeImageField(IWMergeField field, object bmp, IRowsEnumerator rowsEnum, MemoryStream imageByteStream)

Parameters

Type	Name	Description
IWMergeField	field
System.Object	bmp
IRowsEnumerator	rowsEnum
System.IO.MemoryStream	imageByteStream

Returns

Type	Description
MergeImageFieldEventArgs

Events

BeforeClearField

Occurs during mail merge when an unmerged field is encountered in the document.

Declaration

public event BeforeClearFieldEventHandler BeforeClearField

Event Type

Type	Description
BeforeClearFieldEventHandler

BeforeClearGroupField

Occurs during mail merge when an unmerged group is encountered in the document.

Declaration

public event BeforeClearGroupFieldEventHandler BeforeClearGroupField

Event Type

Type	Description
BeforeClearGroupFieldEventHandler

MergeField

Occurs during mail merge when a text merge field is encountered in the document.

Declaration

public event MergeFieldEventHandler MergeField

Event Type

Type	Description
MergeFieldEventHandler

MergeImageField

Occurs during mail merge when an image merge field is encountered in the document.

Declaration

public event MergeImageFieldEventHandler MergeImageField

Event Type

Type	Description
MergeImageFieldEventHandler