TPDF 0.4.6

TPDF

TPDF is a .NET package for Word/DOCX workflows:

• Convert DOCX to PDF with the packaged in-process TPDF/LibreOffice runtime.
• Render Word MERGEFIELD mail-merge templates with the managed TPDF.MailMerge assembly.
• Merge a template and convert it directly to PDF without asking the caller to save an intermediate DOCX.

The package currently targets Linux x64 and Windows x64.

Install

dotnet add package TPDF

The package carries the native Linux and Windows TPDF runtimes. Its transitive build target copies the native library and tpdf-runtime folder beside your app output.

Convert DOCX To PDF

using TPDF;

Tpdf.ConvertDocxToPdf("input.docx", "output.pdf");

You can also pass DOCX bytes. TPDF still creates a temporary DOCX internally because the native converter is path-based, but your application does not have to persist or manage that file.

byte[] docxBytes = File.ReadAllBytes("input.docx");

Tpdf.ConvertDocxToPdf(docxBytes, "output.pdf");
byte[] pdfBytes = Tpdf.ConvertDocxToPdf(docxBytes);

Mail Merge Only

Use the Tpdf facade when you want to render a Word mail-merge template to a DOCX.

using TPDF;
using TPDF.MailMerge;

var data = new MailMergeData(
    Fields: new Dictionary<string, MailMergeValue>(StringComparer.OrdinalIgnoreCase)
    {
        ["OrderId"] = new MailMergeValue.Text("TPDF-ORDER-001"),
        ["CustomerName"] = new MailMergeValue.Text("Morten Gryning"),
        ["SalesPrice"] = new MailMergeValue.Text("249.900 kr.")
    },
    Regions: new Dictionary<string, IReadOnlyList<IReadOnlyDictionary<string, MailMergeValue>>>(StringComparer.OrdinalIgnoreCase)
    {
        ["CarEquipments"] = new[]
        {
            new Dictionary<string, MailMergeValue>(StringComparer.OrdinalIgnoreCase)
            {
                ["Name"] = new MailMergeValue.Text("Vinterhjul"),
                ["Price"] = new MailMergeValue.Text("8.000 kr.")
            },
            new Dictionary<string, MailMergeValue>(StringComparer.OrdinalIgnoreCase)
            {
                ["Name"] = new MailMergeValue.Text("Adaptiv fartpilot"),
                ["Price"] = new MailMergeValue.Text("12.000 kr.")
            }
        }
    });

Tpdf.MergeMailMergeTemplate("template.docx", "merged.docx", data);

For an in-memory merge:

byte[] mergedDocx = Tpdf.MergeMailMergeTemplate("template.docx", data);

For templates that do not need merge data, use an empty data object:

Tpdf.MergeMailMergeTemplate("template.docx", "merged.docx", new MailMergeData());

// or
Tpdf.MergeMailMergeTemplate("template.docx", "merged.docx", MailMergeData.Empty);

For stream-oriented code:

using var template = File.OpenRead("template.docx");
using var merged = File.Create("merged.docx");
Tpdf.MergeMailMergeTemplate(template, merged, data);

DTO Adapter

If your existing code prepares report DTOs for Aspose-style mail merge, you can build MailMergeData from those DTOs instead of hand-writing dictionaries.

using TPDF;
using TPDF.MailMerge;

var data = new MailMergeDataBuilder()
    .AddFieldsFromObject(reportDto)
    .AddRegion("CarEquipments", reportDto.CarEquipments)
    .Build();

Tpdf.MergeMailMergeTemplate("template.docx", "merged.docx", data);

Single fields are flattened using dot notation, so reportDto.Buyer.Name becomes Buyer.Name. Byte arrays become image values for fields such as Image:LogoStream. Collection properties are skipped during field flattening so lists can be added deliberately as named regions.

For compact code, a DTO can also be converted directly:

var data = reportDto.ToMailMergeData();

Region rows can come from regular objects, dictionaries, or existing MailMergeValue rows:

var data = new MailMergeDataBuilder()
    .AddFieldsFromObject(reportDto)
    .AddRegion("Items", items.Select(i => new { i.Name, i.Price }))
    .Build();

Use MailMergeObjectAdapterOptions when you want predictable formatting:

using System.Globalization;

var options = new MailMergeObjectAdapterOptions
{
    Culture = CultureInfo.GetCultureInfo("da-DK"),
    DateTimeFormat = "dd-MM-yyyy",
    FloatingPointFormat = "N"
};

var data = new MailMergeDataBuilder()
    .AddFieldsFromObject(reportDto, options: options)
    .AddRegion("Items", reportDto.Items, options)
    .Build();

Merge And Convert To PDF

For the common server flow, merge first and pass the merged DOCX bytes straight into the converter:

byte[] mergedDocx = Tpdf.MergeMailMergeTemplate("template.docx", data);

byte[] pdfBytes = Tpdf.ConvertDocxToPdf(mergedDocx);

Or use the combined helper:

Tpdf.ConvertMailMergeTemplateToPdf("template.docx", "output.pdf", data);
byte[] pdfBytes = Tpdf.ConvertMailMergeTemplateToPdf("template.docx", data);

The combined helper does not require the caller to save merged.docx. Internally it renders the merged DOCX in memory, writes a temporary DOCX for the native TPDF converter, reads or writes the PDF result, and removes the temporary folder.

Template Support

TPDF.MailMerge is designed for Word mail-merge templates and aims to match common Aspose.Words mail-merge output. Aspose is not used at runtime. It supports:

• Regular Word MERGEFIELD fields.
• Repeating regions using TableStart:RegionName and TableEnd:RegionName.
• Image fields such as Image:LogoStream with PNG byte values.
• Word IF field structures used in mail-merge templates.
• Headers, footers, text boxes, VML/DrawingML image placeholders, and common OpenXML field shapes.

It does not use the custom <<[Field]>> syntax. That syntax was only used by internal comparison tooling.

Data Model

MailMergeData.Fields supplies single-record values:

["OrderId"] = new MailMergeValue.Text("TPDF-ORDER-001")

MailMergeData.Regions supplies repeated rows for fields wrapped in TableStart: / TableEnd::

["Items"] = new[]
{
    new Dictionary<string, MailMergeValue>
    {
        ["Name"] = new MailMergeValue.Text("Line item"),
        ["Price"] = new MailMergeValue.Text("100 kr.")
    }
}

For image merge fields, the template field is usually named Image:LogoStream, while the data key is LogoStream:

["LogoStream"] = new MailMergeValue.ImagePng(File.ReadAllBytes("logo.png"))

Runtime Lifecycle

Tpdf.Initialize() is optional. Call it during application startup if you want to warm up the runtime and catch startup/configuration errors early. If you skip it, the first conversion initializes the runtime automatically.

Tpdf.Initialize();

TPDF uses a process-lifetime LibreOffice runtime singleton and does not spawn soffice. Conversions are serialized internally to respect the embedded LibreOffice runtime contract.

Tpdf.Shutdown() exists for API completeness, but native runtime unload is not currently supported.

Deployment Notes

The NuGet package copies:

• TPDF.Managed.dll
• TPDF.MailMerge.dll
• libtpdf.so on Linux, or tpdf.dll on Windows
• the sibling tpdf-runtime folder required by the converter

For app deployment, publish/copy the application output folder with those runtime files intact.