Видове операции Mail Merge

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

Най-честият пример за използване на прост 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 и цялото съдържание на документа ще се повтаря за всеки запис в източника на данни.