C# veya VB.NET kullanarak Word Belgelerinde Adres Mektup Birleştirme - .NET Adres Mektup Birleştirme API'si

Bu yazıda, MS Word veya Office Interop olmadan C# veya VB.NET kullanarak MS Word Adres Mektup Birleştirmeyi nasıl yapacağınızı göstereceğim. Aspose.Words for .NET, tüm temel ve genişletilmiş MS Word Adres Mektup Birleştirme özelliklerini sağlayan, zengin özelliklere sahip ve güçlü bir Word API’sidir. Windows Forms, ASP.NET web uygulamaları veya herhangi bir .NET/.NET Core uygulamasında mektuplar, zarflar, raporlar, faturalar ve diğer belge türlerini oluşturmanıza olanak tanır.

.NET Adres Mektup Birleştirme API’mizin öne çıkan özelliklerini kapsayan bu makale aşağıdaki bölümlerden oluşmaktadır:

• Adres Mektup Birleştirme nedir?
• Adres Mektup Birleştirme için Veri Kaynakları
• Adres Mektup Birleştirme için Şablon Hazırlama
• .NET Adres Mektup Birleştirme API’si - Kurulum
• C# kullanarak Word Belgesinde Adres Mektup Birleştirme gerçekleştirin
• XML Veri Kaynağını Kullanarak Adres Mektup Birleştirme
• Birleştirme Alanlarının Özel Biçimlendirilmesi
• Bölgelerle Adres Mektup Birleştirme
• İç İçe Adres Mektup Birleştirme Bölgeleri

Adres Mektup Birleştirme nedir?

Posta Birleştirme raporların, mektupların, zarfların, faturaların ve diğer belge türlerinin otomatik olarak oluşturulmasının yoludur. MS Word’deki Adres Mektup Birleştirme, birleştirme alanlarını içeren bir şablon belge oluşturmanıza ve ardından veri kaynağındaki kayıtları kullanarak bu alanları doldurmanıza olanak tanır. Adres Mektup Birleştirme’yi anlamak için, on farklı kişiye bir mektup göndermeniz gerektiğini ve yalnızca isim ve adres alanlarının güncellenmesi gerektiğini varsayalım. Böyle bir durumda, basitçe bir mektup şablonu oluşturun ve ardından veri kaynağını kullanarak ad ve adres birleştirme alanlarını doldurarak harfleri dinamik olarak oluşturun.

Adres Mektup Birleştirme için Veri Kaynakları

Adres Mektup Birleştirme için veriler, XML, JSON veya bir veritabanı gibi herhangi bir veri kaynağından alınabilir. Aspose.Words for .NET söz konusu olduğunda, ADO.NET tarafından desteklenen herhangi bir veri kaynağını kullanabilirsiniz. Veriler bir DataSet, DataTable, DataView veya bir değerler dizisine yüklenebilir.

Adres Mektup Birleştirme için Şablon Hazırlama

Adres Mektup Birleştirme şablonu, birleştirme alanlarını içeren belgedir. Bu alanlar daha sonra Adres Mektup Birleştirme yürütüldüğünde veri kaynağındaki verilerle doldurulur. Şablon belgesinin bir şablon formatı olması gerekmez ve bir DOC/DOCX belgesi olabilir. Adres Mektup Birleştirme için bu şekilde şablon hazırlayabilirsiniz.

• Belgenizi açın veya MS Word’de yeni bir tane oluşturun.
• İmleci birleştirme alanı eklemek istediğiniz yere getirin.
• Ekle menüsünden Alan seçeneğini seçin.
• Alan adları listesinden MergeField’ı seçin.
• Alan adı alanına birleştirme alanı için bir ad girin ve Tamam’a basın.
• Belgeyi kaydedin.

Aşağıda, örnek şablon belgesinin ekran görüntüsü verilmiştir.

.NET Adres Mektup Birleştirme API’si - Kurulum

Aspose.Words for .NET aşağıdaki yollar kullanılarak indirilebilir veya kurulabilir:

• DLL’yi indir
• NuGet Paket Yöneticisi aracılığıyla yükleyin

C# kullanarak Word Belgesinde Adres Mektup Birleştirme gerçekleştirin

Şablonu hazır hale getirdikten sonra, belgeleri oluşturmak için Adres Mektup Birleştirmeyi yürütebilirsiniz. Aşağıda, yukarıda belirtilen şablonda Adres Mektup Birleştirmeyi yürütme adımları verilmiştir.

• Document sınıfını kullanarak şablon belgesini yükleyin.
• Document.MailMerge.TrimWhitespaces gibi gerekli Adres Mektup Birleştirme seçeneklerini ayarlayın.
• Document.MailMerge.Execute() yöntemini kullanarak bir Adres Mektup Birleştirme yürütün ve parametre olarak veri kaynağını iletin.
• Oluşturulan belgeyi Document.Save(String) yöntemini kullanarak kaydedin.

Aşağıdaki kod örneği, MS Word Adres Mektup Birleştirme’nin C# dilinde bir dizi değer kullanılarak nasıl yürütüleceğini gösterir.

// Eksiksiz örnekler ve veri dosyaları için lütfen https://github.com/aspose-words/Aspose.Words-for-.NET adresine gidin.
// Belgeler dizininin yolu.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 
// Mevcut bir belgeyi açın.
Document doc = new Document(dataDir + "MailMerge.ExecuteArray.doc");

// Sondaki ve baştaki boşlukları kırp, adres mektup birleştirme değerleri
doc.MailMerge.TrimWhitespaces = false;

// Belgedeki alanları kullanıcı verileriyle doldurun.
doc.MailMerge.Execute(
    new string[] { "FullName", "Company", "Address", "Address2", "City" },
    new object[] { "James Bond", "MI5 Headquarters", "Milbank", "", "London" });

dataDir = dataDir + "MailMerge.ExecuteArray_out.doc";
// Belgeyi Word formatında, diske kaydetme veya mevcut tarayıcıda açma seçeneğiyle istemci tarayıcıya gönderin.
doc.Save(dataDir);

Adres Mektup Birleştirmeden Sonra Word Belgesi

C#’ta XML Veri Kaynağını Kullanarak Adres Mektup Birleştirme Gerçekleştirin

XML dosyaları, verileri içe/dışa aktarmanın yanı sıra tutmak için yaygın olarak kullanılır. Aspose.Words for .NET ayrıca Adres Mektup Birleştirme için bir veri kaynağı olarak XML’i destekler. XML’i bir DataSet nesnesine okuyun ve Adres Mektup Birleştirmeyi yürütün. Kullanacağımız örnek XML dosyası aşağıdadır.

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

Aşağıdaki kod örneği, verileri bir XML veri kaynağından alır ve Adres Mektup Birleştirmeyi C# kullanarak yürütür.

// Eksiksiz örnekler ve veri dosyaları için lütfen https://github.com/aspose-words/Aspose.Words-for-.NET adresine gidin.
// Belgeler dizininin yolu.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 

// Veri Kümesini oluşturun ve XML'i okuyun.
DataSet customersDs = new DataSet();
customersDs.ReadXml(dataDir + "Customers.xml");

string fileName = "TestFile XML.doc";
// Bir şablon belgesi açın.
Document doc = new Document(dataDir + fileName);

// DataTable'ı kullanarak şablonu XML'den alınan verilerle doldurmak için adres mektup birleştirmeyi yürütün.
doc.MailMerge.Execute(customersDs.Tables["Customer"]);

dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);
// Çıkış belgesini kaydedin.
doc.Save(dataDir);

Aşağıda, XML verileriyle doldurulacak Adres Mektup Birleştirme şablon yer almaktadır.

Adres Mektup Birleştirme işlemini gerçekleştirdikten sonra elde ettiğimiz Word belgesinin 1. sayfası aşağıdadır.

Birleştirme Alanlarının Özel Biçimlendirilmesi

Aspose.Words for .NET, yürütme sırasında Adres Mektup Birleştirme üzerinde size daha fazla kontrol sağlar. MailMerge.FieldMergingCallback özelliği, herhangi bir birleştirme alanıyla karşılaşıldığında Adres Mektup Birleştirmeyi özelleştirmenize olanak tanır. MailMerge.FieldMergingCallback, IFieldMergingCallback.FieldMerging ve IFieldMergingCallback.ImageFieldMerging yöntemlerini uygulayan sınıfı kabul eder.

Aşağıdaki kod örneği, Adres Mektup Birleştirme işleminin nasıl özelleştirileceğini ve bu şablonda hücrelere biçimlendirmenin nasıl uygulanacağını gösterir.

// Eksiksiz örnekler ve veri dosyaları için lütfen https://github.com/aspose-words/Aspose.Words-for-.NET adresine gidin.
// Belgeler dizininin yolu.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 
Document doc = new Document(dataDir + "MailMerge.AlternatingRows.doc");

// MergeField olayı için bir işleyici ekleyin.
doc.MailMerge.FieldMergingCallback = new HandleMergeFieldAlternatingRows();

// Bölgelerle adres mektup birleştirmeyi yürütün.
DataTable dataTable = GetSuppliersDataTable();
doc.MailMerge.ExecuteWithRegions(dataTable);
dataDir = dataDir + "MailMerge.AlternatingRows_out.doc";
doc.Save(dataDir);

Aşağıda, HandleMergeFieldAlternatingRows sınıfının uygulaması yer almaktadır.

// Eksiksiz örnekler ve veri dosyaları için lütfen https://github.com/aspose-words/Aspose.Words-for-.NET adresine gidin.
private class HandleMergeFieldAlternatingRows : IFieldMergingCallback
{
    ///<summary>
    /// Belgede karşılaşılan her birleştirme alanı için çağrılır.
    /// Bazı verileri adres mektup birleştirme motoruna geri gönderebilir veya bir şeyler yapabiliriz
    /// Aksi halde belge ile. Bu durumda hücre biçimlendirmesini değiştiririz.
    ///</summary>
    void IFieldMergingCallback.FieldMerging(FieldMergingArgs e)
    {
        if (mBuilder == null)
            mBuilder = new DocumentBuilder(e.Document);

        // Bu şekilde yeni bir satırın başlangıcını yakalamış oluyoruz.
        if (e.FieldName.Equals("CompanyName"))
        {
            // Satır numarasının çift mi tek mi olduğuna bağlı olarak rengi seçin.
            Color rowColor;
            if (IsOdd(mRowIdx))
                rowColor = Color.FromArgb(213, 227, 235);
            else
                rowColor = Color.FromArgb(242, 242, 242);

            // Şu anda tüm satır için hücre özelliklerini ayarlamanın bir yolu yoktur.
            // Bu yüzden satırdaki tüm hücreleri yinelemeliyiz.
           for (int colIdx = 0; colIdx < 4; colIdx++)
            {
                mBuilder.MoveToCell(0, mRowIdx, colIdx, 0);
                mBuilder.CellFormat.Shading.BackgroundPatternColor = rowColor;
            }

            mRowIdx++;
        }
    }

    void IFieldMergingCallback.ImageFieldMerging(ImageFieldMergingArgs args)
    {
        // Hiçbir şey yapma.
    }

    private DocumentBuilder mBuilder;
    private int mRowIdx;
}     
///<summary>
/// Değer tek ise true döndürür; değer çift ise false.
///</summary>
private static bool IsOdd(int value)
{
    // Kod biraz karmaşıktır, ancak bunun dışında otomatik olarak VB'ye dönüştürme çalışmaz.
    return ((value / 2) * 2).Equals(value);
}      
///<summary>
/// DataTable oluşturun ve onu verilerle doldurun.
/// Gerçek hayatta bu DataTable bir veritabanından doldurulmalıdır.
///</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# Kullanarak Bölgelerle Adres Mektup Birleştirme

Word belgesinde belirli bir bölgeyi doldurmanız ve tekrarlamanız gerektiğinde durum olabilir. Böyle bir durumda, Adres Mektup Birleştirmeyi bölgelerle kullanabilirsiniz. Bir bölge oluşturmak için bölgenin başlangıcını ve bitişini belirtmeniz gerekir ve ardından Mail Megre, veri kaynağındaki her kayıt için o bölgeyi tekrar eder. Örneğin, aşağıdaki şablon sırasıyla «TableStart:Orders», «TableEnd:Orders» ve «TableStart:OrderDetails», «TableEnd:OrderDetails» birleştirme alanlarına sahip Siparişler ve OrderDetails olmak üzere iki bölge içerir.

Yukarıda bahsedilen şablon için bölgelerde Mail Megre gerçekleştiren kod örneği aşağıdadır.

// Eksiksiz örnekler ve veri dosyaları için lütfen https://github.com/aspose-words/Aspose.Words-for-.NET adresine gidin.
// Belgeler dizininin yolu.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting();
string fileName = "MailMerge.ExecuteWithRegions.doc";
Document doc = new Document(dataDir + fileName);
 
// DataTable'ı veri kaynağı olarak kullanın.
int orderId = 10444;
DataTable orderTable = GetTestOrder(orderId);
doc.MailMerge.ExecuteWithRegions(orderTable);
 
// DataTable kullanmak yerine, özel sıralama veya filtre için bir DataView oluşturabilir ve adres mektup birleştirme yapabilirsiniz.
DataView orderDetailsView = new DataView(GetTestOrderDetails(orderId));
orderDetailsView.Sort = "ExtendedPrice DESC";
 
// Adres mektup birleştirme işlemini yürütün.
doc.MailMerge.ExecuteWithRegions(orderDetailsView);
 
// Birleştirilmiş belgeyi kaydedin.
dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);
doc.Save(dataDir);

Veritabanından veri okuma yöntemleri aşağıdadır.

// Eksiksiz örnekler ve veri dosyaları için lütfen https://github.com/aspose-words/Aspose.Words-for-.NET adresine gidin.
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>
/// Bir bağlantı oluşturan yardımcı program işlevi, komut, 
/// Komutu yürütür ve sonucu bir DataTable'da döndürür.
///</summary>
private static DataTable ExecuteDataTable(string commandText)
{
    // Veritabanı bağlantısını açın.
    string connString = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=" +
        RunExamples.GetDataDir_Database() + "Northwind.mdb";
    OleDbConnection conn = new OleDbConnection(connString);
    conn.Open();

    // Bir komut oluşturun ve yürütün.
    OleDbCommand cmd = new OleDbCommand(commandText, conn);
    OleDbDataAdapter da = new OleDbDataAdapter(cmd);
    DataTable table = new DataTable();
    da.Fill(table);

    // Veritabanını kapatın.
    conn.Close();

    return table;
}

İç İçe Adres Mektup Birleştirme Bölgeleri

Çoğu zaman, veri kaynağında sahip olduğumuz veriler, ilişkiler biçiminde gelir. Örneğin, “Sipariş” tablosu, bir siparişteki kalemlerin kayıtlarını tutacak “Sipariş Ayrıntıları” ile bire çok ilişkiye sahip olacaktır. Bu tür ebeveyn-çocuk ilişkileriyle başa çıkmak için iç içe Adres Mektup Birleştirme kullanılır. Aşağıda, bu senaryoya çok uygun bir örnek fatura şablonu yer almaktadır.

İç içe Adres Mektup Birleştirme için kullanacağımız örnek XML veri kaynağı aşağıdadır.

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

Oysa bu XML için OrderSchema.xsd şöyledir:

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

Aşağıdaki kod örneği, C# kullanarak iç içe Adres Mektup Birleştirmeyi yürütmek için kullanılır.

// Eksiksiz örnekler ve veri dosyaları için lütfen https://github.com/aspose-words/Aspose.Words-for-.NET adresine gidin.
// Belgeler dizininin yolu.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 
	 
// Veri Kümesini oluşturun ve XML'i okuyun.
DataSet pizzaDs = new DataSet();
	 
// Datatable.TableNames ve DataSet.Relations, ReadXml aracılığıyla .NET tarafından dolaylı olarak tanımlanır.
pizzaDs.ReadXml(dataDir + "CustomerData.xml");
string fileName = "Invoice Template.doc";

// Şablon belgesini açın.
Document doc = new Document(dataDir + fileName);
	 
// Sondaki ve baştaki boşlukları kırpın, adres mektup birleştirme değerleri.
doc.MailMerge.TrimWhitespaces = false;
	 
// Bölgelerle iç içe adres mektup birleştirmeyi yürütün.
doc.MailMerge.ExecuteWithRegions(pizzaDs);
dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);

// Çıktıyı dosyaya kaydedin.
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);

Adres Mektup Birleştirmeden Sonra Word Belgesi

Adres Mektup Birleştirmeyi yürüttükten sonra ortaya çıkan Word belgesinin ilk sayfası aşağıdadır.

Çözüm

Aspose.Words for .NET, .NET uygulamaları için tüm standart ve genişletilmiş Adres Mektup Birleştirme özelliklerini sağlayan, zengin özelliklere sahip bir Adres Mektup Birleştirme API’sidir. Birkaç satırlık bir kodla, çeşitli veri kaynağı türlerinden sorunsuz bir şekilde basit veya karmaşık raporlar oluşturabilirsiniz. .NET Adres Mektup Birleştirme API’si hakkında daha fazla bilgiyi belgelerden edinebilirsiniz. Aspose.Words for .NET hakkında bilgi edinmek için geliştirici kılavuzları ve GitHub kod örnekleriyle başlayın.

Aspose.Words for .NET’i Ücretsiz Deneyin

Aspose.Words for .NET’i herhangi bir sınırlama olmaksızın denemek için ücretsiz bir geçici lisans alabilirsiniz. Geçici lisansınızı şimdi alın.

Ayrıca bakınız

• C# .NET’teki Şablonlardan Word Belgeleri Oluşturun