Como criar modelos de formulário preenchíveis em C# usando IronWord

O que o recurso faz

O mecanismo de mesclagem de correspondência lida com ambos os estilos de campo de mesclagem que o Word produz:

• Campos simples, no formato "FieldName", que é o que você obtém ao digitar <> diretamente no modelo
• Campos complexos, a estrutura XML de múltiplos elementos que o Word gera através de Inserir → Partes Rápidas → Campo

Os modelos podem incluir espaços reservados de valor único que são substituídos uma vez por documento, e regiões repetidas delimitadas por marcadores "TableStart:Name" e "TableEnd:Name", que se expandem para uma linha por registro de dados.

Essa segunda parte é onde o recurso ganha seu lugar. Regiões repetidas são como uma única linha de modelo em uma fatura se expande em uma tabela de itens lineares com 50 linhas, ou como um espaço de contato em uma folha de etiquetas se torna uma grade completa Avery preenchida a partir de um banco de dados.

Cartas de apresentação personalizadas de um CRM

A maioria das equipes começa a mesclagem de correspondência por meio das operações de vendas. O CRM mantém registros de clientes; operações de marketing ou vendas precisam enviar cartas de apresentação personalizadas, pacotes de boas-vindas ou avisos de renovação. O padrão é direto: um modelo, uma linha por cliente, um documento personalizado de saída.

// Template: "Dear «FirstName», thank you for your order of «Amount»..."
DataTable customers = LoadFromSalesforce();   // FirstName, LastName, Amount, ...

foreach (DataRow row in customers.Rows)
{
    var doc = new WordDocument("cover-letter-template.docx");
    doc.MailMerge.Execute(row);
    doc.SaveAs($"letters/{row["LastName"]}.docx");
}

// Template: "Dear «FirstName», thank you for your order of «Amount»..."
DataTable customers = LoadFromSalesforce();   // FirstName, LastName, Amount, ...

foreach (DataRow row in customers.Rows)
{
    var doc = new WordDocument("cover-letter-template.docx");
    doc.MailMerge.Execute(row);
    doc.SaveAs($"letters/{row["LastName"]}.docx");
}

Imports System.Data

' Template: "Dear «FirstName», thank you for your order of «Amount»..."
Dim customers As DataTable = LoadFromSalesforce() ' FirstName, LastName, Amount, ...

For Each row As DataRow In customers.Rows
    Dim doc As New WordDocument("cover-letter-template.docx")
    doc.MailMerge.Execute(row)
    doc.SaveAs($"letters/{row("LastName")}.docx")
Next

A fonte de dados é um DataTable, o que significa que qualquer coisa que carregue em um (Salesforce, HubSpot, SQL Server, um CSV, uma resposta de API) se torna uma fonte de mesclagem de correspondência sem código de adaptador adicional.

Faturas com itens de linha repetidos

A faturação é onde a capacidade de região repetida se destaca. Um modelo de fatura tem um cabeçalho (nome do cliente, ID do pedido, datas), uma linha em uma tabela de itens de linha, e um rodapé (totais). Quando a mesclagem é executada, a única linha do modelo se expande para uma linha por produto, independentemente de o pedido ter um item de linha ou cinquenta.

// Template:
//   Bill To: «CustomerName»  Order: «OrderId»
//   ┌──────────┬─────┬──────────┐
//   │ «TableStart:Items»«Product» │ «Qty» │ «LineTotal» «TableEnd:Items» │
//   └──────────┴─────┴──────────┘
//   Total: «Total»

var doc = new WordDocument("invoice-template.docx");

doc.MailMerge.ExecuteWithRegions(orderLineItems);  // one row per product
doc.MailMerge.Execute(new Dictionary<string, string>
{
    { "CustomerName", "Acme Industries" },
    { "OrderId",      "10444" },
    { "Total",        "$1,117.71" },
});

doc.SaveAs("invoice-10444.docx");

// Template:
//   Bill To: «CustomerName»  Order: «OrderId»
//   ┌──────────┬─────┬──────────┐
//   │ «TableStart:Items»«Product» │ «Qty» │ «LineTotal» «TableEnd:Items» │
//   └──────────┴─────┴──────────┘
//   Total: «Total»

var doc = new WordDocument("invoice-template.docx");

doc.MailMerge.ExecuteWithRegions(orderLineItems);  // one row per product
doc.MailMerge.Execute(new Dictionary<string, string>
{
    { "CustomerName", "Acme Industries" },
    { "OrderId",      "10444" },
    { "Total",        "$1,117.71" },
});

doc.SaveAs("invoice-10444.docx");

Imports System.Collections.Generic

' Template:
'   Bill To: «CustomerName»  Order: «OrderId»
'   ┌──────────┬─────┬──────────┐
'   │ «TableStart:Items»«Product» │ «Qty» │ «LineTotal» «TableEnd:Items» │
'   └──────────┴─────┴──────────┘
'   Total: «Total»

Dim doc As New WordDocument("invoice-template.docx")

doc.MailMerge.ExecuteWithRegions(orderLineItems)  ' one row per product
doc.MailMerge.Execute(New Dictionary(Of String, String) From {
    {"CustomerName", "Acme Industries"},
    {"OrderId", "10444"},
    {"Total", "$1,117.71"}
})

doc.SaveAs("invoice-10444.docx")

O mesmo padrão funciona para cotações, pedidos de compra, extratos e qualquer documento onde uma lista de tamanho variável está dentro de uma página de formato fixo.

Folhas de etiquetas Avery e envelopes

Equipes de envio e operações geram etiquetas e envelopes a partir de listas de contatos, e os layouts (Avery 5160, 5161, 5163, e seus equivalentes internacionais) são modelos padronizados que existem há décadas. IronWord os preenche diretamente: cada célula na grade de etiquetas pega o contato apropriado de uma única chamada de API.

// Template: a 3×10 Avery 5160 grid, each cell has «CONTACT_FULLNAME» / «CONTACT_ADDRESS»
var doc = new WordDocument("avery-5160.docx");

doc.MailMerge.Execute(new Dictionary<string, string>
{
    { "CONTACT_FULLNAME", "Jane Doe" },
    { "CONTACT_ADDRESS",  "100 Main Street, Boston, MA 02108" },
});

doc.SaveAs("labels-jane.docx");

// Template: a 3×10 Avery 5160 grid, each cell has «CONTACT_FULLNAME» / «CONTACT_ADDRESS»
var doc = new WordDocument("avery-5160.docx");

doc.MailMerge.Execute(new Dictionary<string, string>
{
    { "CONTACT_FULLNAME", "Jane Doe" },
    { "CONTACT_ADDRESS",  "100 Main Street, Boston, MA 02108" },
});

doc.SaveAs("labels-jane.docx");

Imports System.Collections.Generic

' Template: a 3×10 Avery 5160 grid, each cell has «CONTACT_FULLNAME» / «CONTACT_ADDRESS»
Dim doc As New WordDocument("avery-5160.docx")

doc.MailMerge.Execute(New Dictionary(Of String, String) From {
    {"CONTACT_FULLNAME", "Jane Doe"},
    {"CONTACT_ADDRESS", "100 Main Street, Boston, MA 02108"}
})

doc.SaveAs("labels-jane.docx")

Para listas de contatos de comprimento variável, o padrão ExecuteWithRegions do exemplo de fatura se aplica: defina uma célula como a unidade de repetição e o resto da folha se preenche automaticamente.

Relatórios multirregionais

A aplicação mais poderosa é os relatórios multirregionais. Um resumo trimestral pode incluir seções "Principais Clientes" e "Produtos Principais", cada uma conduzida por sua própria tabela de dados. Com um DataSet contendo várias tabelas, a mesclagem expande ambas as regiões em uma única chamada.

// Template:
//   Top Customers
//   «TableStart:Customers» • «Name» | «City» | «Revenue» «TableEnd:Customers»
//   Top Products
//   «TableStart:Products»  «ProductName»: «Revenue»     «TableEnd:Products»

var ds = new DataSet();
ds.Tables.Add(topCustomers);   // TableName = "Customers"
ds.Tables.Add(topProducts);    // TableName = "Products"

var doc = new WordDocument("quarterly-report.docx");
doc.MailMerge.ExecuteWithRegions(ds);          // expands both regions
doc.MailMerge.Execute(new Dictionary<string, string>
{
    { "CompanyName", "Iron Software" },
    { "ReportDate",  "Q2 2026" },
});
doc.SaveAs("Q2-2026-report.docx");

// Template:
//   Top Customers
//   «TableStart:Customers» • «Name» | «City» | «Revenue» «TableEnd:Customers»
//   Top Products
//   «TableStart:Products»  «ProductName»: «Revenue»     «TableEnd:Products»

var ds = new DataSet();
ds.Tables.Add(topCustomers);   // TableName = "Customers"
ds.Tables.Add(topProducts);    // TableName = "Products"

var doc = new WordDocument("quarterly-report.docx");
doc.MailMerge.ExecuteWithRegions(ds);          // expands both regions
doc.MailMerge.Execute(new Dictionary<string, string>
{
    { "CompanyName", "Iron Software" },
    { "ReportDate",  "Q2 2026" },
});
doc.SaveAs("Q2-2026-report.docx");

Imports System.Data
Imports System.Collections.Generic

' Template:
'   Top Customers
'   «TableStart:Customers» • «Name» | «City» | «Revenue» «TableEnd:Customers»
'   Top Products
'   «TableStart:Products»  «ProductName»: «Revenue»     «TableEnd:Products»

Dim ds As New DataSet()
ds.Tables.Add(topCustomers)   ' TableName = "Customers"
ds.Tables.Add(topProducts)    ' TableName = "Products"

Dim doc As New WordDocument("quarterly-report.docx")
doc.MailMerge.ExecuteWithRegions(ds)          ' expands both regions
doc.MailMerge.Execute(New Dictionary(Of String, String) From {
    {"CompanyName", "Iron Software"},
    {"ReportDate", "Q2 2026"}
})
doc.SaveAs("Q2-2026-report.docx")

Cada DataTable no DataSet corresponde à sua região "TableStart:..." correspondente por nome, e os campos escalares preenchem os valores de cabeçalho na mesma passagem.

Para equipes com fluxos de trabalho de documentos como estes aguardando uma implementação .NET limpa, a Iron Suite agrupa o IronWord junto com IronPDF, IronOCR, IronXL e IronBarcode em uma única licença.

Comece um teste gratuito, sem necessidade de cartão de crédito.

Por que isso funciona

Algumas coisas distinguem esta abordagem das alternativas:

Sintaxe nativa do Word. Modelos são projetados no Microsoft Word, usando as ferramentas de campo de mesclagem que o Word já fornece. Salve como .docx, entregue o arquivo ao IronWord, e a mesclagem será executada. Sem linguagem de modelo proprietária, sem camada de tradução, sem curva de aprendizado separada para a equipe que projeta os documentos.

Ambos os formatos de campo simples e complexo. O Word produz duas estruturas de campo distintas, dependendo de como o campo foi inserido. IronWord lida com ambos, o que significa que modelos existentes projetados por diferentes membros da equipe de maneiras diferentes funcionam sem modificação.

Sem dependências externas. A biblioteca é executada inteiramente em .NET. Sem instalação do Word, sem COM, sem licença do Office, sem fragilidade de interop. O mesmo código que é executado em uma máquina desenvolvedora Windows executa-se identicamente em um contêiner Linux, uma Função Azure ou um agente de compilação sem servidor.

Resumo

A mesclagem de correspondência tem sido uma lacuna de longa data no espaço de ferramentas de documentos .NET, e as soluções alternativas não envelheceram bem. A mesclagem de correspondência nativa do IronWord fecha essa lacuna com um modelo que espelha a própria sintaxe de campo de mesclagem do Word, suporta tanto valores simples quanto regiões repetidas, e roda sem qualquer bagagem de implantação que historicamente acompanha a automação de documentos em .NET.

Para equipes que geram faturas, etiquetas, cartas, contratos e relatórios em escala, este é o caminho mais limpo de um único modelo para milhares de documentos personalizados.