C# Mail Merge API | MS Word Mail Merge API для .NET

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

Нижче наведено знімок екрана документа зразок шаблону.

.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 після злиття

Виконання злиття за допомогою джерела даних 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.

Нижче наведено сторінку 1 результуючого документа Word, який ми отримуємо після виконання злиття.

Спеціальне форматування полів злиття

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» відповідно.

Нижче наведено зразок коду, який виконує 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;
}

Вкладені області злиття

Найчастіше дані, які ми маємо в джерелі даних, надходять у формі зв’язків. Наприклад, таблиця «Замовлення» матиме зв’язок «один-до-багатьох» із «Деталі замовлення», у якому зберігатимуться записи про елементи замовлення. Для роботи з такими батьківсько-дочірніми стосунками використовується вкладене злиття. Нижче наведено зразок шаблон рахунка-фактури, який добре підходить для цього сценарію.

Нижче наведено приклад джерела даних 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, отриманого після виконання злиття.

Висновок

Aspose.Words for .NET — це багатофункціональний API злиття, який надає всі стандартні та розширені функції злиття для програм .NET. За допомогою кількох рядків коду ви можете легко створювати прості чи складні звіти з різних типів джерел даних. Ви можете прочитати більше про .NET Mail Merge API у документації. Щоб дізнатися про Aspose.Words for .NET, почніть із зразків коду посібників для розробників і GitHub.

Спробуйте Aspose.Words for .NET безкоштовно

Ви можете отримати безкоштовну тимчасову ліцензію, щоб спробувати Aspose.Words for .NET без будь-яких обмежень. Отримайте тимчасову ліцензію зараз.

Дивись також

Створюйте документи Word із шаблонів у C# .NET

Що таке злиття?#

Джерела даних для злиття#

Підготовка шаблону для злиття#

.NET Mail Merge API – встановлення#

Виконайте злиття в документі Word за допомогою C##

Документ Word після злиття#

Виконання злиття за допомогою джерела даних XML у C##

Спеціальне форматування полів злиття#

Злиття пошти з регіонами за допомогою C##

Вкладені області злиття#

Документ Word після злиття#

Висновок#

Спробуйте Aspose.Words for .NET безкоштовно#

Дивись також#

Що таке злиття?

Джерела даних для злиття

Підготовка шаблону для злиття

.NET Mail Merge API – встановлення

Виконайте злиття в документі Word за допомогою C#

Документ Word після злиття

Виконання злиття за допомогою джерела даних XML у C#

Спеціальне форматування полів злиття

Злиття пошти з регіонами за допомогою C#

Вкладені області злиття

Документ Word після злиття

Висновок

Спробуйте Aspose.Words for .NET безкоштовно

Дивись також