Automatizar Relatórios com C# Mail Merge | Plugin Mail Merge do Aspose.Words

Automatizar a criação de documentos personalizados—como relatórios, cartas e faturas—pode aumentar significativamente a eficiência em seu fluxo de trabalho. Com C# Mail Merge alimentado por Aspose.Words for .NET, você pode alcançar isso de forma tranquila. Este guia irá orientá-lo sobre como usar o Aspose.Words Mail Merge Plugin para realizar a geração de documentos de forma eficiente e escalável dentro de suas aplicações .NET—sem a necessidade de MS Word ou Office Interop. Ao final deste guia, você estará preparado para integrar C# mail merge para automação de relatórios e otimizar seu fluxo de trabalho de relatórios.

Conteúdos

• O que é Mail Merge?
• Fontes de Dados para Mail Merge
• Preparando Modelos para Mail Merge
• Começando com Aspose.Words for .NET
• Executar Mail Merge com Dados de Exemplo
• Mail Merge com Dados XML
• Formatação Personalizada de Campos de Mesclagem
• Mail Merge com Regiões
• Mail Merge Aninhado
• Conclusão

O que é Mail Merge?

Mail Merge é uma metodologia poderosa para gerar documentos dinamicamente, preenchendo modelos com dados de várias fontes. Com Aspose.Words, você pode automatizar tarefas como:

• Gerar cartas e faturas personalizadas.
• Criar relatórios em massa usando formatos estruturados como XML, JSON ou bancos de dados, possibilitando geração dinâmica de relatórios com C# e Aspose.Words.

Fontes de Dados para Mail Merge

Aspose.Words suporta uma variedade de fontes de dados, incluindo:

• Objetos: Preencher modelos usando instâncias de classe.
• XML: Carregar dados estruturados para campos dinâmicos.
• JSON: Integrar facilmente com APIs modernas.
• CSV: Aproveitar dados tabulares para geração de documentos em massa.
• DataTable/DataSet: Utilizar ADO.NET para integração com bancos de dados.

Preparando Modelo para Mail Merge

O modelo de mail merge é o documento que contém campos de mesclagem que serão preenchidos com dados da sua fonte de dados especificada durante a execução. O modelo pode estar no formato DOC ou DOCX e não requer um estilo específico. Siga estas etapas para criar um modelo de mail merge:

1. Abra seu documento ou crie um novo no MS Word.
2. Coloque o cursor onde deseja inserir um campo de mesclagem.
3. No menu Inserir, selecione a opção Campo.
4. Na lista de Nomes de campo, selecione MergeField.
5. Especifique um nome para o campo de mesclagem na caixa Nome do campo e clique em OK.
6. Salve o documento.

A captura de tela a seguir ilustra um modelo de exemplo de documento.

.NET Mail Merge API - Instalação

Você pode instalar Aspose.Words for .NET através de vários métodos:

• Baixar DLL
• Instalar via NuGet Package Manager

Executar Mail Merge em Documento Word usando C#

Uma vez que seu modelo esteja pronto, você pode executar o mail merge para gerar documentos. Aqui estão os passos para realizar o mail merge em seu modelo preparado:

1. Carregue o documento modelo usando a classe Document.
2. Defina as opções de mail merge necessárias, como Document.MailMerge.TrimWhitespaces.
3. Execute o mail merge usando o método Document.MailMerge.Execute(), passando a fonte de dados como parâmetro.
4. Salve o documento gerado usando o método Document.Save(String).

Aqui está um exemplo de código que demonstra como automatizar a geração de relatórios em C# usando um array de valores:

Documento Word após Mail Merge

Executar Mail Merge usando Fonte de Dados XML em C#

Arquivos XML são comumente utilizados para armazenar e transferir dados. Aspose.Words for .NET suporta XML como fonte de dados para operações de mail merge. Basta ler o XML em um objeto DataSet e executar o mail merge. Abaixo está um arquivo XML de exemplo para nosso 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>

O seguinte exemplo de código recupera dados de uma fonte de dados XML e executa o mail merge usando C#.

Abaixo está o modelo de mail merge que será preenchido com dados do arquivo XML.

Esta imagem representa a primeira página do documento Word resultante obtido após a execução do mail merge.

Formatação Personalizada de Campos de Mesclagem

Aspose.Words for .NET fornece controle aprimorado sobre o processo de mail merge. A propriedade MailMerge.FieldMergingCallback permite que você configure o comportamento do mail merge à medida que cada campo de mesclagem é encontrado. Implementar os métodos IFieldMergingCallback.FieldMerging e IFieldMergingCallback.ImageFieldMerging permite a personalização da operação de mail merge.

Abaixo está um exemplo de código que demonstra como aplicar formatação personalizada durante o mail merge através do modelo de exemplo fornecido:

O seguinte implementa a classe HandleMergeFieldAlternatingRows.

Mail Merge com Regiões usando C#

Em alguns casos, você pode precisar preencher e repetir uma região específica dentro do documento Word. Para tais cenários, utilize mail merge com regiões. Para criar uma região, especifique tanto o início quanto o fim da região; o mail merge então repetirá essa região para cada registro na fonte de dados. O exemplo de modelo abaixo contém duas regiões—Orders e OrderDetails—utilizando os campos de mesclagem «TableStart:Orders», «TableEnd:Orders», «TableStart:OrderDetails» e «TableEnd:OrderDetails».

Aqui está um exemplo de código que executa o mail merge com base em regiões para o modelo mencionado anteriormente.

Os seguintes métodos ilustram como ler dados de um banco de dados.

Mail Merge Aninhado

Frequentemente, os dados da fonte estão estruturados em formatos relacionais. Por exemplo, “Orders” pode ter um relacionamento um-para-muitos com “OrderDetails”, que mantém registros de itens dentro de um pedido. Em tais cenários, utilize mail merge aninhado. Abaixo está um modelo de fatura que se adequa bem a esse cenário.

A seguir está uma fonte de dados XML para nosso exemplo de mail merge aninhado.

<?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>

O arquivo OrderSchema.xsd correspondente para este XML é:

<?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>

O seguinte exemplo de código executa o mail merge aninhado usando C#.

Documento Word após Mail Merge

Abaixo está a primeira página do documento Word resultante obtido após a execução do mail merge aninhado.

Conclusão

Aspose.Words for .NET é uma API de mail merge abrangente que fornece recursos padrão e estendidos adequados para aplicações .NET. Com apenas algumas linhas de código, você pode desenvolver relatórios simples ou complexos a partir de diversas fontes de dados de forma tranquila. Para orientações sobre as melhores práticas de geração automatizada de relatórios .NET, consulte a documentação. Para começar com Aspose.Words for .NET, explore os guias do desenvolvedor e o código de exemplo no GitHub. O Aspose Plugin também oferece funcionalidades avançadas para geração de relatórios.

Experimente Aspose.Words for .NET Gratuitamente

Você pode obter uma licença temporária gratuita para experimentar o Aspose.Words for .NET sem limitações. Obtenha sua licença temporária agora.