TX Text Control's mail merge feature enables automated document generation by merging templates with structured data, such as from databases or JSON. It supports merge fields, conditional logic, and barcode integration, allowing users to dynamically create personalized reports, invoices, or letters.

This allows business users to create WYSIWYG templates using standard MS Word DOCX documents, eliminating the need for complex reporting tools or developer expertise. These templates can include merge fields, tables, conditional content, and images, making them highly flexible for creating personalized documents.

Why Use TX Text Control for Mail Merge?

The key benefit is pixel-perfect PDF output - the resulting documents look exactly like the original DOCX template, ensuring 100% layout fidelity. This means that business users can visually design templates in MS Word or the TX Text Control Document Editor available for any browser, preview them as they will appear, and then merge structured data (e.g., from a database, JSON, or XML) to create consistent, professional documents.

Because the rendering engine faithfully reproduces document layout in both screen and print output, it eliminates the common formatting inconsistencies found in traditional reporting solutions. The result is high-quality, accurate PDF documents that stay true to the original design - ideal for invoices, contracts, reports, and business correspondence.

This tutorial shows how to perform mail merge on an MS Word document with JSON data and convert the results to a PDF document.

Creating the Application

To demonstrate how easy this is with the TX Text Control library, we will use a .NET console application.

Make sure that you downloaded the latest version of Visual Studio 2022 that comes with the .NET 8 SDK.

Prerequisites

The following tutorial requires a trial version of TX Text Control .NET Server.

• Download Trial Version
  

1. In Visual Studio 2022, create a new project by choosing Create a new project.

2. Select Console App as the project template and confirm with Next.

3. Choose a name for your project and confirm with Next.

4. In the next dialog, choose .NET 8 (Long-term support) as the Framework and confirm with Create.

Adding the NuGet Package

5. In the Solution Explorer, select your created project and choose Manage NuGet Packages... from the Project main menu.

   Select Text Control Offline Packages from the Package source drop-down.

   Install the latest versions of the following package:

   • TXTextControl.TextControl.ASP.SDK

   

Data Object

For this tutorial, we will use a simple Invoice object that represents an invoice with a customer name, address, and a list of items with a description and price.

6. Create a new class file in your project and name it InvoiceData.cs. Copy and paste the following code into the file:

   public class Invoice
   {
       public string InvoiceNumber { get; set; }
       public DateTime InvoiceDate { get; set; }
       public DateTime DueDate { get; set; }
       public decimal AmountDue { get; set; }
       public Customer Customer { get; set; } = new Customer();
       public List<LineItem> LineItems { get; set; } = new List<LineItem>();
   }
   
   public class Customer {
       public string CustomerName { get; set; }
       public string CustomerAddress { get; set; }
   }
   
   public class LineItem
   {
       public string Item { get; set; }
       public string Description { get; set; }
       public int Quantity { get; set; }  
       public decimal Price { get; set; }  
       public decimal Total { get; set; }  
   }

Template

For this tutorial, we will use a simple MS Word template that includes merge fields for the invoice data. The template contains simple text fields and a table for the line items.

Mail Merge

7. Copy your MS Word template into the project folder and name it template.docx.

8. Find the Program.cs file in your project and replace the content with the following code:

   using TXTextControl.DocumentServer;
   using TXTextControl;
   
   // Create invoice object
   Invoice invoice = CreateInvoice();
   
   // Process document generation
   GenerateInvoiceDocument(invoice, "template.docx", "output.pdf");
   
   static Invoice CreateInvoice()
   {
       return new Invoice
       {
           InvoiceNumber = "12345",
           InvoiceDate = DateTime.Parse("2020-01-01"),
           DueDate = DateTime.Parse("2020-01-31"),
           AmountDue = 123.45m,  // Use decimal for currency
           Customer = new Customer
           {
               CustomerName = "John Doe",
               CustomerAddress = "123 Main St., Springfield, IL 62701"
           },
           LineItems = new List<LineItem>
               {
                   new LineItem
                   {
                       Item = "1",
                       Description = "Widget",
                       Quantity = 2,   // Use integer for quantity
                       Price = 45.00m, // Use decimal for price
                       Total = 90.00m
                   },
                   new LineItem
                   {
                       Item = "2",
                       Description = "Gadget",
                       Quantity = 1,
                       Price = 78.45m,
                       Total = 78.45m
                   }
               }
       };
   }
   
   static void GenerateInvoiceDocument(Invoice invoice, string templatePath, string outputPath)
   {
       using (ServerTextControl tx = new ServerTextControl())
       {
           tx.Create();
   
           var loadSettings = new LoadSettings
           {
               ApplicationFieldFormat = ApplicationFieldFormat.MSWord,
               LoadSubTextParts = true
           };
   
           tx.Load(templatePath, StreamType.WordprocessingML, loadSettings);
   
           using (MailMerge mailMerge = new MailMerge { TextComponent = tx })
           {
               mailMerge.MergeObject(invoice);
           }
   
           tx.Save(outputPath, StreamType.AdobePDF);
       }
   }

Run the Application

9. Run the application by pressing F5. When the application is finished, you will find the generated PDF document in the project folder.

The following screenshot shows the resulting PDF document:

Conclusion

TX Text Control's mail merge feature allows business users to create personalized documents by merging templates with structured data. This tutorial demonstrates how to perform a mail merge on an MS Word document with JSON data and convert the results to a PDF document using TX Text Control .NET Server.