У цій статті я покажу вам, як виконати злиття пошти MS Word за допомогою C# або VB.NET без MS Word або Office Interop. Aspose.Words for .NET — це багатофункціональний і потужний API Word, який надає всі базові та розширені функції злиття листів MS Word. Він дозволяє створювати листи, конверти, звіти, рахунки-фактури та інші типи документів у Windows Forms, веб-додатках ASP.NET або будь-якій програмі .NET/.NET Core.
Ця стаття, яка охоплює основні функції нашого API злиття пошти .NET, складається з таких розділів:
- Що таке злиття?
- Джерела даних для злиття
- Підготовка шаблону для злиття
- .NET Mail Merge API – встановлення
- Виконайте злиття в документі Word за допомогою C#
- Злиття з використанням джерела даних XML
- Спеціальне форматування полів злиття
- Злиття пошти з регіонами
- Вкладені області злиття
Що таке злиття?
Злиття — це спосіб автоматизованого формування звітів, листів, конвертів, рахунків та інших видів документів. Злиття пошти в MS Word дозволяє створити шаблон документа, що містить поля злиття, а потім заповнити ці поля за допомогою записів у джерелі даних. Щоб зрозуміти злиття, припустімо, що вам потрібно надіслати лист десяти різним людям, і потрібно оновити лише поля імені та адреси. У такому випадку просто створіть шаблон листа, а потім динамічно згенеруйте листи, заповнивши поля злиття імені та адреси за допомогою джерела даних.
Джерела даних для злиття
Дані для злиття можна отримати з будь-якого джерела даних, наприклад XML, JSON або бази даних. Що стосується Aspose.Words for .NET, ви можете використовувати будь-яке джерело даних, яке підтримується ADO.NET. Дані можна завантажити в DataSet, DataTable, DataView або масив значень.
Підготовка шаблону для злиття
Шаблон злиття — це документ, який містить поля злиття. Потім ці поля заповнюються даними в джерелі даних під час виконання злиття. Шаблон документа не обов’язково має бути у форматі шаблону, він може бути документом DOC/DOCX. Ось як ви можете підготувати шаблон для злиття.
- Відкрийте документ або створіть новий у MS Word.
- Помістіть курсор туди, куди потрібно додати поле злиття.
- У меню «Вставка» виберіть параметр «Поле».
- У списку «Імена полів» виберіть MergeField.
- Введіть ім’я для поля об’єднання в поле Ім’я поля та натисніть OK.
- Збережіть документ.
Нижче наведено знімок екрана документа зразок шаблону.
![Шаблон злиття](images/template.jpg#center)
.NET Mail Merge API – встановлення
Aspose.Words for .NET можна завантажити або встановити такими способами:
Виконайте злиття в документі Word за допомогою C#
Коли ви підготували шаблон, ви можете виконати злиття, щоб створити документи. Нижче наведено кроки для виконання злиття за згаданим вище шаблоном.
- Завантажте шаблон документа за допомогою класу Document.
- Установіть необхідні параметри злиття, наприклад Document.MailMerge.TrimWhitespaces.
- Виконайте злиття за допомогою методу Document.MailMerge.Execute() і передайте джерело даних як параметр.
- Збережіть створений документ за допомогою методу Document.Save(String).
У наведеному нижче прикладі коду показано, як виконати злиття MS Word за допомогою масиву значень у C#.
// Щоб отримати повні приклади та файли даних, перейдіть на сторінку https://github.com/aspose-words/Aspose.Words-for-.NET
// Шлях до каталогу документів.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting();
// Відкрийте наявний документ.
Document doc = new Document(dataDir + "MailMerge.ExecuteArray.doc");
// Вирізати кінцеві та початкові пробіли у значеннях злиття
doc.MailMerge.TrimWhitespaces = false;
// Заповніть поля в документі даними користувача.
doc.MailMerge.Execute(
new string[] { "FullName", "Company", "Address", "Address2", "City" },
new object[] { "James Bond", "MI5 Headquarters", "Milbank", "", "London" });
dataDir = dataDir + "MailMerge.ExecuteArray_out.doc";
// Надішліть документ у форматі Word до браузера клієнта з можливістю збереження на диск або відкриття в поточному браузері.
doc.Save(dataDir);
Документ Word після злиття
![Виконати злиття в C#](images/Mail-Merge-Word-Document-1.jpg#center)
Виконання злиття за допомогою джерела даних XML у C#
Файли XML широко використовуються для зберігання, а також імпорту/експорту даних. Aspose.Words for .NET також підтримує XML як джерело даних для злиття. Просто прочитайте XML в об’єкт DataSet і виконайте злиття. Нижче наведено зразок файлу XML, який ми збираємося використовувати.
<customers>
<customer Name="John Ben Jan" ID="1" Domain="History" City="Boston"/>
<customer Name="Lisa Lane" ID="2" Domain="Chemistry" City="LA"/>
<customer Name="Dagomir Zits" ID="3" Domain="Heraldry" City="Milwaukee"/>
<customer Name="Sara Careira Santy" ID="4" Domain="IT" City="Miami"/>
</customers>
Наведений нижче приклад коду отримує дані з джерела даних XML і виконує злиття за допомогою C#.
// Щоб отримати повні приклади та файли даних, перейдіть на сторінку https://github.com/aspose-words/Aspose.Words-for-.NET
// Шлях до каталогу документів.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting();
// Створіть набір даних і прочитайте XML.
DataSet customersDs = new DataSet();
customersDs.ReadXml(dataDir + "Customers.xml");
string fileName = "TestFile XML.doc";
// Відкрийте шаблон документа.
Document doc = new Document(dataDir + fileName);
// Виконайте злиття, щоб заповнити шаблон даними з XML за допомогою DataTable.
doc.MailMerge.Execute(customersDs.Tables["Customer"]);
dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);
// Збережіть вихідний документ.
doc.Save(dataDir);
Нижче наведено [шаблон] злиття 9, який буде заповнено даними XML.
![Шаблон злиття для XML](images/template2.jpg#center)
Нижче наведено сторінку 1 результуючого документа Word, який ми отримуємо після виконання злиття.
![Виконайте злиття з XML у C#](images/Mail-Merge-Word-Document.jpg#center)
Спеціальне форматування полів злиття
Aspose.Words for .NET дає вам більше контролю над злиттям під час виконання. Властивість MailMerge.FieldMergingCallback дозволяє налаштувати злиття, коли зустрічається будь-яке поле злиття. MailMerge.FieldMergingCallback приймає клас, що реалізує методи IFieldMergingCallback.FieldMerging і IFieldMergingCallback.ImageFieldMerging.
У наведеному нижче прикладі коду показано, як налаштувати операцію злиття та застосувати форматування до комірок у цьому шаблоні.
// Щоб отримати повні приклади та файли даних, перейдіть на сторінку https://github.com/aspose-words/Aspose.Words-for-.NET
// Шлях до каталогу документів.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting();
Document doc = new Document(dataDir + "MailMerge.AlternatingRows.doc");
// Додайте обробник для події MergeField.
doc.MailMerge.FieldMergingCallback = new HandleMergeFieldAlternatingRows();
// Виконайте злиття з регіонами.
DataTable dataTable = GetSuppliersDataTable();
doc.MailMerge.ExecuteWithRegions(dataTable);
dataDir = dataDir + "MailMerge.AlternatingRows_out.doc";
doc.Save(dataDir);
Нижче наведено реалізацію класу HandleMergeFieldAlternatingRows.
// Щоб отримати повні приклади та файли даних, перейдіть на сторінку https://github.com/aspose-words/Aspose.Words-for-.NET
private class HandleMergeFieldAlternatingRows : IFieldMergingCallback
{
///<summary>
/// Викликається для кожного поля злиття, яке зустрічається в документі.
/// Ми можемо або повернути деякі дані механізму злиття, або зробити щось
/// Інше з документом. У цьому випадку ми змінюємо форматування комірки.
///</summary>
void IFieldMergingCallback.FieldMerging(FieldMergingArgs e)
{
if (mBuilder == null)
mBuilder = new DocumentBuilder(e.Document);
// Таким чином ми ловимо початок нового ряду.
if (e.FieldName.Equals("CompanyName"))
{
// Виберіть колір залежно від того, парний чи непарний номер рядка.
Color rowColor;
if (IsOdd(mRowIdx))
rowColor = Color.FromArgb(213, 227, 235);
else
rowColor = Color.FromArgb(242, 242, 242);
// На даний момент немає способу встановити властивості комірки для всього рядка,
// Отже, ми повинні повторити всі клітинки в рядку.
for (int colIdx = 0; colIdx < 4; colIdx++)
{
mBuilder.MoveToCell(0, mRowIdx, colIdx, 0);
mBuilder.CellFormat.Shading.BackgroundPatternColor = rowColor;
}
mRowIdx++;
}
}
void IFieldMergingCallback.ImageFieldMerging(ImageFieldMergingArgs args)
{
// Нічого не робити.
}
private DocumentBuilder mBuilder;
private int mRowIdx;
}
///<summary>
/// Повертає true, якщо значення непарне; false, якщо значення парне.
///</summary>
private static bool IsOdd(int value)
{
// Код дещо складний, але в інших випадках автоматичне перетворення у VB не працює.
return ((value / 2) * 2).Equals(value);
}
///<summary>
/// Створіть DataTable і заповніть її даними.
/// У реальному житті цю DataTable слід заповнювати з бази даних.
///</summary>
private static DataTable GetSuppliersDataTable()
{
DataTable dataTable = new DataTable("Suppliers");
dataTable.Columns.Add("CompanyName");
dataTable.Columns.Add("ContactName");
for (int i = 0; i < 10; i++)
{
DataRow datarow = dataTable.NewRow();
dataTable.Rows.Add(datarow);
datarow[0] = "Company " + i.ToString();
datarow[1] = "Contact " + i.ToString();
}
return dataTable;
}
Злиття пошти з регіонами за допомогою C#
Може бути випадок, коли вам потрібно заповнити та повторити певну область у документі Word. Для такого випадку ви можете використовувати злиття пошти з регіонами. Щоб створити регіон, вам потрібно вказати початок і кінець регіону, а потім Mail Megre повторюватиме цей регіон для кожного запису в джерелі даних. Наприклад, наведений нижче шаблон містить дві області, Orders і OrderDetails із полями злиття «TableStart:Orders», «TableEnd:Orders» і «TableStart:OrderDetails», «TableEnd:OrderDetails» відповідно.
![Злиття пошти з регіонами](images/template_regions.jpg#center)
Нижче наведено зразок коду, який виконує Mail Megre в регіонах для згаданого вище шаблону.
// Щоб отримати повні приклади та файли даних, перейдіть на сторінку https://github.com/aspose-words/Aspose.Words-for-.NET
// Шлях до каталогу документів.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting();
string fileName = "MailMerge.ExecuteWithRegions.doc";
Document doc = new Document(dataDir + fileName);
// Використовуйте DataTable як джерело даних.
int orderId = 10444;
DataTable orderTable = GetTestOrder(orderId);
doc.MailMerge.ExecuteWithRegions(orderTable);
// Замість використання DataTable ви можете створити DataView для спеціального сортування або фільтрування, а потім злиття.
DataView orderDetailsView = new DataView(GetTestOrderDetails(orderId));
orderDetailsView.Sort = "ExtendedPrice DESC";
// Виконайте операцію злиття.
doc.MailMerge.ExecuteWithRegions(orderDetailsView);
// Збережіть об’єднаний документ.
dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);
doc.Save(dataDir);
Нижче наведено методи читання даних із бази даних.
// Щоб отримати повні приклади та файли даних, перейдіть на сторінку https://github.com/aspose-words/Aspose.Words-for-.NET
private static DataTable GetTestOrder(int orderId)
{
DataTable table = ExecuteDataTable(string.Format(
"SELECT * FROM AsposeWordOrders WHERE OrderId = {0}", orderId));
table.TableName = "Orders";
return table;
}
private static DataTable GetTestOrderDetails(int orderId)
{
DataTable table = ExecuteDataTable(string.Format(
"SELECT * FROM AsposeWordOrderDetails WHERE OrderId = {0} ORDER BY ProductID", orderId));
table.TableName = "OrderDetails";
return table;
}
///<summary>
/// Допоміжна функція, яка створює підключення, команду,
/// Виконує команду та повертає результат у DataTable.
///</summary>
private static DataTable ExecuteDataTable(string commandText)
{
// Відкрийте підключення до бази даних.
string connString = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=" +
RunExamples.GetDataDir_Database() + "Northwind.mdb";
OleDbConnection conn = new OleDbConnection(connString);
conn.Open();
// Створіть і виконайте команду.
OleDbCommand cmd = new OleDbCommand(commandText, conn);
OleDbDataAdapter da = new OleDbDataAdapter(cmd);
DataTable table = new DataTable();
da.Fill(table);
// Закрийте базу даних.
conn.Close();
return table;
}
Вкладені області злиття
Найчастіше дані, які ми маємо в джерелі даних, надходять у формі зв’язків. Наприклад, таблиця «Замовлення» матиме зв’язок «один-до-багатьох» із «Деталі замовлення», у якому зберігатимуться записи про елементи замовлення. Для роботи з такими батьківсько-дочірніми стосунками використовується вкладене злиття. Нижче наведено зразок шаблон рахунка-фактури, який добре підходить для цього сценарію.
![Шаблон злиття з регіонами](images/template_nested.jpg#center)
Нижче наведено приклад джерела даних XML, який ми будемо використовувати для вкладеного злиття.
<?xml version="1.0" encoding="utf-8"?>
<Orders xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="OrdersSchema.xsd">
<Order>
<Number>23</Number>
<Address>Nelson Street</Address>
<Suburb>Howick</Suburb>
<City>Auckland</City>
<Phonenumber>543 1234</Phonenumber>
<Date>03/01/2010</Date>
<Total>14.00</Total>
<Item>
<Name>BBQ Chicken Pizza</Name>
<Price>6.00</Price>
<Quantity>1</Quantity>
<ItemTotal>6.00</ItemTotal>
</Item>
<Item>
<Name>1.5 Litre Coke</Name>
<Price>4.00</Price>
<Quantity>2</Quantity>
<ItemTotal>8.00</ItemTotal>
</Item>
</Order>
<Order>
<Number>10</Number>
<Address>Parkville Avenue</Address>
<Suburb>Pakuranga</Suburb>
<City>Auckland</City>
<Phonenumber>548 7342</Phonenumber>
<Date>05/03/2010</Date>
<Total>6.00</Total>
<Item>
<Name>Hawaiian Pizza</Name>
<Price>4.00</Price>
<Quantity>1</Quantity>
<ItemTotal>4.00</ItemTotal>
</Item>
<Item>
<Name>Fries</Name>
<Price>1.00</Price>
<Quantity>2</Quantity>
<ItemTotal>2.00</ItemTotal>
</Item>
</Order>
</Orders>
Тоді як OrderSchema.xsd для цього XML є:
<?xml version="1.0" encoding ="utf-8"?>
<xs:schema id="OrdersSchema" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Orders">
<xs:complexType>
<xs:sequence>
<xs:element name="Order">
<xs:complexType>
<xs:sequence>
<xs:element name="Number"/>
<xs:element name="Address"/>
<xs:element name="Suburb"/>
<xs:element name="City"/>
<xs:element name="Phonenumber">
<xs:element name="Date"/>
<xs:element name="Total"/>
<xs:element name="Item">
<xs:complexType>
<xs:sequence>
<xs:element name="Name"/>
<xs:element name="Price"/>
<xs:element name="Quantity"/>
<xs:element name="ItemTotal"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Наведений нижче зразок коду використовується для виконання вкладеного злиття за допомогою C#.
// Щоб отримати повні приклади та файли даних, перейдіть на сторінку https://github.com/aspose-words/Aspose.Words-for-.NET
// Шлях до каталогу документів.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting();
// Створіть набір даних і прочитайте XML.
DataSet pizzaDs = new DataSet();
// Datatable.TableNames і DataSet.Relations неявно визначені .NET через ReadXml.
pizzaDs.ReadXml(dataDir + "CustomerData.xml");
string fileName = "Invoice Template.doc";
// Відкрийте шаблон документа.
Document doc = new Document(dataDir + fileName);
// Вирізати кінцеві та початкові пробіли у значеннях злиття.
doc.MailMerge.TrimWhitespaces = false;
// Виконайте вкладене злиття з регіонами.
doc.MailMerge.ExecuteWithRegions(pizzaDs);
dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);
// Збережіть результат у файл.
doc.Save(dataDir);
Debug.Assert(doc.MailMerge.GetFieldNames().Length == 0, "There was a problem with mail merge");
Console.WriteLine("\nMail merge performed with nested data successfully.\nFile saved at " + dataDir);
Документ Word після злиття
Нижче наведено першу сторінку документа Word, отриманого після виконання злиття.
![Документ Word після злиття](images/Nested-Mail-Merge-Word-Document.jpg#center)
Висновок
Aspose.Words for .NET — це багатофункціональний API злиття, який надає всі стандартні та розширені функції злиття для програм .NET. За допомогою кількох рядків коду ви можете легко створювати прості чи складні звіти з різних типів джерел даних. Ви можете прочитати більше про .NET Mail Merge API у документації. Щоб дізнатися про Aspose.Words for .NET, почніть із зразків коду посібників для розробників і GitHub.
Спробуйте Aspose.Words for .NET безкоштовно
Ви можете отримати безкоштовну тимчасову ліцензію, щоб спробувати Aspose.Words for .NET без будь-яких обмежень. Отримайте тимчасову ліцензію зараз.