# EpubPublication

A writable EPUB package retaining unknown XML and entry payloads. Instances are mutable and not thread-safe.

Class 

`OfficeIMO.Epub`

**Namespace**

`OfficeIMO.Epub`

**Assembly**

`OfficeIMO.Epub`

**Source revision**

`5e5a2dda74b3` with working tree changes

**Source**

[EpubPublication.cs:73](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.cs#L73)

**Implements**

`IDisposable`

**Modifiers**

sealed

A writable EPUB package retaining unknown XML and entry payloads. Instances are mutable and not thread-safe. Use [EpubPublication.Read](/api/epub/officeimo-epub-epubpublication/) 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.

### Returned or exposed by 6

- Method [EpubManuscriptResult.RequireValue](/api/epub/officeimo-epub-epubmanuscriptresult/#method-requirevalue)
- Property [EpubManuscriptResult.Publication](/api/epub/officeimo-epub-epubmanuscriptresult/#property-publication)
- Property [EpubManuscriptResult.Value](/api/epub/officeimo-epub-epubmanuscriptresult/#property-value)
- Method [EpubPublication.Create](/api/epub/officeimo-epub-epubpublication/#method-create-string-string-string-officeimo-epub-epubversion-officeimo-epub-epubpublicationloadoptions)
- Method [EpubPublication.Load](/api/epub/officeimo-epub-epubpublication/#method-load-io-stream-officeimo-epub-epubpublicationloadoptions-threading-cancellationtoken)
- Method [EpubPublication.LoadAsync](/api/epub/officeimo-epub-epubpublication/#method-loadasync-io-stream-officeimo-epub-epubpublicationloadoptions-threading-cancellationtoken)

### Accepted by parameters 1

- Method [EpubPublication.CompareTo](/api/epub/officeimo-epub-epubpublication/#method-compareto-officeimo-epub-epubpublication-threading-cancellationtoken) parameter `revised`

Filter members 

Show inherited

## Methods

`public void AddBibliographyEntry(string manifestId, string listId, string entryId, string entryXhtml, CancellationToken cancellationToken = default)` [#](#method-addbibliographyentry-string-string-string-string-threading-cancellationtoken)

[EpubPublication.Bibliography.cs:11](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Bibliography.cs#L11)

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)` [#](#method-addchapter-string-string-string-string-collections-generic-ienumerable-system-string-boolean)

[EpubPublication.Content.cs:71](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Content.cs#L71)

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**

Returns

`EpubManifestItem`

`public void AddCollection(string id, EpubCollectionMetadata collection)` [#](#method-addcollection-string-officeimo-epub-epubcollectionmetadata)

[EpubPublication.PublishingMetadata.cs:23](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.PublishingMetadata.cs#L23)

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)` [#](#method-addcontributor-string-officeimo-epub-epubcontributormetadata)

[EpubPublication.PublishingMetadata.cs:16](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.PublishingMetadata.cs#L16)

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)` [#](#method-addcreator-string-officeimo-epub-epubcontributormetadata)

[EpubPublication.PublishingMetadata.cs:10](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.PublishingMetadata.cs#L10)

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)` [#](#method-adddublincoremetadata-string-string-string-string)

[EpubPublication.Metadata.cs:42](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Metadata.cs#L42)

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)` [#](#method-addglossaryentry-string-string-string-string-string-threading-cancellationtoken)

[EpubPublication.Glossary.cs:11](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Glossary.cs#L11)

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)` [#](#method-addidentifier-string-officeimo-epub-epubidentifiermetadata)

[EpubPublication.BibliographicMetadata.cs:68](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.BibliographicMetadata.cs#L68)

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)` [#](#method-addindexentry-string-string-string-string-collections-generic-ireadonlylist-officeimo-epub-epubindexlocator-string-threading-cancellationtoken)

[EpubPublication.Index.cs:12](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Index.cs#L12)

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)` [#](#method-addmediaoverlay-string-string-string-officeimo-epub-epubmediaoverlay-threading-cancellationtoken)

[EpubPublication.MediaOverlays.cs:16](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.MediaOverlays.cs#L16)

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**

Returns

`EpubManifestItem`

`public void AddMetadataProperty(string property, string value, string? refines = null)` [#](#method-addmetadataproperty-string-string-string)

[EpubPublication.Metadata.cs:64](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Metadata.cs#L64)

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)` [#](#method-addnote-officeimo-epub-epubnoteoptions-threading-cancellationtoken)

[EpubPublication.Notes.cs:11](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Notes.cs#L11)

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)` [#](#method-addprintpagemarker-string-string-string-string-threading-cancellationtoken)

[EpubPublication.Structure.cs:33](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Structure.cs#L33)

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)` [#](#method-addresource-string-string-string-byte-string)

[EpubPublication.Content.cs:6](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Content.cs#L6)

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**

Returns

`EpubManifestItem`

`public EpubSpineItem AddSpineItem(string manifestId, bool linear = true, string? properties = null)` [#](#method-addspineitem-string-boolean-string)

[EpubPublication.Content.cs:134](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Content.cs#L134)

Adds a distinct reading position for an existing manifest resource.

Parameters

**manifestId string required**

**linear bool = true optional**

**properties string? = null optional**

Returns

`EpubSpineItem`

`public EpubManifestItem AddStylesheet(string id, string containerPath, string css)` [#](#method-addstylesheet-string-string-string)

[EpubPublication.Content.cs:110](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Content.cs#L110)

Adds a UTF-8 stylesheet resource.

Parameters

**id string required**

**containerPath string required**

**css string required**

Returns

`EpubManifestItem`

`public void AddSubject(string id, EpubSubjectMetadata subject)` [#](#method-addsubject-string-officeimo-epub-epubsubjectmetadata)

[EpubPublication.BibliographicMetadata.cs:47](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.BibliographicMetadata.cs#L47)

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)` [#](#method-addtitle-string-officeimo-epub-epubtitlemetadata)

[EpubPublication.BibliographicMetadata.cs:8](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.BibliographicMetadata.cs#L8)

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)` [#](#method-applycontentedits-collections-generic-ienumerable-officeimo-epub-epubcontentedit-threading-cancellationtoken)

[EpubPublication.ScopedEdits.cs:10](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.ScopedEdits.cs#L10)

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)` [#](#method-compareto-officeimo-epub-epubpublication-threading-cancellationtoken)

[EpubPublication.Comparison.cs:9](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Comparison.cs#L9)

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**

Returns

`EpubEditionComparison`

`public static EpubPublication Create(string title, string language = "en", string? identifier = null, EpubVersion version = Epub3, EpubPublicationLoadOptions? retentionLimits = null)` [#](#method-create-string-string-string-officeimo-epub-epubversion-officeimo-epub-epubpublicationloadoptions)

[EpubPublication.cs:73](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.cs#L73)

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**

Returns

`EpubPublication`

`public void DeclareVocabularyPrefix(string prefix, string vocabularyUri)` [#](#method-declarevocabularyprefix-string-string)

[EpubPublication.Metadata.cs:79](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Metadata.cs#L79)

Declares a custom vocabulary prefix without replacing other declarations.

Parameters

**prefix string required**

**vocabularyUri string required**

`public void Dispose()` [#](#method-dispose)

[EpubPublication.Lifecycle.cs:19](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Lifecycle.cs#L19)

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

`public XDocument GetContentXml(string manifestId)` [#](#method-getcontentxml-string)

[EpubPublication.Content.cs:59](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Content.cs#L59)

Returns an independent XML content document for targeted editing.

Parameters

**manifestId string required**

Returns

`XDocument`

`public XDocument GetPackageXml()` [#](#method-getpackagexml)

[EpubPublication.cs:152](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.cs#L152)

Returns an independent copy of package XML for inspection.

Returns

`XDocument`

`public byte[] GetResourceBytes(string manifestId)` [#](#method-getresourcebytes-string)

[EpubPublication.Content.cs:53](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Content.cs#L53)

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

Parameters

**manifestId string required**

Returns

`byte[]`

`public OfficeHiddenDataReport InspectHiddenData()` [#](#method-inspecthiddendata)

[EpubPublication.HiddenData.cs:9](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.HiddenData.cs#L9)

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)` [#](#method-linkbibliographyentry-string-string-string-string-string-threading-cancellationtoken)

[EpubPublication.Bibliography.cs:28](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Bibliography.cs#L28)

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)` [#](#method-linkglossaryterm-string-string-string-string-string-threading-cancellationtoken)

[EpubPublication.Glossary.cs:33](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Glossary.cs#L33)

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)` [#](#method-load-io-stream-officeimo-epub-epubpublicationloadoptions-threading-cancellationtoken)

[EpubPublication.cs:103](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.cs#L103)

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**

Returns

`EpubPublication`

`public static EpubPublication Load(string path, EpubPublicationLoadOptions? options = null, CancellationToken cancellationToken = default)` [#](#method-load-string-officeimo-epub-epubpublicationloadoptions-threading-cancellationtoken)

[EpubPublication.cs:111](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.cs#L111)

Loads a file for bounded package editing.

Parameters

**path string required**

**options OfficeIMO.Epub.EpubPublicationLoadOptions? = null optional**

**cancellationToken System.Threading.CancellationToken = default optional**

Returns

`EpubPublication`

LoadAsync 2 overloads

`public static async Task<EpubPublication> LoadAsync(Stream stream, EpubPublicationLoadOptions? options = null, CancellationToken cancellationToken = default)` [#](#method-loadasync-io-stream-officeimo-epub-epubpublicationloadoptions-threading-cancellationtoken)

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)` [#](#method-loadasync-string-officeimo-epub-epubpublicationloadoptions-threading-cancellationtoken)

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)` [#](#method-mergechapters-string-string-string-threading-cancellationtoken)

[EpubPublication.Merge.cs:10](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Merge.cs#L10)

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)` [#](#method-mergechapters-string-string-string-officeimo-epub-epubchaptermergeoptions-threading-cancellationtoken)

[EpubPublication.Merge.cs:16](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Merge.cs#L16)

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)` [#](#method-movespineitem-int32-int32)

[EpubPublication.Content.cs:145](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Content.cs#L145)

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)` [#](#method-preflight-officeimo-epub-epubsaveoptions-threading-cancellationtoken)

[EpubPublication.Preflight.cs:12](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Preflight.cs#L12)

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**

Returns

`EpubPreflightReport`

`public EpubDocument Read(EpubLoadOptions? options = null, CancellationToken cancellationToken = default)` [#](#method-read-officeimo-epub-epubloadoptions-threading-cancellationtoken)

[EpubPublication.cs:155](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.cs#L155)

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**

Returns

`EpubDocument`

`public OfficeHiddenDataReport RemoveHiddenData(OfficeHiddenDataOptions? options = null)` [#](#method-removehiddendata-officeimo-officehiddendataoptions)

[EpubPublication.HiddenData.cs:17](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.HiddenData.cs#L17)

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)` [#](#method-removeresource-string)

[EpubPublication.Content.cs:163](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Content.cs#L163)

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

Parameters

**manifestId string required**

`public void RemoveSpineItem(int index)` [#](#method-removespineitem-int32)

[EpubPublication.Content.cs:156](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Content.cs#L156)

Removes one reading position without deleting its resource.

Parameters

**index int required**

`public void RenameResource(string manifestId, string containerPath, CancellationToken cancellationToken = default)` [#](#method-renameresource-string-string-threading-cancellationtoken)

[EpubPublication.Rename.cs:25](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Rename.cs#L25)

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)` [#](#method-replacemediaoverlay-string-officeimo-epub-epubmediaoverlay-threading-cancellationtoken)

[EpubPublication.MediaOverlayReplacement.cs:13](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.MediaOverlayReplacement.cs#L13)

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)` [#](#method-save-string-officeimo-epub-epubsaveoptions-threading-cancellationtoken)

[EpubPublication.Writing.cs:110](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Writing.cs#L110)

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**

Returns

`EpubWriteReport`

`public EpubWriteReport Save(Stream stream, EpubSaveOptions? options = null, CancellationToken cancellationToken = default)` [#](#method-save-io-stream-officeimo-epub-epubsaveoptions-threading-cancellationtoken)

[EpubPublication.Writing.cs:123](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Writing.cs#L123)

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**

Returns

`EpubWriteReport`

SaveAsync 2 overloads

`public async Task<EpubWriteReport> SaveAsync(string path, EpubSaveOptions? options = null, CancellationToken cancellationToken = default)` [#](#method-saveasync-string-officeimo-epub-epubsaveoptions-threading-cancellationtoken)

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)` [#](#method-saveasync-io-stream-officeimo-epub-epubsaveoptions-threading-cancellationtoken)

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)` [#](#method-setaccessibilitymetadata-officeimo-epub-epubaccessibilitymetadata)

[EpubPublication.Accessibility.cs:16](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Accessibility.cs#L16)

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)` [#](#method-setcontentxml-string-xml-linq-xdocument)

[EpubPublication.Content.cs:63](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Content.cs#L63)

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)` [#](#method-setcontentxml-collections-generic-ireadonlydictionary-system-string-system-xml-linq-xdocument-threading-cancellationtoken)

[EpubPublication.ContentEdits.cs:10](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.ContentEdits.cs#L10)

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)` [#](#method-setcoverimage-string)

[EpubPublication.Content.cs:114](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Content.cs#L114)

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)` [#](#method-setdocumentmatter-string-officeimo-epub-epubdocumentmatter-threading-cancellationtoken)

[EpubPublication.Structure.cs:9](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Structure.cs#L9)

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)` [#](#method-setfixedlayoutpage-string-officeimo-epub-epubfixedlayoutpage-threading-cancellationtoken)

[EpubPublication.FixedLayout.cs:17](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.FixedLayout.cs#L17)

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)` [#](#method-setmetadataproperty-string-string-string)

[EpubPublication.Metadata.cs:54](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Metadata.cs#L54)

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)` [#](#member-12ab0204f5de304aa7d6f623)

[EpubPublication.Navigation.cs:9](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Navigation.cs#L9)

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)` [#](#method-setprimarytitle-string-officeimo-epub-epubtitlemetadata)

[EpubPublication.BibliographicMetadata.cs:19](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.BibliographicMetadata.cs#L19)

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)` [#](#method-setpublicationdetails-officeimo-epub-epubpublicationdetails)

[EpubPublication.BibliographicMetadata.cs:94](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.BibliographicMetadata.cs#L94)

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)` [#](#method-setrenditionlayout-officeimo-epub-epubrenditionlayout)

[EpubPublication.Metadata.cs:88](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Metadata.cs#L88)

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)` [#](#method-splitchapter-string-string-string-string-string-threading-cancellationtoken)

[EpubPublication.Split.cs:11](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Split.cs#L11)

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**

Returns

`EpubManifestItem`

`public void UpdateResource(string manifestId, byte[] data)` [#](#method-updateresource-string-byte)

[EpubPublication.Content.cs:34](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Content.cs#L34)

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)` [#](#method-write-officeimo-epub-epubsaveoptions-threading-cancellationtoken)

[EpubPublication.Writing.cs:10](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Writing.cs#L10)

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**

Returns

`EpubWriteResult`

## Inherited Methods

`public virtual bool Equals(object? obj)` [#](#method-equals-object)

Inherited from object

Parameters

**obj object? required**

Returns

`bool`

`public virtual int GetHashCode()` [#](#method-gethashcode)

Inherited from object

Returns

`int`

`public Type GetType()` [#](#method-gettype)

Inherited from object

Returns

`Type`

`public virtual string? ToString()` [#](#method-tostring)

Inherited from object

Returns

`string?`

## Properties

`public string PackagePath { get; }` [#](#property-packagepath)

[EpubPublication.cs:140](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.cs#L140)

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

`public string PackageVersion { get; }` [#](#property-packageversion)

[EpubPublication.cs:142](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.cs#L142)

Declared package version, preserved when editing.

`public IReadOnlyList<EpubManifestItem> Manifest { get; }` [#](#property-manifest)

[EpubPublication.cs:144](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.cs#L144)

Typed manifest declarations in package order.

`public IReadOnlyList<EpubSpineItem> Spine { get; }` [#](#property-spine)

[EpubPublication.cs:147](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.cs#L147)

Typed reading positions, including repeated resource references.

`public IReadOnlyList<string> EntryPaths { get; }` [#](#property-entrypaths)

[EpubPublication.cs:150](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.cs#L150)

All retained entry paths, including unmanifested extension payloads.

`public string? FilePath { get; set; }` [#](#property-filepath)

[EpubPublication.Lifecycle.cs:9](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Lifecycle.cs#L9)

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

`public string Title { get; set; }` [#](#property-title)

[EpubPublication.Metadata.cs:10](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Metadata.cs#L10)

Primary title. Other titles and refinements are retained.

`public string Language { get; set; }` [#](#property-language)

[EpubPublication.Metadata.cs:12](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Metadata.cs#L12)

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

`public string Identifier { get; set; }` [#](#property-identifier)

[EpubPublication.Metadata.cs:15](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Metadata.cs#L15)

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

`public string? Creator { get; set; }` [#](#property-creator)

[EpubPublication.Metadata.cs:25](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Metadata.cs#L25)

Primary creator, preserving other contributors and refinements.

`public string? PageProgressionDirection { get; set; }` [#](#property-pageprogressiondirection)

[EpubPublication.Metadata.cs:33](https://github.com/EvotecIT/OfficeIMO/blob/5e5a2dda74b33242f1f075718ee568bb355c03ba/OfficeIMO.Epub/Authoring/EpubPublication.Metadata.cs#L33)

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

<!-- PowerForge markdown artifact sha256:E3F79E2B9416C0FA8DEB94B7E4286A0C67946631ABF910D4BD1204A053FAFB89 -->
