The Merge method of MailMerge accepts a DataTable as a parameter and the MergeObjects method accepts an IEnumerable object such as a List as the data source. This DataTable or object acts as the master table for the merge process.

MergeField names without a prefix in the template are matched to this table and doesn't require a prefix. The rows of the master table are used to create the document instances of the template. In other words: The number of resulting documents in a merge process depends on the number of records in the master table.

All relations between child tables and the master table is defined as a prefix in the merge field name concatenated with a dot:

ChildTable[.ChildTable].ColumnName

Our sample database has the following structure:

In case the master table is Sales_SalesOrderHeader, the merge field values for MergeFields without a prefix are coming from this table. If MergeFields have a prefix, the values are coming from related tables such as Sales_SalesOrderDetail:

Sales_SalesOrdcerDetail.ProductID

The master table is the base table for the complete report. Inside of merge blocks, the master table for this block is the merge block table. All child tables of this block table can be used inside of the merge block with the same notation. In other words: Each merge block as a new master table and relations are based on the block master table.

As a business object, the above DataSet would look similar to the illustrated classes below:

The class SalesOrderHeader has a property of type SalesOrderDetail which acts like a child table in our datasource context.

class SalesOrderHeader
{
    public int RevisionNumber { get; set; }
    public DateTime OrderDate { get; set; }
    public SalesOrderDetail OrderDetail { get; set; }
}

class SalesOrderDetail
{
    public List<Production_Product> Products { get; set; }
    public Customer Customer { get; set; }
}

class Production_Product
{
    public string Name { get; set; }
    public string ProductNumber { get; set; }
}

class Customer
{
    public int CustomerID { get; set; }
    public string Name { get; set; }
    public int SalesPersonID { get; set; }
}

The merge field name syntax is following the same rules as for DataTables. The relation between related objects is defined as a prefix in the merge field name concatenated with a dot.