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 API המספק את כל התכונות הבסיסיות כמו גם המורחבות של מיזוג דואר של MS Word. זה מאפשר לך להפיק מכתבים, מעטפות, דוחות, חשבוניות וסוגים אחרים של מסמכים בתוך Windows Forms, יישומי אינטרנט של ASP.NET או כל יישום .NET/.NET Core.

מאמר זה מכסה את התכונות הבולטות של ממשק ה-API של .NET Mail Merge, מורכב מהסעיפים הבאים:

מה זה מיזוג דואר?
מקורות נתונים למיזוג דואר
הכנת תבנית למיזוג דואר
.NET Mail Merge API - התקנה
בצע מיזוג דואר במסמך Word באמצעות C#
מיזוג דואר באמצעות מקור נתונים ב-XML
עיצוב מותאם אישית של שדות מיזוג
מיזוג דואר עם אזורים
אזורי מיזוג דואר מקוננים

מה זה מיזוג דואר?

מיזוג דואר היא הדרך להפקה אוטומטית של דוחות, מכתבים, מעטפות, חשבוניות וסוגים אחרים של מסמכים. מיזוג דואר ב-MS Word מאפשר לך ליצור מסמך תבנית המכיל שדות מיזוג ולאחר מכן לאכלס שדות אלה באמצעות רשומות במקור הנתונים. כדי להבין מיזוג דואר, נניח שעליך לשלוח מכתב לעשרה אנשים שונים ורק השם ושדות הכתובת צריכים להתעדכן. במקרה כזה, פשוט צור תבנית של המכתב ולאחר מכן צור באופן דינמי את האותיות על ידי איכלוס שדות המיזוג של השם והכתובת באמצעות מקור הנתונים.

מקורות נתונים למיזוג דואר

ניתן לאחזר את הנתונים עבור מיזוג הדואר מכל מקור נתונים כגון XML, JSON או מסד נתונים. מבחינת Aspose.Words עבור NET, אתה יכול להשתמש בכל מקור נתונים שנתמך על ידי ADO.NET. ניתן לטעון את הנתונים לתוך DataSet, DataTable, DataView או מערך של ערכים.

הכנת תבנית למיזוג דואר

תבנית מיזוג הדואר היא המסמך המכיל את שדות המיזוג. לאחר מכן, שדות אלה מאוכלסים בנתונים במקור הנתונים כאשר מיזוג הדואר מבוצע. מסמך התבנית אינו צריך להיות תבנית תבנית והוא יכול להיות מסמך DOC/DOCX. כך תוכלו להכין תבנית למיזוג דואר.

פתח את המסמך שלך או צור מסמך חדש ב-MS Word.
מקם את הסמן במקום שבו ברצונך להוסיף שדה מיזוג.
מתפריט הוספה בחר באפשרות שדה.
מרשימת שמות השדות, בחר MergeField.
הזן שם עבור שדה המיזוג בשדה שם ולחץ על אישור.
שמור את המסמך.

להלן צילום המסך של המסמך תבנית לדוגמה.

.NET Mail Merge API - התקנה

ניתן להוריד או להתקין את Aspose.Words עבור 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";
// שלח את המסמך בפורמט וורד לדפדפן הלקוח עם אפשרות לשמור בדיסק או לפתוח בתוך הדפדפן הנוכחי.
doc.Save(dataDir);

מסמך Word לאחר מיזוג דואר

בצע מיזוג דואר באמצעות מקור נתונים XML ב-C#

קובצי ה-XML נמצאים בשימוש נרחב לשמירה וגם לייבוא/ייצוא של נתונים. Aspose.Words עבור 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);

להלן מיזוג הדואר תבנית שיאוכלס בנתוני XML.

להלן עמוד 1 של מסמך Word שנוצר לאחר ביצוע מיזוג הדואר.

עיצוב מותאם אישית של שדות מיזוג

Aspose.Words עבור .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 עבור .NET הוא API עתיר תכונות של מיזוג דואר המספק את כל תכונות המיזוג הסטנדרטיות כמו גם מורחבות עבור יישומי NET. בתוך כמה שורות קוד, אתה יכול ליצור דוחות פשוטים או מורכבים מסוגים שונים של מקורות נתונים בצורה חלקה. תוכל לקרוא עוד על ממשק ה-API של .NET Mail Merge מתוך תיעוד. כדי ללמוד על Aspose.Words עבור .NET, התחל עם מדריכי המפתחים ודוגמאות הקוד GitHub.

נסה את Aspose.Words עבור NET בחינם

אתה יכול לקבל רישיון זמני בחינם לנסות את Aspose.Words עבור NET ללא כל הגבלה. קבל את הרישיון הזמני שלך עכשיו.

ראה גם

צור מסמכי Word מתבניות ב-C# .NET

מה זה מיזוג דואר?#

מקורות נתונים למיזוג דואר#

הכנת תבנית למיזוג דואר#

.NET Mail Merge API - התקנה#

בצע מיזוג דואר במסמך Word באמצעות C##

מסמך Word לאחר מיזוג דואר#

בצע מיזוג דואר באמצעות מקור נתונים XML ב-C##

עיצוב מותאם אישית של שדות מיזוג#

מיזוג דואר עם אזורים באמצעות C##

אזורי מיזוג דואר מקוננים#

מסמך Word לאחר מיזוג דואר#

סיכום#

נסה את Aspose.Words עבור NET בחינם#

ראה גם#

מה זה מיזוג דואר?

מקורות נתונים למיזוג דואר

הכנת תבנית למיזוג דואר

.NET Mail Merge API - התקנה

בצע מיזוג דואר במסמך Word באמצעות C#

מסמך Word לאחר מיזוג דואר

בצע מיזוג דואר באמצעות מקור נתונים XML ב-C#

עיצוב מותאם אישית של שדות מיזוג

מיזוג דואר עם אזורים באמצעות C#

אזורי מיזוג דואר מקוננים

מסמך Word לאחר מיזוג דואר

סיכום

נסה את Aspose.Words עבור NET בחינם

ראה גם