Class MailMerge
Represents the mail merge functionality in the Word document.
Inheritance
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 |
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 |
---|
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
---|
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 |
---|
MergeImageFieldEventArgs |
Events
BeforeClearField
Occurs during mail merge when an unmerged field is encountered in the document.
Declaration
public event BeforeClearFieldEventHandler BeforeClearField
Event Type
Type |
---|
BeforeClearFieldEventHandler |
BeforeClearGroupField
Occurs during mail merge when an unmerged group is encountered in the document.
Declaration
public event BeforeClearGroupFieldEventHandler BeforeClearGroupField
Event Type
Type |
---|
BeforeClearGroupFieldEventHandler |
MergeField
Occurs during mail merge when a text merge field is encountered in the document.
Declaration
public event MergeFieldEventHandler MergeField
Event Type
Type |
---|
MergeFieldEventHandler |
MergeImageField
Occurs during mail merge when an image merge field is encountered in the document.
Declaration
public event MergeImageFieldEventHandler MergeImageField
Event Type
Type |
---|
MergeImageFieldEventHandler |