OfficeIMO.Excel.Pdf 3.6.0

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;
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;
using OfficeIMO.Excel;
using OfficeIMO.Excel.Pdf;
using OfficeIMO.Pdf;

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

var options = new ExcelPdfExportOptions {
    Sheets = new[] { new OfficeSheetSelector("Summary"), new OfficeSheetSelector("Revenue"), new OfficeSheetSelector("Costs") },
    UseWorksheetPrintAreas = true,
    UseWorksheetPageSetup = true,
    UseWorksheetHeadersAndFooters = true,
    UseWorksheetPageBreaks = true,
    UseWorksheetPrintTitleColumns = true,
    PageSize = PdfPageSizes.A4.Landscape(),
    Margins = PdfPageMargins.Uniform(OfficeIMO.OfficeLength.Centimeters(1.2))
};

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

Export a workbook to bytes or a stream

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

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

using var pdf = workbook.ToPdf();
byte[] pdfBytes = pdf.ToBytes(new OfficeIMO.Pdf.PdfSaveOptions { AllowLoss = true });

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

PDF export admits at most 1,000,000 dense worksheet positions across its selected ranges by default, including empty positions inside sparse used ranges. Set ExcelPdfExportOptions.MaxMaterializedWorksheetCells for a trusted workbook when the host has enough memory for a larger export. The converter rejects a range before reading it if the aggregate limit would be exceeded.

Surface mapping warnings

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

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

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

OfficeConversionReport report = workbook.SaveAsPdf("dashboard.pdf", options);
foreach (OfficeDiagnostic finding in report.Diagnostics) {
    Console.WriteLine($"{finding.Code}: {finding.Message}");
}

What it maps

• Workbook sheets, selected sheet lists, visible used ranges, print areas, page setup, margins, orientation, and worksheet page breaks.
• A sheet without stored margins prints with Excel's Normal margins: 0.7 inch left and right, 0.75 inch top and bottom, and 0.3 inch header and footer margins. Header and footer text lines up with the sheet's left and right margins. Margins or explicit PdfOptions margins override this.
• A single column wider than the printable width prints once, cut at the page edge, rather than continuing on another page.
• 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 ExcelPdfExportOptions.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 findings through OfficeConversionReport.Diagnostics.

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.

Worksheets print at the scale their page setup asks for: 100 % unless the sheet stores a manual scale or fit-to-page settings, as in Excel. Content wider or taller than a page is never shrunk silently. Cells continue on further pages, and a chart, picture or shape that crosses a page edge continues on the page that holds the following rows or columns; one that extends past the last row or column gets its own continuation pages.

The worksheet canvas follows Excel's display rules for cell text. Text spills into empty neighbouring cells: left-aligned text to the right, right-aligned text to the left, centred text both ways. It stops at a cell that holds a value and never spills from wrapped, shrink-to-fit, rotated or merged cells. Without a print area, text in the last column can run on to the page edge. Numbers and dates never spill: a General number is rounded to the column width, and any other number or date that does not fit shows ####. Rows without a stored height grow to fit their largest font and their wrapped text. Formulas saved without a cached result are calculated for the PDF without changing the workbook; formulas the built-in calculator cannot evaluate are exported blank and reported. A pivot table saved without its output cells is calculated from its cache in an in-memory copy, or reported when it cannot be.

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.

Tagged PDF output preserves structured-table header cells below titles or other worksheet content, including when worksheet cell styles are disabled or the table style is unknown. Only cells inside a source table's enabled header row receive column-header tags. This does not make those rows repeat or change their formatting.

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 ThrowIfLoss() 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.