Interface IDocxForm

Namespace

DocToolkit.Extensions.DependencyInjection

Assembly

DocToolkit.Extensions.DependencyInjection.dll

Reads, checks and fills the content controls a Word document carries — the format's own answer to a fill-in form. Registered by AddDocToolkit(IServiceCollection, Action<DocToolkitOptions>?).

public interface IDocxForm

Remarks

One of three template models, not a replacement for the other two. IDocxEditor fills {{placeholder}} text and IDocxMailMerge fills MERGEFIELD instructions; which you need is decided by whoever authored the document.

Only the document BODY is read or written. A control in a header or footer is invisible here — IDocxMailMerge does reach headers.

Methods

Fill(byte[], IReadOnlyDictionary<string, DocxFormValue>, DocxFormKey)

A copy of docx with each named control set to its value.

byte[] Fill(byte[] docx, IReadOnlyDictionary<string, DocxFormValue> values, DocxFormKey key = DocxFormKey.TagThenAlias)

Parameters

docx byte[]

The document to fill.

values IReadOnlyDictionary<string, DocxFormValue>

The value for each control.

key DocxFormKey

Which name identifies a control.

Returns

byte[]

Remarks

Lenient about a MISSING value — a control with no entry keeps its own existing text. Not lenient about a value that does not fit a typed control, and the three typed kinds disagree: a drop-down value outside its list throws, while a bad date or boolean is silently skipped. Run Validate first; it reports all three the same way.

Exceptions

ArgumentNullException

An argument is null.

ArgumentException

docx is empty, or a value is null.

DocumentConversionException

It could not be read or written, or a value did not fit a typed control.

FillAsync(Stream, Stream, IReadOnlyDictionary<string, DocxFormValue>, DocxFormKey, CancellationToken)

A copy of docx with each named control set to its value.

Task FillAsync(Stream source, Stream destination, IReadOnlyDictionary<string, DocxFormValue> values, DocxFormKey key = DocxFormKey.TagThenAlias, CancellationToken ct = default)

Parameters

source Stream

The document to fill. Read to its end; never disposed or sought.

destination Stream

Receives the filled document. Written; never disposed or sought.

values IReadOnlyDictionary<string, DocxFormValue>

The value for each control.

key DocxFormKey

Which name identifies a control.

ct CancellationToken

Cancels before the document is read, and while it is written.

Returns

Task

Inspect(byte[], DocxFormKey)

Reads the content controls in docx's body, and what they hold. Not necessarily every control — see Fields.

DocxFormReport Inspect(byte[] docx, DocxFormKey key = DocxFormKey.TagThenAlias)

Parameters

docx byte[]

The document to read.

key DocxFormKey

Which name identifies a control.

Returns

DocxFormReport

Exceptions

ArgumentNullException

docx is null.

ArgumentException

docx is empty.

DocumentConversionException

It could not be opened or read.

InspectAsync(Stream, DocxFormKey, CancellationToken)

Reads the content controls in docx's body, and what they hold. Not necessarily every control — see Fields.

Task<DocxFormReport> InspectAsync(Stream source, DocxFormKey key = DocxFormKey.TagThenAlias, CancellationToken ct = default)

Parameters

source Stream

The document to read. Read to its end; never disposed or sought.

key DocxFormKey

Which name identifies a control.

ct CancellationToken

Cancels before the document is read.

Returns

Task<DocxFormReport>

Validate(byte[], IReadOnlyDictionary<string, DocxFormValue>, DocxFormKey)

Checks values against the controls in docx without writing anything. Not a promise that Fill(byte[], IReadOnlyDictionary<string, DocxFormValue>, DocxFormKey) will succeed — image bytes are not decoded here.

DocxFormValidation Validate(byte[] docx, IReadOnlyDictionary<string, DocxFormValue> values, DocxFormKey key = DocxFormKey.TagThenAlias)

Parameters

docx byte[]

The document to check against.

values IReadOnlyDictionary<string, DocxFormValue>

The values to check.

key DocxFormKey

Which name identifies a control.

Returns

DocxFormValidation

Exceptions

ArgumentNullException

An argument is null.

ArgumentException

docx is empty, or a value is null.

DocumentConversionException

It could not be opened or read.

ValidateAsync(Stream, IReadOnlyDictionary<string, DocxFormValue>, DocxFormKey, CancellationToken)

Checks values against the controls in docx without writing anything. Not a promise that Fill(byte[], IReadOnlyDictionary<string, DocxFormValue>, DocxFormKey) will succeed — image bytes are not decoded here.

Task<DocxFormValidation> ValidateAsync(Stream source, IReadOnlyDictionary<string, DocxFormValue> values, DocxFormKey key = DocxFormKey.TagThenAlias, CancellationToken ct = default)

Parameters

source Stream

The document to check against. Read to its end; never disposed or sought.

values IReadOnlyDictionary<string, DocxFormValue>

The values to check.

key DocxFormKey

Which name identifies a control.

ct CancellationToken

Cancels before the document is read.

Returns

Task<DocxFormValidation>