Class DocToDocxConverter

Namespace

DocToolkit

Assembly

DocToolkit.dll

Reads a Word 97-2003 binary document (.doc) — the format Word used before .docx — and converts it to a .docx package, or reads its text directly.

public static class DocToDocxConverter

Inheritance

object

DocToDocxConverter

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Import only. There is no .doc writing here and there will not be: the underlying library reports native .doc saving as unsupported, so offering it would mean claiming something that does not work.

Converting refuses by default when the source holds content a .docx cannot carry. A legacy .doc keeps pictures, drawings and form fields in a binary stream that the import can see but cannot project. Rather than quietly hand back a document missing them, Convert(byte[]) throws — see AllowContentLoss to accept the loss on purpose, and ConvertWithReport(byte[], LegacyDocOptions?) to record exactly what it was.

ExtractText(byte[]) never refuses and takes no options, because text is not what that binary stream holds. Reading a .doc someone sent you is the common case and it does not need a policy decision.

Measured 2026-08-16 against documents produced by Word itself: text, tables (every cell) and character formatting such as bold survive conversion intact.

Methods

Convert(byte[])

Converts the legacy .doc in doc to a .docx package.

public static byte[] Convert(byte[] doc)

Parameters

doc byte[]

The Word 97-2003 binary document to convert.

Returns

byte[]

Remarks

Throws when the source holds content the .docx cannot carry. Use Convert(byte[], LegacyDocOptions?) to accept that loss deliberately.

Exceptions

ArgumentNullException

doc is null.

ArgumentException

doc is empty.

DocumentConversionException

The document could not be converted, or it holds content a .docx cannot carry and AllowContentLoss was not set.

Convert(byte[], LegacyDocOptions?)

Converts the legacy .doc in doc to a .docx package.

public static byte[] Convert(byte[] doc, LegacyDocOptions? options)

Parameters

doc byte[]

The Word 97-2003 binary document to convert.

options LegacyDocOptions

How to treat content the .docx cannot carry. null means the default: refuse.

Returns

byte[]

ConvertAsync(Stream, Stream, LegacyDocOptions?, CancellationToken)

Reads a legacy .doc from source and writes the converted .docx package to destination.

Neither stream is disposed, closed or sought, so source may be forward-only — an HTTP request body, for instance.

public static Task ConvertAsync(Stream source, Stream destination, LegacyDocOptions? options, CancellationToken ct = default)

Parameters

source Stream

The stream the .doc is read from.

destination Stream

The stream the .docx package is written to.

options LegacyDocOptions

How to treat content the .docx cannot carry. null means the default: refuse.

ct CancellationToken

Cancels the read and the write.

Returns

Task

ConvertAsync(Stream, Stream, CancellationToken)

Reads a legacy .doc from source and writes the converted .docx package to destination.

Neither stream is disposed, closed or sought, so source may be forward-only — an HTTP request body, for instance.

public static Task ConvertAsync(Stream source, Stream destination, CancellationToken ct = default)

Parameters

source Stream

The stream the .doc is read from.

destination Stream

The stream the .docx package is written to.

ct CancellationToken

Cancels the read and the write.

Returns

Task

Exceptions

ArgumentException

source is not readable or held no bytes, or destination is not writable.

OperationCanceledException

ct was cancelled.

ConvertWithReport(byte[], LegacyDocOptions?)

Converts the legacy .doc in doc and reports what the import could not carry across.

public static ConversionResult<byte[]> ConvertWithReport(byte[] doc, LegacyDocOptions? options = null)

Parameters

doc byte[]

The Word 97-2003 binary document to convert.

options LegacyDocOptions

How to treat content the .docx cannot carry. null means the default: refuse.

Returns

ConversionResult<byte[]>

Remarks

Returns exactly the bytes Convert(byte[], LegacyDocOptions?) returns for the same input and options — the conversion runs once, and the report is read off the same loaded document rather than from a second pass.

The report is worth reading even on a document that converts without the opt-in: an import can be lossless and still have something to say, such as quick-save revision history that is readable but is not carried across as editable revisions.

ConvertWithReportAsync(Stream, LegacyDocOptions?, CancellationToken)

Converts the legacy .doc in doc and reports what the import could not carry across.

public static Task<ConversionResult<byte[]>> ConvertWithReportAsync(Stream source, LegacyDocOptions? options = null, CancellationToken ct = default)

Parameters

source Stream

The stream the .doc is read from.

options LegacyDocOptions

How to treat content the .docx cannot carry. null means the default: refuse.

ct CancellationToken

Cancels the read and the conversion.

Returns

Task<ConversionResult<byte[]>>

Remarks

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

The converted bytes come back in the result rather than through a destination stream, unlike ConvertAsync(Stream, Stream, CancellationToken). That is the only shape that mirrors the synchronous member it is named after: the report and the document are one value, and splitting them across a return value and an out-parameter stream would make this the odd member of its own family. PresentationEditor.AddChartAsync already returns bytes from a Stream source the same way.

Exceptions

ArgumentNullException

source is null.

ArgumentException

source is not readable or held no bytes.

OperationCanceledException

ct was cancelled.

ExtractText(byte[])

Reads the text of the legacy .doc in doc, including the contents of table cells.

public static string ExtractText(byte[] doc)

Parameters

doc byte[]

The Word 97-2003 binary document to read.

Returns

string

Remarks

Takes no options and never refuses over content loss, unlike the Convert overloads: what a .doc's binary stream holds is pictures, drawings and form fields, none of which are text, so there is nothing for a loss policy to decide.

Blocks are separated the way ExtractText(byte[]) separates them, so adjacent paragraphs do not fuse into one word.

Exceptions

ArgumentNullException

doc is null.

ArgumentException

doc is empty.

DocumentConversionException

The document could not be read.

ExtractTextAsync(Stream, CancellationToken)

Reads a legacy .doc from source and returns its text.

source is read to its end and is not disposed, closed or sought.

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

Parameters

source Stream

The stream the .doc is read from.

ct CancellationToken

Cancels the read.

Returns

Task<string>

Exceptions

ArgumentNullException

doc is null.

ArgumentException

doc is empty.

DocumentConversionException

The document could not be read.

ArgumentException

source is not readable or held no bytes.

OperationCanceledException

ct was cancelled.