MailMerge Class

Namespace:
GemBox.Document.MailMerging
Assembly:
GemBox.Document.dll

Represents a class that is used for mail merging - an operation by which DocumentModel may work in conjunction with data from an external data source, importing this data into a DocumentModel according to a set of codes contained in DocumentModel known as Fields.

public sealed class MailMerge
Public NotInheritable Class MailMerge
Inheritance:
System.Object
MailMerge
Remarks

MailMerge can be accessed through MailMerge property.

Mail merge can be executed with a variety of data source types on a whole document or a named part of the document. For more information, see mail merge.

For mail merge examples, see mail merge examples.

Properties

ClearOptions

Gets or sets the mail merge clear options.

public MailMergeClearOptions ClearOptions { get; set; }
Public Property ClearOptions As MailMergeClearOptions
Property Value
MailMergeClearOptions

The mail merge clear options.

Document

Gets the owner document.

public DocumentModel Document { get; }
Public ReadOnly Property Document As DocumentModel
Property Value
DocumentModel

The owner document.

FieldMappings

Gets the mappings from field names to data source column names.

public FieldMappingDictionary FieldMappings { get; }
Public ReadOnly Property FieldMappings As FieldMappingDictionary
Property Value
FieldMappingDictionary

The mappings from field names to data source column names.

Remarks

Keys and values cannot be null or System.String.Empty.

Key comparison is case-insensitive.

PictureBasePath

Gets or sets the base path for pictures used during picture merging.

public string PictureBasePath { get; set; }
Public Property PictureBasePath As String
Property Value
System.String

The base path for pictures used during picture merging.

See Also

PicturePrefix

Gets or sets a string that specifies the prefix of a merge field name. If the merge field name starts with this prefix, the merge field will be merged as a picture.

The default value is "Picture:".

public string PicturePrefix { get; set; }
Public Property PicturePrefix As String
Property Value
System.String

Prefix that specifies merge field, which should be merged as a picture.

See Also

RangeEndPrefix

Gets or sets the range end prefix that signals the mail merge engine that named range has ended.

public string RangeEndPrefix { get; set; }
Public Property RangeEndPrefix As String
Property Value
System.String

The range end prefix that signals the mail merge engine that named range has ended.

RangeStartPrefix

Gets or sets the range start prefix that signals the mail merge engine that following Fields are a part of a named range.

public string RangeStartPrefix { get; set; }
Public Property RangeStartPrefix As String
Property Value
System.String

The range start prefix that signals the mail merge engine that following Fields are a part of a named range.

Methods

Execute(Object)

Executes a mail merge operation with specified data source.

[ComVisible(true)]
public void Execute(object dataSource)
<ComVisible(True)>
Public Sub Execute(dataSource As Object)
Parameters
dataSource
System.Object

The mail merge data source.

Remarks

Range name is extracted from the dataSource as describe in mail merge article.

Execute(Object, String)

Executes a mail merge operation with specified range name and data source.

[ComVisible(false)]
public void Execute(object dataSource, string rangeName)
<ComVisible(False)>
Public Sub Execute(dataSource As Object, rangeName As String)
Parameters
dataSource
System.Object

The mail merge data source.

rangeName
System.String

The mail merge range name.

GetMergeFieldNames()

Gets the merge field names.

public IEnumerable<string> GetMergeFieldNames()
Public Function GetMergeFieldNames As IEnumerable(Of String)
Returns
System.Collections.Generic.IEnumerable<System.String>

A sequence of a merge field names.

RemoveMergeFields()

Removes all mail merge related fields (MergeField, MergeBarcode, MergeRec, MergeSeq, and Next fields).

public void RemoveMergeFields()
Public Sub RemoveMergeFields

RemoveMergeFields(Boolean)

Removes the Fields with FieldType value of MergeField or MergeBarcode from the owning DocumentModel.

public void RemoveMergeFields(bool allRelatedMergeFields)
Public Sub RemoveMergeFields(allRelatedMergeFields As Boolean)
Parameters
allRelatedMergeFields
System.Boolean

if set to true all other mail merge related fields are removed, such as MergeRec, MergeSeq, and Next fields.

Events

FieldMerging

Occurs when Field is merging with data source value and can be used to customize the merging operation.

public event EventHandler<FieldMergingEventArgs> FieldMerging
Public Event FieldMerging As EventHandler(Of FieldMergingEventArgs)
Event Type
System.EventHandler<FieldMergingEventArgs>

Examples