1. IronWord
  2. Guías
  3. Combinar correspondencia

How to Mail Merge Word Documents in C

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

IronWord realiza la combinación de correspondencia en C# al completar los marcadores MERGEFIELD en una plantilla de Word con sus datos, extraídos de diccionarios, objetos DataSet, o tablas de región repetida, todo sin Microsoft Office Interop. Los campos combinados creados en Microsoft Word, o cualquier herramienta compatible, se detectan automáticamente.

La fusión de correspondencia es la forma estándar de generar documentos personalizados a gran escala: cartas de formulario, facturas, certificados, contratos e informes que comparten una plantilla pero difieren por destinatario. En lugar de editar cada documento manualmente, usted crea una sola plantilla .docx con campos de combinación y deja que IronWord los complete desde su fuente de datos. Cada operación se alcanza a través del punto de entrada WordDocument.MailMerge.

Inicio rápido: Fusionar Correspondencia en un Documento Word

Cargue una plantilla que contenga marcadores MERGEFIELD, pase un diccionario de nombres de campo y valores a Execute, y guarde el resultado.

  1. Instala IronWord con el Administrador de Paquetes NuGet

    PM > Install-Package IronWord

  2. Copie y ejecute este fragmento de código.

    WordDocument doc = new WordDocument("template.docx");
doc.MailMerge.Execute(new Dictionary<string, string> { { "FirstName", "Jane" }, { "Company", "Acme Corp" } });
doc.SaveAs("output.docx");

  3. Despliegue para probar en su entorno real

    Comienza a usar IronWord en tu proyecto hoy mismo con una prueba gratuita

    arrow pointer

Flujo de trabajo mínimo (5 pasos)

  1. Descargue la biblioteca C# para fusión de correspondencia en Word desde NuGet
  2. Cree una plantilla de Word con marcadores de posición MERGEFIELD
  3. Cargue la plantilla con el constructor WordDocument
  4. Llame a MailMerge.Execute o MailMerge.ExecuteWithRegions con su fuente de datos
  5. Guarda el documento completado


¿Cómo hago una fusión de correspondencia desde un Diccionario?

La fuente de datos más sencilla es un IDictionary<string, string> claveado por el nombre del campo de combinación. Execute reemplaza cada campo cuyo nombre coincida con una clave.

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

ConsejosLas búsquedas de nombres de campos son insensibles a mayúsculas y minúsculas por defecto, coincidiendo con Microsoft Word. Configure MailMerge.Options.CaseInsensitiveFieldNames = false para requerir una coincidencia exacta.

También puede proporcionar dos secuencias paralelas de nombres de campo y valores:

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) lanza un ArgumentException cuando las dos secuencias tienen longitudes diferentes.

¿Cómo hago una fusión de correspondencia desde un DataTable o DataRow?

Cuando los datos provienen de una base de datos o de un DataSet existente, pase un DataTable o un DataRow directamente a Execute. Los nombres de campos de fusión se emparejan con nombres de columnas. Execute(DataTable) utiliza los valores de la primera fila de la tabla, mientras que Execute(DataRow) utiliza los nombres de las columnas de la tabla principal de la fila.

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

¿Cómo relleno regiones de tablas repetidas?

Las regiones repetidas convierten una fila de plantilla en muchas, lo que es ideal para artículos de línea de factura o listas de pedidos. En la plantilla, encierre el contenido repetido entre dos campos marcadores llamados TableStart:RegionName y TableEnd:RegionName. Luego llame a ExecuteWithRegions, que repite el contenido de la región una vez por cada fila de la tabla correspondiente.

ExecuteWithRegions acepta un DataSet completo (expandiendo todas las regiones cuyo nombre coincida con una tabla), un solo DataTable (expandiendo la región cuyo nombre coincida dataTable.TableName), o un nombre de región junto con un 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

ExecuteWithRegions solo completa regiones repetitivas. Para también completar los campos de combinación estándar fuera de las regiones, llame a Execute(...) después de expandir las regiones, como se muestra arriba.

¿Cómo inspecciono los campos de fusión de una plantilla?

Antes de fusionar, puede descubrir qué contiene una plantilla, lo cual es útil para validar plantillas o construir la fuente de datos dinámicamente.

  • GetFieldNames() devuelve los nombres de todos los campos de combinación de estilo valor, en orden de documento y sin duplicados.
  • GetRegionNames() devuelve los nombres de todas las regiones TableStart declaradas en el documento.
  • GetFields() devuelve cada campo, incluidos los marcadores TableEnd, como objetos 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

Cada MergeField expone su Name, el texto completo Instruction tal como se almacena en el documento (por ejemplo MERGEFIELD FirstName \* MERGEFORMAT), un RegionName que solo se establece para los marcadores de región (por ejemplo "Orders" de "TableStart:Orders"), y un Kind que clasifica el campo como Value (texto reemplazado con un valor de datos), TableStart o TableEnd (los límites de una región repetitiva), o NextRecord (un campo NEXT que avanza al siguiente registro de datos dentro del mismo cuerpo de plantilla).

¿Cómo controlo los campos sin límites y valores nulos?

El comportamiento de la combinación se configura a través de MailMerge.Options:

Opción Default Comportamiento
RemoveUnusedFields true Elimina campos de fusión que no tienen una clave correspondiente en la fuente de datos. Configure en false para dejarlos en su lugar.
RemoveUnusedRegions true Elimina regiones TableEnd sin tabla correspondiente en la fuente de datos.
NullValueReplacement "" Texto sustituido cuando la fuente de datos proporciona un valor null para un campo.
CaseInsensitiveFieldNames true Ignora las mayúsculas y minúsculas al emparejar nombres de campos, correspondiente al comportamiento de 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

Para una sustitución de valor sencilla sin una fuente de datos, vea cómo reemplazar texto en un documento de Word.

Preguntas Frecuentes

¿Cómo hago una combinación de correspondencia en un documento de Word en C#?

Carga una plantilla de Word que contenga marcadores de posición MERGEFIELD con el constructor WordDocument, luego llama a doc.MailMerge.Execute con un IDictionary, DataTable o DataRow para reemplazar cada campo cuyo nombre coincida con una clave o columna, y guarda el resultado con SaveAs. Los campos de combinación creados en Microsoft Word se detectan automáticamente, y no se requiere instalación de Microsoft Office.

¿Qué fuentes de datos puede usar IronWord para la combinación de correspondencia?

MailMerge.Execute acepta un IDictionary de nombres de campos y valores, dos secuencias paralelas de nombres de campos y valores, un DataTable (usando la primera fila) o un DataRow (usando las columnas de su tabla principal). MailMerge.ExecuteWithRegions acepta un DataSet o DataTable para expandir regiones de tabla repetidas.

¿Cómo lleno regiones de tabla repetidas en una combinación de correspondencia de Word?

Envuelve el contenido repetido en la plantilla entre campos de combinación TableStart:RegionName y TableEnd:RegionName, luego llama a MailMerge.ExecuteWithRegions con un DataSet o DataTable. El contenido de la región se repite una vez por fila de la tabla coincidente. Debido a que ExecuteWithRegions solo completa regiones, llama a Execute después para llenar cualquier campo de combinación estándar.

¿Puedo inspeccionar los campos de combinación de una plantilla antes de combinar?

Sí. MailMerge.GetFieldNames devuelve los nombres de campos de estilo valor en el orden del documento, GetRegionNames devuelve los nombres de las regiones TableStart y GetFields devuelve objetos MergeField exponiendo el Nombre, Instrucción, Tipo (Value, TableStart, TableEnd o NextRecord) y RegionName de cada campo.

¿Qué sucede con los campos de combinación sin datos coincidentes?

Por defecto, MailMergeOptions.RemoveUnusedFields es verdadero, por lo que los campos sin clave coincidente en la fuente de datos se eliminan de la salida. Configúralo como falso para dejarlos en su lugar. Las regiones TableStart/TableEnd no coincidentes se eliminan cuando RemoveUnusedRegions es verdadero, y los valores nulos se reemplazan con la cadena NullValueReplacement.

¿La coincidencia de campos de combinación distingue entre mayúsculas y minúsculas?

No. Las búsquedas de nombres de campo no distinguen entre mayúsculas y minúsculas por defecto, coincidiendo con el comportamiento de Microsoft Word. Configura MailMerge.Options.CaseInsensitiveFieldNames como falso si necesitas una coincidencia exacta de mayúsculas.

Curtis Chau
Curtis Chau
  Chatea con el equipo de ingeniería ahora
Escritor Técnico

Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien ...

Leer más
¿Listo para empezar?
Nuget Descargas 48,355 | Versión: 2026.7 recién lanzado
Still Scrolling Icon

¿Aún desplazándote?

¿Quieres una prueba rápida? PM > Install-Package IronWord
ejecuta una muestra observa cómo tus datos se convierten en un documento de Word.