1. IronWord
  2. Poradniki
  3. Laczenie poczty

How to Mail Merge Word Documents in C

Curtis Chau
Curtis Chau
Zaktualizowano:
This article was translated from English: Does it need improvement?
Translated
View the article in English

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.

Szybki start: Łączenie korespondencji w dokumencie Word

Wczytaj szablon, ktory zawiera miejsca MERGEFIELD, przekaż slownik nazw i wartosci pol do Execute i zapisz wynik.

  1. Install IronWord with NuGet Package Manager

    PM > Install-Package IronWord

  2. Skopiuj 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");

  3. Wdrożenie do testowania w środowisku produkcyjnym

    Rozpocznij używanie IronWord w swoim projekcie już dziś z darmową wersją próbną

    arrow pointer

Minimalny proces (5 kroków)

  1. Pobierz bibliotekę C# dla łączenia korespondencji Word z NuGet
  2. Stwórz szablon Word z zastępnikami MERGEFIELD
  3. Załaduj szablon korzystając z konstruktora WordDocument
  4. Wywołaj MailMerge.Execute lub MailMerge.ExecuteWithRegions z Twoim źródłem danych
  5. 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");
WordDocument doc = new WordDocument("template.docx");
doc.MailMerge.Execute(new Dictionary<string, string>
{
    { "FirstName", "Jane" },
    { "LastName",  "Smith" },
    { "Company",   "Acme Corp" }
});
doc.SaveAs("output.docx");
Dim doc As New WordDocument("template.docx")
doc.MailMerge.Execute(New Dictionary(Of String, String) From {
    {"FirstName", "Jane"},
    {"LastName", "Smith"},
    {"Company", "Acme Corp"}
})
doc.SaveAs("output.docx")
$vbLabelText   $csharpLabel

PoradyWyszukiwanie nazw pól jest domyślnie nieczułe na wielkość liter, zgodnie z Microsoft Word. Ustaw 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" });
doc.MailMerge.Execute(
    new[] { "FirstName", "LastName" },
    new[] { "Jane", "Smith" });
doc.MailMerge.Execute(  
    New String() { "FirstName", "LastName" },  
    New String() { "Jane", "Smith" })
$vbLabelText   $csharpLabel

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");
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");
Imports System.Data

Dim table As New DataTable()
table.Columns.Add("FirstName")
table.Columns.Add("LastName")
Dim row As DataRow = table.NewRow()
row("FirstName") = "Jane"
row("LastName") = "Smith"
table.Rows.Add(row)

Dim doc As New WordDocument("template.docx")
doc.MailMerge.Execute(row)
doc.SaveAs("output.docx")
$vbLabelText   $csharpLabel

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");
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");
Imports System.Data
Imports System.Collections.Generic

Dim orders As New DataTable("Orders")
orders.Columns.Add("Item")
orders.Columns.Add("Qty")
orders.Rows.Add("Widget A", "3")
orders.Rows.Add("Widget B", "1")

Dim ds As New DataSet()
ds.Tables.Add(orders)

Dim doc As New WordDocument("invoice-template.docx")
doc.MailMerge.ExecuteWithRegions(ds)
doc.MailMerge.Execute(New Dictionary(Of String, String) From {{"CustomerName", "Jane Smith"}})
doc.SaveAs("invoice.docx")
$vbLabelText   $csharpLabel

Zwróć uwagę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 regionow TableStart zadeklarowanych w dokumencie.
  • GetFields() zwraca kazde pole, wlacznie z znacznikami TableEnd, jako obiekty MergeField.
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"]
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"]
Dim doc As New WordDocument("template.docx")
Dim fieldNames As IReadOnlyList(Of String) = doc.MailMerge.GetFieldNames()
Dim regionNames As IReadOnlyList(Of String) = doc.MailMerge.GetRegionNames()
' fieldNames:  ["FirstName", "LastName", "Company"]
' regionNames: ["Orders", "LineItems"]
$vbLabelText   $csharpLabel

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");
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");
Dim doc As New WordDocument("template.docx")
doc.MailMerge.Options.RemoveUnusedFields = False
doc.MailMerge.Execute(New Dictionary(Of String, String) From {{"FirstName", "Jane"}})
doc.SaveAs("partial-output.docx")
$vbLabelText   $csharpLabel

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.

Curtis Chau
Curtis Chau
  Czat z zespołem inżynierów teraz
Autor tekstów technicznych

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

Czytaj więcej
Gotowy, aby rozpocząć?
Nuget Pliki do pobrania 48,355 | Wersja: 2026.7 właśnie wydany
Still Scrolling Icon

Wciąż przewijasz?

Czy chcesz szybko dowodu? PM > Install-Package IronWord
uruchom próbkę zobacz, jak twoje dane stają się dokumentem Word.