انواع عملیات Mail Merge

ایده اصلی Mail Merge این است که به طور خودکار یک سند یا چندین سند بر اساس قالب و داده های شما از منبع داده خود ایجاد کنید. Aspose.Words به شما اجازه می دهد تا دو نوع مختلف از عملیات Mail Merge را انجام دهید: ساده Mail Merge و Mail Merge با مناطق.

رایج ترین مثال استفاده از simple Mail Merge زمانی است که می خواهید یک سند برای مشتریان مختلف با اضافه کردن نام آنها در ابتدای سند ارسال کنید. برای انجام این کار، شما باید زمینه های ادغام مانند First Name و Last Name را در قالب خود ایجاد کنید، و سپس آنها را با داده های منبع داده خود پر کنید. در حالی که رایج ترین مثال استفاده از Mail Merge با مناطق زمانی است که شما می خواهید یک سند ارسال کنید که شامل سفارشات خاص با لیست تمام موارد در هر سفارش است. برای انجام این کار، شما باید مناطق ادغام را در داخل منطقه خود برای هر سفارش ایجاد کنید تا آن را با تمام داده های مورد نیاز برای آیتم ها پر کنید.

تفاوت اصلی بین هر دو عملیات ادغام این است که ساده Mail Merge (بدون مناطق) کل سند را در هر رکورد منبع داده تکرار می کند، در حالی که Mail Merge با مناطق فقط مناطق تعیین شده را در هر رکورد تکرار می کند. شما می توانید یک عملیات ساده Mail Merge را به عنوان یک مورد خاص از ادغام با مناطقی که تنها منطقه کل سند است، در نظر بگیرید.

کلاس MailMerge نشان دهنده یک قابلیت Mail Merge است. با خواص آن، شما می توانید رفتار مورد نیاز را قبل از اجرای یک عملیات Mail Merge سفارشی کنید.

عملیات ساده Mail Merge

یک Mail Merge ساده برای پر کردن فیلدهای Mail Merge داخل قالب شما با داده های مورد نیاز از منبع داده شما (نمایش جدول واحد) استفاده می شود. پس شبیه به کلاسیک Mail Merge در Microsoft Word است.

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

محدودیت اصلی استفاده از این نوع این است که کل محتوای سند برای هر رکورد در منبع داده تکرار خواهد شد.

چگونه یک عملیات ساده Mail Merge را اجرا کنیم

وقتی قالب شما آماده شد، می توانید عملیات ساده Mail Merge را شروع کنید. Aspose.Words به شما اجازه می دهد تا یک عملیات ساده Mail Merge را با استفاده از Execute methods مختلف که اشیاء داده های مختلف را به عنوان منبع داده قبول می کند، اجرا کنید.

مثال کد زیر نشان می دهد که چگونه یک عملیات ساده Mail Merge را با استفاده از یکی از روش Execute اجرا کنیم:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
// Include the code for our template.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Create Merge Fields.
builder.InsertField(" MERGEFIELD CustomerName ");
builder.InsertParagraph();
builder.InsertField(" MERGEFIELD Item ");
builder.InsertParagraph();
builder.InsertField(" MERGEFIELD Quantity ");

// Fill the fields in the document with user data.
doc.MailMerge.Execute(new string[] { "CustomerName", "Item", "Quantity" },
    new object[] { "John Doe", "Hawaiian", "2" });

doc.Save(ArtifactsDir + "BaseOperations.SimpleMailMerge.docx");

شما می توانید تفاوت بین سند را قبل از اجرای ساده متوجه شوید mail merge:

و بعد از اجرای ساده mail merge:

چگونه چندین سند ادغام شده ایجاد کنیم

در Aspose.Words، عملیات استاندارد Mail Merge تنها یک سند را با محتوای منبع داده شما پر می کند. بنابراین، شما باید عملیات Mail Merge را چندین بار اجرا کنید تا چندین سند ادغام شده به عنوان خروجی ایجاد کنید.

مثال کد زیر نشان می دهد که چگونه چندین سند ادغام شده را در طول یک عملیات Mail Merge تولید کنیم:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
string connString = @"Provider=Microsoft.ACE.OLEDB.12.0;Data Source=" + DatabaseDir + "Northwind.accdb";

Document doc = new Document(MyDir + "Mail merge destination - Northwind suppliers.docx");

OleDbConnection conn = new OleDbConnection(connString);
conn.Open();
            
OleDbCommand cmd = new OleDbCommand("SELECT * FROM Customers", conn);
OleDbDataAdapter da = new OleDbDataAdapter(cmd);
            
DataTable data = new DataTable();
da.Fill(data);

// Perform a loop through each DataRow to iterate through the DataTable. Clone the template document
// instead of loading it from disk for better speed performance before the mail merge operation.
// You can load the template document from a file or stream but it is faster to load the document
// only once and then clone it in memory before each mail merge operation.
            
int counter = 1;
foreach (DataRow row in data.Rows)
{
    Document dstDoc = (Document) doc.Clone(true);

    dstDoc.MailMerge.Execute(row);

    dstDoc.Save(string.Format(ArtifactsDir + "BaseOperations.ProduceMultipleDocuments_{0}.docx", counter++));
}

شما می توانید فایل نمونه این مثال را از Aspose.Words GitHub.

Mail Merge با مناطق

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

شما می توانید مناطق آشیانه ای (کودک) و همچنین مناطق ادغام ایجاد کنید. مزیت اصلی استفاده از این نوع افزایش پویا قطعات داخل یک سند است. جزئیات بیشتر را در مقاله بعدی “Nested Mail Merge with Regions"مشاهده کنید.

اطلاعات مربوط به یک منطقه Mail Merge را می توان با استفاده از کلاس MailMergeRegionInfo بدست آورد.

نحوه اجرای Mail Merge با مناطق

منطقه Mail Merge یک بخش خاص در داخل یک سند است که دارای نقطه شروع و نقطه پایان است. هر دو نقطه به عنوان فیلد های Mail Merge که نام های خاص “TableStart:XXX” و “TableEnd:XXX” دارند، نشان داده می شوند. تمام محتوایی که در یک منطقه Mail Merge گنجانده شده است به طور خودکار برای هر رکورد در منبع داده تکرار می شود.

Aspose.Words به شما اجازه می دهد تا Mail Merge را با مناطق با استفاده از Execute methods مختلف که اشیاء داده های مختلف را به عنوان منبع داده قبول می کنند، اجرا کنید.

به عنوان اولین قدم، ما باید DataSet را ایجاد کنیم تا بعدا آن را به عنوان پارامتر ورودی به روش ExecuteWithRegions منتقل کنیم:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
private DataSet CreateDataSet()
{
    // Create the customers table.
    DataTable tableCustomers = new DataTable("Customers");
    tableCustomers.Columns.Add("CustomerID");
    tableCustomers.Columns.Add("CustomerName");
    tableCustomers.Rows.Add(new object[] { 1, "John Doe" });
    tableCustomers.Rows.Add(new object[] { 2, "Jane Doe" });

    // Create the orders table.
    DataTable tableOrders = new DataTable("Orders");
    tableOrders.Columns.Add("CustomerID");
    tableOrders.Columns.Add("ItemName");
    tableOrders.Columns.Add("Quantity");
    tableOrders.Rows.Add(new object[] { 1, "Hawaiian", 2 });
    tableOrders.Rows.Add(new object[] { 2, "Pepperoni", 1 });
    tableOrders.Rows.Add(new object[] { 2, "Chicago", 1 });

    // Add both tables to a data set.
    DataSet dataSet = new DataSet();
    dataSet.Tables.Add(tableCustomers);
    dataSet.Tables.Add(tableOrders);

    // The "CustomerID" column, also the primary key of the customers table is the foreign key for the Orders table.
    dataSet.Relations.Add(tableCustomers.Columns["CustomerID"], tableOrders.Columns["CustomerID"]);

    return dataSet;
}

مثال کد زیر نشان می دهد که چگونه Mail Merge را با مناطق با استفاده از روش ExecuteWithRegions(DataSet) اجرا کنیم:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// The start point of mail merge with regions the dataset.
builder.InsertField(" MERGEFIELD TableStart:Customers");
            
// Data from rows of the "CustomerName" column of the "Customers" table will go in this MERGEFIELD.
builder.Write("Orders for ");
builder.InsertField(" MERGEFIELD CustomerName");
builder.Write(":");

// Create column headers.
builder.StartTable();
builder.InsertCell();
builder.Write("Item");
builder.InsertCell();
builder.Write("Quantity");
builder.EndRow();

// We have a second data table called "Orders", which has a many-to-one relationship with "Customers"
// picking up rows with the same CustomerID value.
builder.InsertCell();
builder.InsertField(" MERGEFIELD TableStart:Orders");
builder.InsertField(" MERGEFIELD ItemName");
builder.InsertCell();
builder.InsertField(" MERGEFIELD Quantity");
builder.InsertField(" MERGEFIELD TableEnd:Orders");
builder.EndTable();

// The end point of mail merge with regions.
builder.InsertField(" MERGEFIELD TableEnd:Customers");

// Pass our dataset to perform mail merge with regions.
DataSet customersAndOrders = CreateDataSet();
doc.MailMerge.ExecuteWithRegions(customersAndOrders);

doc.Save(ArtifactsDir + "BaseOperations.MailMergeWithRegions.docx");

شما می توانید تفاوت بین سند را قبل از اجرای Mail Merge با مناطق مشاهده کنید:

و پس از اجرای Mail Merge با مناطق:

محدودیت های Mail Merge با مناطق

برخی از نکات مهم وجود دارد که شما باید در هنگام انجام یک Mail Merge با مناطق در نظر بگیرید:

• نقطه شروع TableStart:Orders و نقطه پایان TableEnd:Orders هر دو باید در یک ردیف یا سلول باشند. به عنوان مثال، اگر یک منطقه ادغام را در یک سلول جدول شروع کنید، باید منطقه ادغام را در همان ردیف سلول اول پایان دهید.
• نام فیلد ادغام باید با نام ستون در DataTable شما مطابقت داشته باشد. مگر اینکه شما فیلد های نقشه برداری شده را مشخص کرده باشید، Mail Merge با مناطق برای هر فیلد ادغام که نام متفاوتی از نام ستون دارد، موفق نخواهد بود.

اگر یکی از این قوانین شکسته شود، نتایج غیر منتظره ای خواهید داشت یا ممکن است استثنا ایجاد شود.

اگر از مناطق Mail Merge استفاده نکنید، مشابه Microsoft Word mail merge خواهد بود و کل محتوای سند برای هر رکورد در منبع داده تکرار خواهد شد.