ImageFieldMergingArgs Class

Provides data for the ImageFieldMerging(ImageFieldMergingArgs) event.

Inheritance Hierarchy

Namespace:  Aspose.Words.MailMerging
Assembly:  Aspose.Words (in Aspose.Words.dll) Version: 20.7.0


public class ImageFieldMergingArgs : FieldMergingArgsBase

The ImageFieldMergingArgs type exposes the following members.


Public propertyCode exampleDocument
Returns the Document object for which the mail merge is performed.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleDocumentFieldName
Gets the name of the merge field as specified in the document.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleField
Gets the object that represents the current merge field.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleFieldName
Gets the name of the merge field in the data source.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleFieldValue
Gets or sets the value of the field from the data source.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleImage
Specifies the image that the mail merge engine must insert into the document.
Public propertyCode exampleImageFileName
Sets the file name of the image that the mail merge engine must insert into the document.
Public propertyCode exampleImageHeight
Specifies the image height for the image to insert into the document.
Public propertyCode exampleImageStream
Specifies the stream for the mail merge engine to read an image from.
Public propertyCode exampleImageWidth
Specifies the image width for the image to insert into the document.
Public propertyCode exampleRecordIndex
Gets the zero based index of the record that is being merged.
(Inherited from FieldMergingArgsBase.)
Public propertyShape
Specifies the shape that the mail merge engine must insert into the document.
Public propertyCode exampleTableName
Gets the name of the data table for the current merge operation or empty string if the name is not available.
(Inherited from FieldMergingArgsBase.)


Public methodEquals (Inherited from Object.)
Public methodGetHashCode (Inherited from Object.)
Public methodGetType (Inherited from Object.)
Public methodToString (Inherited from Object.)


This event occurs during mail merge when an image mail merge field is encountered in the document. You can respond to this event to return a file name, stream, or an Image object to the mail merge engine so it is inserted into the document.

There are three properties available ImageFileName, ImageStream and Image to specify where the image must be taken from. Set only one of these properties.

To insert an image mail merge field into a document in Word, select Insert/Field command, then select MergeField and type Image:MyFieldName.


Shows how to insert images stored in a database BLOB field into a report.
public void ImageFromBlob()
    Document doc = new Document(MyDir + "Mail merge destination - Northwind employees.docx");

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

    // Open a database connection
    string connString = $"Provider=Microsoft.Jet.OLEDB.4.0;Data Source={DatabaseDir + "Northwind.mdb"};";
    string query = "SELECT FirstName, LastName, Title, Address, City, Region, Country, PhotoBLOB FROM Employees";

    using (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(query, conn);
        IDataReader dataReader = cmd.ExecuteReader();

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

    doc.Save(ArtifactsDir + "MailMergeEvent.ImageFromBlob.docx");

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 set the dimensions of merged images.
public void MergeFieldImageDimension()
    Document doc = new Document();

    // Insert a merge field where images will be placed during the mail merge
    DocumentBuilder builder = new DocumentBuilder(doc);
    FieldMergeField field = (FieldMergeField)builder.InsertField("MERGEFIELD Image:ImageColumn");

    Assert.AreEqual("Image:ImageColumn", field.FieldName);

    // Create a data table for the mail merge
    // The name of the column that contains our image filenames needs to match the name of our merge field
    DataTable dataTable = new DataTable("Images");
    dataTable.Columns.Add(new DataColumn("ImageColumn"));
    dataTable.Rows.Add(ImageDir + "Logo.jpg");
    dataTable.Rows.Add(ImageDir + "Transparent background logo.png");
    dataTable.Rows.Add(ImageDir + "Enhanced Windows MetaFile.emf");

    doc.MailMerge.FieldMergingCallback = new MergedImageResizer(200, 200, MergeFieldImageDimensionUnit.Point);

    doc.Save(ArtifactsDir + "Field.MERGEFIELD.ImageDimension.docx");

/// <summary>
/// Sets the size of all mail merged images to one defined width and height.
/// </summary>
private class MergedImageResizer : IFieldMergingCallback
    public MergedImageResizer(double imageWidth, double imageHeight, MergeFieldImageDimensionUnit unit)
        mImageWidth = imageWidth;
        mImageHeight = imageHeight;
        mUnit = unit;

    public void FieldMerging(FieldMergingArgs e)
        throw new NotImplementedException();

    public void ImageFieldMerging(ImageFieldMergingArgs args)
        args.ImageFileName = args.FieldValue.ToString();
        args.ImageWidth = new MergeFieldImageDimension(mImageWidth, mUnit);
        args.ImageHeight = new MergeFieldImageDimension(mImageHeight, mUnit);

        Assert.AreEqual(mImageWidth, args.ImageWidth.Value);
        Assert.AreEqual(mUnit, args.ImageWidth.Unit);
        Assert.AreEqual(mImageHeight, args.ImageHeight.Value);
        Assert.AreEqual(mUnit, args.ImageHeight.Unit);

    private readonly double mImageWidth;
    private readonly double mImageHeight;
    private readonly MergeFieldImageDimensionUnit mUnit;

See Also