MailMerge Class

Represents the mail merge functionality.

ExpandedInheritance Hierarchy

SystemObject
  Aspose.Words.MailMergingMailMerge

Namespace:  Aspose.Words.MailMerging
Assembly:  Aspose.Words (in Aspose.Words.dll) Version: 21.9.0

ExpandedSyntax

public class MailMerge

The MailMerge type exposes the following members.

ExpandedProperties

  NameDescription
Public propertyCode exampleCleanupOptions
Gets or sets a set of flags that specify what items should be removed during mail merge.
Public propertyCode exampleCleanupParagraphsWithPunctuationMarks
Gets or sets a value indicating whether paragraphs with punctuation marks are considered as empty and should be removed if the RemoveEmptyParagraphs option is specified.
Public propertyCode exampleFieldMergingCallback
Occurs during mail merge when a mail merge field is encountered in the document.
Public propertyCode exampleMailMergeCallback
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 propertyCode exampleMergeDuplicateRegions
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 propertyCode exampleMergeWholeDocument
Gets or sets a value indicating whether fields in whole document are updated while executing of a mail merge with regions.
Public propertyCode examplePreserveUnusedTags
Gets or sets a value indicating whether the unused "mustache" tags should be preserved.
Public propertyCode exampleRegionEndTag
Gets or sets a mail merge region end tag.
Public propertyCode exampleRegionStartTag
Gets or sets a mail merge region start tag.
Public propertyCode exampleRestartListsAtEachSection
Gets or sets a value indicating whether lists are restarted at each section after executing of a mail merge.
Public propertyRetainFirstSectionStart
Gets or sets a value indicating whether the SectionStart of the first document section and its copies for subsequent data source rows are retained during mail merge or updated according to MS Word behaviour.
Public propertyCode exampleTrimWhitespaces
Gets or sets a value indicating whether trailing and leading whitespaces are trimmed from mail merge values.
Public propertyCode exampleUnconditionalMergeFieldsAndRegions
Gets or sets a value indicating whether merge fields and merge regions are merged regardless of the parent IF field's condition.
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 propertyCode exampleUseWholeParagraphAsRegion
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.

ExpandedMethods

  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 methodExecute(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 methodCode exampleExecuteWithRegions(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.
Public methodCode exampleGetFieldNames
Returns a collection of mail merge field names available in the document.
Public methodCode exampleGetFieldNamesForRegion(String)
Returns a collection of mail merge field names available in the region.
Public methodCode exampleGetFieldNamesForRegion(String, Int32)
Returns a collection of mail merge field names available in the region.
Public methodGetHashCode
Serves as the default hash function.
(Inherited from Object.)
Public methodCode exampleGetRegionsByName
Returns a collection of mail merge regions with the specified name.
Public methodCode exampleGetRegionsHierarchy
Returns a full hierarchy of regions (with fields) available in the document.
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)

ExpandedRemarks

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.

ExpandedExamples

Shows how to execute a mail merge with data from a DataTable.
public void ExecuteDataTable()
{
    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" });

    // Below are two ways of using a DataTable as the data source for a mail merge.
    // 1 -  Use the entire table for the mail merge to create one output mail merge document for every row in the table:
    Document doc = CreateSourceDocExecuteDataTable();

    doc.MailMerge.Execute(table);

    doc.Save(ArtifactsDir + "MailMerge.ExecuteDataTable.WholeTable.docx");

    // 2 -  Use one row of the table to create one output mail merge document:
    doc = CreateSourceDocExecuteDataTable();

    doc.MailMerge.Execute(table.Rows[1]);

    doc.Save(ArtifactsDir + "MailMerge.ExecuteDataTable.OneRow.docx");
}

/// <summary>
/// Creates a mail merge source document.
/// </summary>
private static Document CreateSourceDocExecuteDataTable()
{
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    builder.InsertField(" MERGEFIELD CustomerName ");
    builder.InsertParagraph();
    builder.InsertField(" MERGEFIELD Address ");

    return doc;
}

ExpandedSee Also