OfficeIMO.Excel.Pdf 3.5.2

OfficeIMO.Excel.Pdf - Excel to PDF export

OfficeIMO.Excel.Pdf exports OfficeIMO.Excel workbooks to PDF through the first-party OfficeIMO.Pdf engine. It also imports logical PDF tables into editable Excel worksheets.

Install

dotnet add package OfficeIMO.Excel.Pdf

Quick start

using OfficeIMO.Excel;
using OfficeIMO.Excel.Pdf;

using var workbook = ExcelDocument.Load("report.xlsx");
workbook.SaveAsPdf("report.pdf");

Examples

Export selected sheets with worksheet print settings

using OfficeIMO.Excel;
using OfficeIMO.Excel.Pdf;
using OfficeIMO.Pdf;

using var workbook = ExcelDocument.Load("monthly-report.xlsx");

var options = new ExcelToPdfOptions {
    SheetNames = new[] { "Summary", "Revenue", "Costs" },
    UseWorksheetPrintAreas = true,
    UseWorksheetPageSetup = true,
    UseWorksheetHeadersAndFooters = true,
    UseWorksheetPageBreaks = true,
    UseWorksheetPrintTitleColumns = true,
    PageSize = PageSizes.A4.Landscape(),
    Margins = PageMargins.UniformCentimeters(1.2)
};

workbook.SaveAsPdf("monthly-report.pdf", options);

Export a workbook to bytes or a stream

using OfficeIMO.Excel;
using OfficeIMO.Excel.Pdf;

using var workbook = ExcelDocument.Load("statement.xlsx");

byte[] pdfBytes = workbook.ToPdfBytes();

using var stream = File.Create("statement.pdf");
workbook.SaveAsPdf(stream);

Surface mapping warnings

using OfficeIMO.Excel;
using OfficeIMO.Excel.Pdf;
using OfficeIMO.Pdf;

using var workbook = ExcelDocument.Load("dashboard.xlsx");
var options = new ExcelToPdfOptions {
    IncludeSheetHeadings = true,
    RespectWorksheetHiddenRowsAndColumns = true,
    UseWorksheetCharts = true
}.UseProfile(PdfExportProfile.Faithful);

options.TextFallbacks = PdfTextFallbackFeatures.Default;
options.ResourcePolicy = PdfResourcePolicy.CreateTrustedHost();

var result = workbook.SaveAsPdfResult("dashboard.pdf", options);
if (!result.Succeeded) {
    foreach (string diagnostic in result.Diagnostics) {
        Console.WriteLine(diagnostic);
    }
}

foreach (var warning in result.Warnings) {
    Console.WriteLine($"{warning.Source}: {warning.Message}");
}

result.Report.RequireNoErrorWarnings();

Import structured PDF data

using OfficeIMO.Excel.Pdf;
using OfficeIMO.Pdf;

PdfDocument pdf = PdfDocument.Load("statement.pdf");
PdfExcelTableImportReport report = pdf.SaveTablesAsExcel("statement-tables.xlsx").RequireSuccess().Report!;

foreach (var table in report.Entries) {
    Console.WriteLine($"{table.SheetName}: page {table.PageNumber}");
}

Console.WriteLine($"Non-table page content detected: {report.HasOmittedPageContent}");

Import only selected PDF pages

using OfficeIMO.Excel.Pdf;
using OfficeIMO.Pdf;

PdfDocument pdf = PdfDocument.Load("bank-statement.pdf");
PdfExcelTableImportReport report = pdf.SaveTablesAsExcel(
    "bank-statement-q1.xlsx",
    new PdfTablesToExcelOptions {
        ReadOptions = new PdfReadOptions {
            PageSelection = PdfPageSelection.Parse("1-3")
        },
        MaxRows = 250
    }).RequireSuccess().Report!;

Console.WriteLine($"Imported {report.Entries.Count} table(s).");
report.RequireNoLoss(); // rejects row truncation and non-table page content

ReadOptions also exposes the canonical Fast/Structured profile and semantic work limits for large or deliberately bounded imports. It is ignored when the source is already a PdfDocumentReadResult.

Tables without explicit header evidence retain all source rows, with generated Excel column names. If you have reviewed the source and confirmed its first row as headers, set UseFirstRowAsHeader = true. This applies to each logical table with unknown schema; tables with an established header keep their existing body boundary. The import excludes the confirmed header from type detection and MaxRows, and records the decision in PdfExcelTableImportEntry.FirstRowUsedAsHeader. Recognition results from standalone images and scanned PDFs use this same importer.

Set PreserveColumnProportions = true to retain the detected table's relative column widths, including quarter-turn tables. With the default AutoFitColumns = true, auto-fit supplies the total width and detected proportions determine each column's share. With AutoFitColumns = false, the total comes from worksheet default widths. If a mapped column would exceed Excel's 255-character width limit, one common scale reduces the total while retaining the proportions. The option is off by default. Missing or invalid geometry keeps the existing widths; PdfExcelTableImportEntry.ColumnProportionsApplied records whether the mapping succeeded. These widths use Excel character units and can leave individual values unfitted. They do not guarantee physical PDF dimensions, authored ruling boundaries, or exact printer geometry. PDF-to-ODS uses the same policy through the shared importer, with approximate spreadsheet unit conversion.

Compatible table segments continue across adjacent pages by default. The shared PDF table analysis classifies Boolean, percentage, date-time, time-only, currency, numeric, and text columns with confidence; the import options decide which detected families become typed Excel cells. Consistent currency columns become decimal cells and retain their detected symbol or ISO 4217 code, prefix or suffix placement, source spacing, and each cell's visible fractional precision in the Excel number format. Mixed currency tokens or affix conventions remain text so the import does not silently normalize their meaning.

What it maps

• Workbook sheets, selected sheet lists, visible used ranges, print areas, page setup, margins, orientation, and worksheet page breaks.
• Repeated print-title rows and columns, headers, footers, page/date/time/sheet/workbook tokens, and supported header/footer images.
• Cell display values, common number formats, fills, font emphasis, alignment, borders, merged cells, links, row heights, column widths, conditional fills/data bars/icons, and table layout primitives. General alignment follows stored cell types: numeric and date values align right, Booleans align center, and text retains its text alignment. Boolean display uses TRUE and FALSE.
• Numeric cell text uses the Excel owner's display formatter, including optional decimal placeholders, single-digit scientific mantissas with exponent sign/case/padding, percentage scaling, grouping, negative sections, quoted/escaped numeric literals, literal percent signs, and the [Red] format color. Stored numeric precision is preserved before formatting, including values immediately beside a fraction midpoint. Other format colors are not projected. Imported formats use at most four sections; extra sections do not affect display selection.
• Text cells and text formula caches retain their text and font color, even when the text looks numeric and the cell has a numeric, date, or elapsed-time format.
• Supported worksheet images and common chart snapshots through shared OfficeIMO drawing primitives.
• Deterministic profile presets through ExcelToPdfOptions.UseProfile(...). Applying a profile always resets the complete profile-owned option set, so reusing an options instance is history-independent.
• Shared TextFallbacks and ResourcePolicy controls for Unicode, symbols, emoji, and host-resource trust. The balanced default uses installed fonts while denying arbitrary local and remote reads; portable deterministic mode is explicit.
• Source-faithful zero-options output: worksheet-name headings are opt-in through IncludeSheetHeadings.
• Per-operation conversion warnings through PdfDocumentConversionResult.Report or PdfSaveResult.Report.

Worksheet print areas are exported separately, in their stored order, with each area starting on a new page. Both worksheet layouts honor local A1 cells and ranges, whole-row and whole-column selections, and multiple areas. Content outside the selected areas is excluded. Repeated title rows, first/even/odd headers and footers, and page numbering belong to the worksheet and continue across its areas. Internal links to a cell appearing in several areas target its first exported occurrence. Invalid or external print-area references are rejected instead of widening the selection to the used range.

Worksheet fit-to-page mode includes retained image, chart, and shape extents before choosing page breaks, and defaults each omitted fit dimension to one page. A zero dimension leaves that axis unlimited. Manual scaling remains active when fit-to-page mode is disabled, even when the file retains cached fit dimensions.

Bubble charts use aligned X/Y/size triples, the authored bubble scale percentage, and area or width sizing through the same Core bubble renderer as PNG export. Automatic per-series colours remain resolved from the workbook theme and chart style. A caller-supplied ChartStyle palette replaces automatic colours. showNegBubbles = false omits negative-size bubbles; a request to show them emits ExcelChartBubbleNegativeSizesUnsupported because Core cannot paint negative sizes. Positive bubbles remain visible. Invalid bubble settings and flat projections of 3-D bubbles emit ExcelChartBubbleSettingsApproximated. Native Excel's absolute bubble diameters can differ.

Worksheet horizontal and vertical print centering position the scaled scene inside its print margins. Supported DrawingML shapes and text boxes use the same shape/text drawing owner as PNG export; UseWorksheetImages = false omits these objects as well as pictures. Unsupported objects produce a conversion warning. Header and footer pictures resolve their VML image relationships, including imported files with an undeclared standard relationship prefix or a stale relationship identifier.

The default worksheet canvas preserves authored font sizes in wrapped cells. A cell with shrink-to-fit enabled reduces its own text without changing neighboring cells; wrapping takes precedence when both settings are present.

WorksheetCanvas paginates using worksheet row heights and column widths, repeats configured title columns on horizontal pages, and applies the worksheet's down-then-over or over-then-down page order. Title columns left of a print area are included without exporting the intervening columns. A title column repeats after the page sequence reaches it; it is not moved onto an earlier page. Titles already inside a page's body are emitted once; titles beyond the print area's last column are excluded. Manual breaks remain on axes with an unlimited fit count, while a constrained fit axis determines its own page boundaries. Unspecified cell vertical alignment uses Excel's bottom alignment; explicit top and center settings take precedence.

Column character units use the workbook default font. When its registered named font covers the decimal digits, the canvas uses that font's maximum digit advance and point size to size columns. Implicit columns derive their width from the worksheet's base column width plus the format's margin and gridline allowance. Authored default and per-column widths already include that allowance. A larger cell or header font does not change those units. Trusted local exports can use installed document fonts when both ResourcePolicy.AllowSystemFontEmbedding and ResourcePolicy.AllowDocumentFontEmbedding are enabled. If the default font is unavailable, the canvas retains its width estimate. Printer-specific font hinting and rounding can still produce different widths in native Excel output.

FlowTable reflows cells into PDF tables and repeats title columns across requested horizontal chunks. Fit-to-height scales cell fonts, padding, and minimum row heights together. Rows can grow to retain their laid-out text, so this mode does not promise worksheet page counts.

Print-title rows can start inside the print area. Canvas automatic pages and both layouts' manual row chunks repeat only title rows reached before the current body segment, including a break within a title block. Flow-table automatic continuation still repeats leading header rows; title rows starting later in a single flowing table are not repeated automatically.

Manual row and column breaks also divide merged cells. Each fragment retains the original cell's full text box for wrapping and alignment, then clips it to that page. Flow-table cell images retain their full-cell placement and clip to each fragment; canvas images retain worksheet coordinates. Outer borders stay at the original merge edges. Diagonal borders retain their full-cell slope on the fragment containing the source anchor. Worksheet formatting keeps Excel's default bottom alignment when the source cell has no explicit alignment. Breaks on constrained fit axes still follow the fit settings.

Current limits

• Workbook content is read through OfficeIMO.Excel; layout and PDF writing use OfficeIMO.Pdf.
• Worksheet-canvas conditional icons use shared vector artwork and reserve space before cell text. The flow-table profile retains generic indicators; exact native icon pixels and print insets are not guaranteed.
• Shapes paint above worksheet pictures and charts. Mixed DrawingML object stacking and rich-text runs within a shape are not fully reproduced.
• Worksheet column widths and fit scaling use layout estimates. Exact Excel printer geometry and derived fit percentages are not guaranteed; fit-to-width documents can have different scale and page counts. Use producer comparisons for workflows that depend on identical pagination.
• PDF import is structured-data recovery. It reconstructs detected tables as worksheets; SourceScope and HasOmittedPageContent report text, source vector graphics, images, links, forms, annotations, or actions that are not represented by those tables. HasLoss and RequireNoLoss() include both that omitted page content and table-row truncation.
• The current reverse route recovers detected tables and structured values; arbitrary PDF page art is reported rather than presented as an editable workbook. Open recovery work is tracked in the repository roadmap.

Related packages

• OfficeIMO.Excel - Excel workbook model.
• OfficeIMO.Pdf - PDF engine.
• OfficeIMO.Html.Pdf - HTML/PDF bridge.

Targets and license

• Targets: netstandard2.0, net8.0, net10.0.
• License: MIT.
• Repository: EvotecIT/OfficeIMO

Dependency footprint

• External: None beyond the dependencies of its OfficeIMO format packages; no native or commercial PDF renderer.
• OfficeIMO: OfficeIMO.Excel, OfficeIMO.Pdf, and OfficeIMO.Core own layout mapping, rendering, table recovery, and reports.

See the complete OfficeIMO package map for related formats and conversion paths.

Generated capability summary

This table is generated from the package-neutral OfficeIMO operation catalog. The detailed source contracts remain authoritative for feature-level behavior and limitations.

The complete rows for OfficeIMO.Excel.Pdf are published in the generated operation contract.