Automatize Relatórios com C# Mail Merge | Plugin Mail Merge da Aspose.Words

Introdução

Economize tempo e esforço automatizando a criação de documentos personalizados, como relatórios, cartas e faturas com C# Mail Merge suportado pela Aspose.Words para .NET. Este guia explica como utilizar o Plugin Mail Merge da Aspose.Words para realizar a geração de documentos de forma eficiente e escalável dentro de seus aplicativos .NET—sem a necessidade do MS Word ou Office Interop. Você aprenderá a integrar C# mail merge para automação de relatórios, permitindo otimizar seu fluxo de trabalho de relatórios.

Conteúdos:

• O que é Mail Merge?
• Fontes de Dados para Mail Merge
• Preparando Modelos de Mail Merge
• Introdução ao Aspose.Words para .NET
• Realizar 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 para gerar documentos dinamicamente, preenchendo modelos com dados de várias fontes. Com Aspose.Words, você pode automatizar tarefas como:

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

Fontes de Dados para Mail Merge

Aspose.Words suporta diversas fontes de dados:

• Objetos: Preencha modelos usando instâncias de classe.
• XML: Carregue dados estruturados para campos dinâmicos.
• JSON: Integre facilmente com APIs modernas.
• CSV: Aproveite dados tabulares para geração em massa de documentos.
• DataTable/DataSet: Utilize ADO.NET para integração de banco 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 de sua fonte de dados especificada durante a execução. O modelo pode estar em formato DOC ou DOCX; não requer necessariamente um estilo de modelo 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 amostra documentado.

API .NET Mail Merge - Instalação

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

• Baixar DLL
• Instalar via Gerenciador de Pacotes NuGet

Realizar Mail Merge em Documento Word usando C#

Uma vez que seu modelo esteja pronto, execute o mail merge para gerar documentos. Aqui estão os passos para realizar 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 demonstrando como automatizar a geração de relatórios em C# usando um array de valores:

Documento Word após Mail Merge

Realizar Mail Merge usando Fonte de Dados XML em C#

Arquivos XML são comumente utilizados para armazenar e transferir dados. Aspose.Words para .NET também 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.

<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 executar o mail merge.

Formatação Personalizada de Campos de Mesclagem

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

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

A seguir, implementa a classe HandleMergeFieldAlternatingRows.

Mail Merge com Regiões usando C#

Em certas situações, você pode precisar preencher e repetir uma região específica dentro do documento Word. Para tais casos, utilize o 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—Pedidos e DetalhesPedido—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 nas regiões para o modelo mencionado anteriormente.

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

Regiões de Mail Merge Aninhadas

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

A seguinte 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>Pizza de Frango Grelhado</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 Havaiana</Name>
            <Price>4.00</Price>
            <Quantity>1</Quantity>
            <ItemTotal>4.00</ItemTotal>
        </Item>
        <Item>
            <Name>Fritas</Name>
            <Price>1.00</Price>
            <Quantity>2</Quantity>
            <ItemTotal>2.00</ItemTotal>
        </Item>
    </Order>
</Orders>

O correspondente arquivo OrderSchema.xsd 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 trecho de código a seguir 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 executar o mail merge aninhado.

Conclusão

Aspose.Words para .NET é uma API de mail merge abrangente que fornece recursos padrão e estendidos adequados para aplicativos .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 integrada. Para orientações sobre as melhores práticas para geração de relatórios automatizados em .NET, consulte a documentação. Para começar a usar a Aspose.Words para .NET, explore os guias de desenvolvedor disponíveis e o código de amostra no GitHub. O Plugin Aspose também oferece funcionalidades avançadas para geração de relatórios.

Experimente Aspose.Words para .NET gratuitamente

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

Veja Também

• Gerar Documentos Word a partir de Modelos em C# .NET