Use MailMerge in .NET on Linux to Generate Pixel-Perfect PDFs from DOCX Templates

Many business applications offer the core functionality of creating customized, high-quality documents, such as invoices, quotes, and contracts. With MailMerge ╰ TX Text Control .NET Server for ASP.NET
╰ DocumentServer Namespace
╰ MailMerge Class
The MailMerge class is a .NET component that can be used to effortlessly merge template documents with database content in .NET projects, such as ASP.NET web applications, web services or Windows services. , companies can automate this process by merging structured data into templates compatible with MS Word. These templates can then be used to generate pixel-perfect PDF documents for archiving, sharing, or electronic signing.

What is MailMerge?

MailMerge is a process that allows you to populate placeholders in a document template with dynamic data from external sources, such as JSON, databases, or XML. It enables you to create fully formatted, data-driven documents automatically, without manually editing the content.

MailMerge is ideal for:

• Generating invoices, quotes, contracts, and reports
• Sending personalized letters or notifications
• Populating tables with multiple records (e.g., invoice line items)

Templates form the foundation of an effective mail merge workflow. Typically created as DOCX (Office Open XML) documents or in another supported format, templates include merge fields, which are placeholders replaced with actual data during the merging process.

Integrated Template Design

TX Text Control provides a fully programmable, embeddable Document Editor to empower users to create and maintain these templates directly within your web application. The editor supports all major front-end frameworks, including ASP.NET Core, Angular, Blazor, React or JavaScript.

With the built-in editor, you can load and edit DOCX templates directly in the browser. You can also insert and configure merge fields visually, preview and test templates with live data, and store templates in a database or document management system. These features enable your users to work entirely within your application ecosystem without needing Microsoft Word or any other external tools.

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

You need to download and install the trial version of TX Text Control .NET Server for ASP.NET.

• Download Trial Version
  Setup download and installation required.

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

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. Enter a project name and choose a location to save the project. Confirm with Next.

4. Choose .NET 8.0 (Long Term Support) as the Framework.

5. Enable the Enable container support checkbox and choose Linux as the Container OS.

6. Choose Dockerfile for the Container build type option and confirm with Create.

   

Adding the NuGet Packages

7. In the Solution Explorer, select your created project and choose Manage NuGet Packages... from the Project main menu. Select Text Control Offline Packages as the Package source.

   Install the following package:

   • TXTextControl.TextControl.Core.SDK

   

Data Object

In this example, we will use a simple data object containing the information to be merged into the template. This object can be a class, a record, or any other type of structure that holds the necessary information. In this tutorial, we will use a simple invoice object representing an invoice with a customer's name and address and a list of items with descriptions and prices.

8. In the Solution Explorer, right-click on the project and choose Add > Class.... Name the class Invoice.cs and confirm with Add. Copy the following code into the Invoice.cs 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; }
   	}

   view raw test.cs hosted with ❤ by GitHub

Template Design

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 item, which will be populated with the data from the Invoice object. The screenshot below shows the template in the TX Text Control Document Editor:

The class is converted into JSON with sample data to fill the drop-downs with the available field names, and then the data structure is loaded into the editor. Then, the template is saved as a DOCX file and loaded into the editor.

9. Download the invoice template and save it in the project directory.

Using ServerTextControl and MailMerge

10. Find the Program.cs file in the Solution Explorer and replace the code with the following code snippet:

    	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);
    	}
    	}

    view raw test.cs hosted with ❤ by GitHub

Run with Docker

11. Select Container (Dockerfile) as the startup profile and start the application.

    

Run with WSL

For a faster development experience, you can run the application in WSL (Windows Subsystem for Linux).

• Select WSL as the startup profile and start the application.

  

Enable WSL (Windows Subsystem for Linux)

In case you haven't enabled WSL yet, follow these steps:

Enable WSL (Windows Subsystem for Linux)

1. Open PowerShell as an administrator.

2. Run the following command:

   wsl --install

   This installs the default Linux distribution (usually Ubuntu) and enables necessary features.

3. After the installation, restart your computer.

Set WSL 2 as the Default Version

To set WSL 2 as the default version, follow these steps:

1. Open PowerShell as an administrator.

2. Run the following command:

   wsl --set-default-version 2

3. If you haven't installed a Linux distribution yet, you can do so via:

   wsl --install -d Ubuntu

Conclusion

In this tutorial, we have demonstrated how to create a simple .NET console application that uses TX Text Control's MailMerge functionality to generate a PDF document from a template and data object. The process involves creating a data object, designing a template, and using the ServerTextControl class to perform the mail merge operation.

TX Text Control allows you to easily integrate document generation capabilities into your .NET applications. This enables you to automate the creation of customized documents, such as invoices, quotes, and contracts.