Introducción

Ahorre tiempo y esfuerzo automatizando 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 Complemento Mail Merge de Aspose.Words para realizar una generación de documentos eficiente y escalable dentro de sus aplicaciones .NET, sin necesidad de MS Word o Office Interop. Aprenderá a integrar C# mail merge para la automatización de informes, lo que le permitirá optimizar su flujo de trabajo de informes.

Contenidos:

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

Mail Merge es una metodología para generar documentos dinámicamente al poblar plantillas con datos de diversas fuentes. Con Aspose.Words, puede automatizar sin problemas tareas como:

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

Fuentes de datos para Mail Merge

Aspose.Words soporta diversas fuentes de datos:

  • Objetos: Población de plantillas utilizando instancias de clase.
  • XML: Cargar datos estructurados para campos dinámicos.
  • JSON: Integración sencilla con APIs modernas.
  • CSV: Aprovechar datos tabulares para la generación masiva de documentos.
  • DataTable/DataSet: Utilizar ADO.NET para la integración de bases de datos.

Preparando la plantilla para Mail Merge

La plantilla de mail merge es el documento que contiene campos de combinación que se poblarán con datos de su 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. Siga estos pasos para crear una plantilla de mail merge:

  1. Abra su documento o cree uno nuevo en MS Word.
  2. Coloque el cursor donde desea insertar un campo de combinación.
  3. Desde el menú Insertar, seleccione la opción Campo.
  4. Desde la lista de nombres de campos, seleccione MergeField.
  5. Especifique un nombre para el campo de combinación en el cuadro Nombre del campo y haga clic en OK.
  6. Guarde el documento.

La siguiente captura de pantalla ilustra un ejemplo de plantilla.

Plantilla de Mail Merge

API de Mail Merge para .NET - Instalación

Puede instalar Aspose.Words para .NET a través de varios métodos:

Realizar Mail Merge en un documento de Word usando C#

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

  1. Cargue el documento de plantilla utilizando la clase Document.
  2. Configure las opciones requeridas para el mail merge, como Document.MailMerge.TrimWhitespaces.
  3. Ejecute el mail merge utilizando el método Document.MailMerge.Execute(), pasando la fuente de datos como parámetro.
  4. Guarde el documento generado utilizando 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# usando un arreglo de valores:

Documento de Word después de Mail Merge

Ejecutar Mail Merge en C#

Realizar Mail Merge utilizando la fuente de datos XML en C#

Los archivos XML se utilizan comúnmente para almacenar y transferir datos. Aspose.Words para .NET también admite XML como fuente de datos para operaciones de mail merge. Simplemente lea el XML en un objeto DataSet y ejecute el mail merge. A continuación se muestra 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 utilizando C#.

A continuación se muestra la plantilla de mail merge que se poblará 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 combinación

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

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

A continuación se implementa la clase HandleMergeFieldAlternatingRows.

Mail Merge con regiones usando C#

En ciertos casos, puede necesitar poblar y repetir una región específica dentro del documento de Word. Para tales casos, utilice mail merge con regiones. Para crear una región, especifique 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: Pedidos y DetallesDePedido, utilizando los campos de combinación «TableStart:Orders», «TableEnd:Orders», «TableStart:OrderDetails» y «TableEnd:OrderDetails».

Mail Merge con Regiones

Aquí hay 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, “Pedidos” puede tener una relación de uno a muchos con “DetallesDePedido,” que mantiene los registros de los artículos dentro de un pedido. En tales escenarios, utilice mail merge anidado. A continuación se muestra una plantilla de factura que se adapta bien a este escenario.

Plantilla de Mail Merge con Regiones

La siguiente es 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>Nelson Street</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>Refresco 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 usando 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 completa que proporciona características tanto estándar como ampliadas adecuadas para aplicaciones .NET. Con solo unas pocas líneas de código, puede desarrollar informes simples o complejos a partir de diversas fuentes de datos sin inconvenientes. Para obtener pautas sobre las mejores prácticas de generación automatizada de informes en .NET, consulte la documentación. Para comenzar con Aspose.Words para .NET, explore las guías de desarrolladores disponibles y el código de muestra en GitHub. El Complemento Aspose también ofrece funcionalidades avanzadas para la generación de informes.

Pruebe Aspose.Words para .NET gratis

Puede obtener una licencia temporal gratuita para probar Aspose.Words para .NET sin limitaciones. Obtenga su licencia temporal ahora.

Vea también