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

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.

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.

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.