Mail Merge Clear Options

The GemBox.Document mail merge process allows you to remove or clear various parts of the document using MailMergeClearOptions, if no data has been merged or imported to that part of the document.

A merge field is considered to be merged if its data source value is defined, not null and empty.

The following example shows how you can perform mail merge operations with specified clear options for removing fields, paragraphs, rows, tables, or the whole merge range if no data has been merged into them.

Word document generated with mail merge process that has clear options defined
Screenshot of executed mail merge with clear options
using GemBox.Document;
using GemBox.Document.MailMerging;

class Program
{
    static void Main()
    {
        // If using the Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY");

        var document = DocumentModel.Load("%#MergeClearOptions.docx%");

        // Data source with "Populated" value, but no "Empty" value.
        var data = new { Populated = "sample value" };

        // Execute mail merge on "Example1" merge range.
        // Also, remove fields and paragraphs that didn't merge in this range.
        document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveUnusedFields | MailMergeClearOptions.RemoveEmptyParagraphs;
        document.MailMerge.Execute(data, "Example1");

        // Execute mail merge on "Example2" merge range.
        // Also, remove rows that didn't merge in this range.
        document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveEmptyTableRows;
        document.MailMerge.Execute(data, "Example2");

        // Execute mail merge on "Example3" merge range.
        // Also, remove fields and tables that didn't merge in this range.
        document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveUnusedFields | MailMergeClearOptions.RemoveEmptyTables;
        document.MailMerge.Execute(data, "Example3");

        // Execute mail merge on "Example4" merge range.
        // Also, remove the range if all fields didn't merge in this range.
        document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveEmptyRanges;
        document.MailMerge.Execute(data, "Example4");

        document.Save("Merged Clear Options Output.%OutputFileType%");
    }
}
Imports GemBox.Document
Imports GemBox.Document.MailMerging

Module Program

    Sub Main()

        ' If using the Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY")

        Dim document = DocumentModel.Load("%#MergeClearOptions.docx%")

        ' Data source with "Populated" value, but no "Empty" value.
        Dim data As New With {.Populated = "sample value"}

        ' Execute mail merge on "Example1" merge range.
        ' Also, remove fields and paragraphs that didn't merge in this range.
        document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveUnusedFields Or MailMergeClearOptions.RemoveEmptyParagraphs
        document.MailMerge.Execute(data, "Example1")

        ' Execute mail merge on "Example2" merge range.
        ' Also, remove rows that didn't merge in this range.
        document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveEmptyTableRows
        document.MailMerge.Execute(data, "Example2")

        ' Execute mail merge on "Example3" merge range.
        ' Also, remove fields and tables that didn't merge in this range.
        document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveUnusedFields Or MailMergeClearOptions.RemoveEmptyTables
        document.MailMerge.Execute(data, "Example3")

        ' Execute mail merge on "Example4" merge range.
        ' Also, remove the range if all fields didn't merge in this range.
        document.MailMerge.ClearOptions = MailMergeClearOptions.RemoveEmptyRanges
        document.MailMerge.Execute(data, "Example4")

        document.Save("Merged Clear Options Output.%OutputFileType%")

    End Sub
End Module

Note, when starting the mail merge process, GemBox.Document will first locate a merge range in which it will operate. If the range name is resolved to a null or empty value, then the whole document is taken as the merge range.

In that case, if no data was merged, MailMergeClearOptions.RemoveEmptyRanges will remove the whole document content. To avoid this, you can specify the range name using the MailMerge.Execute overload method, as shown in the example above.

For more information, see the Mail merge process help page.

See also


Next steps

GemBox.Document is a .NET component that enables you to read, write, edit, convert, and print document files from your .NET applications using one simple API. How about testing it today?

Download Buy