TPDF 0.4.19

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.
• Merge multiple PDF documents into one final PDF.
• Stamp final PDF page numbers after conversion or after combining multiple PDFs.

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

Merge PDFs

Use MergePdfs when you have multiple final PDF documents and want one combined PDF. Do not concatenate DOCX or PDF byte arrays directly.

using TPDF;

byte[] firstPdf = Tpdf.ConvertDocxToPdf(firstDocxBytes);
byte[] secondPdf = Tpdf.ConvertDocxToPdf(secondDocxBytes);

byte[] combinedPdf = Tpdf.MergePdfs(firstPdf, secondPdf);

For file-based code:

Tpdf.MergePdfs(new[] { "first.pdf", "second.pdf" }, "combined.pdf");

If your workflow starts with a generated PDF and then appends an extra PDF, use AppendPdf to make the ordering explicit:

using TPDF;

byte[] generatedPdf = Tpdf.ConvertMailMergeTemplateToPdf("template.docx", data);
byte[] appendixPdf = File.ReadAllBytes("appendix.pdf");

byte[] finalPdf = Tpdf.AppendPdf(generatedPdf, appendixPdf);

For file-based code:

Tpdf.ConvertMailMergeTemplateToPdf("template.docx", "generated.pdf", data);
Tpdf.AppendPdf("generated.pdf", "appendix.pdf", "final.pdf");

Merge DOCX Documents To PDF

Use MergeDocxDocumentsToPdf when you have multiple DOCX documents and the final output should be one PDF. TPDF converts each DOCX to PDF and then merges the resulting PDFs, using the same behavior on Windows and Linux.

using TPDF;

byte[] combinedPdf = Tpdf.MergeDocxDocumentsToPdf(firstDocxBytes, secondDocxBytes);

For file-based code:

Tpdf.MergeDocxDocumentsToPdf(new[] { "first.docx", "second.docx" }, "combined.pdf");

Stamp PDF Page Numbers

Use StampPageNumbers after the final PDF has all pages. This matches the common Aspose-style flow where page numbers are added after the document is converted and combined.

using TPDF;

byte[] pdfBytes = Tpdf.ConvertDocxToPdf(docxBytes);
byte[] stampedPdfBytes = Tpdf.StampPageNumbers(pdfBytes);

For file-based code:

Tpdf.StampPageNumbers("input.pdf", "output.pdf");

The default format is {page}/{total}, for example 1/3, 2/3, 3/3. You can override the format, margins, font size, and style:

byte[] stampedPdfBytes = Tpdf.StampPageNumbers(pdfBytes, new PdfPageNumberStampOptions
{
    Format = "{page}/{total}",
    BottomMarginPoints = 0.2 * 72,
    RightMarginPoints = 0.5 * 72,
    FontSize = 10,
    Bold = true,
    Italic = true
});

TPDF uses bundled runtime fonts for the stamp so the default behavior does not depend on Calibri or Arial being installed on the host machine.

Add PDF Text Watermarks

Use AddTextWatermark after conversion or merging when you want an Aspose-style text watermark on every page of the final PDF.

using TPDF;

byte[] pdfBytes = Tpdf.ConvertDocxToPdf(docxBytes);
byte[] watermarkedPdfBytes = Tpdf.AddTextWatermark(pdfBytes, "PREVIEW");

For file-based code:

Tpdf.AddTextWatermark("input.pdf", "output.pdf", "PREVIEW");

The watermark options mirror the common Aspose text watermark and PDF stamp knobs: font family, font size, color, diagonal or horizontal layout, transparency, background or foreground placement, rotation, and page alignment.

byte[] watermarkedPdfBytes = Tpdf.AddTextWatermark(pdfBytes, "PREVIEW", new PdfTextWatermarkOptions
{
    FontFamily = "Arial",
    FontSize = 36,
    Color = PdfWatermarkColor.PaleVioletRed,
    Layout = PdfWatermarkLayout.Diagonal,
    IsSemitrasparent = false,
    IsBackground = false,
    RotationAngle = -40
});

TPDF writes the watermark as vector PDF text using the same bundled font fallback as page-number stamping.

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

Image Fields

Add PNG image bytes with AddImagePng. The data key should be the plain field name:

using TPDF;
using TPDF.MailMerge;

var data = new MailMergeDataBuilder()
    .AddField("Title", "Vehicle advertisement")
    .AddImagePng("AdImage", File.ReadAllBytes("vehicle-preview.png"))
    .AddImagePng("DealerLogo", File.ReadAllBytes("dealer-logo.png"))
    .Build();

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

In a regular Word mail-merge template, insert image fields as real Word MERGEFIELD fields with the Image: prefix:

MERGEFIELD Image:AdImage
MERGEFIELD Image:DealerLogo

Word usually displays those fields as «Image:AdImage» and «Image:DealerLogo».

In Estimatic-style text-placeholder templates, use either the explicit image form or the plain image field name:

<<[Image:AdImage]>>
<<[DealerLogo]>>

Both forms look up the same data keys passed to AddImagePng, so .AddImagePng("AdImage", bytes) can be inserted with either <<[Image:AdImage]>> or <<[AdImage]>>.

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);
byte[] stampedPdfBytes = Tpdf.StampPageNumbers(pdfBytes);

Or use the combined helper:

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

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.

For multi-template reports, merge each template to DOCX, combine those DOCX documents directly to one PDF, then stamp the final document:

var mergedDocxs = new List<byte[]>();

foreach (var templatePath in templatePaths)
{
    byte[] mergedDocx = Tpdf.MergeMailMergeTemplate(templatePath, data);
    mergedDocxs.Add(mergedDocx);
}

byte[] combinedPdf = Tpdf.MergeDocxDocumentsToPdf(mergedDocxs);
byte[] finalPdf = Tpdf.StampPageNumbers(combinedPdf);

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.
• Estimatic-style text placeholders such as <<[FieldName]>>, including image placeholders backed by PNG values.

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.

Printer access is disabled by default before LibreOffice starts, so hidden server-side conversions do not block on disconnected default or network printers. Test harnesses that deliberately need printer-dependent layout can opt in before Tpdf.Initialize() or the first conversion:

Tpdf.SetPrinterAccessEnabled(true);
Tpdf.Initialize();

The same opt-in is available from native code as tpdf_set_printer_access_enabled(1) or from tpdf-test with --enable-printer-access.

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.