Ofdrw.Net.Packaging 0.1.0-preview.6

Ofdrw.Net

Ofdrw.Net is a preview-stage .NET SDK and CLI for OFD document packaging, reading, editing, rendering, conversion, and signature-integrity workflows.

免责声明（请在使用前阅读）

本项目当前处于早期阶段（MVP/预览版），实现目标是为 .NET 生态提供 OFD 文档生成、读取与格式转换能力。

• 本项目并非官方标准实现，也不构成对任何国家/行业标准合规性的承诺。
• 在医疗、档案、司法、政务等高风险场景中使用前，请自行完成充分的功能验证、兼容性验证与安全评估。
• 与签名、签章、加密、长期保存、合规审计相关的能力当前仅部分实现或预留扩展点，不应默认视为满足生产要求。
• 因使用本项目造成的直接或间接损失，使用者应自行评估并承担相应风险。

Acknowledgements

• 本项目在模块划分、能力边界与目标方向上参考了原项目 ofdrw/ofdrw（OFD Reader & Writer, Java）。
• 感谢原项目为 OFD 生态提供的开源实践与 API 设计思路。本项目为 .NET 生态下的独立实现，不隶属于原项目。

Capabilities

See docs/feature-parity.md for the maintained OFDRW comparison, completed hardening work, and remaining production gaps. See conversion contracts for page selection, original-text diagnostics, font initialization, resource budgets, and editing behavior. See the OFD format tutorials for a progressive walk through GB/T 33190 package structure, pages, text, paths, images, templates, and signatures, plus OFD-H medical-record profile notes, mapped to both ofdrw and this repository.

• OFD core models, document builder API, globally unique object IDs, layers, templates, text runs, vector paths, images, fonts, attachments, annotations, and custom tags.
• Bounded OFD ZIP loading with path traversal, entry count, expanded-size, and compression-ratio checks.
• Standard package writing with OFD.xml, document/page/resource references, attachments, custom tags, templates, and preserved extension entries.
• Loss-aware reading that keeps unknown XML nodes and package entries available for round-trip workflows.
• Text extraction, page reorder/removal/crop, and self-contained document merge helpers.
• PDF to OFD dual-layer conversion with rendered pages for visual fidelity and transparent, positioned OFD text objects for search and extraction.
• Direct DOCX/OpenXML to native OFD text conversion without PDF, plus an optional dual-layer mode that combines rendered pages with the original DOCX text.
• OFD to PDF conversion with templates, layers, embedded fonts, positioned text runs, vector paths, images, crop origins, image transforms, opacity, and path clipping.
• OFD page to self-contained SVG conversion with template vectors, text, colors, transforms, and embedded images.
• OFD signature description generation through a pluggable signed-value provider.
• SM3, SHA-1, and SHA-256 protected-entry digest verification plus pluggable SignedValue.dat verification.
• Command-line conversion, extraction, editing, SVG, and signature verification tools packaged as Ofdrw.Net.Cli.

DocxConversionOptions.OfdMode defaults to Native: DOCX/OpenXML text is written directly as visible OFD TextObject elements and no PDF renderer is invoked. Select DualLayer when Word-compatible visual fidelity matters; Word, LibreOffice, or BuiltIn then supplies page images while the machine-readable layer still comes directly from the original DOCX/OpenXML rather than PDF extraction. DocxConversionEngine.Auto prefers Microsoft Word on macOS, then LibreOffice, and finally BuiltIn for that rendered path. PDF-to-OFD independently retains extractable PDF words as transparent OFD text unless PdfToOfdOptions.TextLayerMode is None.

For Developers

All packages are published on NuGet. The current preview release is 0.1.0-preview.6. See the release notes.

Which package should I install?

• For most format-conversion applications, install Ofdrw.Net.Converter. It brings in the DOCX, PDF, and SVG converters.
• For one conversion direction only, install the matching Converter.Docx, Converter.Pdf, or Converter.Svg package to keep dependencies narrower.
• For programmatic OFD generation and editing, install Ofdrw.Net.Layout together with Ofdrw.Net.Packaging; add Ofdrw.Net.Reader when loading or extracting content from existing OFD files.
• For signature creation or verification, add Ofdrw.Net.Signatures separately. It is not included by the conversion meta-package.
• For shell scripts and interactive use, install Ofdrw.Net.Cli as a global .NET tool instead of adding it to an application project.
• Ofdrw.Net.Core and Ofdrw.Net.Converter.Abstractions are primarily building blocks. Install them directly only when using the models/contracts alone or implementing a custom converter.

Published packages:

Install the high-level conversion package:

dotnet add package Ofdrw.Net.Converter --version 0.1.0-preview.6

For a narrower dependency surface, install the PDF converter package directly:

dotnet add package Ofdrw.Net.Converter.Pdf --version 0.1.0-preview.6

Install DOCX conversion independently:

dotnet add package Ofdrw.Net.Converter.Docx --version 0.1.0-preview.6

Install SVG or signature support independently:

dotnet add package Ofdrw.Net.Converter.Svg --version 0.1.0-preview.6
dotnet add package Ofdrw.Net.Signatures --version 0.1.0-preview.6

Convert PDF to OFD:

using Ofdrw.Net.Converter.Pdf.Converters;

await using var input = File.OpenRead("input.pdf");
await using var output = File.Create("output.ofd");

var converter = new PdfToOfdConverter();
await converter.ConvertAsync(input, output);

Convert DOCX to PDF or OFD:

using Ofdrw.Net.Converter.Docx.Converters;

await using var docx = File.OpenRead("input.docx");
await using var pdf = File.Create("output.pdf");
await new DocxToPdfConverter().ConvertAsync(docx, pdf);

await using var secondDocx = File.OpenRead("input.docx");
await using var ofd = File.Create("output.ofd");
await new DocxToOfdConverter().ConvertAsync(secondDocx, ofd);

Both converters expose stream-based APIs. DocxToOfdConverter uses the direct native route by default, so original DOCX text remains ordinary OFD text data without a PDF intermediate. Set DocxConversionOptions.OfdMode = DocxToOfdMode.DualLayer to retain a rendered visual page as well; this private PDF intermediate is deleted after conversion and never becomes the semantic text source. DocxConversionOptions.Engine selects Auto, MicrosoftWord, LibreOffice, or BuiltIn for PDF and dual-layer rendering.

Convert OFD to PDF:

using Ofdrw.Net.Converter.Pdf.Converters;

await using var input = File.OpenRead("input.ofd");
await using var output = File.Create("output.pdf");

var converter = new OfdToPdfConverter();
await converter.ConvertAsync(input, output);

Convert one OFD page to SVG:

using Ofdrw.Net.Converter.Svg.Converters;

await using var input = File.OpenRead("input.ofd");
await using var output = File.Create("page-1.svg");

await new OfdToSvgConverter().ConvertAsync(input, output, pageIndex: 0);

Convert selected pages with 1-based page numbers in your application code converted to zero-based indexes:

var pages = new[] { 0, 2, 3 }; // pages 1, 3, and 4
await converter.ConvertAsync(input, output, pages);

Build an OFD document programmatically:

using Ofdrw.Net.Core.Models;
using Ofdrw.Net.Layout.Builders;
using Ofdrw.Net.Packaging;

var builder = new OfdDocumentBuilder();
builder.AddPage(new OfdPage
{
    Index = 0,
    WidthMillimeters = 210,
    HeightMillimeters = 297,
    Elements =
    {
        new OfdTextElement
        {
            Text = "Hello OFD",
            FontName = "SimSun",
            FontSizeMillimeters = 4,
            XMillimeters = 20,
            YMillimeters = 20,
            WidthMillimeters = 80,
            HeightMillimeters = 10
        }
    }
});

await using var output = File.Create("hello.ofd");
await new OfdPackageWriter().WriteAsync(builder.Build(), output);

Read an OFD package:

using Ofdrw.Net.Reader.Readers;

await using var input = File.OpenRead("input.ofd");
var package = await new OfdReader().ReadAsync(input);

Console.WriteLine(package.Pages.Count);

Extract text or edit page order:

using Ofdrw.Net.Layout.Editing;
using Ofdrw.Net.Reader.Extraction;

var text = new OfdTextExtractor().Extract(package, includeTemplates: true);
OfdDocumentEditor.ReorderPages(package, new[] { 2, 0, 1 });
OfdDocumentEditor.CropPage(package.Pages[0], x: 10, y: 10, width: 180, height: 260);

Verify signed-entry integrity:

using Ofdrw.Net.Signatures.Verification;

await using var input = File.OpenRead("signed.ofd");
var report = await new OfdSignatureVerifier().VerifyAsync(input);

Console.WriteLine(report.ReferenceIntegrityValid);
Console.WriteLine(report.FullyValid);

ReferenceIntegrityValid only means every declared protected-entry digest matched. FullyValid additionally requires an IOfdSignedValueVerifier registered for each signature method and a valid SignedValue.dat. This distinction prevents an SM3 digest check from being mistaken for full SES/SM2 electronic-seal verification.

Create a signature by implementing IOfdSignatureProvider. The provider receives the exact serialized Signature.xml bytes and the OFD property-information path, and returns the vendor/SES signed-value bytes. OfdSignatureService writes the standard signature list, protected-entry references, signature description, optional seal, and SignedValue.dat.

For CLI Users

Install the CLI as a .NET tool:

dotnet tool install --global Ofdrw.Net.Cli --version 0.1.0-preview.6

Convert by file extension:

ofdrw convert input.pdf output.ofd
ofdrw convert input.ofd output.pdf
ofdrw convert input.docx output.pdf
ofdrw convert input.docx output.ofd

Specify the conversion direction explicitly:

ofdrw pdf-to-ofd --input input.pdf --output output.ofd
ofdrw ofd-to-pdf --input input.ofd --output output.pdf
ofdrw docx-to-pdf --input input.docx --output output.pdf
ofdrw docx-to-ofd --input input.docx --output output.ofd
ofdrw ofd-to-svg --input input.ofd --output page-1.svg --pages 1

Select a DOCX renderer or provide fonts for the LibreOffice backend:

ofdrw docx-to-pdf input.docx output.pdf --docx-engine built-in
ofdrw docx-to-pdf input.docx output.pdf --docx-engine word
ofdrw docx-to-ofd input.docx output.ofd --docx-ofd-mode native
ofdrw docx-to-ofd input.docx output.ofd --docx-ofd-mode dual-layer --docx-engine libreoffice --font-directory /path/to/fonts

Convert selected pages:

ofdrw pdf-to-ofd -i input.pdf -o selected.ofd --pages 1,3-5
ofdrw ofd-to-pdf -i input.ofd -o selected.pdf --pages 2

Extract text and edit documents:

ofdrw extract-text input.ofd output.txt --include-templates
ofdrw reorder input.ofd reordered.ofd --pages 3,1,2
ofdrw merge merged.ofd first.ofd second.ofd

Verify signatures:

ofdrw verify-signatures --input signed.ofd

The signature command exits with 0 for full verification, 2 when protected-entry integrity passes but the signed-value algorithm has no registered verifier, and 3 for invalid or incomplete signatures.

Show help:

ofdrw --help

Run the CLI from a source checkout:

dotnet run --project src/Ofdrw.Net.Cli/Ofdrw.Net.Cli.csproj -- convert input.pdf output.ofd

Build a standalone executable from source:

dotnet publish src/Ofdrw.Net.Cli/Ofdrw.Net.Cli.csproj -c Release -o artifacts/ofdrw-cli
./artifacts/ofdrw-cli/Ofdrw.Net.Cli convert input.pdf output.ofd

Repository Layout

• src/Ofdrw.Net.Core
• src/Ofdrw.Net.Packaging
• src/Ofdrw.Net.Layout
• src/Ofdrw.Net.Reader
• src/Ofdrw.Net.Converter.Abstractions
• src/Ofdrw.Net.Converter.Docx
• src/Ofdrw.Net.Converter.Pdf
• src/Ofdrw.Net.Converter.Svg
• src/Ofdrw.Net.Signatures
• src/Ofdrw.Net.Converter
• src/Ofdrw.Net.Cli
• tests
• e2e/Ofdrw.Net.Converter.Pdf.E2E

Development

Restore, build, and test:

dotnet restore Ofdrw.Net.sln
dotnet build Ofdrw.Net.sln
dotnet test Ofdrw.Net.sln

Pack locally:

dotnet pack Ofdrw.Net.sln -c Release -o artifacts/nuget

Run the package-consumer E2E check:

scripts/run-converter-package-e2e.sh

Use a specific local package version for E2E:

scripts/run-converter-package-e2e.sh 0.1.0-preview.local

Notes

• SDK libraries target netstandard2.0 and netstandard2.1.
• The CLI targets net10.0.
• Existing source XML is preserved for high-fidelity round trips. Clear an element's SourceXml before expecting all typed property changes to be serialized.
• Merge produces a self-contained typed document, flattens referenced templates, and rejects unknown raw objects unless SkipUnsupportedRawElements is explicitly enabled.
• SM3 reference digests are built in. SES/SM2 electronic-seal verification must be supplied through IOfdSignedValueVerifier.
• GM/T 0099 encrypted-envelope processing and long-term archival validation are not built in. OfdCryptographicCapabilities exposes these support boundaries to applications.
• A repository license has not yet been selected by the project owner. The NuGet workflow now blocks publication until both a license file and NuGet license metadata exist. Direct dependency declarations are recorded in THIRD-PARTY-NOTICES.md.