How to Mail Merge Word Documents in C#
IronWord wykonuje scalanie korespondencji w C# poprzez uzupelnienie szablonu Word z miejscami MERGEFIELD Twoimi danymi, pochodzacymi ze slownikow, DataSet obiektow lub tabel obszarow powtarzanych, wszystko to bez uzywania Microsoft Office Interop. Pola scalania stworzone w Microsoft Word lub innym kompatybilnym narzedziu sa automatycznie wykrywane.
Łączenie korespondencji to standardowy sposób generowania spersonalizowanych dokumentów na dużą skalę: listów formowych, faktur, certyfikatów, umów, i raportów, które dzielą jeden szablon, ale różnią się w zależności od odbiorcy. Zamiast edytowac kazdy dokument recznie, tworzysz jeden szablon .docx z polami scalania i pozwalasz, aby IronWord uzupelnil je z Twojego zrodla danych. Kazda operacja jest dostepna poprzez punkt wejsciowy WordDocument.MailMerge.
Wczytaj szablon, ktory zawiera miejsca MERGEFIELD, przekaż slownik nazw i wartosci pol do Execute i zapisz wynik.
-
1Install IronWord with NuGet Package Manager
-
2Skopiuj i uruchom ten fragment kodu.
WordDocument doc = new WordDocument("template.docx"); doc.MailMerge.Execute(new Dictionary<string, string> { { "FirstName", "Jane" }, { "Company", "Acme Corp" } }); doc.SaveAs("output.docx");C# -
3Wdrożenie do testowania w środowisku produkcyjnym
Rozpocznij używanie IronWord w swoim projekcie już dziś z darmową wersją próbną
Minimalny proces (5 kroków)
- Pobierz bibliotekę C# dla łączenia korespondencji Word z NuGet
- Stwórz szablon Word z zastępnikami
MERGEFIELD - Załaduj szablon korzystając z konstruktora
WordDocument - Wywołaj
MailMerge.ExecutelubMailMerge.ExecuteWithRegionsz Twoim źródłem danych - Zapisz wypełniony dokument
Jak łączyć korespondencję z słownika?
Najprostszym zrodlem danych jest IDictionary<string, string> z kluczami oznaczajacymi nazwy pol scalania. Execute zamienia kazde pole, ktorego nazwa pasuje do klucza.
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, aby wymagac dokladnego dopasowania wielkosci liter.Możesz również dostarczyć dwie równoległe sekwencje nazw pól i wartości:
doc.MailMerge.Execute(
new[] { "FirstName", "LastName" },
new[] { "Jane", "Smith" });Execute(fieldNames, values) rzuca ArgumentException, gdy dwie sekwencje maja rozne dlugosci.
Jak zrealizować łączenie korespondencji z DataTable lub DataRow?
Gdy dane pochodza z bazy danych lub istniejacego DataSet, przekaź DataTable lub DataRow bezposrednio do Execute. Nazwy pól do łączenia są dopasowywane do nazw kolumn. Execute(DataTable) wykorzystuje wartosci z pierwszego wiersza tabeli, podczas gdy Execute(DataRow) uzywa nazw kolumn tabeli nadrzednej dla wiersza.
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");Jak wypełniać powtarzające się obszary tabel?
Powtarzające się obszary zamieniają jeden wiersz szablonu w wiele, co jest idealne dla pozycji na fakturze lub listy zamówień. W szablonie otocz powtarzalne tresci pomiedzy dwoma polami znacznikow nazwanymi TableStart:RegionName i TableEnd:RegionName. Nastepnie wywolaj ExecuteWithRegions, ktory powtarza tresc regionu raz na wiersz zgodnej tabeli.
ExecuteWithRegions akceptuje pelny DataSet (rozszerzajac kazdy region, ktorego nazwa pasuje do tabeli), jeden DataTable (rozszerzajac region, ktorego nazwa odpowiada dataTable.TableName), lub nazwe regionu wraz z DataTable.
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");ExecuteWithRegions uzupelnia tylko powtarzajace sie regiony. Aby rowniez wypelnic standardowe pola scalania poza regionami, wywolaj Execute(...) po rozszerzeniu regionow, jak pokazano powyzej.Jak sprawdzić pola do łączenia w szablonie?
Przed łączeniem możesz odkryć, co zawiera szablon, co jest przydatne zarówno do walidacji szablonów, jak i dynamicznego budowania źródła danych.
GetFieldNames()zwraca nazwy wszystkich pol scalania typu wartosciowego, w kolejnosci dokumentu i bez powtorek.GetRegionNames()zwraca nazwy wszystkich regionowTableStartzadeklarowanych w dokumencie.GetFields()zwraca kazde pole, wlacznie z znacznikamiTableEnd, jako obiektyMergeField.
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"]Kazdy MergeField udostępnia swoj Name, pelny tekst Instruction zapisany w dokumencie (na przyklad MERGEFIELD FirstName \* MERGEFORMAT), RegionName ustawiony tylko dla znacznikow regionow (na przyklad "Orders" z "TableStart:Orders"), oraz Kind klasyfikujacy pole jako Value (tekst zamieniany na wartosc danych), TableStart lub TableEnd (graniczny region powtarzajacy sie), lub NextRecord (pole NEXT, ktore przechodzi do nastepnego rekordu danych w tej samej tresci szablonu).
Jak kontrolować niedopasowane pola i wartości null?
Zachowanie skalowania jest konfigurowane przez MailMerge.Options:
| Opcja | Default | Zachowanie |
|---|---|---|
RemoveUnusedFields | true | Usuwa pola do łączenia, które nie mają dopasowanego klucza w źródle danych. Ustaw na false, aby pozostawic je na miejscu. |
RemoveUnusedRegions | true | Usuwa regiony TableEnd, dla ktorych brak pasujacej tabeli w zrodle danych. |
NullValueReplacement | "" | Tekst zamieniony, gdy zrodlo danych dostarcza wartosc null dla pola. |
CaseInsensitiveFieldNames | true | Ignoruje wielkość liter przy dopasowaniu nazw pól, nawiązując do zachowania Microsoft Word. |
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");Aby uzyskać prostą zamianę wartości bez źródła danych, zobacz jak zamienić tekst w dokumencie Word.
Często Zadawane Pytania
Jak scalić dokument Word w C#?
Załaduj szablon Worda zawierający miejsca zastępcze MERGEFIELD za pomocą konstruktora WordDocument, następnie wywołaj doc.MailMerge.Execute z IDictionary, DataTable lub DataRow, aby zastąpić każde pole, którego nazwa odpowiada kluczowi lub kolumnie, i zapisz wynik za pomocą SaveAs. Pola scalania utworzone w Microsoft Word są wykrywane automatycznie, a instalacja Microsoft Office nie jest wymagana.
Z jakich źródeł danych może korzystać scalanie korespondencji w IronWord?
MailMerge.Execute akceptuje IDictionary nazw pól i wartości, dwa równoległe sekwencje nazw pól i wartości, DataTable (używa pierwszego wiersza) lub DataRow (używa kolumn tabeli macierzystej). MailMerge.ExecuteWithRegions akceptuje DataSet lub DataTable do rozwinięcia powtarzających się regionów tabel.
Jak wypełnić powtarzające się regiony tabeli w scalaniu korespondencji Word?
Opakuj powtarzającą się zawartość w szablonie między polami scalania TableStart:RegionName a TableEnd:RegionName, następnie wywołaj MailMerge.ExecuteWithRegions z DataSet lub DataTable. Zawartość regionu powtarza się raz na każdego wiersza pasującej tabeli. Ponieważ ExecuteWithRegions wypełnia tylko regiony, wywołaj Execute później, aby wypełnić standardowe pola scalania.
Czy mogę sprawdzić pola scalania szablonu przed scaleniem?
Tak. MailMerge.GetFieldNames zwraca nazwy pól w stylu value w porządku występowania w dokumencie, GetRegionNames zwraca nazwy regionów TableStart, a GetFields zwraca obiekty MergeField ujawniające nazwę, instrukcję, rodzaj (Value, TableStart, TableEnd lub NextRecord) i nazwę regionu każdego pola.
Co się dzieje z polami scalania bez dopasowanych danych?
Domyślnie MailMergeOptions.RemoveUnusedFields jest ustawione na true, więc pola bez pasującego klucza w źródle danych są usuwane z wyjścia. Ustaw ją na false, aby pozostawić je na miejscu. Niedopasowane regiony TableStart/TableEnd są usuwane, gdy RemoveUnusedRegions jest ustawione na true, a wartości null są zastępowane ciągiem NullValueReplacement.
Czy dopasowywanie pól scalania jest wrażliwy na wielkość liter?
Nie. Domyślnie wyszukiwania nazw pól nie są wrażliwe na wielkość liter, co odpowiada zachowaniu Microsoft Word. Ustaw MailMerge.Options.CaseInsensitiveFieldNames na false, jeśli potrzebujesz dokładnego dopasowania wielkości liter.
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 posiada tytuł licencjata z informatyki (Uniwersytet Carleton) i specjalizuje się w front-endowym rozwoju, z ekspertką w Node.js, TypeScript, JavaScript i React. Pasjonuje się tworzeniem intuicyjnych i estetycznie przyjemnych interfejsów użytkownika, Curtis cieszy się pracą z nowoczesnymi frameworkami i tworzeniem dobrze zorganizowanych, atrakcyjnych wizualnie podręczników.
