Pada artikel ini, saya akan menunjukkan kepada Anda bagaimana melakukan MS Word Mail Merge menggunakan C# atau VB.NET tanpa MS Word atau Office Interop. Aspose.Words for .NET adalah Word API yang kaya fitur dan kuat yang menyediakan semua fitur MS Word Mail Merge dasar dan tambahan. Ini memungkinkan Anda membuat surat, amplop, laporan, faktur, dan jenis dokumen lainnya dalam Windows Forms, aplikasi web ASP.NET, atau aplikasi .NET/.NET Core apa pun.

Meliputi fitur menonjol dari .NET Mail Merge API kami, artikel ini terdiri dari bagian berikut:

Apa itu Gabungan Surat?

Mail Merge adalah cara membuat laporan, surat, amplop, faktur, dan jenis dokumen lainnya secara otomatis. Gabungan Surat di MS Word memungkinkan Anda membuat dokumen templat yang berisi bidang gabungan dan kemudian mengisi bidang tersebut menggunakan catatan di sumber data. Untuk memahami Penggabungan Surat, misalkan Anda harus mengirim surat ke sepuluh orang yang berbeda dan hanya bidang nama dan alamat yang akan diperbarui. Dalam kasus seperti itu, cukup buat templat surat lalu buat surat secara dinamis dengan mengisi kolom gabungan nama dan alamat menggunakan sumber data.

Sumber Data untuk Gabungan Surat

Data untuk Mail Merge dapat diambil dari sumber data apa pun seperti XML, JSON, atau database. Sejauh menyangkut Aspose.Words for .NET, Anda dapat menggunakan sumber data apa pun yang didukung oleh ADO.NET. Data dapat dimuat ke dalam DataSet, DataTable, DataView, atau array nilai.

Mempersiapkan Templat untuk Gabungan Surat

Templat Gabungan Surat adalah dokumen yang berisi bidang gabungan. Bidang ini kemudian diisi dengan data di sumber data saat Penggabungan Surat dijalankan. Dokumen template tidak perlu berupa format template dan dapat berupa dokumen DOC/DOCX. Ini adalah bagaimana Anda dapat menyiapkan template untuk Mail Merge.

  • Buka dokumen Anda atau buat yang baru di MS Word.
  • Tempatkan kursor di tempat Anda ingin menambahkan bidang gabungan.
  • Dari menu Sisipkan pilih opsi Bidang.
  • Dari daftar Nama bidang, pilih MergeField.
  • Masukkan nama untuk bidang gabungan di Nama bidang dan tekan OK.
  • Simpan dokumen.

Berikut adalah screenshot dari dokumen contoh template.

Templat Gabungan Surat

.NET Mail Merge API - Instalasi

Aspose.Words for .NET dapat diunduh atau diinstal menggunakan cara berikut:

Lakukan Mail Merge di Dokumen Word menggunakan C#

Setelah Anda menyiapkan template, Anda dapat menjalankan Mail Merge untuk menghasilkan dokumen. Berikut ini adalah langkah-langkah untuk mengeksekusi Mail Merge pada template yang disebutkan di atas.

Contoh kode berikut menunjukkan cara menjalankan MS Word Mail Merge menggunakan array nilai di C#.

// Untuk contoh lengkap dan file data, silakan buka https://github.com/aspose-words/Aspose.Words-for-.NET
// Path ke direktori dokumen.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 
// Buka dokumen yang ada.
Document doc = new Document(dataDir + "MailMerge.ExecuteArray.doc");

// Pangkas nilai gabungan surat spasi putih akhir dan awal
doc.MailMerge.TrimWhitespaces = false;

// Isi kolom dalam dokumen dengan data pengguna.
doc.MailMerge.Execute(
    new string[] { "FullName", "Company", "Address", "Address2", "City" },
    new object[] { "James Bond", "MI5 Headquarters", "Milbank", "", "London" });

dataDir = dataDir + "MailMerge.ExecuteArray_out.doc";
// Kirim dokumen dalam format Word ke browser klien dengan opsi untuk menyimpan ke disk atau membuka di dalam browser saat ini.
doc.Save(dataDir);

Dokumen Word setelah Mail Merge

Jalankan Mail Merge di C#

Lakukan Penggabungan Surat menggunakan Sumber Data XML di C#

File XML banyak digunakan untuk menyimpan serta mengimpor/mengekspor data. Aspose.Words for .NET juga mendukung XML sebagai sumber data untuk Mail Merge. Cukup baca XML ke objek DataSet dan jalankan Mail Merge. Berikut ini adalah contoh file XML yang akan kita gunakan.

<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>

Contoh kode berikut mengambil data dari sumber data XML dan mengeksekusi Mail Merge menggunakan C#.

// Untuk contoh lengkap dan file data, silakan buka https://github.com/aspose-words/Aspose.Words-for-.NET
// Path ke direktori dokumen.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 

// Buat Dataset dan baca XML.
DataSet customersDs = new DataSet();
customersDs.ReadXml(dataDir + "Customers.xml");

string fileName = "TestFile XML.doc";
// Buka dokumen templat.
Document doc = new Document(dataDir + fileName);

// Jalankan penggabungan surat untuk mengisi template dengan data dari XML menggunakan DataTable.
doc.MailMerge.Execute(customersDs.Tables["Customer"]);

dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);
// Simpan dokumen keluaran.
doc.Save(dataDir);

Di bawah ini adalah Mail Merge template yang akan diisi dengan data XML.

Templat Gabungan Surat untuk XML

Berikut ini adalah halaman 1 dari resultan dokumen Word yang kita dapatkan setelah mengeksekusi Mail Merge.

Jalankan Penggabungan Surat dengan XML di C#

Pemformatan Kustom Bidang Gabungan

Aspose.Words for .NET memberi Anda lebih banyak kontrol atas Penggabungan Surat selama eksekusi. Properti MailMerge.FieldMergingCallback memungkinkan Anda menyesuaikan Penggabungan Surat saat ada bidang gabungan yang ditemukan. MailMerge.FieldMergingCallback menerima kelas yang menerapkan metode IFieldMergingCallback.FieldMerging dan IFieldMergingCallback.ImageFieldMerging.

Contoh kode berikut menunjukkan cara mengkustomisasi operasi Mail Merge dan menerapkan pemformatan ke sel di dalam template ini.

// Untuk contoh lengkap dan file data, silakan buka https://github.com/aspose-words/Aspose.Words-for-.NET
// Path ke direktori dokumen.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 
Document doc = new Document(dataDir + "MailMerge.AlternatingRows.doc");

// Tambahkan handler untuk acara MergeField.
doc.MailMerge.FieldMergingCallback = new HandleMergeFieldAlternatingRows();

// Jalankan gabungan surat dengan wilayah.
DataTable dataTable = GetSuppliersDataTable();
doc.MailMerge.ExecuteWithRegions(dataTable);
dataDir = dataDir + "MailMerge.AlternatingRows_out.doc";
doc.Save(dataDir);

Berikut adalah implementasi kelas HandleMergeFieldAlternatingRows.

// Untuk contoh lengkap dan file data, silakan buka https://github.com/aspose-words/Aspose.Words-for-.NET
private class HandleMergeFieldAlternatingRows : IFieldMergingCallback
{
    ///<summary>
    /// Dipanggil untuk setiap bidang gabungan yang ditemui dalam dokumen.
    /// Kami dapat mengembalikan beberapa data ke mesin gabungan surat atau melakukan sesuatu
    /// Lain dengan dokumen. Dalam hal ini kami memodifikasi pemformatan sel.
    ///</summary>
    void IFieldMergingCallback.FieldMerging(FieldMergingArgs e)
    {
        if (mBuilder == null)
            mBuilder = new DocumentBuilder(e.Document);

        // Dengan cara ini kami menangkap awal dari baris baru.
        if (e.FieldName.Equals("CompanyName"))
        {
            // Pilih warna tergantung pada apakah nomor barisnya genap atau ganjil.
            Color rowColor;
            if (IsOdd(mRowIdx))
                rowColor = Color.FromArgb(213, 227, 235);
            else
                rowColor = Color.FromArgb(242, 242, 242);

            // Tidak ada cara untuk menyetel properti sel untuk seluruh baris saat ini,
            // Jadi kita harus mengulangi semua sel di baris.
           for (int colIdx = 0; colIdx < 4; colIdx++)
            {
                mBuilder.MoveToCell(0, mRowIdx, colIdx, 0);
                mBuilder.CellFormat.Shading.BackgroundPatternColor = rowColor;
            }

            mRowIdx++;
        }
    }

    void IFieldMergingCallback.ImageFieldMerging(ImageFieldMergingArgs args)
    {
        // Tidak melakukan apapun.
    }

    private DocumentBuilder mBuilder;
    private int mRowIdx;
}     
///<summary>
/// Mengembalikan true jika nilainya ganjil; salah jika nilainya genap.
///</summary>
private static bool IsOdd(int value)
{
    // Kodenya agak rumit, tetapi sebaliknya konversi otomatis ke VB tidak berfungsi.
    return ((value / 2) * 2).Equals(value);
}      
///<summary>
/// Buat DataTable dan isi dengan data.
/// Dalam kehidupan nyata DataTable ini harus diisi dari database.
///</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;
}

Mail Merge dengan Wilayah menggunakan C#

Mungkin ada kasus ketika Anda perlu mengisi dan mengulangi wilayah tertentu dalam dokumen Word. Untuk kasus seperti itu, Anda dapat menggunakan Gabungan Surat dengan wilayah. Untuk membuat wilayah, Anda perlu menentukan awal dan akhir wilayah, lalu Mail Megre akan mengulangi wilayah tersebut untuk setiap rekaman di sumber data. Misalnya, Templat berikut berisi dua wilayah, Pesanan dan DetailPesanan dengan kolom gabungan «TableStart:Orders», «TableEnd:Orders» dan «TableStart:OrderDetails», «TableEnd:OrderDetails».

Mail Merge dengan Wilayah

Berikut ini adalah contoh kode yang menjalankan Mail Megre pada region untuk template yang disebutkan di atas.

// Untuk contoh lengkap dan file data, silakan buka https://github.com/aspose-words/Aspose.Words-for-.NET
// Path ke direktori dokumen.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting();
string fileName = "MailMerge.ExecuteWithRegions.doc";
Document doc = new Document(dataDir + fileName);
 
// Gunakan DataTable sebagai sumber data.
int orderId = 10444;
DataTable orderTable = GetTestOrder(orderId);
doc.MailMerge.ExecuteWithRegions(orderTable);
 
// Alih-alih menggunakan DataTable, Anda dapat membuat DataView untuk pengurutan atau filter kustom, lalu gabungan surat.
DataView orderDetailsView = new DataView(GetTestOrderDetails(orderId));
orderDetailsView.Sort = "ExtendedPrice DESC";
 
// Jalankan operasi gabungan surat.
doc.MailMerge.ExecuteWithRegions(orderDetailsView);
 
// Simpan dokumen gabungan.
dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);
doc.Save(dataDir);

Berikut ini adalah metode untuk membaca data dari database.

// Untuk contoh lengkap dan file data, silakan buka 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>
/// Fungsi utilitas yang membuat koneksi, perintah, 
/// Jalankan perintah dan kembalikan hasilnya dalam DataTable.
///</summary>
private static DataTable ExecuteDataTable(string commandText)
{
    // Buka koneksi database.
    string connString = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=" +
        RunExamples.GetDataDir_Database() + "Northwind.mdb";
    OleDbConnection conn = new OleDbConnection(connString);
    conn.Open();

    // Membuat dan menjalankan perintah.
    OleDbCommand cmd = new OleDbCommand(commandText, conn);
    OleDbDataAdapter da = new OleDbDataAdapter(cmd);
    DataTable table = new DataTable();
    da.Fill(table);

    // Tutup basis data.
    conn.Close();

    return table;
}

Wilayah Gabungan Surat Bersarang

Paling sering, data yang kita miliki di sumber data datang dalam bentuk hubungan. Misalnya, tabel “Pesanan” akan memiliki hubungan satu-ke-banyak dengan “DetailPesanan” yang akan menyimpan catatan item dalam pesanan. Untuk menangani hubungan induk-anak seperti itu, Mail Merge bersarang digunakan. Berikut adalah contoh templat faktur yang sesuai dengan skenario ini.

Templat Gabungan Surat dengan Wilayah

Berikut ini adalah contoh sumber data XML yang akan kita gunakan untuk Gabungan Surat bersarang.

<?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>

Sedangkan OrderSchema.xsd untuk XML ini adalah:

<?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>

Contoh kode berikut digunakan untuk mengeksekusi gabungan Surat bersarang menggunakan C#.

// Untuk contoh lengkap dan file data, silakan buka https://github.com/aspose-words/Aspose.Words-for-.NET
// Path ke direktori dokumen.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 
	 
// Buat Dataset dan baca XML.
DataSet pizzaDs = new DataSet();
	 
// Datatable.TableNames dan DataSet.Relations didefinisikan secara implisit oleh .NET melalui ReadXml.
pizzaDs.ReadXml(dataDir + "CustomerData.xml");
string fileName = "Invoice Template.doc";

// Buka dokumen templat.
Document doc = new Document(dataDir + fileName);
	 
// Pangkas nilai gabungan surat spasi putih akhir dan awal.
doc.MailMerge.TrimWhitespaces = false;
	 
// Jalankan gabungan surat bersarang dengan wilayah.
doc.MailMerge.ExecuteWithRegions(pizzaDs);
dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);

// Simpan hasilnya ke file.
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);

Dokumen Word setelah Mail Merge

Di bawah ini adalah halaman pertama dari dokumen Word yang dihasilkan setelah menjalankan Mail Merge.

Dokumen Word setelah Mail Merge

Kesimpulan

Aspose.Words for .NET adalah Mail Merge API kaya fitur yang menyediakan semua fitur Mail Merge standar dan tambahan untuk aplikasi .NET. Dalam beberapa baris kode, Anda dapat membuat laporan sederhana atau kompleks dari berbagai jenis sumber data dengan lancar. Anda dapat membaca lebih lanjut tentang .NET Mail Merge API dari dokumentasi. Untuk mempelajari tentang Aspose.Words for .NET, mulailah dengan panduan pengembang, dan contoh kode GitHub.

Coba Aspose.Words for .NET Gratis

Anda bisa mendapatkan lisensi sementara gratis untuk mencoba Aspose.Words for .NET tanpa batasan apa pun. Dapatkan lisensi sementara Anda sekarang.

Lihat juga