Class Document

Namespace

ComOfficeKit

Assembly

ComOfficeKit.dll

An open document. Open(string) returns a WordDocument, a Spreadsheet or a Presentation; what only one kind can do is on that type.

public abstract class Document : IDisposable

Inheritance

object

Document

Implements

IDisposable

Derived

Presentation

Spreadsheet

WordDocument

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

A document owns everything it opened in the engine and any temporary file it made. Dispose it when you are done; every other member of a disposed document throws ObjectDisposedException. A document that is never disposed is released when the garbage collector finalises it.

Calls on one document take turns: a call made while another is running on the same document waits for it. Different documents can be used from different threads at once.

Properties

Format

The document's format: the one it was opened in, or the one it was last saved in with SaveAs(string). SaveAs(Stream) writes this format.

public DocumentFormat Format { get; }

Property Value

DocumentFormat

Kind

What kind of document this is.

public DocumentKind Kind { get; }

Property Value

DocumentKind

PageCount

How many pages the document has: a Word document's pages as laid out; the pages ActiveSheet prints; a deck's slides, hidden ones included.

public int PageCount { get; }

Property Value

int

Exceptions

LicenseException

The licence does not allow laying the document out.

SourcePath

The file the document was opened from, or last saved to with SaveAs(string), as a full path; null for a document opened from a stream and not saved to a file since.

public string? SourcePath { get; }

Property Value

string

Methods

CreateBlank(DocumentFormat, string)

Writes a new, blank document to path, replacing a file already there: a Word document of one empty A4 page, a workbook of one empty sheet, or a deck of one title slide. Open it with Open(string).

public static void CreateBlank(DocumentFormat format, string path)

Parameters

format DocumentFormat

Docx, Xlsx or Pptx.

path string

Where to write it. Its extension must be the format's.

Exceptions

ComOfficeKitException

IO when the file cannot be written.

LicenseException

The licence does not allow it.

Dispose()

Releases what the document holds in the engine and deletes its temporary files. Safe to call more than once.

public void Dispose()

ExportPdf(Stream)

Writes the document as a PDF to destination, at its current position, as ExportPdf(string) does to a file. The stream is flushed and left open.

public void ExportPdf(Stream destination)

Parameters

destination Stream

A writable stream.

Exceptions

ComOfficeKitException

As ExportPdf(string): Internal when a font the document uses cannot be read.

LicenseException

The licence does not allow exporting.

ExportPdf(string)

Writes the document as a PDF to path, replacing a file already there only once the whole PDF is written: a Word document's pages; the pages ActiveSheet prints; a deck's slides that are not hidden, as PowerPoint prints them. Text stays text, with its fonts embedded.

public void ExportPdf(string path)

Parameters

path string

Where to write the PDF.

Remarks

The engine writes the PDF itself: it needs no printer and no Print Spooler service, so it works on a server that runs without them. Text is written as the glyphs the layout measured, in embedded fonts, so it can be searched and copied.

Exceptions

ComOfficeKitException

IO when the file cannot be written; Internal when a font the document uses cannot be read, the font named in the message.

LicenseException

The licence does not allow exporting.

Open(Stream, DocumentFormat)

Opens a document read from stream, from its current position to its end. The stream is read before this returns and is left open.

public static Document Open(Stream stream, DocumentFormat format)

Parameters

stream Stream

A readable stream holding the file.

format DocumentFormat

The file's format: a stream has no extension to tell.

Returns

Document

A WordDocument, a Spreadsheet or a Presentation, whose SourcePath is null.

Exceptions

ComOfficeKitException

Parse when the bytes are not a readable file of format.

LicenseException

The licence does not allow it.

Open(string)

Opens the file at path. The format comes from its extension, in any case: .docx, .xlsx, .xlsm, .pptx, .csv or .tsv.

public static Document Open(string path)

Parameters

path string

The file to open.

Returns

Document

A WordDocument, a Spreadsheet or a Presentation.

Exceptions

ComOfficeKitException

UnsupportedFormat for another extension; IO when the file cannot be read; Parse when it is not a readable file of its format.

LicenseException

The licence does not allow it.

RenderPage(int, double)

Draws page index (from 0) as an image: opaque, on white, at dpi dots per inch. Its size in pixels is the page's size in points × dpi ÷ 72, rounded up.

public PageImage RenderPage(int index, double dpi = 96)

Parameters

index int

The page, counting from 0; less than PageCount.

dpi double

From 24 to 600: a finite number, never NaN or an infinity. 96 is the size Windows shows at 100 %.

Returns

PageImage

The page's pixels, which the caller owns.

Exceptions

ArgumentOutOfRangeException

index is negative or not less than PageCount; dpi is not a number from 24 to 600 (NaN and the infinities included); or at dpi the page would be more than 16,384 pixels a side. Checked here, before the engine is called, as every argument is.

LicenseException

The licence does not allow rendering.

Save()

Saves the document to SourcePath, in Format. Parts of the file the document did not change are carried over as they were.

public void Save()

Exceptions

InvalidOperationException

The document has no SourcePath: it was opened from a stream. Use SaveAs(string).

ComOfficeKitException

IO when the file cannot be written.

LicenseException

The licence does not allow saving.

SaveAs(Stream)

Writes the document to destination in Format, at the stream's current position. The stream is flushed and left open; SourcePath does not change.

public void SaveAs(Stream destination)

Parameters

destination Stream

A writable stream.

Exceptions

LicenseException

The licence does not allow saving.

SaveAs(string)

Saves the document to path, which then becomes its SourcePath. The format comes from the extension and must suit the kind: a Word document saves as .docx; a workbook as .xlsx, .xlsm, .csv or .tsv; a deck as .pptx. Parts of the file the document did not change are carried over as they were.

public void SaveAs(string path)

Parameters

path string

Where to save. A file already there is replaced.

Exceptions

ComOfficeKitException

IO when the file cannot be written.

LicenseException

The licence does not allow saving.