Interface IDocxEditor

Namespace: DocToolkit.Extensions.DependencyInjection

Assembly: DocToolkit.Extensions.DependencyInjection.dll

Creates, reads and edits Word (.docx) documents. Registered by AddDocToolkit(IServiceCollection, Action<DocToolkitOptions>?).

public interface IDocxEditor

Methods

AddBookmark(byte[], int, string)

Adds a bookmark named name to the paragraph at paragraphIndex, and returns the updated document.

byte[] AddBookmark(byte[] docx, int paragraphIndex, string name)

Parameters

docx byte[]: The document to edit. It is not modified.
paragraphIndex int: The 0-based paragraph to mark.
name string: The bookmark name.

Returns

byte[]: A new document; the input is not modified.

Remarks

paragraphIndex is 0-based, matching everything else this interface indexes.

Exceptions

ArgumentNullException: docx or name is null.
ArgumentException: docx is empty, or name is blank.
ArgumentOutOfRangeException: paragraphIndex is negative, or at or beyond the paragraph count.
DocumentConversionException: The document could not be opened or written.

AddBookmarkAsync(Stream, int, string, Stream, CancellationToken)

Adds a bookmark named name to the paragraph at paragraphIndex, and returns the updated document.

Task AddBookmarkAsync(Stream source, int paragraphIndex, string name, Stream destination, CancellationToken ct = default)

Parameters

source Stream: The stream the document is read from.
paragraphIndex int: The 0-based paragraph to mark.
name string: The bookmark name.
destination Stream: The stream the updated document is written to.
ct CancellationToken: Cancels the read, the edit and the write.

Returns

Task

Remarks

source is read to its end and destination is written; neither is disposed, closed or sought.

Exceptions

ArgumentNullException: An argument is null.
ArgumentException: source is not readable or held no bytes, name is blank, or destination is not writable.
ArgumentOutOfRangeException: paragraphIndex is negative, or at or beyond the paragraph count.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The document could not be opened or written.

AddEndnote(byte[], string, string)

Adds an endnote at every occurrence of placeholder, inline, across the document body.

byte[] AddEndnote(byte[] docx, string placeholder, string endnoteText)

Parameters

docx byte[]
placeholder string
endnoteText string

Returns

byte[]

Exceptions

ArgumentNullException: Any of the three required arguments is null.
ArgumentException: docx is empty, or placeholder is blank.
DocumentConversionException: The package could not be edited, or placeholder does not appear in the body.

AddEndnoteAsync(Stream, string, string, Stream, CancellationToken)

Reads a .docx from source, adds an endnote at every occurrence of placeholder, and writes the result to destination — see AddEndnote(byte[], string, string). Neither stream is disposed, closed or sought.

Task AddEndnoteAsync(Stream source, string placeholder, string endnoteText, Stream destination, CancellationToken ct = default)

Parameters

source Stream
placeholder string
endnoteText string
destination Stream
ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException: Any argument is null.
ArgumentException: source is not readable or held no bytes, destination is not writable, or placeholder is blank.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The package could not be edited, or the placeholder was not found.

AddFootnote(byte[], string, string)

Adds a footnote at every occurrence of placeholder, inline, across the document body.

byte[] AddFootnote(byte[] docx, string placeholder, string footnoteText)

Parameters

docx byte[]
placeholder string
footnoteText string

Returns

byte[]

Exceptions

ArgumentNullException: Any of the three required arguments is null.
ArgumentException: docx is empty, or placeholder is blank.
DocumentConversionException: The package could not be edited, or placeholder does not appear in the body.

AddFootnoteAsync(Stream, string, string, Stream, CancellationToken)

Reads a .docx from source, adds a footnote at every occurrence of placeholder, and writes the result to destination — see AddFootnote(byte[], string, string). Neither stream is disposed, closed or sought.

Task AddFootnoteAsync(Stream source, string placeholder, string footnoteText, Stream destination, CancellationToken ct = default)

Parameters

source Stream
placeholder string
footnoteText string
destination Stream
ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException: Any argument is null.
ArgumentException: source is not readable or held no bytes, destination is not writable, or placeholder is blank.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The package could not be edited, or the placeholder was not found.

AddTableOfContents(byte[], string, int, int)

Replaces the paragraph containing only placeholder with a table of contents spanning heading levels minLevel through maxLevel.

byte[] AddTableOfContents(byte[] docx, string placeholder, int minLevel = 1, int maxLevel = 3)

Parameters

docx byte[]
placeholder string
minLevel int
maxLevel int

Returns

byte[]

Exceptions

ArgumentNullException: Either required argument is null.
ArgumentException: docx is empty, placeholder is blank, or minLevel is greater than maxLevel.
ArgumentOutOfRangeException: minLevel or maxLevel is outside 1-9.
DocumentConversionException: The package could not be edited; no paragraph containing only the placeholder was found; the paragraph holding it also holds content other than plain text; that paragraph's w:pPr carries a w:sectPr, so replacing it would discard a section break; or more than one paragraph's text exactly matches the placeholder.

AddTableOfContentsAsync(Stream, string, Stream, int, int, CancellationToken)

Reads a .docx from source, replaces the paragraph containing only placeholder with a table of contents, and writes the result to destination — see AddTableOfContents(byte[], string, int, int). Neither stream is disposed, closed or sought.

Task AddTableOfContentsAsync(Stream source, string placeholder, Stream destination, int minLevel = 1, int maxLevel = 3, CancellationToken ct = default)

Parameters

source Stream
placeholder string
destination Stream
minLevel int
maxLevel int
ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException: Any argument is null.
ArgumentException: source is not readable or held no bytes, destination is not writable, placeholder is blank, or minLevel is greater than maxLevel.
ArgumentOutOfRangeException: minLevel or maxLevel is outside 1-9.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The package could not be edited; no matching paragraph was found; the paragraph holding the placeholder also holds content other than plain text; that paragraph's w:pPr carries a w:sectPr, so replacing it would discard a section break; or more than one paragraph's text exactly matches the placeholder.

AddWatermark(byte[], string)

Stamps text across the page as a watermark, and returns the updated document.

byte[] AddWatermark(byte[] docx, string text)

Parameters

docx byte[]: The document to stamp. It is not modified.
text string: The watermark text.

Returns

byte[]: A new document; the input is not modified.

Remarks

Applied to every section the document reports, which is not always one per w:sectPr in the body. Measured: a document produced by Merge(IEnumerable<byte[]>) carries two w:sectPr elements but reports a single section, so it receives one watermark rather than one per merged document — pages belonging to the later part may therefore be unmarked. See the package README's Known Limitations.

Exceptions

ArgumentNullException: docx or text is null.
ArgumentException: docx is empty, or text is blank.
DocumentConversionException: The document could not be opened or written.

AddWatermarkAsync(Stream, string, Stream, CancellationToken)

Stamps text across the page as a watermark, and returns the updated document.

Task AddWatermarkAsync(Stream source, string text, Stream destination, CancellationToken ct = default)

Parameters

source Stream: The stream the document is read from.
text string: The watermark text.
destination Stream: The stream the stamped document is written to.
ct CancellationToken: Cancels the read, the edit and the write.

Returns

Task

Remarks

Applied to every section, for the reason AddWatermark(byte[], string) records. source is read to its end and destination is written; neither is disposed, closed or sought.

Exceptions

ArgumentNullException: An argument is null.
ArgumentException: source is not readable or held no bytes, text is blank, or destination is not writable.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The document could not be opened or written.

Create(IEnumerable<DocxBlock>)

Builds a document from blocks — headings, paragraphs, tables and inline images. Content comes from data rather than markup, so there is no HTML to escape and a value containing < cannot corrupt the document's structure. An empty sequence is valid.

byte[] Create(IEnumerable<DocxBlock> blocks)

Parameters

blocks IEnumerable<DocxBlock>

Returns

byte[]

Exceptions

ArgumentNullException: blocks is null.
ArgumentException: An element of blocks is null.
DocumentConversionException: The document could not be built.

Create(IEnumerable<DocxBlock>, PageSetup)

As above, laid out on page rather than the A4 default.

byte[] Create(IEnumerable<DocxBlock> blocks, PageSetup page)

Parameters

blocks IEnumerable<DocxBlock>: The content, written in order.
page PageSetup: The page size, orientation and margins.

Returns

byte[]

Exceptions

ArgumentNullException: blocks or page is null.
ArgumentException: An element of blocks is null.
DocumentConversionException: The document could not be built.

CreateAsync(IEnumerable<DocxBlock>, PageSetup, Stream, CancellationToken)

As above, laid out on page rather than the A4 default.

Task CreateAsync(IEnumerable<DocxBlock> blocks, PageSetup page, Stream destination, CancellationToken ct = default)

Parameters

blocks IEnumerable<DocxBlock>: The content, written in order.
page PageSetup: The page size, orientation and margins.
destination Stream: The stream the document is written to.
ct CancellationToken: Cancels the build and the write.

Returns

Task

Exceptions

ArgumentNullException: Any argument is null.
ArgumentException: An element of blocks is null, or destination is not writable.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The document could not be built or written.

CreateAsync(IEnumerable<DocxBlock>, Stream, CancellationToken)

Builds a document from blocks and writes it to destination. See Create(IEnumerable<DocxBlock>) for the block semantics. destination is written and is neither disposed, closed nor sought, so an HTTP response body is a valid destination.

Task CreateAsync(IEnumerable<DocxBlock> blocks, Stream destination, CancellationToken ct = default)

Parameters

blocks IEnumerable<DocxBlock>
destination Stream
ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException: blocks or destination is null.
ArgumentException: An element of blocks is null, or destination is not writable.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The document could not be built or written.

ExtractText(byte[])

Returns the plain text of the document body. Headers, footers, footnotes and endnotes are not included.

string ExtractText(byte[] docx)

Parameters

docx byte[]

Returns

string

Exceptions

ArgumentNullException: docx is null.
ArgumentException: docx is empty.
DocumentConversionException: The package could not be opened or read.

ExtractText(byte[], bool)

Returns the plain text of the document. When includeHeadersAndFooters is true, headers and footers follow the body text; footnotes and endnotes are never included.

string ExtractText(byte[] docx, bool includeHeadersAndFooters)

Parameters

docx byte[]
includeHeadersAndFooters bool

Returns

string

Exceptions

ArgumentNullException: docx is null.
ArgumentException: docx is empty.
DocumentConversionException: The package could not be opened or read.

ExtractTextAsync(Stream, bool, CancellationToken)

Reads a .docx from source and returns its plain text. See ExtractText(byte[], bool) for what includeHeadersAndFooters controls. source is read to its end and is neither disposed, closed nor sought.

Task<string> ExtractTextAsync(Stream source, bool includeHeadersAndFooters, CancellationToken ct = default)

Parameters

source Stream
includeHeadersAndFooters bool
ct CancellationToken

Returns

Task<string>

Exceptions

ArgumentNullException: source is null.
ArgumentException: source is not readable or held no bytes.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The package could not be opened or read.

ExtractTextAsync(Stream, CancellationToken)

Reads a .docx from source and returns the plain text of its body. Headers, footers, footnotes and endnotes are not included. source is read to its end and is neither disposed, closed nor sought.

Task<string> ExtractTextAsync(Stream source, CancellationToken ct = default)

Parameters

source Stream
ct CancellationToken

Returns

Task<string>

Exceptions

ArgumentNullException: source is null.
ArgumentException: source is not readable or held no bytes.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The package could not be opened or read.

FillRows(byte[], string, IEnumerable<IReadOnlyDictionary<string, string>>)

Expands a template table row once per record. A row holding {{collection.Field}} markers becomes one row per record, each keeping the template row's formatting.

byte[] FillRows(byte[] docx, string collection, IEnumerable<IReadOnlyDictionary<string, string>> rows)

Parameters

docx byte[]
collection string
rows IEnumerable<IReadOnlyDictionary<string, string>>

Returns

byte[]

Exceptions

ArgumentNullException: Any argument is null.
ArgumentException: docx is empty, or collection is blank.
DocumentConversionException: The package could not be opened or edited.

FillRowsAsync(Stream, string, IEnumerable<IReadOnlyDictionary<string, string>>, Stream, CancellationToken)

Reads a .docx from source, expands the template row once per record, and writes the result to destination. See FillRows(byte[], string, IEnumerable<IReadOnlyDictionary<string, string>>) for the expansion rules. Neither stream is disposed, closed or sought.

Task FillRowsAsync(Stream source, string collection, IEnumerable<IReadOnlyDictionary<string, string>> rows, Stream destination, CancellationToken ct = default)

Parameters

source Stream
collection string
rows IEnumerable<IReadOnlyDictionary<string, string>>
destination Stream
ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException: Any argument is null.
ArgumentException: source is not readable or held no bytes, destination is not writable, or collection is blank.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The package could not be opened or edited.

InspectSignatures(byte[])

Inspects docx for digital signatures — whether it carries one, how many, and who claims to have signed it. Does not validate anything cryptographically; see ValidateSignatures(byte[], DocumentSignatureValidationOptions?).

DocumentSignatureInfo InspectSignatures(byte[] docx)

Parameters

docx byte[]

Returns

DocumentSignatureInfo

Exceptions

ArgumentNullException: docx is null.
ArgumentException: docx is empty.
DocumentConversionException: The document could not be inspected.

InspectSignaturesAsync(Stream, CancellationToken)

Reads a .docx from source and inspects it for digital signatures — see InspectSignatures(byte[]). source is read to its end and is neither disposed, closed nor sought.

Task<DocumentSignatureInfo> InspectSignaturesAsync(Stream source, CancellationToken ct = default)

Parameters

source Stream
ct CancellationToken

Returns

Task<DocumentSignatureInfo>

Exceptions

ArgumentNullException: source is null.
ArgumentException: source is not readable or held no bytes.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The document could not be inspected.

IsProtected(byte[])

Whether docx is encrypted - that is, whether the other members here will refuse it. Reads the file signature; needs no password.

bool IsProtected(byte[] docx)

Parameters

docx byte[]

Returns

bool

Exceptions

ArgumentNullException: docx is null.

IsProtectedAsync(Stream, CancellationToken)

Whether docx is encrypted - that is, whether the other members here will refuse it. Reads the file signature; needs no password.

Task<bool> IsProtectedAsync(Stream source, CancellationToken ct = default)

Parameters

source Stream: The stream the document is read from.
ct CancellationToken: Cancels the read.

Returns

Task<bool>

Remarks

source is read to its end and is neither disposed, closed nor sought. Unlike IsProtected(byte[]), which answers false for an empty array, an empty source is rejected - every Stream overload in this package treats a source that held no bytes as a caller error rather than as content.

Exceptions

ArgumentNullException: source is null.
ArgumentException: source is not readable or held no bytes.
OperationCanceledException: ct was cancelled.

Merge(IEnumerable<byte[]>)

Joins docx end to end, in order, into one document — the DOCX counterpart of Merge(IEnumerable<byte[]>).

byte[] Merge(IEnumerable<byte[]> docx)

Parameters

docx IEnumerable<byte[]>: The documents to join, in order. At least one.

Returns

byte[]: A new document; none of the inputs is modified.

Remarks

Each document keeps its own page setup, as its own section, so merging an A4 document with a Letter one produces a two-section file.

Where two documents define the same style id differently, the FIRST definition wins and the later content adopts it, silently — no error is raised and no text is lost, only the appearance changes. Give the documents distinct style ids, or merge documents that share a template. Both behaviours were measured; see the package README's Known Limitations.

Exceptions

ArgumentNullException: docx, or an element of it, is null.
ArgumentException: docx is empty, or an element holds no bytes.
DocumentConversionException: A document could not be opened or the result could not be written.

MergeAsync(IEnumerable<Stream>, Stream, CancellationToken)

Joins docx end to end, in order, into one document — the DOCX counterpart of Merge(IEnumerable<byte[]>).

Task MergeAsync(IEnumerable<Stream> sources, Stream destination, CancellationToken ct = default)

Parameters

sources IEnumerable<Stream>: The streams the documents are read from, in order. At least one.
destination Stream: The stream the joined document is written to.
ct CancellationToken: Cancels the reads, the merge and the write.

Returns

Task

Remarks

Every stream in sources is read to its end and destination is written; none is disposed, closed or sought.

Exceptions

ArgumentNullException: sources or destination is null.
ArgumentException: sources is empty, one of them is not readable or held no bytes, or destination is not writable.
OperationCanceledException: ct was cancelled.
DocumentConversionException: A document could not be opened or the result could not be written.

Protect(byte[], string)

A copy of docx encrypted with password.

byte[] Protect(byte[] docx, string password)

Parameters

docx byte[]
password string

Returns

byte[]

Remarks

File encryption, not the "restrict editing" flag. The result is a compound file rather than a DOCX package, so every other member here refuses it - call Unprotect(byte[], string) first.

Exceptions

ArgumentNullException: docx or password is null.
ArgumentException: docx is empty, or password is empty.
DocumentConversionException: It could not be read or encrypted.

ProtectAsync(Stream, Stream, string, CancellationToken)

Reads a document from source and writes the encrypted copy to destination. Neither stream is disposed, closed or sought.

Task ProtectAsync(Stream source, Stream destination, string password, CancellationToken ct = default)

Parameters

source Stream
destination Stream
password string
ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException: Either stream is null, or password is null.
ArgumentException: A stream is unusable, or password is empty.
OperationCanceledException: ct was cancelled.
DocumentConversionException: It could not be encrypted.

ReadBookmarks(byte[])

Every bookmark name in the document, in the order the document declares them.

IReadOnlyList<string> ReadBookmarks(byte[] docx)

Parameters

docx byte[]: The document to read.

Returns

IReadOnlyList<string>: The bookmark names, in declaration order.

Remarks

Names only. A bookmark's position matters to Word and to AddTableOfContents, but there is no public position type here to return one against, and inventing one is a larger decision than reading the names.

Exceptions

ArgumentNullException: docx is null.
ArgumentException: docx is empty.
DocumentConversionException: The document could not be opened or read.

ReadBookmarksAsync(Stream, CancellationToken)

Every bookmark name in the document, in the order the document declares them.

Task<IReadOnlyList<string>> ReadBookmarksAsync(Stream source, CancellationToken ct = default)

Parameters

source Stream: The stream the document is read from.
ct CancellationToken: Cancels the read.

Returns

Task<IReadOnlyList<string>>: The bookmark names, in declaration order.

Remarks

source is read to its end and is neither disposed, closed nor sought.

Exceptions

ArgumentNullException: source is null.
ArgumentException: source is not readable or held no bytes.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The document could not be opened or read.

ReadMetadata(byte[])

The document properties docx carries.

DocumentMetadata ReadMetadata(byte[] docx)

Parameters

docx byte[]

Returns

DocumentMetadata

Exceptions

ArgumentNullException: docx is null.
ArgumentException: docx is empty.
DocumentConversionException: The document could not be read.

ReadMetadataAsync(Stream, CancellationToken)

The document properties docx carries.

Task<DocumentMetadata> ReadMetadataAsync(Stream source, CancellationToken ct = default)

Parameters

source Stream: The stream the document is read from.
ct CancellationToken: Cancels the read.

Returns

Task<DocumentMetadata>

Remarks

source is read to its end and is neither disposed, closed nor sought.

Exceptions

ArgumentNullException: source is null.
ArgumentException: source is not readable or held no bytes.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The document could not be read.

ReadTable(byte[], int)

The table at index, as rows of cell text.

IReadOnlyList<IReadOnlyList<string>> ReadTable(byte[] docx, int index)

Parameters

docx byte[]: The .docx content to read.
index int: 0-based, indexing what TableCount(byte[]) reports.

Returns

IReadOnlyList<IReadOnlyList<string>>

Remarks

Cell text is produced the same way ExtractText(byte[]) produces it, so a cell holding several paragraphs is separated by newlines and a nested table keeps its own structure.

Rows are returned with the shape they have. A horizontally merged cell means a row genuinely holds fewer cells than its neighbours; padding the grid to a rectangle would invent cells that are not in the document.

Exceptions

ArgumentNullException: docx is null.
ArgumentException: docx is empty.
ArgumentOutOfRangeException: index is negative, or at or beyond TableCount(byte[]).
DocumentConversionException: The package could not be read.

ReadTableAsync(Stream, int, CancellationToken)

The table at index, as rows of cell text.

Task<IReadOnlyList<IReadOnlyList<string>>> ReadTableAsync(Stream source, int index, CancellationToken ct = default)

Parameters

source Stream
index int: 0-based, indexing what TableCount(byte[]) reports.
ct CancellationToken

Returns

Task<IReadOnlyList<IReadOnlyList<string>>>

Remarks

Cell text is produced the same way ExtractText(byte[]) produces it, so a cell holding several paragraphs is separated by newlines and a nested table keeps its own structure.

Exceptions

ArgumentNullException: docx is null.
ArgumentException: docx is empty.
ArgumentOutOfRangeException: index is negative, or at or beyond TableCount(byte[]).
DocumentConversionException: The package could not be read.

RemoveWatermarks(byte[])

Removes every watermark from every section, and returns the updated document. A document with none comes back unchanged rather than refused.

byte[] RemoveWatermarks(byte[] docx)

Parameters

docx byte[]: The document to clear. It is not modified.

Returns

byte[]: A new document; the input is not modified.

Exceptions

ArgumentNullException: docx is null.
ArgumentException: docx is empty.
DocumentConversionException: The document could not be opened or written.

RemoveWatermarksAsync(Stream, Stream, CancellationToken)

Removes every watermark from every section, and returns the updated document. A document with none comes back unchanged rather than refused.

Task RemoveWatermarksAsync(Stream source, Stream destination, CancellationToken ct = default)

Parameters

source Stream: The stream the document is read from.
destination Stream: The stream the cleared document is written to.
ct CancellationToken: Cancels the read, the edit and the write.

Returns

Task

Remarks

source is read to its end and destination is written; neither is disposed, closed or sought.

Exceptions

ArgumentNullException: source or destination is null.
ArgumentException: source is not readable or held no bytes, or destination is not writable.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The document could not be opened or written.

ReplaceImage(byte[], string, byte[], double?, double?)

Replaces a text placeholder with an image, sized from the image's own header unless a dimension is given. PNG and JPEG only, decided by magic bytes rather than by filename.

byte[] ReplaceImage(byte[] docx, string placeholder, byte[] image, double? widthPoints = null, double? heightPoints = null)

Parameters

docx byte[]
placeholder string
image byte[]
widthPoints double?
heightPoints double?

Returns

byte[]

Exceptions

ArgumentNullException: Any argument is null.
ArgumentException: docx or image is empty, placeholder is blank, or the image is neither PNG nor JPEG.
ArgumentOutOfRangeException: A supplied size is zero or negative, or the resulting size is larger than a drawing extent can hold.
DocumentConversionException: The package could not be opened or edited.

ReplaceImageAsync(Stream, string, byte[], Stream, double?, double?, CancellationToken)

Reads a .docx from source, replaces the placeholder with an image, and writes the result to destination. See ReplaceImage(byte[], string, byte[], double?, double?) for sizing and format rules. Neither stream is disposed, closed or sought.

Task ReplaceImageAsync(Stream source, string placeholder, byte[] image, Stream destination, double? widthPoints = null, double? heightPoints = null, CancellationToken ct = default)

Parameters

source Stream
placeholder string
image byte[]
destination Stream
widthPoints double?
heightPoints double?
ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException: Any argument is null.
ArgumentException: source is not readable or held no bytes, destination is not writable, placeholder is blank, or the image is neither PNG nor JPEG.
ArgumentOutOfRangeException: A supplied size is zero or negative, or the resulting size is larger than a drawing extent can hold.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The package could not be opened or edited.

ReplaceText(byte[], IReadOnlyDictionary<string, string>)

Replaces every key with its value across the document body, headers, footers, footnotes and endnotes.

byte[] ReplaceText(byte[] docx, IReadOnlyDictionary<string, string> replacements)

Parameters

docx byte[]
replacements IReadOnlyDictionary<string, string>

Returns

byte[]

Exceptions

ArgumentNullException: Either argument is null.
ArgumentException: docx is empty.
DocumentConversionException: The package could not be opened or edited.

ReplaceText(byte[], Regex, string)

Replaces every match of pattern with replacement, across the body, headers, footers, footnotes and endnotes (A116).

byte[] ReplaceText(byte[] docx, Regex pattern, string replacement)

Parameters

docx byte[]: The .docx package to edit.
pattern Regex: The pattern to find. Must have a finite MatchTimeout.
replacement string: The substitution template applied to each match.

Returns

byte[]

Remarks

The dictionary overload above matches literal keys; this one matches a pattern. Everything else is identical - the same walk, the same splice, the same run-boundary handling.

replacement is a substitution TEMPLATE, not a literal. $1 and friends expand to captured groups the way Regex.Replace expands them, so a literal $</code> must be written <code>$$.

Zero-width matches are skipped, because one consumes no characters and inserting a replacement for it would not advance through the text.

pattern must carry a match timeout, and an unbounded one is refused. A pattern that can backtrack catastrophically has no upper bound on its running time, and a hang is worse than a failure because the caller cannot catch it. Construct it as new Regex(text, RegexOptions.None, TimeSpan.FromSeconds(1)).

Exceptions

ArgumentNullException: Any argument is null.
ArgumentException: docx is empty, or pattern was built without a match timeout.
DocumentConversionException: The package could not be opened or edited.

ReplaceTextAsync(Stream, IReadOnlyDictionary<string, string>, Stream, CancellationToken)

Reads a .docx from source, replaces every key with its value, and writes the result to destination. See ReplaceText(byte[], IReadOnlyDictionary<string, string>) for exactly what counts as a match. source is read to its end and destination is written; neither is disposed, closed or sought.

Task ReplaceTextAsync(Stream source, IReadOnlyDictionary<string, string> replacements, Stream destination, CancellationToken ct = default)

Parameters

source Stream
replacements IReadOnlyDictionary<string, string>
destination Stream
ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException: Any argument is null.
ArgumentException: source is not readable or held no bytes, or destination is not writable.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The package could not be opened or edited.

ReplaceTextAsync(Stream, Regex, string, Stream, CancellationToken)

Replaces every match of pattern with replacement, across the body, headers, footers, footnotes and endnotes (A116).

Task ReplaceTextAsync(Stream source, Regex pattern, string replacement, Stream destination, CancellationToken ct = default)

Parameters

source Stream: The stream the .docx package is read from.
pattern Regex: The pattern to find. Must have a finite MatchTimeout.
replacement string: The substitution template applied to each match.
destination Stream: The stream the edited .docx package is written to.
ct CancellationToken: Cancels the read, the edit and the write.

Returns

Task

Remarks

source is read to its end and destination is written; neither is disposed, closed or sought.

This remarks replaces the one on ReplaceText(byte[], Regex, string) rather than adding to it, so its warnings are restated: replacement is a template in which $1 expands to a captured group, zero-width matches are skipped, and an unbounded pattern is refused.

Exceptions

OperationCanceledException: ct was cancelled.

TableCount(byte[])

How many tables the document body holds.

int TableCount(byte[] docx)

Parameters

docx byte[]

Returns

int

Remarks

Top-level tables only. A table nested inside a cell is part of that cell's text rather than an entry of its own, so this count and the indexes it bounds stay stable.

Exceptions

ArgumentNullException: docx is null.
ArgumentException: docx is empty.
DocumentConversionException: The package could not be read.

TableCountAsync(Stream, CancellationToken)

How many tables the document body holds.

Task<int> TableCountAsync(Stream source, CancellationToken ct = default)

Parameters

source Stream
ct CancellationToken

Returns

Task<int>

Remarks

Top-level tables only. A table nested inside a cell is part of that cell's text rather than an entry of its own, so this count and the indexes it bounds stay stable.

Exceptions

ArgumentNullException: docx is null.
ArgumentException: docx is empty.
DocumentConversionException: The package could not be read.

Unprotect(byte[], string)

A copy of docx with its encryption removed.

byte[] Unprotect(byte[] docx, string password)

Parameters

docx byte[]
password string

Returns

byte[]

Exceptions

ArgumentNullException: docx or password is null.
ArgumentException: docx is empty, or password is empty.
DocumentConversionException: The password was wrong, the document was not encrypted, or it could not be read.

UnprotectAsync(Stream, Stream, string, CancellationToken)

Reads an encrypted document from source and writes the unprotected copy to destination. Neither stream is disposed, closed or sought.

Task UnprotectAsync(Stream source, Stream destination, string password, CancellationToken ct = default)

Parameters

source Stream
destination Stream
password string
ct CancellationToken

Returns

Task

Exceptions

ArgumentNullException: Either stream is null, or password is null.
ArgumentException: A stream is unusable, or password is empty.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The password was wrong, or it could not be read.

ValidateSignatures(byte[], DocumentSignatureValidationOptions?)

Validates every digital signature docx carries, returning the report-level tamper-detection verdict alongside each signature's own certificate chain trust and revocation status. Never performs revocation checking or certificate downloads over the network, regardless of options — see DocumentSignatureValidationOptions's own remarks.

DocumentSignatureValidationReport ValidateSignatures(byte[] docx, DocumentSignatureValidationOptions? options = null)

Parameters

docx byte[]
options DocumentSignatureValidationOptions

Returns

DocumentSignatureValidationReport

Exceptions

ArgumentNullException: docx is null.
ArgumentException: docx is empty.
DocumentConversionException: The document could not be validated.

ValidateSignaturesAsync(Stream, DocumentSignatureValidationOptions?, CancellationToken)

Reads a .docx from source and validates its digital signatures — see ValidateSignatures(byte[], DocumentSignatureValidationOptions?). source is read to its end and is neither disposed, closed nor sought.

Task<DocumentSignatureValidationReport> ValidateSignaturesAsync(Stream source, DocumentSignatureValidationOptions? options = null, CancellationToken ct = default)

Parameters

source Stream
options DocumentSignatureValidationOptions
ct CancellationToken

Returns

Task<DocumentSignatureValidationReport>

Exceptions

ArgumentNullException: source is null.
ArgumentException: source is not readable or held no bytes.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The document could not be validated.

WithMetadata(byte[], DocumentMetadata)

A copy of docx carrying metadata.

byte[] WithMetadata(byte[] docx, DocumentMetadata metadata)

Parameters

docx byte[]
metadata DocumentMetadata

Returns

byte[]

Remarks

A null property leaves what the document already had in place, so stamping a title does not silently erase an author. Pass an empty string to clear one.

Exceptions

ArgumentNullException: docx or metadata is null.
ArgumentException: docx is empty.
DocumentConversionException: The document could not be read or written.

WithMetadataAsync(Stream, DocumentMetadata, Stream, CancellationToken)

A copy of docx carrying metadata.

Task WithMetadataAsync(Stream source, DocumentMetadata metadata, Stream destination, CancellationToken ct = default)

Parameters

source Stream: The stream the document is read from.
metadata DocumentMetadata: The properties to stamp.
destination Stream: The stream the updated document is written to.
ct CancellationToken: Cancels the read, the edit and the write.

Returns

Task

Remarks

source is read to its end and destination is written; neither is disposed, closed or sought, and neither has to be seekable.

Exceptions

ArgumentNullException: An argument is null.
ArgumentException: source is not readable or held no bytes, or destination is not writable.
OperationCanceledException: ct was cancelled.
DocumentConversionException: The document could not be read or written.

Table of Contents

Interface IDocxEditor

Methods

AddBookmark(byte[], int, string)

Parameters

Returns

Remarks

Exceptions

AddBookmarkAsync(Stream, int, string, Stream, CancellationToken)

Parameters

Returns

Remarks

Exceptions

AddEndnote(byte[], string, string)

Parameters

Returns

Exceptions

AddEndnoteAsync(Stream, string, string, Stream, CancellationToken)

Parameters

Returns

Exceptions

AddFootnote(byte[], string, string)

Parameters

Returns

Exceptions

AddFootnoteAsync(Stream, string, string, Stream, CancellationToken)

Parameters

Returns

Exceptions

AddTableOfContents(byte[], string, int, int)

Parameters

Returns

Exceptions

AddTableOfContentsAsync(Stream, string, Stream, int, int, CancellationToken)

Parameters

Returns

Exceptions

AddWatermark(byte[], string)

Parameters

Returns

Remarks

Exceptions

AddWatermarkAsync(Stream, string, Stream, CancellationToken)

Parameters

Returns

Remarks

Exceptions

Create(IEnumerable<DocxBlock>)

Parameters

Returns

Exceptions

Create(IEnumerable<DocxBlock>, PageSetup)

Parameters

Returns

Exceptions

CreateAsync(IEnumerable<DocxBlock>, PageSetup, Stream, CancellationToken)

Parameters

Returns

Exceptions

CreateAsync(IEnumerable<DocxBlock>, Stream, CancellationToken)

Parameters

Returns

Exceptions

ExtractText(byte[])

Parameters

Returns

Exceptions

ExtractText(byte[], bool)

Parameters

Returns

Exceptions

ExtractTextAsync(Stream, bool, CancellationToken)

Parameters

Returns

Exceptions

ExtractTextAsync(Stream, CancellationToken)

Parameters

Returns

Exceptions

FillRows(byte[], string, IEnumerable<IReadOnlyDictionary<string, string>>)