Introducción

Automatizar la creación de documentos personalizados—como informes, cartas y facturas—puede ahorrarte tiempo y esfuerzo. Con C# Mail Merge impulsado por Aspose.Words para .NET, puedes lograr esto sin problemas. Esta guía te llevará a través del uso del Plugin de Mail Merge de Aspose.Words para realizar una generación de documentos eficiente y escalable dentro de tus aplicaciones .NET—sin necesidad de MS Word o Office Interop. Al final, estarás preparado para integrar C# mail merge para la automatización de informes y optimizar tu flujo de trabajo de informes.

Contenidos:

¿Qué es Mail Merge?

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

  • Generar cartas y facturas personalizadas.
  • Crear informes masivos utilizando 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 una variedad de fuentes de datos, incluyendo:

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

Preparando Plantilla para Mail Merge

La plantilla de mail merge es el documento que contiene campos de merge que serán llenados con datos de tu fuente de datos especificada durante la ejecución. La plantilla puede estar en formato DOC o DOCX y no requiere un estilo 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 deseas insertar un campo de merge.
  3. Desde el menú Insertar, selecciona la opción Campo.
  4. Desde la lista de Nombres de campo, selecciona MergeField.
  5. Especifica un nombre para el campo de merge en el cuadro Nombre del campo y haz clic en Aceptar.
  6. Guarda el documento.

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

Plantilla de Mail Merge

API de Mail Merge de .NET - Instalación

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

Realizar Mail Merge en Documento de Word usando C#

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

  1. Carga el documento de plantilla usando la clase Document.
  2. Establece las opciones de mail merge requeridas, como Document.MailMerge.TrimWhitespaces.
  3. Ejecuta el mail merge usando 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# usando 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 son comúnmente utilizados para almacenar y transferir datos. Aspose.Words para .NET 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 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 usando C#.

A continuación se muestra 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#

Formato Personalizado de Campos de Merge

Aspose.Words para .NET proporciona un control mejorado sobre el proceso de mail merge. La propiedad MailMerge.FieldMergingCallback te permite configurar el comportamiento de mail merge a medida que se encuentra cada campo de merge. Implementar los métodos IFieldMergingCallback.FieldMerging y IFieldMergingCallback.ImageFieldMerging permite la personalización de 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:

El siguiente implementa la clase HandleMergeFieldAlternatingRows.

Mail Merge con Regiones usando C#

En algunos casos, es posible que necesites llenar y repetir una región específica dentro del documento de Word. Para tales escenarios, 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 merge «TableStart:Orders», «TableEnd:Orders», «TableStart:OrderDetails» y «TableEnd:OrderDetails».

Mail Merge con Regiones

Aquí hay un ejemplo de código que ejecuta el 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

A menudo, los datos de la fuente están estructurados en formatos relacionales. Por ejemplo, “Orders” puede tener una relación 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 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>BBQ Chicken Pizza</Name>
            <Price>6.00</Price>
            <Quantity>1</Quantity>
            <ItemTotal>6.00</ItemTotal>
        </Item>
        <Item>
            <Name>1.5 Litre Coke</Name>
            <Price>4.00</Price>
            <Quantity>2</Quantity>
            <ItemTotal>8.00</ItemTotal>
        </Item>
    </Order>
    <Order>
        <Number>10</Number>
        <Address>Parkville Avenue</Address>
        <Suburb>Pakuranga</Suburb>
        <City>Auckland</City>
        <Phonenumber>548 7342</Phonenumber>
        <Date>05/03/2010</Date>
        <Total>6.00</Total>
        <Item>
            <Name>Hawaiian Pizza</Name>
            <Price>4.00</Price>
            <Quantity>1</Quantity>
            <ItemTotal>4.00</ItemTotal>
        </Item>
        <Item>
            <Name>Fries</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 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 a partir de diversas fuentes de datos sin problemas. Para obtener orientación sobre las mejores prácticas de generación de informes automatizados en .NET, consulta la documentación. Para comenzar con Aspose.Words para .NET, explora las guías para desarrolladores y el código de muestra en GitHub. El Plugin de 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.

Ver También