Frequently asked questions about mail merge in Word document

28 Mar 20258 minutes to read

The frequently asked questions about working with mail merge in Word documents using DocIO are listed below.

Is it possible to format merge fields with image formats before performing a mail merge?

No, it is not possible to format merge fields with image formats before performing a mail merge. Merge fields in Word documents support only text formatting, whereas images require graphical formatting. However, you can format images dynamically using the MergeImageField event in DocIO during the mail merge process.

The following code example shows how to use the MergeImageField event during Mail merge process.

//Opens the template document
FileStream fileStreamPath = new FileStream("Template.docx", FileMode.Open, FileAccess.Read, FileShare.ReadWrite);
WordDocument document = new WordDocument(fileStreamPath, FormatType.Docx);
//Uses the mail merge events handler for image fields
document.MailMerge.MergeImageField += new MergeImageFieldEventHandler(MergeField_ProductImage);
//Specifies the field names and field values
string[] fieldNames = new string[] { "Logo"};
string[] fieldValues = new string[] { "Logo.png"};
//Executes the mail merge with groups
document.MailMerge.Execute(fieldNames, fieldValues);
//Saves the Word document to MemoryStream
MemoryStream stream = new MemoryStream();
document.Save(stream, FormatType.Docx);
//Closes the Word document
document.Close();
//Opens the template document
WordDocument document = new WordDocument("Template.docx");
//Uses the mail merge events handler for image fields
document.MailMerge.MergeImageField += new MergeImageFieldEventHandler(MergeField_ProductImage);
//Specifies the field names and field values
string[] fieldNames = new string[] { "Logo"};
string[] fieldValues = new string[] { "Logo.png"};
//Executes the mail merge with groups
document.MailMerge.Execute(fieldNames, fieldValues);
//Saves and closes WordDocument instance
document.Save("Sample.docx", FormatType.Docx);
document.Close();
'Opens the template document
Dim document As New WordDocument("Template.docx")
'Uses the mail merge events handler for image fields
AddHandler document.MailMerge.MergeImageField, AddressOf MergeField_ProductImage
'Specifies the field names and field values
Dim fieldNames As String() = New String() {"Logo"}
Dim fieldValues As String() = New String() {"Logo.png"}
'Executes the mail merge with groups
document.MailMerge.Execute(fieldNames, fieldValues)
'Saves and closes WordDocument instance
document.Save("Sample.docx", FormatType.Docx)
document.Close()

The following code example shows how to bind the image from file system during Mail merge process by using MergeImageFieldEventHandler.

private void MergeField_ProductImage(object sender, MergeImageFieldEventArgs args)
{
    //Binds image from file system during mail merge
    if (args.FieldName == "Logo")
    {
        string ProductFileName = args.FieldValue.ToString();
        //Gets the image from file system
        FileStream imageStream = new FileStream(ProductFileName, FileMode.Open, FileAccess.Read);
        args.ImageStream = imageStream;
        //Gets the picture, to be merged for image merge field
        WPicture picture = args.Picture;
        //Resizes the picture
        picture.Height = 50;
        picture.Width = 150;
    }
}
private void MergeField_ProductImage(object sender, MergeImageFieldEventArgs args)
{
    //Binds image from file system during mail merge
    if (args.FieldName == "Logo")
    {
        string ProductFileName = args.FieldValue.ToString();
        //Gets the image from file system
        args.Image = Image.FromFile(ProductFileName);
        //Gets the picture, to be merged for image merge field
        WPicture picture = args.Picture;
        //Resizes the picture
        picture.Height = 50;
        picture.Width = 150;
    }
}
Private Sub MergeField_ProductImage(ByVal sender As Object, ByVal args As MergeImageFieldEventArgs)
    'Binds image from file system during mail merge
    If args.FieldName = "Logo" Then
        Dim ProductFileName As String = args.FieldValue.ToString()
        'Gets the image from file system
        args.Image = Image.FromFile(ProductFileName)
        'Gets the picture, to be merged for image merge field
        Dim picture As WPicture = args.Picture
        'Resizes the picture
        picture.Height = 50
        picture.Width = 150
    End If
End Sub

You can download a complete working sample from GitHub.

Why does DocIO use merge field values from the parent group when the nested group data does not contain a value?

If the data source for nested group mail merge has the same field name in both the nested and parent groups, this behavior occurs.

Explanation:
In DocIO, if a merge field in a nested group has a null value, the mail merge process automatically checks the parent group for a field with the same name. If the field exists in the parent group, its value is assigned to the field in the nested group. This is the default behavior in DocIO.

Example:
Consider the following data source structure:

Parent group:
FieldName: FirstName = Andrew
FieldName: LastName = Fuller

Nested group:
FieldName: FirstName = null
If the FirstName field in the nested group has a null value, DocIO will automatically assign the FirstName value from the parent group (Andrew) to the nested group field.

Suggestions to modify this behavior:
To prevent the nested group’s field from inheriting the value of the parent group, you can use one of the following solutions:

Solution 1: Set empty strings for empty fields
Assign an empty string to the merge field in the nested group instead of null. This ensures that the field remains empty and does not inherit values from the parent group.

Solution 2: Use unique field names
Rename fields in the parent and nested groups to have distinct names. This avoids any conflict and ensures the parent group’s values are not applied to the nested group.

How to identify merge fields that do not exist in the data source?

To find merge fields that have null values or missing from the data source, set ClearFields API as false before performing mail merge. This ensures unmerged fields remain visible in the output document. Refer here for code example.

For identifying only null value fields or missing from data source, use the BeforeClearField event during the mail merge process to replace them with an error message. Refer here for code example.

Why is each record merging on a new page during mail merge?

In DocIO, simple mail merge clones the entire document for each record, causing each entry to start on a new page. For example, with 10 records, the document repeats 10 times.

To merge all records into a single table or specific region on the same page, use group mail merge instead.

Refer to the Group Mail Merge documentation for details.

Why does TryAdd() not work with ExpandoObject in .NET Framework 4.8?

Microsoft did not implement TryAdd() for ExpandoObject in .NET Framework 4.8, which results in an exception when used. To check which versions support TryAdd(), refer here.

Since TryAdd() is not available, you can manually check if a key exists before adding a new entry to the dictionary using the following workaround:

if (!(dynamicObject as IDictionary<string, object>).ContainsKey(node.LocalName))
    (dynamicObject as IDictionary<string, object>).Add(node.LocalName, node.InnerText);