Raw capture — raw/csharp-document-generation-developer-guide-for-dotnet.md

url: https://www.textcontrol.com/blog/2026/07/08/csharp-document-generation-developer-guide-for-dotnet/ title: "C# Document Generation: A Developer's Guide for .NET" author: Deepika Kathiravan date_fetched: 2026-07-18 date_published: 2026-07-08 site: Text Control Blog

C# Document Generation: A Developer's Guide for .NET

Author: Deepika Kathiravan Published: July 8, 2026 Tags: ASP.NET, Reporting, ASP.NET Core, Document Generation, PDF

Core Definition

The article defines document generation as "the automatic creation of documents from application data" using approaches like building in code, converting from HTML, or populating templates with data from databases, APIs, or user input. Output formats are typically PDF, DOCX, or HTML. The author focuses primarily on the template-based model, where a pre-designed document with merge fields is populated at runtime.

The Four Approaches

1. Code-Built (Programmatic)

Documents are constructed element-by-element in code (paragraphs, fonts, tables, images). Offers complete control and no external template files, but "the layout lives inside your source" — every wording or branding change requires a developer and redeployment. Design-heavy documents create "long, brittle construction methods that no non-developer can touch."

2. HTML-to-PDF Conversion

An HTML document is generated (often via a templating engine) and then rendered to PDF. Efficient for those already familiar with HTML/CSS, but "HTML and CSS were designed for screens, not paginated print." Precise page control — headers/footers, page breaks across tables, exact margins, reliable numbering — is difficult. Business users remain dependent on developers since editing happens in markup.

3. Headless-Format Libraries

These libraries manipulate file formats like DOCX and PDF entirely in code without a UI. Many support mail merge for programmatic template population. Offers broad format coverage and strong server-side performance, but "there is no editing surface at all." If users need to author or review documents, you must pair the library with a separate editor and maintain the integration.

4. Template-Based with Document Model and Editor

Templates are designed as documents in any word processor or editor, with merge fields added. The same document model supports both authoring and generation. "It can run fully headless on the server for automated generation, while still offering an editor when users need to author or edit documents." Content owners can maintain templates without developer involvement. Paginated layout, tables, headers, and footers are native features.

The Key Question: Who Owns the Template?

The article's central thesis: "when the document needs to change, who can change it?" In code-built and HTML-to-PDF approaches, the template lives in source code — every adjustment is a developer ticket, code review, and deployment. In headless libraries, the template can be a separate file, but without an editor in the toolkit, changing it still falls to developers. With a template-based document model, business users can revise content in tools they already know, "without touching application code."

End-to-End Pipeline in One .NET Stack

The author describes four stages handled within a single coherent SDK:

  1. Author — Templates designed in any word processor or an embeddable editor (WinForms, WPF, ASP.NET Core with JavaScript/Angular/React). Business users control layout; developers expose the editing surface.

  2. Generate — The merge engine loads a template, assigns data, performs the merge, and outputs the finished document. Capable engines handle nested merge blocks for master-detail data, line items, and image merge fields.

  3. Render — Merged documents export as PDF or PDF/A for archiving, or to other formats, without Microsoft Office or Adobe Acrobat on the server.

  4. Sign — The pipeline can carry documents into electronic signature workflows, making signing "a stage of the process rather than an additional platform to integrate."

Code Example

using TXTextControl.DocumentServer;

TXTextControl.LoadSettings ls = new TXTextControl.LoadSettings()
{
    ApplicationFieldFormat = TXTextControl.ApplicationFieldFormat.MSWord
};

string jsonData = File.ReadAllText("data.json");

using (TXTextControl.ServerTextControl tx = new TXTextControl.ServerTextControl())
{
    tx.Create();
    tx.Load("template.docx", TXTextControl.StreamType.WordprocessingML, ls);

    using (MailMerge mailMerge = new MailMerge())
    {
        mailMerge.TextComponent = tx;
        mailMerge.MergeJsonData(jsonData);
    }

    TXTextControl.SaveSettings saveSettings = new TXTextControl.SaveSettings();
    tx.Save("result.pdf", TXTextControl.StreamType.AdobePDFA, saveSettings);
}

Key notes from the article: - ServerTextControl is a non-visual engine running server-side without UI or Microsoft Office - Use StreamType.AdobePDFA for long-term archiving; AdobePDF for standard PDF - MergeJsonData accepts a single JSON object or an array of objects - Merge fields must be recognized on load by setting ApplicationFieldFormat.MSWord

Decision Guide

The article offers a quick mapping: - Documents fully defined in code → code-built or HTML-to-PDF library suffices - Server-only file transformation, no human authoring → headless format library - Humans author, edit, or review documents requiring exact appearance → template-based document model - End-to-end lifecycle (author → generate → render → sign) → template-based model is "the lowest-maintenance path"

FAQ Highlights