Jenis Operasi Mail Merge

Gagasan utama Mail Merge adalah membuat dokumen atau beberapa dokumen secara otomatis berdasarkan templat Anda dan data yang diambil dari sumber data Anda. Aspose.Words memungkinkan Anda melakukan dua jenis operasi Mail Merge yang berbeda: Mail Merge sederhana dan Mail Merge dengan wilayah.

Contoh paling umum menggunakan Mail Merge sederhana adalah saat Anda ingin mengirim dokumen untuk klien yang berbeda dengan mencantumkan nama mereka di awal dokumen. Untuk melakukannya, Anda perlu membuat bidang gabungan seperti First Name dan Last Name di templat Anda, lalu mengisinya dengan data dari sumber data Anda. Sedangkan contoh paling umum menggunakan Mail Merge dengan wilayah adalah saat Anda ingin mengirim dokumen yang menyertakan pesanan tertentu dengan daftar semua item dalam setiap pesanan. Untuk melakukan ini, Anda perlu membuat wilayah gabungan di dalam wilayah templat Anda sendiri untuk setiap pesanan, untuk mengisinya dengan semua data yang diperlukan untuk item tersebut.

Perbedaan utama antara kedua operasi penggabungan adalah bahwa Mail Merge sederhana (tanpa wilayah) mengulangi seluruh dokumen per setiap catatan sumber data, sedangkan Mail Merge dengan wilayah hanya mengulangi wilayah yang ditentukan per catatan. Anda dapat menganggap operasi Mail Merge sederhana sebagai kasus penggabungan tertentu dengan wilayah di mana satu-satunya wilayah adalah keseluruhan dokumen.

Kelas MailMerge mewakili fungsionalitas Mail Merge. Dengan propertinya, Anda dapat menyesuaikan perilaku yang diperlukan sebelum menjalankan operasi Mail Merge.

Operasi Mail Merge Sederhana

Mail Merge sederhana digunakan untuk mengisi kolom Mail Merge di dalam templat Anda dengan data yang diperlukan dari sumber data Anda (representasi tabel tunggal). Jadi ini mirip dengan Mail Merge klasik di Microsoft Word.

Anda dapat menambahkan satu atau lebih bidang gabungan di templat Anda, lalu menjalankan operasi Mail Merge sederhana. Disarankan untuk menggunakannya jika templat Anda tidak berisi wilayah gabungan apa pun.

Batasan utama penggunaan tipe ini adalah seluruh konten dokumen akan diulang untuk setiap catatan di sumber data.

Cara Menjalankan Operasi Mail Merge Sederhana

Setelah templat Anda siap, Anda dapat mulai melakukan operasi Mail Merge sederhana. Aspose.Words memungkinkan Anda menjalankan operasi Mail Merge sederhana menggunakan Execute methods berbeda yang menerima berbagai objek data sebagai sumber data.

Contoh kode berikut menunjukkan cara menjalankan operasi Mail Merge sederhana menggunakan salah satu metode 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");

Anda dapat melihat perbedaan antara dokumen sebelum menjalankan mail mergesederhana:

Dan setelah mengeksekusi mail mergesederhana:

Cara Membuat Beberapa Dokumen Gabungan

Dalam Aspose.Words, operasi Mail Merge standar hanya mengisi satu dokumen dengan konten dari sumber data Anda. Jadi, Anda perlu menjalankan operasi Mail Merge beberapa kali untuk membuat beberapa dokumen gabungan sebagai keluaran.

Contoh kode berikut menunjukkan cara membuat beberapa dokumen gabungan selama operasi 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++));
}

Anda dapat mengunduh file contoh contoh ini dari Aspose.Words GitHub.

Mail Merge dengan Wilayah

Anda dapat membuat wilayah berbeda di templat Anda untuk memiliki area khusus yang dapat Anda isi dengan data Anda. Gunakan Mail Merge dengan wilayah jika Anda ingin menyisipkan tabel, baris dengan data berulang untuk membuat dokumen Anda berkembang secara dinamis dengan menentukan wilayah tersebut di dalam templat Anda.

Anda dapat membuat wilayah bersarang (turunan) serta menggabungkan wilayah. Keuntungan utama menggunakan tipe ini adalah menambah bagian di dalam dokumen secara dinamis. Lihat detail selengkapnya di artikel berikutnya “Bersarang Mail Merge dengan Wilayah”.

Informasi tentang wilayah Mail Merge dapat diperoleh dengan menggunakan kelas MailMergeRegionInfo.

Cara Mengeksekusi Mail Merge dengan Region

Wilayah Mail Merge adalah bagian tertentu di dalam dokumen yang memiliki titik awal dan titik akhir. Kedua titik direpresentasikan sebagai bidang Mail Merge yang memiliki nama spesifik “TableStart:XXX” dan “TableEnd:XXX”. Semua konten yang disertakan dalam wilayah Mail Merge akan diulang secara otomatis untuk setiap rekaman di sumber data.

Aspose.Words memungkinkan Anda menjalankan Mail Merge dengan wilayah menggunakan Execute methods berbeda yang menerima berbagai objek data sebagai sumber data.

Sebagai langkah pertama, kita perlu membuat DataSet untuk diteruskan nanti sebagai parameter input ke metode 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;
}

Contoh kode berikut menunjukkan cara menjalankan Mail Merge dengan wilayah menggunakan metode 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");

Anda dapat melihat perbedaan antara dokumen sebelum mengeksekusi Mail Merge dengan wilayah:

Dan setelah mengeksekusi Mail Merge dengan wilayah:

Batasan Mail Merge dengan Wilayah

Ada beberapa poin penting yang perlu Anda pertimbangkan saat melakukan Mail Merge dengan wilayah:

• Titik awal TableStart:Orders dan titik akhir TableEnd:Orders keduanya harus berada di baris atau sel yang sama. Misalnya, jika Anda memulai wilayah penggabungan di sel tabel, Anda harus mengakhiri wilayah penggabungan di baris yang sama dengan sel pertama.
• Nama bidang gabungan harus cocok dengan nama kolom di DataTable Anda. Kecuali Anda telah menentukan bidang yang dipetakan, Mail Merge dengan wilayah tidak akan berhasil untuk bidang gabungan apa pun yang memiliki nama berbeda dari nama kolom.

Jika salah satu dari aturan ini dilanggar, Anda akan mendapatkan hasil yang tidak terduga atau pengecualian dapat dilemparkan.

Jika Anda tidak menggunakan wilayah Mail Merge, maka akan serupa dengan Microsoft Word mail merge, dan seluruh konten dokumen akan diulang untuk setiap catatan di sumber data.