Introducción

Ahorra tiempo y esfuerzo al automatizar la creación de documentos personalizados como informes, cartas y facturas con C# Mail Merge impulsado por Aspose.Words para .NET. Esta guía explica cómo utilizar el Plugin Mail Merge de Aspose.Words para realizar generación de documentos eficiente y escalable dentro de tus aplicaciones .NET—sin necesidad de MS Word o Office Interop. Aprenderás a integrar C# mail merge para la automatización de informes, permitiéndote optimizar tu flujo de trabajo de informes.

Contenidos:

¿Qué es Mail Merge? {#¿Qué-es-Mail-Merge?}

Mail Merge es una metodología para generar documentos de manera dinámica al rellenar plantillas con datos de diversas fuentes. Con Aspose.Words, puedes automatizar sin inconvenientes tareas como:

  • Generar cartas y facturas con detalles personalizados.
  • Crear informes masivos utilizando datos de formatos estructurados como XML, JSON o bases de datos, lo que permite generación dinámica de informes con C# y Aspose.Words.

Fuentes de Datos para Mail Merge

Aspose.Words soporta diversas fuentes de datos:

  • Objetos: Rellena plantillas usando instancias de clase.
  • XML: Carga datos estructurados para campos dinámicos.
  • JSON: Integra fácilmente con APIs modernas.
  • CSV: Aprovecha datos tabulares para la generación masiva de documentos.
  • DataTable/DataSet: Utiliza ADO.NET para integración con bases de datos.

Preparando Plantilla para Mail Merge

La plantilla de mail merge es el documento que contiene los campos de fusión que serán rellenados con datos de tu fuente de datos especificada durante la ejecución. La plantilla puede estar en formato DOC o DOCX; no requiere necesariamente un estilo de plantilla específico. Sigue estos pasos para crear una plantilla de mail merge:

  1. Abre tu documento o crea uno nuevo en MS Word.
  2. Coloca el cursor donde desees insertar un campo de fusión.
  3. En el menú Insertar, selecciona la opción Campo.
  4. En la lista de Nombres de campo, selecciona MergeField.
  5. Especifica un nombre para el campo de fusión en el recuadro de Nombre del campo y haz clic en Aceptar.
  6. Guarda el documento.

La siguiente captura de pantalla ilustra un documento de plantilla de ejemplo.

Plantilla de Mail Merge

API de Mail Merge en .NET - Instalación

Puedes instalar Aspose.Words para .NET a través de diversos métodos:

Realizar Mail Merge en Documento de Word usando C#

Una vez que tu plantilla esté lista, ejecuta el correo masivo para generar documentos. Aquí están los pasos para realizar mail merge en tu plantilla preparada:

  1. Carga el documento de plantilla utilizando la clase Document.
  2. Establece las opciones de mail merge requeridas, como Document.MailMerge.TrimWhitespaces.
  3. Ejecuta el mail merge utilizando el método Document.MailMerge.Execute(), pasando la fuente de datos como parámetro.
  4. Guarda el documento generado usando el método Document.Save(String).

Aquí hay un ejemplo de código que demuestra cómo automatizar la generación de informes en C# utilizando un array de valores:

Documento de Word después de Mail Merge

Ejecutar Mail Merge en C#

Realizar Mail Merge usando Fuente de Datos XML en C#

Los archivos XML se utilizan comúnmente para almacenar y transferir datos. Aspose.Words para .NET también soporta XML como fuente de datos para operaciones de mail merge. Simplemente lee el XML en un objeto DataSet y ejecuta el mail merge. A continuación, un archivo XML de ejemplo para nuestro caso de uso.

<customers>
    <customer Name="John Ben Jan" ID="1" Domain="History" City="Boston"/>
    <customer Name="Lisa Lane" ID="2" Domain="Chemistry" City="LA"/>
    <customer Name="Dagomir Zits" ID="3" Domain="Heraldry" City="Milwaukee"/>
    <customer Name="Sara Careira Santy" ID="4" Domain="IT" City="Miami"/>
</customers>

El siguiente ejemplo de código recupera datos de una fuente de datos XML y ejecuta el mail merge usando C#.

A continuación, la plantilla de mail merge que será poblada con datos del archivo XML.

Plantilla de Mail Merge para XML

Esta imagen representa la primera página del documento de Word resultante obtenido después de ejecutar el mail merge.

Ejecutar Mail Merge con XML en C#

Formateo Personalizado de Campos de Fusión

Aspose.Words para .NET proporciona un control mejorado sobre el proceso de mail merge. La propiedad MailMerge.FieldMergingCallback te permite configurer el comportamiento del mail merge cada vez que se encuentra un campo de fusión. Implementar los métodos IFieldMergingCallback.FieldMerging y IFieldMergingCallback.ImageFieldMerging permite personalizar la operación de mail merge.

A continuación, un ejemplo de código que demuestra cómo aplicar formateo personalizado durante el mail merge a través de la plantilla de ejemplo proporcionada:

El siguiente implementa la clase HandleMergeFieldAlternatingRows.

Mail Merge con Regiones usando C#

En ciertas instancias, puede ser necesario poblar y repetir una región específica dentro del documento de Word. Para tales casos, utiliza mail merge con regiones. Para crear una región, especifica tanto el inicio como el final de la región; el mail merge repetirá esta región para cada registro en la fuente de datos. El siguiente ejemplo de plantilla contiene dos regiones—Orders y OrderDetails—utilizando los campos de fusión «TableStart:Orders», «TableEnd:Orders», «TableStart:OrderDetails» y «TableEnd:OrderDetails».

Mail Merge con Regiones

A continuación se muestra un ejemplo de código que ejecuta mail merge basado en regiones para la plantilla mencionada anteriormente.

Los siguientes métodos ilustran cómo leer datos de una base de datos.

Regiones de Mail Merge Anidadas

Frecuentemente, los datos de la fuente están estructurados en formatos relacionales. Por ejemplo, “Orders” puede tener una relación de uno a muchos con “OrderDetails”, que mantiene registros de los artículos dentro de un pedido. En tales escenarios, utiliza mail merge anidado. A continuación, se presenta una plantilla de factura que se adapta bien a este escenario.

Plantilla de Mail Merge con Regiones

A continuación se muestra una fuente de datos XML para nuestro ejemplo de mail merge anidado.

<?xml version="1.0" encoding="utf-8"?>
<Orders xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="OrdersSchema.xsd">
    <Order>
        <Number>23</Number>
        <Address>Calle Nelson</Address>
        <Suburb>Howick</Suburb>
        <City>Auckland</City>
        <Phonenumber>543 1234</Phonenumber>
        <Date>03/01/2010</Date>
        <Total>14.00</Total>
        <Item>
            <Name>Pizza de Pollo a la Parrilla</Name>
            <Price>6.00</Price>
            <Quantity>1</Quantity>
            <ItemTotal>6.00</ItemTotal>
        </Item>
        <Item>
            <Name>Coca-Cola de 1.5 Litros</Name>
            <Price>4.00</Price>
            <Quantity>2</Quantity>
            <ItemTotal>8.00</ItemTotal>
        </Item>
    </Order>
    <Order>
        <Number>10</Number>
        <Address>Avenida Parkville</Address>
        <Suburb>Pakuranga</Suburb>
        <City>Auckland</City>
        <Phonenumber>548 7342</Phonenumber>
        <Date>05/03/2010</Date>
        <Total>6.00</Total>
        <Item>
            <Name>Pizza Hawaiana</Name>
            <Price>4.00</Price>
            <Quantity>1</Quantity>
            <ItemTotal>4.00</ItemTotal>
        </Item>
        <Item>
            <Name>Papas fritas</Name>
            <Price>1.00</Price>
            <Quantity>2</Quantity>
            <ItemTotal>2.00</ItemTotal>
        </Item>
    </Order>
</Orders>

El correspondiente archivo OrderSchema.xsd para este XML es:

<?xml version="1.0" encoding ="utf-8"?>
<xs:schema id="OrdersSchema" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="Orders">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="Order">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element name="Number"/>
                            <xs:element name="Address"/>
                            <xs:element name="Suburb"/>
                            <xs:element name="City"/>
                            <xs:element name="Phonenumber"/>
                            <xs:element name="Date"/>
                            <xs:element name="Total"/>
                            <xs:element name="Item">
                                <xs:complexType>
                                    <xs:sequence>
                                        <xs:element name="Name"/>
                                        <xs:element name="Price"/>
                                        <xs:element name="Quantity"/>
                                        <xs:element name="ItemTotal"/>
                                    </xs:sequence>
                                </xs:complexType>
                            </xs:element>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

El siguiente ejemplo de código ejecuta el mail merge anidado utilizando C#.

Documento de Word después de Mail Merge

A continuación se muestra la primera página del documento de Word resultante obtenido después de ejecutar el mail merge anidado.

Documento de Word después de Mail Merge

Conclusión

Aspose.Words para .NET es una API de mail merge integral que proporciona tanto características estándar como extendidas, adecuadas para aplicaciones .NET. Con solo unas pocas líneas de código, puedes desarrollar informes simples o complejos de diversas fuentes de datos sin inconvenientes. Para orientación sobre las mejores prácticas para la generación automatizada de informes en .NET, consulta la documentación. Para comenzar con Aspose.Words para .NET, explora las guías para desarrolladores y el código de ejemplo en GitHub. El Plugin Aspose también ofrece funcionalidades avanzadas para la generación de informes.

Prueba Aspose.Words para .NET Gratis

Puedes obtener una licencia temporal gratuita para probar Aspose.Words para .NET sin limitaciones. Obtén tu licencia temporal ahora.

Consulta También