Типы операций Mail Merge

Основная идея Mail Merge заключается в автоматическом создании документа или нескольких документов на основе вашего шаблона и данных, полученных из вашего источника данных. Aspose.Words позволяет выполнять два различных типа операций Mail Merge: простые Mail Merge и Mail Merge с регионами.

Наиболее распространенным примером использования simple Mail Merge является ситуация, когда вы хотите отправить документ для разных клиентов, указав их имена в начале документа. Чтобы сделать это, вам нужно создать поля слияния, такие как First Name и Last Name, в вашем шаблоне, а затем заполнить их данными из вашего источника данных. Принимая во внимание, что наиболее распространенный пример использования Mail Merge с регионами - это когда вы хотите отправить документ, содержащий конкретные заказы со списком всех позиций в каждом заказе. Для этого вам нужно будет создать регионы слияния внутри вашего шаблона – собственный регион для каждого заказа, чтобы заполнить его всеми необходимыми данными для товаров.

Основное различие между обеими операциями слияния заключается в том, что простой Mail Merge (без областей) повторяет весь документ для каждой записи источника данных, тогда как Mail Merge с областями повторяет только определенные области для каждой записи. Вы можете рассматривать простую операцию Mail Merge как частный случай слияния с областями, где единственной областью является весь документ целиком.

Класс MailMerge представляет функциональность Mail Merge. С помощью его свойств вы можете настроить требуемое поведение перед выполнением операции Mail Merge.

Простое Mail Merge Управление

Простое значение Mail Merge используется для заполнения полей Mail Merge внутри вашего шаблона необходимыми данными из вашего источника данных (представление в виде одной таблицы). Таким образом, оно аналогично классическому значению Mail Merge в Microsoft Word.

Вы можете добавить одно или несколько полей для объединения в свой шаблон, а затем выполнить простую операцию Mail Merge. Рекомендуется использовать ее, если в вашем шаблоне нет областей для объединения.

Основным ограничением использования этого типа является то, что все содержимое документа будет повторяться для каждой записи в источнике данных.

Как выполнить простую операцию Mail Merge

Как только ваш шаблон будет готов, вы можете приступить к выполнению простой операции Mail Merge. Aspose.Words позволяет выполнить простую операцию Mail Merge, используя различные Execute methods, которые принимают различные объекты данных в качестве источника данных.

В следующем примере кода показано, как выполнить простую операцию Mail Merge, используя один из методов Execute:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
// Include the code for our template.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Create Merge Fields.
builder.InsertField(" MERGEFIELD CustomerName ");
builder.InsertParagraph();
builder.InsertField(" MERGEFIELD Item ");
builder.InsertParagraph();
builder.InsertField(" MERGEFIELD Quantity ");

// Fill the fields in the document with user data.
doc.MailMerge.Execute(new string[] { "CustomerName", "Item", "Quantity" },
    new object[] { "John Doe", "Hawaiian", "2" });

doc.Save(ArtifactsDir + "BaseOperations.SimpleMailMerge.docx");

Вы можете заметить разницу между документами перед выполнением простого mail merge:

И после выполнения простого mail merge:

Как создать несколько объединенных документов

В случае Aspose.Words стандартная операция Mail Merge заполняет содержимым из вашего источника данных только один документ. Таким образом, вам нужно будет выполнить операцию Mail Merge несколько раз, чтобы создать несколько объединенных документов в качестве выходных данных.

В следующем примере кода показано, как создать несколько объединенных документов во время операции Mail Merge:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
string connString = @"Provider=Microsoft.ACE.OLEDB.12.0;Data Source=" + DatabaseDir + "Northwind.accdb";

Document doc = new Document(MyDir + "Mail merge destination - Northwind suppliers.docx");

OleDbConnection conn = new OleDbConnection(connString);
conn.Open();
            
OleDbCommand cmd = new OleDbCommand("SELECT * FROM Customers", conn);
OleDbDataAdapter da = new OleDbDataAdapter(cmd);
            
DataTable data = new DataTable();
da.Fill(data);

// Perform a loop through each DataRow to iterate through the DataTable. Clone the template document
// instead of loading it from disk for better speed performance before the mail merge operation.
// You can load the template document from a file or stream but it is faster to load the document
// only once and then clone it in memory before each mail merge operation.
            
int counter = 1;
foreach (DataRow row in data.Rows)
{
    Document dstDoc = (Document) doc.Clone(true);

    dstDoc.MailMerge.Execute(row);

    dstDoc.Save(string.Format(ArtifactsDir + "BaseOperations.ProduceMultipleDocuments_{0}.docx", counter++));
}

Вы можете скачать примерный файл этого примера с сайта Aspose.Words GitHub.

Mail Merge с регионами

Вы можете создавать различные области в своем шаблоне, чтобы иметь специальные области, которые вы можете просто заполнить своими данными. Используйте Mail Merge с регионами, если вы хотите вставлять таблицы, строки с повторяющимися данными, чтобы ваши документы динамически расширялись, указав эти области в вашем шаблоне.

Вы можете создавать вложенные (дочерние) области, а также объединять области. Основное преимущество использования этого типа заключается в динамическом увеличении частей внутри документа. Более подробную информацию смотрите в следующей статье “Вложенные Mail Merge области с областями”.

Информация о регионе Mail Merge может быть получена с помощью класса MailMergeRegionInfo.

Как выполнить Mail Merge с регионами

Область Mail Merge - это определенная часть документа, имеющая начальную и конечную точки. Обе точки представлены в виде Mail Merge полей с определенными именами “TableStart:XXX” и “TableEnd:XXX”. Все содержимое, включенное в область Mail Merge, будет автоматически повторяться для каждой записи в источнике данных.

Aspose.Words позволяет выполнять Mail Merge с регионами, использующими разные Execute methods, которые принимают различные объекты данных в качестве источника данных.

В качестве первого шага нам нужно создать DataSet, чтобы позже передать его в качестве входного параметра методу ExecuteWithRegions:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
private DataSet CreateDataSet()
{
    // Create the customers table.
    DataTable tableCustomers = new DataTable("Customers");
    tableCustomers.Columns.Add("CustomerID");
    tableCustomers.Columns.Add("CustomerName");
    tableCustomers.Rows.Add(new object[] { 1, "John Doe" });
    tableCustomers.Rows.Add(new object[] { 2, "Jane Doe" });

    // Create the orders table.
    DataTable tableOrders = new DataTable("Orders");
    tableOrders.Columns.Add("CustomerID");
    tableOrders.Columns.Add("ItemName");
    tableOrders.Columns.Add("Quantity");
    tableOrders.Rows.Add(new object[] { 1, "Hawaiian", 2 });
    tableOrders.Rows.Add(new object[] { 2, "Pepperoni", 1 });
    tableOrders.Rows.Add(new object[] { 2, "Chicago", 1 });

    // Add both tables to a data set.
    DataSet dataSet = new DataSet();
    dataSet.Tables.Add(tableCustomers);
    dataSet.Tables.Add(tableOrders);

    // The "CustomerID" column, also the primary key of the customers table is the foreign key for the Orders table.
    dataSet.Relations.Add(tableCustomers.Columns["CustomerID"], tableOrders.Columns["CustomerID"]);

    return dataSet;
}

В следующем примере кода показано, как выполнить Mail Merge с регионами, используя метод ExecuteWithRegions(DataSet):

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// The start point of mail merge with regions the dataset.
builder.InsertField(" MERGEFIELD TableStart:Customers");
            
// Data from rows of the "CustomerName" column of the "Customers" table will go in this MERGEFIELD.
builder.Write("Orders for ");
builder.InsertField(" MERGEFIELD CustomerName");
builder.Write(":");

// Create column headers.
builder.StartTable();
builder.InsertCell();
builder.Write("Item");
builder.InsertCell();
builder.Write("Quantity");
builder.EndRow();

// We have a second data table called "Orders", which has a many-to-one relationship with "Customers"
// picking up rows with the same CustomerID value.
builder.InsertCell();
builder.InsertField(" MERGEFIELD TableStart:Orders");
builder.InsertField(" MERGEFIELD ItemName");
builder.InsertCell();
builder.InsertField(" MERGEFIELD Quantity");
builder.InsertField(" MERGEFIELD TableEnd:Orders");
builder.EndTable();

// The end point of mail merge with regions.
builder.InsertField(" MERGEFIELD TableEnd:Customers");

// Pass our dataset to perform mail merge with regions.
DataSet customersAndOrders = CreateDataSet();
doc.MailMerge.ExecuteWithRegions(customersAndOrders);

doc.Save(ArtifactsDir + "BaseOperations.MailMergeWithRegions.docx");

Вы можете заметить разницу между документами перед выполнением Mail Merge с регионами:

И после выполнения Mail Merge с регионами:

Ограничения Mail Merge для регионов

Есть несколько важных моментов, которые необходимо учитывать при выполнении Mail Merge с регионами:

• Начальная точка TableStart:Orders и конечная точка TableEnd:Orders должны находиться в одной строке или ячейке. Например, если область объединения начинается в ячейке таблицы, то область объединения должна заканчиваться в той же строке, что и первая ячейка.
• Имя объединяемого поля должно совпадать с именем столбца в вашем DataTable. Если вы не указали сопоставленные поля, Mail Merge с регионами не будет успешным для любого объединяемого поля, имя которого отличается от имени столбца.

Если одно из этих правил будет нарушено, вы получите неожиданные результаты или может возникнуть исключение.

Если вы не используете Mail Merge регионы, то это будет аналогично Microsoft Word mail merge, и все содержимое документа будет повторяться для каждой записи в источнике данных.