How to Mail Merge Word Documents in C#
IronWord, verilerinizi sözlükler, DataSet nesnelerinden veya tekrarlanan-bölge tablolarından alarak, Word şablonundaki MERGEFIELD yer tutucularını doldurarak C#'ta birleştirme işlemi yapar, tümü Microsoft Office Interop kullanmadan. Microsoft Word veya herhangi bir uyumlu araçla oluşturulan birleşim alanları otomatik olarak algılanır.
E-posta birleştirme, ölçekte kişiselleştirilmiş belgeler oluşturmanın standart yoludur: bir şablon paylaşan, ancak alıcıya göre farklılık gösteren form mektupları, faturalar, sertifikalar, sözleşmeler ve raporlar. Her belgeyi elle düzenlemek yerine, birleşim alanları içeren tek bir .docx şablonu oluşturur ve IronWord'un bunları veri kaynağınızdan doldurmasına izin verirsiniz. Her işleme WordDocument.MailMerge giriş noktası aracılığıyla erişilir.
MERGEFIELD yer tutucuları içeren bir şablon yükleyin, Execute'a alan adları ve değerlerinden oluşan bir sözlük aktarın ve sonucu kaydedin.
-
1Install IronWord with NuGet Package Manager
-
2Bu kod parçacığını kopyalayın ve çalıştırın.
WordDocument doc = new WordDocument("template.docx"); doc.MailMerge.Execute(new Dictionary<string, string> { { "FirstName", "Jane" }, { "Company", "Acme Corp" } }); doc.SaveAs("output.docx");C# -
3Canlı ortamınızda test için dağıtım yapın
Ücretsiz deneme ile bugün projenizde IronWord kullanmaya başlayın
Asgari İş Akışı (5 adım)
- C# e-posta birleştirme için NuGet'ten kütüphaneyi indirin
MERGEFIELDyer tutucularını içeren bir Word şablonu oluşturunWordDocumentyapıcı fonksiyonunu kullanarak şablonu yükleyin- Veri kaynağınız ile
MailMerge.ExecuteveyaMailMerge.ExecuteWithRegionsçağırın - Doldurulmuş belgeyi kaydedin
Bir Sözlükten E-posta Birleştirmesini Nasıl Yaparım?
En basit veri kaynağı birleşim alanı adlarına göre anahtarlanmış bir IDictionary<string, string>'dır. Execute adı bir anahtarla eşleşen her alanı değiştirir.
WordDocument doc = new WordDocument("template.docx");
doc.MailMerge.Execute(new Dictionary<string, string>
{
{ "FirstName", "Jane" },
{ "LastName", "Smith" },
{ "Company", "Acme Corp" }
});
doc.SaveAs("output.docx");MailMerge.Options.CaseInsensitiveFieldNames = false ayarlarını yapın.Ayrıca, alan adları ve değerlerinden oluşan iki paralel dizi sağlayabilirsiniz:
doc.MailMerge.Execute(
new[] { "FirstName", "LastName" },
new[] { "Jane", "Smith" });Execute(fieldNames, values), iki dizi farklı uzunluklardaysa bir ArgumentException atar.
Bir DataTable veya DataRow'dan E-posta Birleştirmesini Nasıl Yaparım?
Veriler bir veritabanından veya mevcut bir DataSet'den geldiğinde, bir DataTable veya DataRow doğrudan Execute'a aktarın. Birleştirme alanı adları sütun adları ile eşleştirilir. Execute(DataTable), tablonun ilk satırındaki değerleri kullanırken, Execute(DataRow) satırın üst tablo adlarını kullanır.
DataTable table = new DataTable();
table.Columns.Add("FirstName");
table.Columns.Add("LastName");
DataRow row = table.NewRow();
row["FirstName"] = "Jane";
row["LastName"] = "Smith";
table.Rows.Add(row);
WordDocument doc = new WordDocument("template.docx");
doc.MailMerge.Execute(row);
doc.SaveAs("output.docx");Tekrar Eden Tablo Bölgelerini Nasıl Doldururum?
Tekrar eden bölgeler, bir şablon satırını birden fazla satıra dönüştürür, bu da fatura hat öğeleri veya sipariş listeleri için idealdir. Şablonda, tekrarlanan içeriği TableStart:RegionName ve TableEnd:RegionName adındaki iki işaret alanı arasına almaya çalışın. Daha sonra, eşleşen tablonun her satırı için bir defa bölgenin içeriğini tekrarlayan ExecuteWithRegions'ı çağırın.
ExecuteWithRegions, tam bir DataSet (adı bir tabloyla eşleşen her bölgeyi genişletir), tek bir DataTable (adı dataTable.TableName ile eşleşen bölgeyi genişletir) veya bir DataTable ile birlikte bir bölge adı kabul eder.
DataTable orders = new DataTable("Orders");
orders.Columns.Add("Item");
orders.Columns.Add("Qty");
orders.Rows.Add("Widget A", "3");
orders.Rows.Add("Widget B", "1");
DataSet ds = new DataSet();
ds.Tables.Add(orders);
WordDocument doc = new WordDocument("invoice-template.docx");
doc.MailMerge.ExecuteWithRegions(ds);
doc.MailMerge.Execute(new Dictionary<string, string> { { "CustomerName", "Jane Smith" } });
doc.SaveAs("invoice.docx");[(i:(ExecuteWithRegions yalnızca tekrarlanan bölgeleri doldurur. Bölgelerin dışında standart birleşim alanlarını da doldurmak için, yukarıda gösterildiği gibi bölgeleri genişlettikten sonra Execute(...)'i çağırın.)}]
Bir Şablonun Birleştirme Alanlarını Nasıl İncelerim?
Birleştirmeden önce, bir şablonun neler içerdiğini keşfedebilir, bu da şablonları doğrulamak veya veri kaynağını dinamik olarak oluşturmak için faydalıdır.
GetFieldNames(), belgede sıralı ve tekrarlanmamış tüm değer-stili birleşim alanlarının adlarını geri döndürür.GetRegionNames(), belgede bildirilen tümTableStartbölgelerinin adlarını geri döndürür.GetFields(),TableEndişaretçileri de dahil olmak üzere her alanıMergeFieldnesneleri olarak geri döndürür.
WordDocument doc = new WordDocument("template.docx");
IReadOnlyList<string> fieldNames = doc.MailMerge.GetFieldNames();
IReadOnlyList<string> regionNames = doc.MailMerge.GetRegionNames();
// fieldNames: ["FirstName", "LastName", "Company"]
// regionNames: ["Orders", "LineItems"]Her MergeField, Name'sunu, belgede saklandığı haliyle tam Instruction metnini (örneğin MERGEFIELD FirstName \* MERGEFORMAT), yalnızca bölge işaretçileri için ayarlanan bir RegionName (örneğin "Orders", "TableStart:Orders"'den) ve alanı Value (veri değeri ile değiştirilen metin), TableStart 'ye veya TableEnd 'ye sınıflandıran bir Kind (tekrarlanan bir bölge sınırları) veya NextRecord (aynı şablon gövdesi içinde bir sonraki veri kaydına ilerleyen bir NEXT alanı) açar.
Eşleşmemiş Alanları ve Null Değerlerini Nasıl Kontrol Edebilirim?
Birleştirme davranışı MailMerge.Options aracılığıyla yapılandırılır:
| Seçenek | Default | Davranış |
|---|---|---|
RemoveUnusedFields | true | Veri kaynağında eşleşen bir anahtar bulunmayan birleştirme alanlarını kaldırır. Yerinde bırakmak için false olarak ayarlayın. |
RemoveUnusedRegions | true | Veri kaynağında eşleşen tablo bulunmayan TableEnd bölgeleri kaldırır. |
NullValueReplacement | "" | Bir alan için veri kaynağı bir null değeri sağladığında yerleşen metin. |
CaseInsensitiveFieldNames | true | Alan adları eşleştirilirken büyük/küçük harf göz ardı edilir, bu Microsoft Word davranışıdır. |
WordDocument doc = new WordDocument("template.docx");
doc.MailMerge.Options.RemoveUnusedFields = false;
doc.MailMerge.Execute(new Dictionary<string, string> { { "FirstName", "Jane" } });
doc.SaveAs("partial-output.docx");Basit değer yerine koyma işlemini bir veri kaynağı olmadan yapmak istiyorsanız, bir Word belgesinde metni nasıl değiştireceğinizi görmek için tıklayın.
Sıkça Sorulan Sorular
C# ile bir Word belgesinde nasıl posta birleştirme yaparım?
MERGEFIELD yer tutucuları içeren bir Word şablonunu WordDocument yapılandırıcısı ile yükleyin, ardından bir IDictionary, DataTable veya DataRow ile doc.MailMerge.Execute çağırarak adı bir anahtar veya sütunla eşleşen her alanı değiştirin ve sonucu SaveAs ile kaydedin. Microsoft Word'de oluşturulan birleştirme alanları otomatik olarak algılanır ve Microsoft Office yüklemeye gerek yoktur.
IronWord hangi veri kaynaklarını posta birleştirme için kullanabilir?
MailMerge.Execute, alan adları ve değerlerinin iki paralel dizisini, alan isimleri ve değerleri içeren bir IDictionary'yi, DataTable (ilk satırı kullanarak) ya da DataRow'u (ebeveyn tablosunun sütunlarını kullanarak) kabul eder. MailMerge.ExecuteWithRegions, tekrar eden tablo bölgelerini genişletmek için bir DataSet veya DataTable kabul eder.
Word posta birleştirmesinde tekrarlayan tablo bölgelerini nasıl doldururum?
Şablondaki tekrarlayan içeriği TableStart:RegionName ve TableEnd:RegionName birleştirme alanları arasında sarın, ardından MailMerge.ExecuteWithRegions'u bir DataSet veya DataTable ile çağırın. Bölgenin içeriği, eşleşen tablonun her satırında bir kez tekrarlanır. ExecuteWithRegions yalnızca bölgeleri doldurduğu için, herhangi bir standart birleştirme alanını doldurmak için birleştirme sonrası Execute'u çağırın.
Bir şablonun birleştirme alanlarını birleştirmeden önce inceleyebilir miyim?
Evet. MailMerge.GetFieldNames, belge sırasındaki değer stilinde alan adlarını döndürür, GetRegionNames TableStart bölge adlarını döndürür ve GetFields, her alanın Adını, Talimatını, Türünü (Değer, TableStart, TableEnd veya NextRecord) ve BölgeAdını açığa çıkaran MergeField nesnelerini döndürür.
Eşleşmeyen verilerle birleştirme alanları ne olur?
Varsayılan olarak MailMergeOptions.RemoveUnusedFields true'dur, bu nedenle veri kaynağında eşleşen bir anahtarı olmayan alanlar çıktıdan kaldırılır. Bunu false olarak ayarlayarak yerinde bırakılmalarını sağlayabilirsiniz. RemoveUnusedRegions true iken eşleşmeyen TableStart/TableEnd bölgeleri kaldırılır ve boş değerler NullValueReplacement dizgisi ile değiştirilir.
Posta birleştirme alan eşleştirmesi büyük/küçük harf duyarlı mı?
Hayır. Alan adı aramaları varsayılan olarak büyük/küçük harf duyarsızdır, Microsoft Word davranışı ile eşleşir. MailMerge.Options.CaseInsensitiveFieldNames'ı false olarak ayarlayarak tam bir harf eşleşmesine ihtiyacınız varsa bunun tersini yapın.
How does IronWord handle unmatched fields and null values in mail merge?
IronWord offers options such as RemoveUnusedFields, RemoveUnusedRegions, and NullValueReplacement in MailMerge.Options to control the behavior for unmatched fields and null values.
What is the minimal workflow to mail merge a Word document using IronWord?
The minimal workflow involves downloading the IronWord library, authoring a Word template, loading it with WordDocument, executing the merge with your data, and saving the populated document.
How does case sensitivity affect field name matching in IronWord mail merge?
In IronWord, field name lookups in the mail merge are case-insensitive by default, similar to Microsoft Word. You can adjust this behavior using MailMerge.Options.CaseInsensitiveFieldNames.
How does IronWord support mail merging multiple documents or templates?
IronWord allows you to quickly fill multiple documents by reusing the same template with different data or by using the ExecuteWithRegions method for repeating data entries.
Curtis Chau, Bilgisayar Bilimleri alanında Lisans Derecesine (Carleton Üniversitesi) sahip ve Node.js, TypeScript, JavaScript ve React konularında uzmanlaşmış ön uç geliştirmeyle ilgileniyor. Sezgisel ve estetik açıdan hoş kullanıcı arayüzleri oluşturma tutkunu, Curtis modern çerçevelerle çalışmayı ve iyi yapılandırılmış, görsel olarak çekici kılavuzlar oluşturmayı seviyor.
