Namespace DocToolkit

Classes

ChartData: The categories and series a chart plots — one category axis shared by every series, the same shape OfficeIMO.Drawing.OfficeChartData uses, which is what lets AddChart methods on WorkbookEditor and PresentationEditor share one data model.

ChartSeries: One named series of numeric values in a ChartData.

ConversionResult<T>: A converted document together with everything the conversion could not carry across.

ConversionWarning: One thing a conversion could not carry across faithfully.

DocToDocxConverter: Reads a Word 97-2003 binary document (.doc) — the format Word used before .docx — and converts it to a .docx package, or reads its text directly.

The names to subscribe to for DocToolkit's telemetry.

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource(DocToolkitTelemetry.ActivitySourceName))
    .WithMetrics(m => m.AddMeter(DocToolkitTelemetry.MeterName));

Only the opt-in remote-image fetch is instrumented, and that is a deliberate scope rather than a first instalment. Every other call in this package is one synchronous, in-process, stateless operation that throws a typed exception on failure — a caller can time and log around it and learn everything a span would tell them. The fetch path is the exception: it is the only place this library reaches the network, the decision to allow or refuse a host happens deep inside HtmlToOpenXml's pipeline, and a refused fetch is deliberately silent — the image is skipped and the document still succeeds. Without this, a consumer who enabled remote images had no way to find out that an image never arrived, or why.

DocumentConversionException: Thrown when a document conversion fails.

DocumentMetadata: The document properties a DOCX, XLSX or PPTX file carries about itself — what a file manager shows in its properties panel, and what a search indexer reads.

DocumentSignatureInfo: The result of a structural signature inspection — whether a document carries a signature and who claims to have signed it, without validating anything cryptographically.

DocumentSignatureValidationOptions: Options for ValidateSignatures.

DocumentSignatureValidationReport: The result of validating every signature a document carries.

DocumentSignatureValidationResult: One signature's independently validated state.

DocxBlock

One block of content in a document built by Create(IEnumerable<DocxBlock>).

The hierarchy is CLOSED: the constructor is private protected, the concrete types are internal sealed, and a block can only be obtained from one of the factory methods below. A consumer therefore cannot define a block the writer has never heard of — an unrenderable block is unrepresentable rather than a runtime failure.

Each factory validates its arguments immediately, so a bad value throws at the line that produced it rather than later inside a Create(IEnumerable<DocxBlock>) call assembling many blocks at once.

DocxComment: A single comment, together with any replies to it.

DocxCompare: Compares two versions of a document and returns the later one with the differences marked as tracked changes (A118).

DocxEditor: Creates, reads and edits Word (.docx) documents.

DocxForm: Reads, checks and fills the content controls a Word document carries — the format's own answer to a fill-in form.

DocxFormField: One content control, and its current content.

DocxFormIssue: One problem with a set of values.

DocxFormReport: The content controls a document carries, and what is currently in them.

DocxFormValidation: Whether a set of values fits a document's content controls.

DocxFormValue: A value read from, or written into, a Word content control.

DocxHeader: The content of one header or footer.

DocxHeaderSegment: One piece of a header or footer line: literal text, or a field the reader evaluates per page.

DocxMailMerge: Fills a Word mail-merge template — a document carrying MERGEFIELD instructions — from a set of named values.

DocxMailMergeBatchItem: One record's document, from a batch call, together with what happened to every field in it.

DocxMailMergeBlockData: One repeated block row, for the nested form of repeating-region merging.

DocxMailMergeBlockReport: What happened when a template's conditional blocks or repeating regions were resolved — which names the template asked for that the caller did not supply, and any structural problem.

DocxMailMergeBlockResult: A merged document, together with what happened to its conditional blocks or repeating regions.

DocxMailMergeField: What happened to one merge field.

DocxMailMergeFileBatchItem: One record's output file, from a file-path batch call, together with what happened to every field in it.

DocxMailMergeIssue: Something wrong with a mail-merge template.

DocxMailMergeReport: What happened to every merge field in a document.

DocxMailMergeResult: A merged document, together with what happened to every field in it.

DocxMailMergeTableRowGroup: One grouped table-row mail-merge data set — a group/header row plus its detail rows.

DocxMailMergeTemplate: What a mail-merge template asks for, read without merging anything.

DocxReview: Reads and resolves a document's review state — the comments and tracked changes a .docx carries from having been through review.

DocxReviewReport: What a document carries from having been through review.

DocxRevision: A single tracked change.

DocxToHtmlConverter

Converts a Word (.docx) package to HTML, keeping the structure ExtractText(byte[]) throws away: headings stay headings, tables stay tables. Use ExtractText when flat text is what you want.

The result is a complete HTML document — <html><head>…<body> — not a fragment, and there is no option to change that. Embedding the output in a larger page means extracting the body with an HTML parser you already trust; this package will not do it by string surgery on the renderer's output.

The result is self-contained. Images in the source document are embedded as data: URIs, so nothing in the output points at a file that does not exist.

DocxToMarkdownConverter

Converts a Word (.docx) package to Markdown, keeping the structure ExtractText(byte[]) throws away: a heading becomes #, a table becomes a pipe table. Use ExtractText when flat text is what you want.

The result is self-contained. Images in the source document are embedded as data: URIs rather than written beside the output and referenced by path, so the string this returns stands on its own.

DocxToPdfConverter: Renders a Word (.docx) package to PDF. Pure managed - no browser, no LibreOffice.

DocxToPdfPreflight: Checks a Word document before converting it, and reports what DocxToPdfConverter may not carry into the PDF.

DocxToPdfPreflightFinding: One construct found in the source.

DocxToPdfPreflightReport: What a document contains that DocxToPdfConverter may not carry into the PDF.

HtmlToDocxConverter: Converts an HTML fragment into a Word (.docx) package.

HtmlToPdfConverter

Converts HTML to PDF by pivoting through DOCX.

There is no permissive, NuGet-only, Linux-safe library that renders HTML to PDF directly: the only free renderers are browsers, and a browser is a native binary. Pivoting through DOCX keeps the whole chain pure managed. The package README says the same under Why HTML to PDF goes through DOCX.

HtmlToPdfOptions: Page setup, remote-image policy and fonts for one HTML to PDF conversion.

LegacyDocOptions: Controls how DocToDocxConverter treats content a Word 97-2003 binary document holds but a .docx package cannot be given.

MarkdownEditor: Reads and updates an existing Markdown document — front matter, headings, tables, and one section's content — without converting to another format first.

MarkdownHeading: One heading found in a Markdown document by FindHeading(string, string, StringComparison).

MarkdownToDocxConverter: Converts Markdown to a Word (.docx) package, completing the round trip DocxToMarkdownConverter opened: a # becomes a heading, a pipe table becomes a table.

MarkdownToPdfConverter: Converts Markdown to PDF by way of DOCX.

PageSetup

The paper a generated document is laid out on: size, orientation and margins, all in points.

Immutable and built by factories — A4, Letter or Custom(double, double) — then copied by Landscape() and WithMargins. The same shape as DocxBlock, PptxSlide, XlsxSheet and XlsxFormula, so the five read as a set.

Points throughout, because DocxBlock.Image already takes widthPoints/heightPoints, and a library with two length units is a library that will eventually mix them up. OOXML stores these as twentieths of a point; that conversion lives in SectionPropertiesFactory and never reaches a caller.

Only two presets. A3, Legal and the rest are one line each and can be added when somebody asks; Custom(double, double) covers them meanwhile.

There is no Portrait(). It has no defensible answer for a square custom page — "the longer side vertical" is undefined when there is no longer side. Both presets are already portrait and this type is immutable, so start from the preset again.

PdfEditor: Operations on a PDF that already exists: how many pages it has, joining several into one, taking a range of pages out, and reading or stamping its document information.

PdfFontOptions: Fonts the caller supplies for characters the renderer cannot otherwise encode.

PdfImage: One image drawn on a PDF page: its pixels, its size in pixels, and where it was placed.

PdfMetadata: The document information a PDF carries about itself — what a file manager shows in its properties panel, and what a search indexer reads.

PdfProtection: The password and permissions applied by Protect(byte[], PdfProtection).

PdfWord: One word of a PDF's text layer, and where it sits on the page.

PivotDataField: One aggregated value column in a pivot table's data area.

PptxSlide

One slide: a title and zero or more bullet lines. Built by Titled(string, params string[]) and passed to Create(IEnumerable<PptxSlide>).

A single sealed type rather than the closed hierarchy DocxBlock uses. That hierarchy exists because a document has four kinds of block an external assembly must not be able to extend; a deck has one kind of slide in this version, so the same machinery would be cost without benefit. Titled(string, params string[]) leaves room for other factories later without changing what already exists.

PptxToPdfConverter

Renders a PowerPoint (.pptx) presentation to PDF, one page per slide. Pure managed — no browser, no LibreOffice, no PowerPoint.

The same three members as DocxToPdfConverter and XlsxToPdfConverter, deliberately: a consumer who has used one has used all three.

No page-setup parameter. A presentation's page size is its p:sldSz — slide geometry, not paper. PresentationEditor writes 16:9, which renders as a 960 × 540 pt PDF page. Accepting a PageSetup here would invite a caller to letterbox their own slides onto a paper size that means nothing to a deck.

Fidelity is bounded, and features the renderer cannot represent are dropped rather than reported — see README's Known limitations.

PresentationEditor: Opens and edits PowerPoint (.pptx) presentations.

RemoteImageOptions

Bounds the one code path in this library that opens a socket: fetching images named by absolute URLs during HTML conversion. Every default here is the restrictive one, so new RemoteImageOptions() is safe to pass without reading this class.

This is not a complete SSRF defence. Host addresses are resolved and checked, then resolved again by the HTTP stack when it connects — a DNS entry that changes between those two moments defeats the check. It stops the ordinary cases, a literal metadata address or a hard-coded internal hostname, and raises the cost of the rest; a service converting genuinely untrusted HTML should also be egress-filtered at the network layer.

WorkbookEditor: Creates, reads and edits Excel (.xlsx) workbooks. Legacy .xls is not supported.

XlsxComment: A comment (a note) on one cell.

XlsxFormat: The presentation Format(byte[], string, XlsxFormat) applies to a sheet: a bold header row, a freeze position, auto-fitted or explicit column widths, a number format per column, an autofilter, conditional formats, data validations, tables, a print setup, merged cells, hyperlinks and comments.

XlsxFormula

A cell value meaning "this cell holds a formula". Use it anywhere a cell value is accepted — inside XlsxSheet rows, inside rows passed to AppendRows(byte[], string, IEnumerable<IEnumerable<object?>>), or as the value argument to SetCell(byte[], string, string, object?).

No cached result is written. The file carries the formula and nothing else. Excel recalculates when it opens the file, and this package's own readers (ReadCell(byte[], string, string), ReadSheet(byte[], string)) compute the value on read — but a third-party reader that only reads cached values, such as openpyxl with data_only=True, sees an empty cell until Excel has opened and saved the file.

This package's own XlsxToPdfConverter used to be exactly such a reader — its renderer reads the raw cell rather than going through ClosedXML's lazy evaluation, so a formula cell rendered its own source text where the value belonged, found 2026-08-31. It now calculates before rendering, so this is no longer a caveat for it specifically. It remains one for anything else that reads this package's output: use EvaluateFormulas(byte[]) to write the computed value into the file itself before handing it to a reader that will not recalculate on its own, and InspectFormulas(byte[]) to find out first whether the engine understands a given formula well enough to trust its value.

A formula that cannot be evaluated reads back as its Excel error string — #DIV/0!, #NAME?, #REF! — rather than throwing, which is what Excel itself shows.

XlsxFormulaCell: One formula cell, as found by InspectFormulas(byte[]).

XlsxFormulaInspection: Which formulas a workbook carries, and whether each one is understood well enough to trust its value — an inventory, not a promise about what the value currently is.

XlsxHyperlink: A hyperlink on one cell, pointing at an external URL.

XlsxPageSetup: A sheet's own print setup: orientation, the range that prints, and the rows that repeat at the top of every printed page.

XlsxRule: A conditional format: highlight the cells in a range that meet a condition.

XlsxSheet

One named sheet and its rows, for building a multi-sheet workbook from data rather than a template.

Content comes from data rather than a template, so there is no source file to edit. Cell typing and culture rules are identical to the single-sheet Create(string, IEnumerable<IEnumerable<object?>>); a cell holding an XlsxFormula is written as a formula.

There is deliberately no separate header row. A header is styling, and this type carries content — the first row is a header only in the sense that you put your headings in it.

XlsxSparkline: A sparkline: a small chart drawn inside one cell, summarising a range on the same sheet.

XlsxTable: An Excel table (a ListObject, what a spreadsheet user means by "make this a table"): a named, banded range with an autofilter and structured references a formula elsewhere in the workbook can use.

XlsxToCsvConverter: Exports one sheet of a workbook as CSV (RFC 4180).

XlsxToHtmlConverter: Exports one sheet of a workbook as an HTML table.

XlsxToPdfConverter

Renders an Excel (.xlsx) workbook to PDF. Pure managed — no browser, no LibreOffice, no Excel.

The same three members as DocxToPdfConverter and PptxToPdfConverter, deliberately: a consumer who has used one has used all three.

No page-setup parameter, for the same reason DocxToPdfConverter has none — the workbook already carries its own print setup, per worksheet, and the renderer honours it. Taking a PageSetup here would mean overriding something the caller's own document already states.

Fidelity is bounded, and features the renderer cannot represent are dropped rather than reported: this package has no warning channel, and adding one is a decision deferred until somebody needs it rather than made by accident here. See README's Known limitations.

XlsxValidation: A data validation: what a person may type into a range of cells once the workbook is open.

Structs

PdfBounds: Where something sits on a PDF page, in PDF user-space points.

XlsxFreeze: Where a sheet is frozen: how many rows and columns stay visible while scrolling.

Enums

ChartType

The chart shapes AddChart methods on WorkbookEditor and PresentationEditor can create — one closed vocabulary shared by both, mirroring OfficeIMO's own OfficeChartKind, minus two values that do not fit the shared categories-and-value-series ChartData shape, so nothing here can drift from what the renderer beneath actually draws.

OfficeChartKind also has Scatter and Bubble, deliberately excluded here: measured directly against both the Excel and PowerPoint chart APIs, both reject a ChartData built from this ticket's model — Excel's Scatter path requires numeric X values where Categories is a string label, PowerPoint's Scatter path rejects the same shape for the identical reason, Excel's shared chart API refuses Bubble outright ("not supported by the shared Excel chart API"), and PowerPoint's Bubble path requires a bubble size per point this model has no field for. A future chart feature could add a companion X/Y-and-size data type for these two; forcing them into this one would have shipped two enum values that always throw.

ConversionLossKind: How badly a conversion lost something.

DocumentSignatureStatus: One dimension of a signature's validated state — mirrors OfficeIMO's own OfficePackageSignatureValidationState 1:1, so nothing here can drift from what the validator beneath actually reports.

DocxFormIssueKind: The kinds of problem a set of values can have.

DocxFormKey: Which name identifies a content control.

DocxFormValueKind: The kinds of value a content control can hold.

DocxMailMergeFieldStatus: What happened to a single merge field.

DocxMailMergeIssueKind: The kinds of template problem this API distinguishes.

DocxRevisionKind: What kind of change a revision records.

DocxToPdfRisk: How confident this library is that the construct is a problem.

HeaderAlignment: Where a header or footer line sits across the page.

PdfEncryptionStrength: The cipher used when a PDF is encrypted.

PivotFunction: The aggregation a PivotDataField applies — mirrors OfficeIMO.Excel.ExcelPivotDataFunction's 11 values 1:1, confirmed by Enum.GetNames, so nothing here can drift from what the writer beneath supports.

XlsxHighlight: How a conditional format draws attention to a cell.

XlsxPageOrientation: A sheet's print orientation.

XlsxRuleKind: Which comparison an XlsxRule makes.

XlsxSparklineKind: The shape of a sparkline.

XlsxTableStyle: A built-in Excel table style tier.

XlsxValidationKind: What an XlsxValidation restricts a cell to.

Table of Contents

Namespace DocToolkit

Classes

Structs

Enums