Mail Merge

• Feb 27, 2024
• 3 minutes to read

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

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

In .NET 6+ 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;
// ...
public class ApplicationBuilder : IDesignTimeApplicationFactory {
    public static WinApplication BuildApplication(string connectionString) {
        var builder = WinApplication.CreateBuilder();
        builder.UseApplication<YourSolutionNameWindowsFormsApplication>();
        builder.Modules
            // ...
            .AddOffice(options => {
                options.RichTextMailMergeDataType = typeof(PeAppre);
            })
        // ...
    }
    // ...
}

In .NET 6+ Applications Without Application Builder or .NET Framework Applications

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);
        // ...
    }
    // ...
}

In .NET Framework Applications

Use the Application Designer:

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). If you use the Application Designer, you must register the type before you open the designer window.

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 Insert Merge Field dropdown (Windows Forms) and Insert Merge Field popup window (ASP.NET Core Blazor and ASP.NET Web Forms), you can choose the Data Type’s fields to add to the document template.

Note

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.

The subfields are not displayed in Insert Merge Field, but you can type them manually: click Show All Field Codes and type the field using the { MERGEFIELD ObjectProperty.SubProperty } notation.

ASP.NET Core Blazor

Windows Forms

Note

In ASP.NET Web Forms applications, create the INCLUDEPICTURE field and specify the name of a BLOB image property to include an image field in the document.

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.