Mail Merge

• Jan 23, 2026
• 4 minutes to read

This topic describes how to enable and use the Mail Merge feature in ASP.NET Core Blazor or Windows Forms applications.

To enable Mail Merge, set the RichTextMailMergeDataType property to the type you use for storing document templates.

In .NET Applications

Specify the type as one of office module options.

File: YourSolutionName.Blazor.Server/Startup.cs or YourSolutionName.Win/Startup.cs.

ASP.NET Core Blazor

using DevExpress.ExpressApp.ApplicationBuilder;
using DevExpress.ExpressApp.Blazor.ApplicationBuilder;
using DevExpress.Persistent.BaseImpl.EF;
// ...
public class Startup {
   // ...
    public void ConfigureServices(IServiceCollection services) {
        // ...
        services.AddXaf(Configuration, builder => {
            builder.UseApplication<YourSolutionNameBlazorApplication>();
            builder.Modules
                // ...
                .AddOffice(options => {
                    options.RichTextMailMergeDataType = typeof(RichTextMailMergeData);
                })
            // ...
        });
        // ...
    }
}

Windows Forms

using DevExpress.ExpressApp.ApplicationBuilder;
using DevExpress.ExpressApp.Win.ApplicationBuilder;
using DevExpress.Persistent.BaseImpl.EF;
// ...
public class ApplicationBuilder : IDesignTimeApplicationFactory {
    public static WinApplication BuildApplication(string connectionString) {
        var builder = WinApplication.CreateBuilder();
        builder.UseApplication<YourSolutionNameWindowsFormsApplication>();
        builder.Modules
            // ...
            .AddOffice(options => {
                options.RichTextMailMergeDataType = typeof(RichTextMailMergeData);
            })
        // ...
    }
    // ...
}

In .NET Applications Without Application Builder

Specify the type when you add the office module:

File: MyApplication.Blazor.Server/MyApplication.Designer.cs or MyApplication.Win/MyApplication.Designer.cs.

using Devexpress.Persistent.BaseImpl.EF
// ...
partial class MyApplication {
    private void InitializeComponent() {
        // ...
        this.officeModule = new DevExpress.ExpressApp.Office.OfficeModule();
        this.officeModule.RichTextMailMergeDataType = typeof(RichTextMailMergeData);
        // ...
    }
    // ...
}

Data Types

You can use one of the following built-in types, depending on your ORM:

ORM	Business Object Type
XPO	DevExpress.Persistent.BaseImpl.RichTextMailMergeData
Entity Framework Core	DevExpress.Persistent.BaseImpl.EF.RichTextMailMergeData

Important

If you use Entity Framework (Core), register the DevExpress.Persistent.BaseImpl.EF.RichTextMailMergeData type in the DbContext (see Ways to Add a Business Class - Import Classes from a Business Class Library or Module).

Mail Merge Template

Run the application and invoke the Reports | Mail Merge Template navigation item to create new and access existing document templates.

ASP.NET Core Blazor

Windows Forms

Use the Data Type field to specify the business class to be used as the document’s data source.

In the drop-down Insert Merge Field window (Windows Forms) or pop-up Insert Merge Field window (ASP.NET Core Blazor), select fields from the data type to add to the document template.

Tip

If the Data Type field does not list the class, use one of the fixes below:

• Apply the VisibleInReportsAttribute (with the parameter set to true) or DefaultClassOptionsAttribute to the class.
• Set the IModelClassReportsVisibility.IsVisibleInReports property of the corresponding BOModel | <Class> node to true.

Subfields in Mail Merge Design Time and Preview

Subfields allow you to reference nested properties in mail merge templates (for example, ObjectProperty.SubProperty).

How to Add Subfields

Subfields are not available in the Insert Merge Field drop-down or pop-up window. To add a subfield:

1. Click Show All Field Codes in the template editor.
2. Type the field using the { MERGEFIELD ObjectProperty.SubProperty } notation.

ASP.NET Core Blazor

Windows Forms

Subfields Behavior in Preview

Windows Forms: Subfields display correctly in preview mode when you click View Merged Data.

ASP.NET Core Blazor: Subfields do not display in preview mode when you click View Merged Data. The ASP.NET Core Blazor DxRichEdit component does not support subfield preview.

Both platforms generate the final merged document and display subfields correctly when you use the Show In document Action described in the View Mail Merge Results section of this topic.

View Mail Merge Results

To view the records merged with the specified document template, select the required business objects in a List View (or open a single object’s Detail View) and click Show in document. The ShowInDocument Action lets you view the records merged with the specified mail merge template directly from ListView.

ASP.NET Core Blazor

Windows Forms

Note

The ShowInDocument Action uses the in-place documents cache to generate and store the Action’s items. Note that this cache is not updated automatically. Refer to the InplaceDocumentCacheStorageBase class description for information on how to update this cache.