IronWord Kullanan C# ile Doldurulabilir Form Şablonları Oluşturma

Özellik ne yapar

Posta birleştirme motoru, Word'ün ürettiği iki tür birleştirme alanını ele alır:

• Basit alanlar, şablona doğrudan <> yazarak elde ettiğiniz "FieldName" formatında olanlar
• Karmaşık alanlar, Word'ün Ekle → Hızlı Parçalar → Alan üzerinden ürettiği çok elemanlı XML yapısı

Şablonlar, belgede bir kez değiştirilecek tek değer yer tutucularını ve her veriş kaydı için bir satıra genişleyen "TableStart:Name" ve "TableEnd:Name" işaretleyicileri ile sınırlanan tekrarlayan bölgeleri içerebilir.

İkinci parça, özelliğin yerini hak ettiği yerdir. Tekrarlayan bölgeler, bir faturadaki tek bir şablon satırının 50 satırlık bir öğe tablosuna genişlemesi veya bir etiket yaprağındaki tek bir iletişim yuvasının bir veritabanından doldurulmuş tam bir Avery ızgarası haline gelmesi için kullanılır.

Bir CRM'den kişiselleştirilmiş kapak mektupları

Çoğu ekip, ilk olarak satış operasyonları aracılığıyla posta birleştirmeye ulaşır. CRM müşteri kayıtlarını tutar; pazarlama ya da satış operasyonları, kişiselleştirilmiş kapak mektupları, karşılama paketleri veya yenilme bildirimleri göndermelidir. Desen basittir: bir şablon, müşteri başına bir satır, kişiselleştirilmiş bir belge çıkar.

// Template: "Dear «FirstName», thank you for your order of «Amount»..."
DataTable customers = LoadFromSalesforce();   // FirstName, LastName, Amount, ...

foreach (DataRow row in customers.Rows)
{
    var doc = new WordDocument("cover-letter-template.docx");
    doc.MailMerge.Execute(row);
    doc.SaveAs($"letters/{row["LastName"]}.docx");
}

// Template: "Dear «FirstName», thank you for your order of «Amount»..."
DataTable customers = LoadFromSalesforce();   // FirstName, LastName, Amount, ...

foreach (DataRow row in customers.Rows)
{
    var doc = new WordDocument("cover-letter-template.docx");
    doc.MailMerge.Execute(row);
    doc.SaveAs($"letters/{row["LastName"]}.docx");
}

Imports System.Data

' Template: "Dear «FirstName», thank you for your order of «Amount»..."
Dim customers As DataTable = LoadFromSalesforce() ' FirstName, LastName, Amount, ...

For Each row As DataRow In customers.Rows
    Dim doc As New WordDocument("cover-letter-template.docx")
    doc.MailMerge.Execute(row)
    doc.SaveAs($"letters/{row("LastName")}.docx")
Next

Veri kaynağı bir DataTable'dır, bu da içine yüklenebilir (Salesforce, HubSpot, SQL Server, bir CSV, bir API yanıtı) her şeyin bir posta birleştirme kaynağı haline gelmesi anlamına gelir ve ek bir adaptör kodu gerektirmez.

Tekrarlayan satır öğeleriyle faturalar

Faturalandırma, tekrarlayan bölge yeteneğinin gerekliliği kazandığı yerdir. Bir fatura şablonunun bir başlığı (müşteri adı, sipariş ID, tarihler), bir satır öğesi tablosunda bir satırı ve bir altbilgisi (toplamlar) vardır. Birleştirme çalışırken, tek şablon satırı, siparişin bir satır öğesi veya elli satırı olsun, her ürün için bir satıra genişler.

// Template:
//   Bill To: «CustomerName»  Order: «OrderId»
//   ┌──────────┬─────┬──────────┐
//   │ «TableStart:Items»«Product» │ «Qty» │ «LineTotal» «TableEnd:Items» │
//   └──────────┴─────┴──────────┘
//   Total: «Total»

var doc = new WordDocument("invoice-template.docx");

doc.MailMerge.ExecuteWithRegions(orderLineItems);  // one row per product
doc.MailMerge.Execute(new Dictionary<string, string>
{
    { "CustomerName", "Acme Industries" },
    { "OrderId",      "10444" },
    { "Total",        "$1,117.71" },
});

doc.SaveAs("invoice-10444.docx");

// Template:
//   Bill To: «CustomerName»  Order: «OrderId»
//   ┌──────────┬─────┬──────────┐
//   │ «TableStart:Items»«Product» │ «Qty» │ «LineTotal» «TableEnd:Items» │
//   └──────────┴─────┴──────────┘
//   Total: «Total»

var doc = new WordDocument("invoice-template.docx");

doc.MailMerge.ExecuteWithRegions(orderLineItems);  // one row per product
doc.MailMerge.Execute(new Dictionary<string, string>
{
    { "CustomerName", "Acme Industries" },
    { "OrderId",      "10444" },
    { "Total",        "$1,117.71" },
});

doc.SaveAs("invoice-10444.docx");

Imports System.Collections.Generic

' Template:
'   Bill To: «CustomerName»  Order: «OrderId»
'   ┌──────────┬─────┬──────────┐
'   │ «TableStart:Items»«Product» │ «Qty» │ «LineTotal» «TableEnd:Items» │
'   └──────────┴─────┴──────────┘
'   Total: «Total»

Dim doc As New WordDocument("invoice-template.docx")

doc.MailMerge.ExecuteWithRegions(orderLineItems)  ' one row per product
doc.MailMerge.Execute(New Dictionary(Of String, String) From {
    {"CustomerName", "Acme Industries"},
    {"OrderId", "10444"},
    {"Total", "$1,117.71"}
})

doc.SaveAs("invoice-10444.docx")

Aynı desen, teklifler, sipariş emirleri, beyanlar ve değişken uzunluktaki bir listenin sabit şekilli bir sayfanın içinde yer aldığı herhangi bir belge için çalışır.

Avery etiket yaprakları ve zarflar

Sevkiyat ve operasyon ekipleri, kişi listelerinden etiket ve zarflar oluşturur ve düzenler (Avery 5160, 5161, 5163 ve uluslararası eşdeğerleri) on yıllardır var olan standartlaştırılmış şablonlardır. IronWord onları doğrudan doldurur: etiket ızgarasındaki her hücre tek bir API çağrısından uygun kişiyle dolar.

// Template: a 3×10 Avery 5160 grid, each cell has «CONTACT_FULLNAME» / «CONTACT_ADDRESS»
var doc = new WordDocument("avery-5160.docx");

doc.MailMerge.Execute(new Dictionary<string, string>
{
    { "CONTACT_FULLNAME", "Jane Doe" },
    { "CONTACT_ADDRESS",  "100 Main Street, Boston, MA 02108" },
});

doc.SaveAs("labels-jane.docx");

// Template: a 3×10 Avery 5160 grid, each cell has «CONTACT_FULLNAME» / «CONTACT_ADDRESS»
var doc = new WordDocument("avery-5160.docx");

doc.MailMerge.Execute(new Dictionary<string, string>
{
    { "CONTACT_FULLNAME", "Jane Doe" },
    { "CONTACT_ADDRESS",  "100 Main Street, Boston, MA 02108" },
});

doc.SaveAs("labels-jane.docx");

Imports System.Collections.Generic

' Template: a 3×10 Avery 5160 grid, each cell has «CONTACT_FULLNAME» / «CONTACT_ADDRESS»
Dim doc As New WordDocument("avery-5160.docx")

doc.MailMerge.Execute(New Dictionary(Of String, String) From {
    {"CONTACT_FULLNAME", "Jane Doe"},
    {"CONTACT_ADDRESS", "100 Main Street, Boston, MA 02108"}
})

doc.SaveAs("labels-jane.docx")

Değişken uzunluklu kişi listeleri için, fatura örneğinden bir ExecuteWithRegions deseni uygulanır: bir hücreyi tekrar eden birim olarak tanımlayın ve sayfanın geri kalanı otomatik olarak dolar.

Çok bölgeli raporlar

En güçlü uygulama çok bölgeli raporlardır. Üç aylık bir özet, her biri kendi veri tablosu tarafından yönlendirilen "En İyi Müşteriler" ve "En İyi Ürünler" bölümlerini içerebilir. Birden çok tablo içeren bir DataSet ile, birleştirme tek bir çağrıda her iki bölgeyi de genişletir.

// Template:
//   Top Customers
//   «TableStart:Customers» • «Name» | «City» | «Revenue» «TableEnd:Customers»
//   Top Products
//   «TableStart:Products»  «ProductName»: «Revenue»     «TableEnd:Products»

var ds = new DataSet();
ds.Tables.Add(topCustomers);   // TableName = "Customers"
ds.Tables.Add(topProducts);    // TableName = "Products"

var doc = new WordDocument("quarterly-report.docx");
doc.MailMerge.ExecuteWithRegions(ds);          // expands both regions
doc.MailMerge.Execute(new Dictionary<string, string>
{
    { "CompanyName", "Iron Software" },
    { "ReportDate",  "Q2 2026" },
});
doc.SaveAs("Q2-2026-report.docx");

// Template:
//   Top Customers
//   «TableStart:Customers» • «Name» | «City» | «Revenue» «TableEnd:Customers»
//   Top Products
//   «TableStart:Products»  «ProductName»: «Revenue»     «TableEnd:Products»

var ds = new DataSet();
ds.Tables.Add(topCustomers);   // TableName = "Customers"
ds.Tables.Add(topProducts);    // TableName = "Products"

var doc = new WordDocument("quarterly-report.docx");
doc.MailMerge.ExecuteWithRegions(ds);          // expands both regions
doc.MailMerge.Execute(new Dictionary<string, string>
{
    { "CompanyName", "Iron Software" },
    { "ReportDate",  "Q2 2026" },
});
doc.SaveAs("Q2-2026-report.docx");

Imports System.Data
Imports System.Collections.Generic

' Template:
'   Top Customers
'   «TableStart:Customers» • «Name» | «City» | «Revenue» «TableEnd:Customers»
'   Top Products
'   «TableStart:Products»  «ProductName»: «Revenue»     «TableEnd:Products»

Dim ds As New DataSet()
ds.Tables.Add(topCustomers)   ' TableName = "Customers"
ds.Tables.Add(topProducts)    ' TableName = "Products"

Dim doc As New WordDocument("quarterly-report.docx")
doc.MailMerge.ExecuteWithRegions(ds)          ' expands both regions
doc.MailMerge.Execute(New Dictionary(Of String, String) From {
    {"CompanyName", "Iron Software"},
    {"ReportDate", "Q2 2026"}
})
doc.SaveAs("Q2-2026-report.docx")

DataSet içindeki her DataTable, adlarına göre karşılık gelen "TableStart:..." bölgesini eşleştirir ve skaler alanlar aynı geçişte başlık değerlerini doldurur.

Belgelerde temiz bir .NET uygulaması bekleyen bu tür iş akışlarına sahip ekipler için, Iron Suite <IronPdf, IronOCR, IronXL ve IronBarcode ile birlikte IronWord'u tek bir lisans içinde birleştirir.

Ücretsiz deneme başlatın, kredi kartı gerektirmez.

Neden bu işe yarar

Bu yaklaşımı alternatiflerinden ayıran birkaç şey vardır:

Yerli Word sözdizimi. Şablonlar Microsoft Word'de tasarlanır ve Word'ün zaten sunduğu birleştirme alanı araçları kullanılır. .docx olarak kaydedin, dosyayı IronWord'a verin ve birleştirme çalışsın. Özel şablon dili yok, çeviri katmanı yok, belgeleri tasarlayan ekip için ayrı bir öğrenme eğrisi yok.

Hem basit hem karmaşık alan formatları. Word, alanın nasıl eklendiğine bağlı olarak iki farklı alan yapısı üretir. IronWord her ikisini de işler, bu da farklı yollarla tasarlanan mevcut ekip üyeleri tarafından oluşturulan şablonların hepsinin değişiklik yapmadan çalıştığı anlamına gelir.

Dışa bağımlılık yok. Kütüphane tamamen .NET üzerinde çalışır. Word kurulumu yok, COM yok, Ofis lisansı yok, interop kırılganlığı yok. Windows geliştirici makinesinde çalıştırılan aynı kod, bir Linux konteynırında, Azure İşlevinde veya başsız bir yerleşim aracında aynı şekilde çalışır.

Özet

Posta birleştirme, .NET belge araçları alanında uzun süredir bir boşluktu ve geçici çözümler iyi yaşlanmadı. IronWord'un yerli posta birleştirmesi, Word'un kendi birleştirme alanı sözdizimini yansıtan, hem basit değerleri hem tekrarlayan bölgeleri destekleyen ve tarihsel olarak .NET'deki belge otomasyonuyla birlikte gelen derleme yükü olmadan çalışan bir modelle bu boşluğu kapatıyor.

Faturaları, etiketleri, mektupları, sözleşmeleri ve raporları ölçekli olarak üreten ekipler için, bu, tek bir şablondan binlerce kişiselleştirilmiş belgeye en temiz yol.