Mail Merge

• Jun 28, 2019
• 4 minutes to read

RichEditDocumentServer allows you to perform mail merge in three steps:

1. Provide a Data Source
2. Load a Document Template
3. Merge and Save the Document

Provide a Data Source

RichEditDocumentServer supports the following data source types:

• System.Collections.IList;
• System.Collections.ArrayList;
• System.Data.DataTable.

Use the RichEditMailMergeOptions.DataSource property to specify the data source used in a mail merge.

C#

server.Options.MailMerge.DataSource = new SampleData();

VB.NET

server.Options.MailMerge.DataSource = New SampleData()

If the data source contains multiple data tables, use the MailMergeOptions.DataMember property to define a specific data member.

Load a Document Template

The template is a document containing fields. These fields refer to the data source’s data column names.

Call the RichEditDocumentServer.LoadDocument or RichEditDocumentServer.LoadDocumentTemplate method to load a document template.

The RichEditDocumentServer allows you to add fields to the template. Call the FieldCollection.Create method to insert one of the following fields to the desired document position:

• MERGEFIELD - for plain text;
• DOCVARIABLE - for formatted content;

• INCLUDEPICTURE - for images.

  Use the INCLUDEPICTURE field as follows: {INCLUDEPICTURE “{MERGEFIELD PictureLocation}” \d} (the PictureLocation is the path to the desired picture).

  If you need to merge different images, make sure that the images have the same name as the field’s contents in the database (for example, as the “FirstName” field), and insert the INCLUDEPICTURE as follows: { INCLUDEPICTURE “PicturesLocation\{ MERGEFIELD FieldName }.jpg” *MERGEFORMAT \d }.

  Tip

  Use the IUriStreamProvider to insert pictures from a database. Refer to the how-to-use-images-when-implementing-the-mail-merge-functionality code example for details.

Merge and Save the Document

Use the following API to set additional merge options (the number of records, merged ranges delimitation, etc.) and merge the document:

API	Description
RichEditControlOptionsBase.MailMerge	Provides access to the default mail merge options.. Use the server.Options.MailMerge notation to access these settings.
Document.CreateMailMergeOptions	Initializes an MailMergeOptions instance, which contains additional mail merge options.
MailMergeOptions.FirstRecordIndex	Gets or sets the record index from which the merge starts.
MailMergeOptions.LastRecordIndex	Gets or sets the record index at which the merge finishes.
MailMergeOptions.MergeMode	Gets or sets how the merged ranges are delimited in the resulting document.
Document.MailMerge	Merges the current document using the specified options, and sends the result to the specified file or stream.

The code sample below shows how to use the RichEditDocumentServer to perform the mail merge:

C#

using (RichEditDocumentServer server = new RichEditDocumentServer())
{
    server.LoadDocument("Documents//invitation.docx", DocumentFormat.Rtf);
    server.Options.MailMerge.DataSource = new SampleData();

    MailMergeOptions myMergeOptions = server.Document.CreateMailMergeOptions();
    myMergeOptions.FirstRecordIndex = 1;
    myMergeOptions.MergeMode = MergeMode.NewParagraph;
    server.MailMerge(myMergeOptions, "result.docx", DocumentFormat.OpenXml);
}
System.Diagnostics.Process.Start("result.docx");

VB.NET

Using server As New RichEditDocumentServer()
    server.LoadDocument("Documents//invitation.docx", DocumentFormat.Rtf)
    server.Options.MailMerge.DataSource = New SampleData()

    Dim myMergeOptions As MailMergeOptions = server.Document.CreateMailMergeOptions()
    myMergeOptions.FirstRecordIndex = 1
    myMergeOptions.MergeMode = MergeMode.NewParagraph
    server.MailMerge(myMergeOptions, "result.docx", DocumentFormat.OpenXml)
End Using
System.Diagnostics.Process.Start("result.docx")

Mail Merge Events

RichEditDocumentServer provides the following events to control specific mail merge steps:

Event	Description
RichEditDocumentServer.MailMergeStarted	Fires before mail merge starts.
RichEditDocumentServer.MailMergeFinished	Fires when mail merge is completed.
RichEditDocumentServer.MailMergeRecordStarted	Fires before each data record is merged with the document in the mail merge process.
RichEditDocumentServer.MailMergeRecordFinished	Fires after each data record is merged with the document in the mail merge process.

The code sample below shows how to handle the RichEditDocumentServer.MailMergeRecordStarted and RichEditDocumentServer.MailMergeRecordFinished events to insert additional content to the mail merge result:

Note

A complete code sample project is available at How to use document variable (DOCVARIABLE) fields.

C#

private static void srv_MailMergeRecordStarted(object sender, MailMergeRecordStartedEventArgs e)
{
    DocumentRange _range = e.RecordDocument.InsertText(e.RecordDocument.Range.Start, String.Format("Created on {0:G}\n\n", DateTime.Now));
    CharacterProperties cp = e.RecordDocument.BeginUpdateCharacters(_range);
    cp.FontSize = 8;
    cp.ForeColor = Color.Red;
    cp.Hidden = true;
    e.RecordDocument.EndUpdateCharacters(cp);
}

private static void srv_MailMergeRecordFinished(object sender, MailMergeRecordFinishedEventArgs e)
{
    e.RecordDocument.AppendDocumentContent("Docs\\bungalow.docx", DocumentFormat.OpenXml);
}

VB.NET

Private Shared Sub srv_MailMergeRecordStarted(ByVal sender As Object, ByVal e As MailMergeRecordStartedEventArgs)
        Dim _range As DocumentRange = e.RecordDocument.InsertText(e.RecordDocument.Range.Start, String.Format("Created on {0:G}" & vbLf & vbLf, DateTime.Now))
        Dim cp As CharacterProperties = e.RecordDocument.BeginUpdateCharacters(_range)
        cp.FontSize = 8
        cp.ForeColor = Color.Red
        cp.Hidden = True
        e.RecordDocument.EndUpdateCharacters(cp)
End Sub

Private Shared Sub srv_MailMergeRecordFinished(ByVal sender As Object, ByVal e As MailMergeRecordFinishedEventArgs)
    e.RecordDocument.AppendDocumentContent("Docs\bungalow.docx", DocumentFormat.OpenXml)
End Sub

Tip

You can transform a mail merge template to a self-contained document in the same RichEditDocumentServer instance by using current data. Refer to the How to replace document fields with their values example for details.