Aspose::Words::MailMerging::MailMerge class

MailMerge class

Represents the mail merge functionality. To learn more, visit the Mail Merge and Reporting documentation article.

class MailMerge : public System::Object

Methods

MethodDescription
DeleteFields()Removes mail merge related fields from the document.
Execute(const System::SharedPtr<Aspose::Words::MailMerging::IMailMergeDataSource>&)Performs a mail merge from a custom data source.
Execute(const System::ArrayPtr<System::String>&, const System::ArrayPtr<System::SharedPtr<System::Object>>&)Performs a mail merge operation for a single record.
ExecuteWithRegions(const System::SharedPtr<Aspose::Words::MailMerging::IMailMergeDataSource>&)Performs a mail merge from a custom data source with mail merge regions.
ExecuteWithRegions(const System::SharedPtr<Aspose::Words::MailMerging::IMailMergeDataSourceRoot>&)Performs a mail merge from a custom data source with mail merge regions.
get_CleanupOptions() constGets a set of flags that specify what items should be removed during mail merge.
get_CleanupParagraphsWithPunctuationMarks() constGets or sets a value indicating whether paragraphs with punctuation marks are considered as empty and should be removed if the RemoveEmptyParagraphs option is specified.
get_FieldMergingCallback() constOccurs during mail merge when a mail merge field is encountered in the document.
get_MailMergeCallback() constAllows to handle particular events during mail merge.
get_MappedDataFields()Returns a collection that represents mapped data fields for the mail merge operation.
get_MergeDuplicateRegions() constGets 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.
get_MergeWholeDocument() constGets a value indicating whether fields in whole document are updated while executing of a mail merge with regions.
get_PreserveUnusedTags() constGets a value indicating whether the unused “mustache” tags should be preserved.
get_RegionEndTag() constGets or sets a mail merge region end tag.
get_RegionStartTag() constGets or sets a mail merge region start tag.
get_RestartListsAtEachSection() constGets or sets a value indicating whether lists are restarted at each section after executing of a mail merge.
get_RetainFirstSectionStart() constGets 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.
get_TrimWhitespaces() constGets or sets a value indicating whether trailing and leading whitespaces are trimmed from mail merge values.
get_UnconditionalMergeFieldsAndRegions() constGets a value indicating whether merge fields and merge regions are merged regardless of the parent IF field’s condition.
get_UseNonMergeFields() constWhen true, specifies that in addition to MERGEFIELD fields, mail merge is performed into some other types of fields and also into “{{fieldName}}” tags.
get_UseWholeParagraphAsRegion() constGets 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.
GetFieldNames()Returns a collection of mail merge field names available in the document.
GetFieldNamesForRegion(const System::String&)Returns a collection of mail merge field names available in the region.
GetFieldNamesForRegion(const System::String&, int32_t)Returns a collection of mail merge field names available in the region.
GetRegionsByName(const System::String&)Returns a collection of mail merge regions with the specified name.
GetRegionsHierarchy()Returns a full hierarchy of regions (with fields) available in the document.
GetType() const override
Is(const System::TypeInfo&) const override
set_CleanupOptions(Aspose::Words::MailMerging::MailMergeCleanupOptions)Sets a set of flags that specify what items should be removed during mail merge.
set_CleanupParagraphsWithPunctuationMarks(bool)Setter for Aspose::Words::MailMerging::MailMerge::get_CleanupParagraphsWithPunctuationMarks.
set_FieldMergingCallback(const System::SharedPtr<Aspose::Words::MailMerging::IFieldMergingCallback>&)Setter for Aspose::Words::MailMerging::MailMerge::get_FieldMergingCallback.
set_MailMergeCallback(const System::SharedPtr<Aspose::Words::MailMerging::IMailMergeCallback>&)Allows to handle particular events during mail merge.
set_MergeDuplicateRegions(bool)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.
set_MergeWholeDocument(bool)Sets a value indicating whether fields in whole document are updated while executing of a mail merge with regions.
set_PreserveUnusedTags(bool)Sets a value indicating whether the unused “mustache” tags should be preserved.
set_RegionEndTag(const System::String&)Setter for Aspose::Words::MailMerging::MailMerge::get_RegionEndTag.
set_RegionStartTag(const System::String&)Setter for Aspose::Words::MailMerging::MailMerge::get_RegionStartTag.
set_RestartListsAtEachSection(bool)Setter for Aspose::Words::MailMerging::MailMerge::get_RestartListsAtEachSection.
set_RetainFirstSectionStart(bool)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.
set_TrimWhitespaces(bool)Setter for Aspose::Words::MailMerging::MailMerge::get_TrimWhitespaces.
set_UnconditionalMergeFieldsAndRegions(bool)Sets a value indicating whether merge fields and merge regions are merged regardless of the parent IF field’s condition.
set_UseNonMergeFields(bool)Setter for Aspose::Words::MailMerging::MailMerge::get_UseNonMergeFields.
set_UseWholeParagraphAsRegion(bool)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.
static Type()

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 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() and other overloads to merge information into a document with mail merge regions defined. You can use 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.

See Also