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(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.

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.

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