Типи операцій 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, і весь вміст документа буде повторюватися для кожного запису у джерелі даних.