Skip to main content

Search OfficeIMO

Enter a topic, API type, or PowerShell command.

Documentation Search all OfficeIMO/
Class

EpubPublication

OfficeIMO.Epub

Namespace
OfficeIMO.Epub
Assembly
OfficeIMO.Epub
Source revision
5e5a2dda74b3 with working tree changes
Implements
IDisposable
Modifiers
sealed

A writable EPUB package retaining unknown XML and entry payloads. Instances are mutable and not thread-safe. Use EpubPublication.Read to project the current publication through the existing extraction owner.

Inheritance

  • object
  • EpubPublication

Usage

Explore 7 API references to this type

This type appears in these public API surfaces even when no hand-authored example is attached directly to the page.

Accepted by parameters 1

Methods

public void AddBibliographyEntry(string manifestId, string listId, string entryId, string entryXhtml, CancellationToken cancellationToken = default) #

Appends a formatted XHTML reference to an existing ol/ul directly inside a body section. Entries retain caller order. Citation formatting belongs to the bibliography renderer or publisher; this operation adds EPUB bibliography structure without sorting, numbering citations, or fetching sources.

Parameters

manifestId string required
listId string required
entryId string required
entryXhtml string required
cancellationToken System.Threading.CancellationToken = default optional
public EpubManifestItem AddChapter(string id, string containerPath, string title, string xhtmlBody, IEnumerable<string>? stylesheets = null, bool linear = true) #

Adds a well-formed XHTML body fragment as a chapter, with a linear spine position and a TOC entry.

Parameters

id string required
containerPath string required
title string required
xhtmlBody string required
stylesheets System.Collections.Generic.IEnumerable<string>? = null optional
linear bool = true optional
public void AddCollection(string id, EpubCollectionMetadata collection) #

Appends a named series or set with its kind, hierarchical position and sorting name atomically. Existing collections remain intact. Requires EPUB 3 and an unused package identifier.

Parameters

id string required
collection OfficeIMO.Epub.EpubCollectionMetadata required
public void AddContributor(string id, EpubContributorMetadata contributor) #

Appends a contributor and its ordered MARC roles, sorting name and language in one package edit. Existing contributors and refinements remain intact. Requires EPUB 3 and an unused package identifier.

Parameters

id string required
contributor OfficeIMO.Epub.EpubContributorMetadata required
public void AddCreator(string id, EpubContributorMetadata creator) #

Appends a creator and its ordered MARC roles, sorting name and language in one package edit. Existing creators and refinements remain intact. Requires EPUB 3 and an unused package identifier.

Parameters

id string required
creator OfficeIMO.Epub.EpubContributorMetadata required
public void AddDublinCoreMetadata(string name, string value, string? id = null, string? language = null) #

Adds an ordered Dublin Core value; existing unknown metadata remains intact.

Parameters

name string required
value string required
id string? = null optional
language string? = null optional
public void AddGlossaryEntry(string manifestId, string listId, string termId, string term, string definitionXhtml, CancellationToken cancellationToken = default) #

Appends a term and XHTML definition to an existing dl directly inside a section in the document body. Adds glossary semantics while preserving the section heading and existing entries. Term text is escaped; definition links use the receiving document's effective HTML base. Entries remain in caller-supplied order.

Parameters

manifestId string required
listId string required
termId string required
term string required
definitionXhtml string required
cancellationToken System.Threading.CancellationToken = default optional
public void AddIdentifier(string id, EpubIdentifierMetadata identifier) #

Appends an EPUB 3 identifier with an ONIX type for ISBNs or DOI. ISBN shape and checksums are validated; range assignment and identifier registration are not. The selected package identity is unchanged.

Parameters

id string required
identifier OfficeIMO.Epub.EpubIdentifierMetadata required
public void AddIndexEntry(string manifestId, string listId, string entryId, string term, IReadOnlyList<EpubIndexLocator> locators, string? subentriesId = null, CancellationToken cancellationToken = default) #

Appends an index term and up to 1024 labelled links to existing XHTML spine content. The destination ul must be directly inside a body section, or inside an existing index li for subentries. Optional subentriesId creates a nested ul for subsequent calls. Publisher order and labels are preserved; sorting, term extraction and page-number calculation are not inferred. The edit commits atomically.

Parameters

manifestId string required
listId string required
entryId string required
term string required
locators System.Collections.Generic.IReadOnlyList<OfficeIMO.Epub.EpubIndexLocator> required
subentriesId string? = null optional
cancellationToken System.Threading.CancellationToken = default optional
public EpubManifestItem AddMediaOverlay(string contentManifestId, string overlayId, string containerPath, EpubMediaOverlay overlay, CancellationToken cancellationToken = default) #

Atomically adds ordered SMIL narration for one XHTML or SVG document, its manifest association, and exact clip-sum duration metadata. Existing overlays are never replaced. Audio durations are caller declarations; encoded audio and reading-system playback require independent validation.

Parameters

contentManifestId string required
overlayId string required
containerPath string required
overlay OfficeIMO.Epub.EpubMediaOverlay required
cancellationToken System.Threading.CancellationToken = default optional
public void AddMetadataProperty(string property, string value, string? refines = null) #

Adds an ordered EPUB 3 property value, including repeatable accessibility declarations.

Parameters

property string required
value string required
refines string? = null optional
public void AddNote(EpubNoteOptions options, CancellationToken cancellationToken = default) #

Adds an EPUB 3 note and links an existing labelled anchor marker to it, with a return link. Both content documents are committed atomically, including identifier and retention checks. Existing reference labels, document heads, and unrelated content are retained. Full publication validation remains part of Write/Preflight; this operation does not certify accessibility.

Parameters

options OfficeIMO.Epub.EpubNoteOptions required
cancellationToken System.Threading.CancellationToken = default optional
public void AddPrintPageMarker(string manifestId, string markerId, string pageLabel, string pageListTitle = "Pages", CancellationToken cancellationToken = default) #

Marks an existing empty XHTML span as a print-page boundary and appends its link to the EPUB 3 page list. Supply markers in the source edition's page order; labels may be Roman numerals or other publisher text. Content and navigation are committed atomically. Existing navigation and headings remain intact. This creates source-page references, not screen pagination or a print layout.

Parameters

manifestId string required
markerId string required
pageLabel string required
pageListTitle string = "Pages" optional
cancellationToken System.Threading.CancellationToken = default optional
public EpubManifestItem AddResource(string id, string containerPath, string mediaType, byte[] data, string? properties = null) #

Adds a local manifest resource at a canonical container path. Payloads are copied and never executed.

Parameters

id string required
containerPath string required
mediaType string required
data byte[] required
properties string? = null optional
public EpubSpineItem AddSpineItem(string manifestId, bool linear = true, string? properties = null) #

Adds a distinct reading position for an existing manifest resource.

Parameters

manifestId string required
linear bool = true optional
properties string? = null optional
public EpubManifestItem AddStylesheet(string id, string containerPath, string css) #

Adds a UTF-8 stylesheet resource.

Parameters

id string required
containerPath string required
css string required
public void AddSubject(string id, EpubSubjectMetadata subject) #

Appends an EPUB 3 subject with optional authority and code in one metadata edit.

Parameters

id string required
subject OfficeIMO.Epub.EpubSubjectMetadata required
public void AddTitle(string id, EpubTitleMetadata title) #

Appends an EPUB 3 title and its refinements atomically without changing the existing primary title.

Parameters

id string required
title OfficeIMO.Epub.EpubTitleMetadata required
public void ApplyContentEdits(IEnumerable<EpubContentEdit> edits, CancellationToken cancellationToken = default) #

Applies up to 10,000 non-overlapping element replacements/deletions atomically. Expected XML detects stale drafts. XHTML targets must be inside body; SVG targets must be below its root. Identifiers and publication references are validated against the complete proposed batch.

Parameters

edits System.Collections.Generic.IEnumerable<OfficeIMO.Epub.EpubContentEdit> required
cancellationToken System.Threading.CancellationToken = default optional
public EpubEditionComparison CompareTo(EpubPublication revised, CancellationToken cancellationToken = default) #

Compares this baseline with a revised edition without mutation. Resources match by manifest ID; unmanifested payloads match by path. XML comparison is structural, not rendered equivalence.

Parameters

revised OfficeIMO.Epub.EpubPublication required
cancellationToken System.Threading.CancellationToken = default optional
public static EpubPublication Create(string title, string language = "en", string? identifier = null, EpubVersion version = Epub3, EpubPublicationLoadOptions? retentionLimits = null) #

Creates a publication with stable identity; newly authored packages need at least one linear chapter.

Parameters

title string required
language string = "en" optional
identifier string? = null optional
version OfficeIMO.Epub.EpubVersion = Epub3 optional
retentionLimits OfficeIMO.Epub.EpubPublicationLoadOptions? = null optional
public void DeclareVocabularyPrefix(string prefix, string vocabularyUri) #

Declares a custom vocabulary prefix without replacing other declarations.

Parameters

prefix string required
vocabularyUri string required
public void Dispose() #

Completes the publication lifecycle without saving or closing caller-owned streams.

public XDocument GetContentXml(string manifestId) #

Returns an independent XML content document for targeted editing.

Parameters

manifestId string required

Returns

XDocument
public XDocument GetPackageXml() #

Returns an independent copy of package XML for inspection.

Returns

XDocument
public byte[] GetResourceBytes(string manifestId) #

Returns an independent copy of retained resource bytes, including original font-obfuscated bytes.

Parameters

manifestId string required

Returns

byte[]
public OfficeHiddenDataReport InspectHiddenData() #

Finds identity metadata and image metadata and provenance without changing the publication.

Returns

OfficeHiddenDataReport
public void LinkBibliographyEntry(string sourceManifestId, string referenceId, string bibliographyManifestId, string entryId, string? backlinkText = null, CancellationToken cancellationToken = default) #

Links an existing labelled body anchor to a bibliography entry, with an optional localized return link.

Parameters

sourceManifestId string required
referenceId string required
bibliographyManifestId string required
entryId string required
backlinkText string? = null optional
cancellationToken System.Threading.CancellationToken = default optional
public void LinkGlossaryTerm(string sourceManifestId, string referenceId, string glossaryManifestId, string termId, string? backlinkText = null, CancellationToken cancellationToken = default) #

Links an existing labelled anchor without an href to a glossary dt followed by one dd. An optional localized backlink is appended to that definition. Both documents are committed atomically; call once per occurrence to link multiple passages to one term. This does not request a reader popup.

Parameters

sourceManifestId string required
referenceId string required
glossaryManifestId string required
termId string required
backlinkText string? = null optional
cancellationToken System.Threading.CancellationToken = default optional
Load 2 overloads
public static EpubPublication Load(Stream stream, EpubPublicationLoadOptions? options = null, CancellationToken cancellationToken = default) #

Loads all bounded entries for editing without conflating retained package content with extracted chapters.

Parameters

stream System.IO.Stream required
options OfficeIMO.Epub.EpubPublicationLoadOptions? = null optional
cancellationToken System.Threading.CancellationToken = default optional
public static EpubPublication Load(string path, EpubPublicationLoadOptions? options = null, CancellationToken cancellationToken = default) #

Loads a file for bounded package editing.

Parameters

path string required
options OfficeIMO.Epub.EpubPublicationLoadOptions? = null optional
cancellationToken System.Threading.CancellationToken = default optional
LoadAsync 2 overloads
public static async Task<EpubPublication> LoadAsync(Stream stream, EpubPublicationLoadOptions? options = null, CancellationToken cancellationToken = default) #

Asynchronously loads a caller-owned stream for editing.

Parameters

stream System.IO.Stream required
options OfficeIMO.Epub.EpubPublicationLoadOptions? = null optional
cancellationToken System.Threading.CancellationToken = default optional

Returns

Task<EpubPublication>
public static async Task<EpubPublication> LoadAsync(string path, EpubPublicationLoadOptions? options = null, CancellationToken cancellationToken = default) #

Asynchronously loads a file for editing.

Parameters

path string required
options OfficeIMO.Epub.EpubPublicationLoadOptions? = null optional
cancellationToken System.Threading.CancellationToken = default optional

Returns

Task<EpubPublication>
MergeChapters 2 overloads
public void MergeChapters(string firstManifestId, string secondManifestId, string boundaryId, CancellationToken cancellationToken = default) #

Merges consecutive compatible reflowable chapters into the first resource. Retains both navigation entries, targets the second chapter's start with boundaryId, and repairs references atomically. Conflicting scaffolding, styles, identifiers and package refinements are rejected.

Parameters

firstManifestId string required
secondManifestId string required
boundaryId string required
cancellationToken System.Threading.CancellationToken = default optional
public void MergeChapters(string firstManifestId, string secondManifestId, string boundaryId, EpubChapterMergeOptions options, CancellationToken cancellationToken = default) #

Merges consecutive reflowable chapters with explicit style, identifier and document-scope reconciliation. The selected cascade applies to both chapters; unresolved scaffold, identifier and package-refinement conflicts fail atomically.

Parameters

firstManifestId string required
secondManifestId string required
boundaryId string required
options OfficeIMO.Epub.EpubChapterMergeOptions required
cancellationToken System.Threading.CancellationToken = default optional
public void MoveSpineItem(int fromIndex, int toIndex) #

Moves a reading position while preserving its attributes and repeated references.

Parameters

fromIndex int required
toIndex int required
public EpubPreflightReport Preflight(EpubSaveOptions? options = null, CancellationToken cancellationToken = default) #

Checks the current publication using the selected save policy and inspects all retained XHTML/SVG identifiers, root and descendant language declarations, image alternatives and EPUB 3 metadata-link relationships. Schema conformance, comprehensive accessibility and reader presentation remain explicitly unchecked. No file is written and no external process is invoked.

Parameters

options OfficeIMO.Epub.EpubSaveOptions? = null optional
cancellationToken System.Threading.CancellationToken = default optional
public EpubDocument Read(EpubLoadOptions? options = null, CancellationToken cancellationToken = default) #

Projects current authored content through the existing EPUB reader, without executing embedded content.

Parameters

options OfficeIMO.Epub.EpubLoadOptions? = null optional
cancellationToken System.Threading.CancellationToken = default optional
public OfficeHiddenDataReport RemoveHiddenData(OfficeHiddenDataOptions? options = null) #

Removes the selected categories of metadata and hidden data, then reports what was found and what happened to each item. Title, language and identifier stay because a valid publication requires them. Save the publication to keep the result.

Parameters

options OfficeIMO.OfficeHiddenDataOptions? = null optional
Categories to remove; defaults to OfficeHiddenDataKind.Default, which keeps provenance.

Returns

OfficeHiddenDataReport
public void RemoveResource(string manifestId) #

Removes an unreferenced declaration and its payload. Callers must first update content/navigation links.

Parameters

manifestId string required
public void RemoveSpineItem(int index) #

Removes one reading position without deleting its resource.

Parameters

index int required
public void RenameResource(string manifestId, string containerPath, CancellationToken cancellationToken = default) #

Moves a local resource and repairs standard package, XHTML, SVG, NCX, SMIL and CSS references atomically. Manifest identifiers and spine positions remain unchanged. Requires one rendition, inspectable non-scripted resources and no encrypted resources or XML base declarations.

Parameters

manifestId string required
containerPath string required
cancellationToken System.Threading.CancellationToken = default optional
public void ReplaceMediaOverlay(string overlayManifestId, EpubMediaOverlay overlay, CancellationToken cancellationToken = default) #

Atomically replaces a single chapter's ordered narration and recalculates duration metadata. Preserves cue and sequence ids for surviving text targets, manifest identity and metadata attributes. Rejects shared or encrypted overlays, unsupported SMIL structures, and referenced cues that would be removed. Audio resources remain unchanged; their durations are caller declarations.

Parameters

overlayManifestId string required
overlay OfficeIMO.Epub.EpubMediaOverlay required
cancellationToken System.Threading.CancellationToken = default optional
Save 2 overloads
public EpubWriteReport Save(string path, EpubSaveOptions? options = null, CancellationToken cancellationToken = default) #

Atomically saves a completed artifact to a file, preserving an existing destination on validation/cancellation failure.

Parameters

path string required
options OfficeIMO.Epub.EpubSaveOptions? = null optional
cancellationToken System.Threading.CancellationToken = default optional
public EpubWriteReport Save(Stream stream, EpubSaveOptions? options = null, CancellationToken cancellationToken = default) #

Writes a staged complete artifact to a caller-owned stream. Seekable streams are replaced and rewound.

Parameters

stream System.IO.Stream required
options OfficeIMO.Epub.EpubSaveOptions? = null optional
cancellationToken System.Threading.CancellationToken = default optional
SaveAsync 2 overloads
public async Task<EpubWriteReport> SaveAsync(string path, EpubSaveOptions? options = null, CancellationToken cancellationToken = default) #

Asynchronously atomically saves a completed artifact to a file.

Parameters

path string required
options OfficeIMO.Epub.EpubSaveOptions? = null optional
cancellationToken System.Threading.CancellationToken = default optional

Returns

Task<EpubWriteReport>
public async Task<EpubWriteReport> SaveAsync(Stream stream, EpubSaveOptions? options = null, CancellationToken cancellationToken = default) #

Asynchronously writes a staged artifact without closing the destination stream.

Parameters

stream System.IO.Stream required
options OfficeIMO.Epub.EpubSaveOptions? = null optional
cancellationToken System.Threading.CancellationToken = default optional

Returns

Task<EpubWriteReport>
public void SetAccessibilityMetadata(EpubAccessibilityMetadata metadata) #

Atomically replaces the five publication-level discovery properties in EPUB 3. Other metadata and refined properties remain intact. Existing declarations retain attributes where their positions remain; removing an identified declaration referenced by a refinement is rejected. Vocabulary tokens are supplied by the publisher, not inferred or certified. Null summary and empty sufficient-mode sets remove those properties.

Parameters

metadata OfficeIMO.Epub.EpubAccessibilityMetadata required
SetContentXml 2 overloads
public void SetContentXml(string manifestId, XDocument content) #

Replaces content XML after validating a supported non-scripted XHTML or SVG root.

Parameters

manifestId string required
content System.Xml.Linq.XDocument required
public void SetContentXml(IReadOnlyDictionary<string, XDocument> documents, CancellationToken cancellationToken = default) #

Atomically replaces selected XHTML/SVG documents after validating their identifiers and the resulting publication references. Use one batch when moving targets or repairing cross-document links. A rejected or cancelled batch leaves all retained content unchanged.

Parameters

documents System.Collections.Generic.IReadOnlyDictionary<string, System.Xml.Linq.XDocument> required
cancellationToken System.Threading.CancellationToken = default optional
public void SetCoverImage(string manifestId) #

Selects a manifest image as the cover, preserving other item properties.

Parameters

manifestId string required
public void SetDocumentMatter(string manifestId, EpubDocumentMatter matter, CancellationToken cancellationToken = default) #

Sets the XHTML body's EPUB 3 front/body/back-matter partition, retaining its other semantic tokens. This declares structure; reading order and navigation are controlled independently by the spine and SetNavigation.

Parameters

manifestId string required
matter OfficeIMO.Epub.EpubDocumentMatter required
cancellationToken System.Threading.CancellationToken = default optional
public void SetFixedLayoutPage(string manifestId, EpubFixedLayoutPage page, CancellationToken cancellationToken = default) #

Atomically configures one EPUB 3 XHTML or SVG spine document's page canvas and fixed-layout presentation overrides. DOM order, identifiers and semantic relationships remain unchanged. Existing content CSS may override the canvas rules; verify rendered output in target readers. SVG replaces width, height and viewBox with a zero-origin viewport without changing artwork coordinates; Regions must be empty. This does not paginate reflowable content or certify accessible reading order.

Parameters

manifestId string required
page OfficeIMO.Epub.EpubFixedLayoutPage required
cancellationToken System.Threading.CancellationToken = default optional
public void SetMetadataProperty(string property, string value, string? refines = null) #

Sets one EPUB 3 property/refinement without replacing unrelated declarations.

Parameters

property string required
value string required
refines string? = null optional
public void SetNavigation(IEnumerable<EpubNavigationEntry> tableOfContents, IEnumerable<EpubNavigationEntry>? pageList = null, IEnumerable<EpubNavigationEntry>? landmarks = null) #

Replaces TOC entries and optionally page-list/landmark entries while retaining unrelated navigation XML.

Parameters

tableOfContents System.Collections.Generic.IEnumerable<OfficeIMO.Epub.EpubNavigationEntry> required
pageList System.Collections.Generic.IEnumerable<OfficeIMO.Epub.EpubNavigationEntry>? = null optional
landmarks System.Collections.Generic.IEnumerable<OfficeIMO.Epub.EpubNavigationEntry>? = null optional
public void SetPrimaryTitle(string id, EpubTitleMetadata title) #

Updates the first title and its EPUB 3 refinements atomically. An existing title id must match id; existing unrelated refinements and attributes are retained. Null optional fields retain their values.

Parameters

id string required
title OfficeIMO.Epub.EpubTitleMetadata required
public void SetPublicationDetails(EpubPublicationDetails details) #

Atomically updates supplied primary EPUB 3 publisher, description, rights and publication-date values. Null fields retain existing values. Other values, attributes and refinements remain intact.

Parameters

details OfficeIMO.Epub.EpubPublicationDetails required
public void SetRenditionLayout(EpubRenditionLayout layout) #

Sets typed package layout metadata. This declares layout; it does not create fixed-page geometry.

Parameters

layout OfficeIMO.Epub.EpubRenditionLayout required
public EpubManifestItem SplitChapter(string manifestId, string boundaryId, string newManifestId, string newContainerPath, string title, CancellationToken cancellationToken = default) #

Splits a reflowable XHTML chapter before an identified block, moving that block and following content into a new chapter immediately after it. Clones the head and structural containers, repairs publication references, and adds a sibling TOC entry. Rejects separated local ID references.

Parameters

manifestId string required
boundaryId string required
newManifestId string required
newContainerPath string required
title string required
cancellationToken System.Threading.CancellationToken = default optional
public void UpdateResource(string manifestId, byte[] data) #

Replaces one local resource payload. Encrypted/obfuscated bytes require an explicit re-keying implementation.

Parameters

manifestId string required
data byte[] required
public EpubWriteResult Write(EpubSaveOptions? options = null, CancellationToken cancellationToken = default) #

Produces a complete bounded ZIP before publication. Unedited imports return their exact original bytes.

Parameters

options OfficeIMO.Epub.EpubSaveOptions? = null optional
cancellationToken System.Threading.CancellationToken = default optional

Properties

public string PackagePath { get; } #

Selected package document path. Other rootfiles and their payloads are preserved.

public string PackageVersion { get; } #

Declared package version, preserved when editing.

public IReadOnlyList<EpubManifestItem> Manifest { get; } #

Typed manifest declarations in package order.

public IReadOnlyList<EpubSpineItem> Spine { get; } #

Typed reading positions, including repeated resource references.

public IReadOnlyList<string> EntryPaths { get; } #

All retained entry paths, including unmanifested extension payloads.

public string? FilePath { get; set; } #

Gets or sets the associated native save path without writing the publication.

public string Title { get; set; } #

Primary title. Other titles and refinements are retained.

public string Language { get; set; } #

Primary language. Chapter-level language declarations are edited independently.

public string Identifier { get; set; } #

Selected package identity. Identity changes are rejected for obfuscated/encrypted packages.

public string? Creator { get; set; } #

Primary creator, preserving other contributors and refinements.

public string? PageProgressionDirection { get; set; } #

Page progression declaration, such as ltr or rtl; null restores the package default.