MailMerge Class
Represents the mail merge functionality.
Inheritance Hierarchy
SystemObject
  Aspose.Words.MailMergingMailMerge

Namespace: Aspose.Words.MailMerging
Assembly: Aspose.Words (in Aspose.Words.dll) Version: 17.10
Syntax
public class MailMerge

The MailMerge type exposes the following members.

Properties
  NameDescription
Public propertyCode exampleCleanupOptions
Gets or sets a set of flags that specify what items should be removed during mail merge.
Public propertyCode exampleFieldMergingCallback
Occurs during mail merge when a mail merge field is encountered in the document.
Public propertyMailMergeCallback
Allows to handle particular events during mail merge.
Public propertyCode exampleMappedDataFields
Returns a collection that represents mapped data fields for the mail merge operation.
Public propertyMergeDuplicateRegions
Gets or sets a value indicating whether all of the document mail merge regions with the name of a data source should be merged while executing of a mail merge with regions against the data source or just the first one.
Public propertyMergeWholeDocument
Gets or sets a value indicating whether fields in whole document is updated while executing of a mail merge with regions.
Public propertyPreserveUnusedTags
Gets or sets a value indicating whether the unused "mustache" tags should be preserved.
Public propertyRegionEndTag
Gets or sets a mail merge region end tag.
Public propertyRegionStartTag
Gets or sets a mail merge region start tag.
Public propertyRemoveEmptyParagraphs Obsolete.
Specifies whether paragraphs that contained mail merge fields with no data should be removed from the document.
Public propertyRemoveEmptyRegions Obsolete.
Specifies whether empty mail merge regions should be removed from the document.
Public propertyRtlCleanupMode Obsolete.
Gets or sets a value indicating how to handle Right-To-Left attributes of mail merge result text runs.
Public propertyTrimWhitespaces
Gets or sets a value indicating whether trailing and leading whitespaces are trimmed from mail merge values.
Public propertyCode exampleUseNonMergeFields
When true, specifies that in addition to MERGEFIELD fields, mail merge is performed into some other types of fields and also into "{{fieldName}}" tags.
Public propertyUseWholeParagraphAsRegion
Gets or sets a value indicating whether whole paragraph with TableStart or TableEnd field or particular range between TableStart and TableEnd fields should be included into mail merge region.
Methods
  NameDescription
Public methodCode exampleDeleteFields
Removes mail merge related fields from the document.
Public methodEquals
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
Public methodCode exampleExecute(DataRow)
Performs mail merge from a DataRow into the document.
Public methodCode exampleExecute(DataTable)
Performs mail merge from a DataTable into the document.
Public methodCode exampleExecute(DataView)
Performs mail merge from a DataView into the document.
Public methodCode exampleExecute(IDataReader)
Performs mail merge from IDataReader into the document.
Public methodCode exampleExecute(IMailMergeDataSource)
Performs a mail merge from a custom data source.
Public methodCode exampleExecute(String, Object)
Performs a mail merge operation for a single record.
Public methodCode exampleExecuteADO
Performs mail merge from an ADO Recordset object into the document.
Public methodCode exampleExecuteWithRegions(DataSet)
Performs mail merge from a DataSet into a document with mail merge regions.
Public methodCode exampleExecuteWithRegions(DataTable)
Performs mail merge from a DataTable into the document with mail merge regions.
Public methodCode exampleExecuteWithRegions(DataView)
Performs mail merge from a DataView into the document with mail merge regions.
Public methodCode exampleExecuteWithRegions(IMailMergeDataSource)
Performs a mail merge from a custom data source with mail merge regions.
Public methodExecuteWithRegions(IMailMergeDataSourceRoot)
Performs a mail merge from a custom data source with mail merge regions.
Public methodCode exampleExecuteWithRegions(IDataReader, String)
Performs mail merge from IDataReader into the document with mail merge regions.
Public methodCode exampleExecuteWithRegionsADO
Performs mail merge from an ADO Recordset object into the document with mail merge regions.
Protected methodFinalize
Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.
(Inherited from Object.)
Public methodCode exampleGetFieldNames
Returns a collection of mail merge field names available in the document.
Public methodGetFieldNamesForRegion(String)
Returns a collection of mail merge field names available in the region.
Public methodGetFieldNamesForRegion(String, Int32)
Returns a collection of mail merge field names available in the region.
Public methodGetHashCode
Serves as a hash function for a particular type.
(Inherited from Object.)
Public methodGetRegionsByName
Returns a collection of mail merge regions with the specified name.
Public methodGetRegionsHierarchy
Returns a full hierarchy of regions (with fields) available in the document.
Public methodGetType
Gets the type of the current instance.
(Inherited from Object.)
Protected methodMemberwiseClone
Creates a shallow copy of the current Object.
(Inherited from Object.)
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Remarks

For mail merge operation to work, the document should contain Word MERGEFIELD and optionally NEXT fields. During mail merge operation, merge fields in the document are replaced with values from your data source.

There are two distinct ways to use mail merge: with mail merge regions and without.

The simplest mail merge is without regions and it is very similar to how mail merge works in Word. Use Execute methods to merge information from some data source such as DataTable, DataSet, DataView, IDataReader or an array of objects into your document. The MailMerge object processes all records of the data source and copies and appends content of the whole document for each record.

Note that when MailMerge object encounters a NEXT field, it selects next record in the data source and continues merging without copying any content.

Use ExecuteWithRegions methods to merge information into a document with mail merge regions defined. You can use DataSet, DataTable, DataView or IDataReader as data sources for this operation.

You need to use mail merge regions if you want to dynamically grow portions inside the document. Without mail merge regions whole document will be repeated for every record of the data source.

Examples
Executes mail merge from an ADO.NET DataTable.
[C#]

Document doc = new Document(MyDir + "MailMerge.ExecuteDataTable.doc");

// This example creates a table, but you would normally load table from a database. 
DataTable table = new DataTable("Test");
table.Columns.Add("CustomerName");
table.Columns.Add("Address");
table.Rows.Add(new object[] {"Thomas Hardy", "120 Hanover Sq., London"});
table.Rows.Add(new object[] {"Paolo Accorti", "Via Monte Bianco 34, Torino"});

// Field values from the table are inserted into the mail merge fields found in the document.
doc.MailMerge.Execute(table);

doc.Save(MyDir + "MailMerge.ExecuteDataTable Out.doc");
[Visual Basic]

Dim doc As New Document(MyDir & "MailMerge.ExecuteDataTable.doc")

' This example creates a table, but you would normally load table from a database. 
Dim table As New DataTable("Test")
table.Columns.Add("CustomerName")
table.Columns.Add("Address")
table.Rows.Add(New Object() {"Thomas Hardy", "120 Hanover Sq., London"})
table.Rows.Add(New Object() {"Paolo Accorti", "Via Monte Bianco 34, Torino"})

' Field values from the table are inserted into the mail merge fields found in the document.
doc.MailMerge.Execute(table)

doc.Save(MyDir & "MailMerge.ExecuteDataTable Out.doc")
See Also