واجهة برمجة تطبيقات دمج المراسلات C# | واجهة برمجة تطبيقات دمج المراسلات في MS Word لـ .NET

في هذه المقالة ، سأوضح لك كيفية إجراء دمج المراسلات في MS Word باستخدام C# أو VB.NET بدون MS Word أو Office Interop. Aspose.Words for .NET عبارة عن واجهة برمجة تطبيقات Word قوية وغنية بالمميزات توفر جميع ميزات دمج المراسلات الأساسية والممتدة في MS Word. يتيح لك إنشاء رسائل ومغلفات وتقارير وفواتير وأنواع أخرى من المستندات داخل نماذج Windows أو تطبيقات الويب ASP.NET أو أي تطبيق .NET / .NET Core.

تغطي هذه المقالة الميزات البارزة لـ .NET Mail Merge API الخاصة بنا ، وتتكون هذه المقالة من الأقسام التالية:

ما هو دمج المراسلات؟
مصادر البيانات لدمج المراسلات
تحضير قالب لدمج المراسلات
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.
أدخل اسمًا لحقل الدمج في اسم الحقل واضغط على موافق.
احفظ المستند.

فيما يلي لقطة شاشة من نموذج نموذج مستند.

NET Mail Merge API - التثبيت

يمكن تنزيل Aspose.Words for .NET أو تثبيته باستخدام الطرق التالية:

قم بإجراء دمج المراسلات في مستند Word باستخدام C#

بمجرد أن يكون القالب جاهزًا ، يمكنك تنفيذ دمج المراسلات لإنشاء المستندات. فيما يلي خطوات تنفيذ دمج المراسلات في القالب المذكور أعلاه.

قم بتحميل مستند النموذج باستخدام فئة المستند.
قم بتعيين خيارات دمج المراسلات المطلوبة مثل Document.MailMerge.TrimWhitespaces.
تنفيذ دمج المراسلات باستخدام طريقة Document.MailMerge.Execute() وتمرير مصدر البيانات كمعامل.
احفظ المستند الذي تم إنشاؤه باستخدام طريقة Document.Save(String).

يُظهر نموذج التعليمات البرمجية التالي كيفية تنفيذ MS Word Mail Merge باستخدام صفيف من القيم في 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>
/// إرجاع صحيح إذا كانت القيمة فردية؛ خطأ إذا كانت القيمة زوجية.
///</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 بتكرار تلك المنطقة لكل سجل في مصدر البيانات. على سبيل المثال ، يحتوي القالب التالي على منطقتين ، الطلبات وتفاصيل الطلب مع حقول الدمج «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 هي واجهة برمجة تطبيقات لدمج المراسلات غنية بالمميزات توفر جميع ميزات دمج المراسلات القياسية وكذلك الموسعة لتطبيقات .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 مجانًا

أنظر أيضا