wordnet 1.6.0

wordnet

Document conversion and automation for .NET. Create, edit and convert Word documents with local processing, bounded resource use and explicit fidelity diagnostics.

This source and package target 1.6.0. The release notes and tested source matrix describe the admitted feature profiles and their limits. The NuGet badge and releases show published availability. Roadmap #138 remains open for broader combinations and qualification.

• Convert DOC and DOCX to and from PDF, Markdown, text, EPUB, MOBI, AZW3, HTML and RTF. Export Word documents to XPS.
• Populate templates with mail-merge fields, repeated table rows, conditional content and caller-supplied images.
• Compose documents and export editable DOCX or selectable-text PDF without Microsoft Office or a remote service.
• Add optional local English OCR for scanned PDFs.
• Render managed PDF/XPS and SVG previews, with optional PNG previews and documented PDF/A-2b and PDF/UA-1 profiles.
• Inspect documents before conversion and enforce configurable resource limits with explicit fidelity diagnostics.

Windows and Linux · x64 and ARM64 · MIT licensed

Quick start · Automation recipes · Supported formats · Documentation

Install

dotnet add package wordnet

The public namespace is WordNet. NuGet package and assembly names use wordnet. The core package includes wordnet.Fonts and supports managed document export without native providers.

For all PDF input, including digital PDFs, install the optional provider at the same version:

dotnet add package wordnet.Ocr

This provider also supplies PNG previews and optional native typography. English OCR additionally requires a local Tesseract 5 library and eng.traineddata. See the OCR setup guide and deployment requirements.

New in 1.6.0

• Bounded DOCX theme/table handling, typed-control ownership and creation, and selected fragment composition.
• Explicit review displays and comparison options, deeper bounded reports, cross-tab placement and conservative table formulas.
• Selected chart, vector, text-box and equation extensions with diagnostics for known reference differences.
• Bounded typography, accessible and tagged archival output profiles, DOTX/OTT identities and preview-layout inspection.
• Template inspection and a narrow in-process DOCX-to-PDF policy plan; general policy enforcement remains open.

These are bounded profiles, not blanket support for arbitrary combinations. See the 1.6.0 release notes, source matrix and linked feature profiles before adopting them. Use matching versions of all three packages.

Previous: 1.5.0

• Improved DOCX defaults, paragraph marks, managed table sizing and footnote layout.
• Typed custom-property fields, deterministic numeric/date pictures, bounded nested IF fields and STYLEREF running headers.
• Opt-in checkbox, list, date and rich-text content controls with explicit local XML binding.
• Mixed and master-detail report regions, count/sum cross-tabs and caller-supplied document fragments.
• Bounded formatting revisions, whole-paragraph moves, matching-section comparison and header/footer text revisions.
• Quarter-turn and shrink-to-fit text boxes, linked box chains and editable line, ellipse and rounded-rectangle shapes.

See the 1.5.0 release notes and capability matrix for migration guidance and supported combinations. The 1.5.0 drawing extensions require ordinary managed fixed output; tagged/archive PDF and native typography combinations remain outside that earlier profile. Use matching versions of all three packages.

Quick start

Convert a DOCX document to PDF and inspect any reported fidelity losses. Stage output before replacing an existing file:

using System;
using System.IO;
using System.Threading;
using WordNet;

using var source = File.OpenRead("input.docx");
using var staged = new MemoryStream();
using var cancellation = new CancellationTokenSource(TimeSpan.FromSeconds(30));

var options = new ConversionOptions(
    FidelityMode.BestEffort,
    maximumInputBytes: 16 * 1024 * 1024,
    maximumOutputBytes: 32 * 1024 * 1024,
    maximumPages: 100);

var converter = new WordConverter();
ConversionResult result = await converter.ConvertAsync(
    source, staged, DocumentFormat.Docx, DocumentFormat.Pdf,
    options, cancellation.Token);

foreach (ConversionDiagnostic diagnostic in result.Diagnostics)
    Console.WriteLine($"{diagnostic.Code}: {diagnostic.Message}");

File.WriteAllBytes("output.pdf", staged.ToArray());

Strict mode is the default and rejects detected unsupported features before copying output. Best effort retains supported content and reports losses. Lenient mode additionally approximates documented layout problems. Malformed input, resource limits, cancellation and I/O errors can still fail in every mode.

For DOCX byte arrays, ConvertToPdf and ConvertToHtml offer in-memory shortcuts with overloads that return diagnostics.

DOC and PDF import always report formatting or reconstruction loss and require best effort or lenient mode. Use Inspect / InspectAsync for preflight diagnostics, source locations, font mappings and optional fixed-page layout. CanConvert describes format pairs; it does not guarantee support for every feature in a document.

See conversion usage and diagnostics.

Automation recipes

WordDocument provides bounded creation, editing, composition and template sessions:

using System.IO;
using WordNet;

WordDocument document = WordDocument.Create();
document.AddParagraph("Quarterly report", headingLevel: 1);
document.AddParagraph("Completed 18 projects this quarter.");

using var output = new MemoryStream();
document.Save(output, DocumentFormat.Docx);
File.WriteAllBytes("report.docx", output.ToArray());

From a source checkout, one command generates a complete invoice and a two-section report, each as editable DOCX and PDF:

dotnet run --project examples/WordNet.Automation -c Release -- artifacts/automation-sample

The invoice includes repeated line items, a caller-provided logo, optional payment terms and totals calculated in application code. The report includes a summary table, header/footer and page fields refreshed during PDF layout. Both recipes print load, edit and save diagnostics and stage conversions before replacing files.

See the recipe instructions and editing and template guide for syntax, limits and expected losses.

To populate an existing template containing a MERGEFIELD Customer field:

using System;
using System.IO;
using WordNet;

var options = new ConversionOptions(FidelityMode.BestEffort);
using var template = File.OpenRead("template.docx");
WordDocument document = WordDocument.Load(
    template, DocumentFormat.Docx, out ConversionResult loadResult, options);
foreach (ConversionDiagnostic diagnostic in loadResult.Diagnostics)
    Console.WriteLine($"{diagnostic.Code}: {diagnostic.Message}");

DocumentEditResult mergeResult = document.Merge(new { Customer = "Example Company" });
foreach (ConversionDiagnostic diagnostic in mergeResult.Diagnostics)
    Console.WriteLine($"{diagnostic.Code}: {diagnostic.Message}");

using var output = new MemoryStream();
ConversionResult result = document.Save(output, DocumentFormat.Docx);
foreach (ConversionDiagnostic diagnostic in result.Diagnostics)
    Console.WriteLine($"{diagnostic.Code}: {diagnostic.Message}");

File.WriteAllBytes("letter.docx", output.ToArray());

Templates use caller-supplied data and images. They do not execute arbitrary code or fetch remote resources.

Supported formats

Each earlier bidirectional exchange below works with both DOC and DOCX. ODT exchanges with DOCX and exports directly to PDF; HTML also exports directly to PDF. Other pairs require DOC or DOCX on one side. XPS is output-only.

The shared layout profile includes section geometry, wrapping and pagination, table widths/merges/repeated headers, bounded drawings, notes and page fields. Optional profiles cover Arabic typography, semantic PDF/UA and previews. These capabilities have specific combination and fidelity limits.

PDF import reconstructs editable content; it does not recover arbitrary original tables, styles or pagination. OCR targets English printed text, with optional rotation/deskew and known two-column reading order. Handwriting is outside the profile.

Password encryption/decryption and DOCX/PDF digital signatures are not implemented and are excluded from the current roadmap at the owner's request. Password-protected input and signed-document workflows remain unsupported; no confidentiality, signature-validity or signer-trust utility is provided. Release 1.3.0 implements the bounded chart/equation subset described above; advanced charts and general mathematical layout remain unsupported. Default DOCX loads render revisions in their accepted state with diagnostics; Strict rejects revision/comment loss. The merged opt-in review profile preserves its declared subset separately. Complete Word pagination parity and arbitrary drawing/CSS behavior are not guaranteed.

See the fidelity profile, DOC subset and interoperability guide.

English OCR

Add matching wordnet.Ocr, then provide a local Tesseract 5 C API library and a directory containing eng.traineddata. Native dependencies must match the application process architecture. Configure EnglishOcrOptions with absolute data-directory and native-library paths, and pass it to ConversionOptions(englishOcr: ...).

On Linux, provision libtesseract5, libfontconfig1 and usable fallback fonts. On Windows, supply the absolute Tesseract DLL path. Recognition runs locally; models are never downloaded during conversion. Orientation correction, two-column prose order and word/line confidence metadata are optional; confidence is not an accuracy guarantee.

See OCR setup and tests, the prerequisite script and OCR metadata. Tesseract and language data are supplied by the host, not included in the NuGet package.

Frameworks and platforms

The library targets net462, net472, netstandard2.0, net8.0 and net10.0 with matching public APIs.

Applications running on actual Framework 4.7.2 x64 must configure the legacy JIT, preserving existing binding redirects:

<configuration>
  <runtime>
    <useLegacyJit enabled="1" />
  </runtime>
</configuration>

The library cannot configure its host runtime. Compilation and package compatibility are separate from runtime qualification. See minimum-runtime requirements and build-specific test evidence.

Streams and resource limits

Caller streams remain open. Reading and writing begin at their current positions; output is not truncated. Supply distinct streams and a fresh destination.

Output is staged inside the converter. Parsing, fidelity and admission-limit failures leave caller output untouched; cancellation or I/O errors during final copying can leave partial output. Opening a destination with File.Create already truncates it, which is why the quick start stages in memory first.

Defaults bound input to 16 MiB, output to 32 MiB, container expansion to 64 MiB, ZIP entries to 1,024, characters to four million, nesting to 64 and pages to 1,000. These are admission checks, not hard CPU/RSS limits. Async methods use async stream I/O; parsers, renderers and most native calls execute synchronously.

XML entities and DTDs are prohibited. Conversion does not execute scripts/macros or fetch remote resources. For untrusted workloads and hard deadlines, use isolated hosting.

Build and test

Install the pinned SDK from global.json, plus .NET 8/10 runtimes. Provision local OCR prerequisites in the same PowerShell process that launches tests:

./eng/prepare-ocr-tests.ps1
dotnet restore wordnet.sln --locked-mode
dotnet build wordnet.sln -c Release --no-restore
dotnet test tests/wordnet.Conversion.Tests -c Release -f net8.0 --no-build --no-restore
dotnet test tests/wordnet.Conversion.Tests -c Release -f net10.0 --no-build --no-restore
dotnet format wordnet.sln --verify-no-changes --no-restore
./eng/pack.ps1

Linux requires Tesseract, fontconfig and the documented fonts. Run Framework tests only on a compatible Windows host. See testing for full prerequisites and platform limits, and the comparison harness for 24 independently authored business fixtures and office-reference measurements.

Documentation

License and support

MIT · Copyright © 2026 Armen Kirakosyan.

Implementation uses independently authored code, published specifications and appropriately licensed dependencies. See third-party and font notices.

Report bugs and feature requests through GitHub Issues. To support development, donate on Patreon.