C# Mail Merge API | MS Word Mail Merge API برای دات نت

در این مقاله، من به شما نشان خواهم داد که چگونه می توانید MS Word Mail Merge را با استفاده از C# یا VB.NET بدون MS Word یا Office Interop انجام دهید. Aspose.Words for .NET یک Word API غنی و قدرتمند است که همه ویژگی‌های اولیه و همچنین توسعه یافته MS Word Mail Merge را ارائه می‌کند. این به شما امکان می دهد نامه ها، پاکت نامه ها، گزارش ها، فاکتورها و انواع دیگر اسناد را در فرم های ویندوز، برنامه های کاربردی وب ASP.NET یا هر برنامه .NET/.NET Core ایجاد کنید.

این مقاله با پوشش ویژگی های برجسته API ادغام ایمیل دات نت ما از بخش های زیر تشکیل شده است:

Mail Merge چیست؟
منابع داده برای ادغام ایمیل
آماده سازی الگو برای ادغام نامه
NET Mail Merge API - نصب
انجام Mail Merge در سند Word با استفاده از C#
ادغام ایمیل با استفاده از منبع داده XML
قالب بندی سفارشی فیلدهای ادغام
ادغام ایمیل با مناطق
مناطق ادغام ایمیل تودرتو

Mail Merge چیست؟

Mail Merge روش تولید خودکار گزارش ها، نامه ها، پاکت نامه ها، فاکتورها و انواع دیگر اسناد است. Mail Merge در MS Word به شما امکان می دهد یک سند الگوی حاوی فیلدهای ادغام ایجاد کنید و سپس با استفاده از سوابق موجود در منبع داده، آن فیلدها را پر کنید. برای درک Mail Merge، فرض کنید باید نامه ای به ده نفر مختلف بفرستید و فقط نام و فیلدهای آدرس باید به روز شوند. در چنین حالتی، به سادگی یک الگوی نامه ایجاد کنید و سپس با پر کردن فیلدهای ادغام نام و آدرس با استفاده از منبع داده، حروف را به صورت پویا تولید کنید.

منابع داده برای ادغام ایمیل

داده‌های Mail Merge را می‌توان از هر منبع داده مانند XML، JSON یا پایگاه داده دریافت کرد. تا جایی که به Aspose.Words برای دات نت مربوط می شود، می توانید از هر منبع داده ای که توسط ADO.NET پشتیبانی می شود استفاده کنید. داده ها را می توان در DataSet، DataTable، DataView یا آرایه ای از مقادیر بارگذاری کرد.

آماده سازی الگو برای ادغام نامه

الگوی Mail Merge سندی است که حاوی فیلدهای ادغام است. پس از اجرای Mail Merge، این فیلدها با داده های موجود در منبع داده پر می شوند. سند الگو لازم نیست قالب قالب باشد و می تواند سند DOC/DOCX باشد. به این ترتیب می توانید یک الگو برای Mail Merge آماده کنید.

سند خود را باز کنید یا یک سند جدید در MS Word ایجاد کنید.
مکان نما را در جایی که می خواهید فیلد ادغام اضافه کنید قرار دهید.
از منوی Insert گزینه Field را انتخاب کنید.
از لیست Field names، MergeField را انتخاب کنید.
نام فیلد ادغام را در نام فیلد وارد کنید و OK را فشار دهید.
سند را ذخیره کنید.

تصویر زیر اسکرین شات از سند نمونه الگو است.

NET Mail Merge API - نصب

Aspose.Words for .NET را می توان با استفاده از روش های زیر دانلود یا نصب کرد:

انجام ادغام نامه در سند Word با استفاده از سی شارپ

هنگامی که قالب را آماده کردید، می توانید Mail Merge را برای تولید اسناد اجرا کنید. مراحل زیر برای اجرای Mail Merge در قالب فوق ذکر شده است.

سند الگو را با استفاده از کلاس Document بارگیری کنید.
گزینه های مورد نیاز Mail Merge مانند Document.MailMerge.TrimWhitespaces را تنظیم کنید.
یک Mail Merge را با استفاده از روش 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 پس از ادغام ایمیل

انجام Mail Merge با استفاده از منبع داده XML در سی شارپ

فایل های XML به طور گسترده ای برای نگهداری و همچنین واردات/صادرات داده ها استفاده می شوند. Aspose.Words برای دات نت همچنین از XML به عنوان منبع داده برای Mail Merge پشتیبانی می کند. فقط XML را در یک شی DataSet بخوانید و Mail Merge را اجرا کنید. در زیر نمونه فایل 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 واکشی می کند و Mail Merge را با استفاده از C# اجرا می کند.

// برای نمونه های کامل و فایل های داده، لطفاً به https://github.com/aspose-words/Aspose.Words-for-.NET بروید
// مسیر دایرکتوری اسناد
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 

// Dataset را ایجاد کنید و 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);

در زیر Mail Merge قالب است که با داده های XML پر می شود.

در زیر صفحه 1 از سند Word حاصل است که پس از اجرای Mail Merge دریافت می کنیم.

قالب بندی سفارشی فیلدهای ادغام

Aspose.Words برای دات نت به شما کنترل بیشتری بر روی Mail Merge در طول اجرا می دهد. ویژگی MailMerge.FieldMergingCallback به شما امکان می دهد تا زمانی که با هر فیلد ادغامی مواجه می شوید، Mail Merge را سفارشی کنید. MailMerge.FieldMergingCallback کلاسی را می پذیرد که متدهای IFieldMergingCallback.FieldMerging و IFieldMergingCallback.ImageFieldMerging را اجرا می کند.

نمونه کد زیر نحوه سفارشی کردن عملیات Mail Merge و اعمال قالب‌بندی در سلول‌های داخل [این الگو13 را نشان می‌دهد.

// برای نمونه های کامل و فایل های داده، لطفاً به 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;
}

ادغام ایمیل با مناطق با استفاده از سی شارپ

ممکن است موردی وجود داشته باشد که شما نیاز به پر کردن و تکرار یک منطقه خاص در سند Word داشته باشید. برای چنین موردی، می توانید از Mail Merge با مناطق استفاده کنید. برای ایجاد یک منطقه باید شروع و پایان منطقه را مشخص کنید و سپس 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;
}

مناطق ادغام ایمیل تودرتو

اغلب، داده هایی که ما در منبع داده داریم به شکل روابط است. به عنوان مثال، جدول “Order” یک رابطه یک به چند با “OrderDetails” خواهد داشت که سوابق موارد را به ترتیب نگه می دارد. برای مقابله با چنین روابط والدین-فرزندی، از Mail Merge تودرتو استفاده می شود. نمونه زیر نمونه الگوی فاکتور است که به خوبی با این سناریو مطابقت دارد.

در زیر نمونه ای از منبع داده 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>

نمونه کد زیر برای اجرای Mail Merge تودرتو با استفاده از C# استفاده می شود.

// برای نمونه های کامل و فایل های داده، لطفاً به https://github.com/aspose-words/Aspose.Words-for-.NET بروید
// مسیر دایرکتوری اسناد
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 
	 
// Dataset را ایجاد کنید و 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 حاصل پس از اجرای Mail Merge است.

نتیجه

Aspose.Words for .NET یک API ادغام ایمیل با ویژگی های غنی است که تمام ویژگی های استاندارد و همچنین توسعه یافته Mail Merge را برای برنامه های NET فراهم می کند. در چند خط کد، می‌توانید گزارش‌های ساده یا پیچیده را از انواع مختلف منابع داده به‌طور یکپارچه ایجاد کنید. می‌توانید اطلاعات بیشتری در مورد API ادغام ایمیل دات نت از مستندات بخوانید. برای آشنایی با Aspose.Words برای دات نت، با نمونه کد راهنماهای توسعه دهنده و GitHub شروع کنید.

Aspose.Words را برای دات نت به صورت رایگان امتحان کنید

برای امتحان Aspose.Words برای دات نت بدون هیچ محدودیتی می توانید یک مجوز موقت رایگان دریافت کنید. [هم اکنون مجوز موقت خود را دریافت کنید19.

همچنین ببینید

ایجاد اسناد Word از قالب ها در C#.NET

Mail Merge چیست؟#

منابع داده برای ادغام ایمیل#

آماده سازی الگو برای ادغام نامه#

NET Mail Merge API - نصب#

انجام ادغام نامه در سند Word با استفاده از سی شارپ#

سند Word پس از ادغام ایمیل#

انجام Mail Merge با استفاده از منبع داده XML در سی شارپ#

قالب بندی سفارشی فیلدهای ادغام#

ادغام ایمیل با مناطق با استفاده از سی شارپ#

مناطق ادغام ایمیل تودرتو#

سند Word پس از ادغام ایمیل#

نتیجه#

Aspose.Words را برای دات نت به صورت رایگان امتحان کنید#

همچنین ببینید#

Mail Merge چیست؟

منابع داده برای ادغام ایمیل

آماده سازی الگو برای ادغام نامه

NET Mail Merge API - نصب

انجام ادغام نامه در سند Word با استفاده از سی شارپ

سند Word پس از ادغام ایمیل

انجام Mail Merge با استفاده از منبع داده XML در سی شارپ

قالب بندی سفارشی فیلدهای ادغام

ادغام ایمیل با مناطق با استفاده از سی شارپ

مناطق ادغام ایمیل تودرتو

سند Word پس از ادغام ایمیل

نتیجه

Aspose.Words را برای دات نت به صورت رایگان امتحان کنید

همچنین ببینید