IFieldMergingCallback Interface
Implement this interface if you want to control how data is inserted into merge fields during a mail merge operation.

Namespace: Aspose.Words.MailMerging
Assembly: Aspose.Words (in Aspose.Words.dll) Version: 20.1
public interface IFieldMergingCallback

The IFieldMergingCallback type exposes the following members.

Public methodCode exampleFieldMerging
Called when the Aspose.Words mail merge engine is about to insert data into a merge field in the document.
Public methodCode exampleImageFieldMerging
Called when the Aspose.Words mail merge engine is about to insert an image into a merge field.
Shows how to insert images stored in a database BLOB field into a report.
public void MailMergeImageFromBlob()
    Document doc = new Document(MyDir + "MailMerge.MergeImage.doc");

    // Set up the event handler for image fields
    doc.MailMerge.FieldMergingCallback = new HandleMergeImageFieldFromBlob();

    // Open a database connection
    string connString = "Provider=Microsoft.ACE.OLEDB.12.0;Data Source=" + DatabaseDir + "Northwind.mdb";
    OleDbConnection conn = new OleDbConnection(connString);

    // Open the data reader. It needs to be in the normal mode that reads all record at once
    OleDbCommand cmd = new OleDbCommand("SELECT * FROM Employees", conn);
    IDataReader dataReader = cmd.ExecuteReader();

    // Perform mail merge
    doc.MailMerge.ExecuteWithRegions(dataReader, "Employees");

    // Close the database

    doc.Save(ArtifactsDir + "MailMerge.MergeImage.doc");

private class HandleMergeImageFieldFromBlob : IFieldMergingCallback
    void IFieldMergingCallback.FieldMerging(FieldMergingArgs args)
        // Do nothing

    /// <summary>
    /// This is called when mail merge engine encounters Image:XXX merge field in the document.
    /// You have a chance to return an Image object, file name or a stream that contains the image.
    /// </summary>
    void IFieldMergingCallback.ImageFieldMerging(ImageFieldMergingArgs e)
        // The field value is a byte array, just cast it and create a stream on it
        MemoryStream imageStream = new MemoryStream((byte[])e.FieldValue);
        // Now the mail merge engine will retrieve the image from the stream
        e.ImageStream = imageStream;
Shows how to mail merge HTML data into a document.
public void MailMergeInsertHtml()
    // File 'MailMerge.InsertHtml.doc' has merge field named 'htmlField1' in it
    // File 'MailMerge.HtmlData.html' contains some valid HTML data
    // The same approach can be used when merging HTML data from database
    Document doc = new Document(MyDir + "MailMerge.InsertHtml.doc");

    // Add a handler for the MergeField event
    doc.MailMerge.FieldMergingCallback = new HandleMergeFieldInsertHtml();

    // Load some HTML from file
    StreamReader sr = File.OpenText(MyDir + "MailMerge.HtmlData.html");
    string htmltext = sr.ReadToEnd();

    // Execute mail merge
    doc.MailMerge.Execute(new string[] { "htmlField1" }, new object[] { htmltext });

    // Save resulting document with a new name
    doc.Save(ArtifactsDir + "MailMerge.InsertHtml.doc");

private class HandleMergeFieldInsertHtml : IFieldMergingCallback
    /// <summary>
    /// This is called when merge field is actually merged with data in the document.
    /// </summary>
    void IFieldMergingCallback.FieldMerging(FieldMergingArgs args)
        // All merge fields that expect HTML data should be marked with some prefix, e.g. 'html'
        if (args.DocumentFieldName.StartsWith("html") && args.Field.GetFieldCode().Contains("\\b"))
            FieldMergeField field = args.Field;

            // Insert the text for this merge field as HTML data, using DocumentBuilder
            DocumentBuilder builder = new DocumentBuilder(args.Document);
            builder.InsertHtml((string) args.FieldValue);

            // The HTML text itself should not be inserted
            // We have already inserted it as an HTML
            args.Text = "";

    void IFieldMergingCallback.ImageFieldMerging(ImageFieldMergingArgs args)
        // Do nothing
See Also