Troubleshooting tips for Mail merge in .NET Word Library

15 Aug 20263 minutes to read

Why is mail merge not working correctly in DocIO?

Mail Merge issues can arise due to incorrect merge fields, mismatched data sources, or missing fields in the template. Ensure the following:

  • Merge fields («FieldName») are used instead of plain text.
  • Data Source Check: Ensure the required fields exist in the data source. Verify the data source column/property names against the merge field names in the Word template.

  • Match Field Names: Sometimes, the field names in the Word document are different from the property names in your data source class. For example, if your document has “FirstName” and “LastName”, but your Employee class uses different names, Mail Merge will not work correctly.

    How to fix this:

    • The property names in your data source class should be exactly the same as the merge field names in your Word document.
    • Field names are case-sensitive, so make sure they match exactly.

How to verify the merge fields: Press Alt + F9 in Microsoft Word to reveal the actual field codes and confirm the merge field names are correct.

Example:

Word Document Fields:
Template document
.NET Class Structure to Match Merge Fields:

public class Employee
{
   public string FirstName { get; set; }  // Matches merge field name
   public string LastName { get; set; }   // Matches merge field name
}
public class Employee
{
   public string FirstName { get; set; }  // Matches merge field name
   public string LastName { get; set; }   // Matches merge field name
}
Public Class Employee
    'Matches merge field name
    Public Property FirstName As String
    'Matches merge field name
    Public Property LastName As String
End Class
  • Show Field Codes: Press Alt + F9 in Microsoft Word to reveal field codes and verify they are correct.

Why does mail merge not recognize manually typed text in Word document?

Mail Merge only works with merge fields, not manually typed placeholders. If text is entered instead of a merge field, Word treats it as plain text.

Solution using Microsoft Word:

  1. Navigate to Insert → Field or press Ctrl+F9.
  2. Right-click the inserted field and select Edit Field.
  3. Choose MergeField from the list and specify the field name.

Solution using DocIO:

Refer to Syncfusion® Documentation for detailed implementation.

Why is nested group Mail Merge not functioning correctly?

Nested Mail Merge requires proper execution using the correct method and structure.

  • Use the appropriate overload of the ExecuteNestedGroup method to handle nested groups effectively. Supported overloads include:
    • ExecuteNestedGroup(MailMergeDataTable) — for implicit relational data, where the child groups are nested within the parent table’s data.
    • ExecuteNestedGroup(MailMergeDataSet, List<DictionaryEntry>) — for explicit relational data, where the relations between parent and child groups are defined using command entries.
  • Ensure the data structure follows the correct hierarchy for nested groups to maintain implicit relational data. Each child group must be represented as a relation between the parent table and the child table in the data source.