Class DocxReview

Namespace

DocToolkit

Assembly

DocToolkit.Docx.dll

Reads and resolves a document's review state — the comments and tracked changes a .docx carries from having been through review.

public static class DocxReview

Inheritance

object

DocxReview

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Separate from DocxEditor deliberately. That class is about a document's content; this is about the record of people arguing over it. The two are read and acted on at different times by different callers, and folding four more operations into an already-large class would have made both harder to read.

This class reads and resolves review state; it cannot create any. There is no method here to add a comment or to record an edit as a tracked change — see the A66 backlog row for why authoring needs a targeting design of its own.

Methods

AcceptRevisions(byte[])

A copy of docx with every tracked change applied and its markup removed.

public static byte[] AcceptRevisions(byte[] docx)

Parameters

docx byte[]

The document to apply changes to.

Returns

byte[]

Remarks

Insertions become ordinary text and deletions go, which is what a reviewer means by "accept all". The result carries no revisions at all, so Inspect(byte[]) on it reports none.

This changes what the document says, and the result cannot be undone. An accepted deletion is not recoverable from the bytes this returns; keep the original if that matters.

Exceptions

ArgumentNullException

docx is null.

ArgumentException

docx is empty.

DocumentConversionException

The document could not be read or written.

AcceptRevisionsAsync(Stream, Stream, CancellationToken)

Writes a copy of the .docx in source to destination with every tracked change applied. source is read to its end and destination is written; neither is disposed, closed nor sought.

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

Parameters

source Stream

The document to apply changes to.

destination Stream

Receives the resulting document.

ct CancellationToken

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

Returns

Task

Remarks

Insertions become ordinary text and deletions go, which is what a reviewer means by "accept all". The result carries no revisions at all, so Inspect(byte[]) on it reports none.

This changes what the document says, and the result cannot be undone. An accepted deletion is not recoverable from the bytes this returns; keep the original if that matters.

Exceptions

ArgumentNullException

source or destination is null.

ArgumentException

A stream is unusable, or source held no bytes.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The document could not be read or written.

Inspect(byte[])

Reads the comments and tracked changes docx carries.

public static DocxReviewReport Inspect(byte[] docx)

Parameters

docx byte[]

The document to inspect.

Returns

DocxReviewReport

Remarks

One call rather than one per kind, because the underlying walk computes both together — separate reads could return counts that disagree because they came from different passes over the same document. A document nobody has reviewed reports empty rather than failing.

Exceptions

ArgumentNullException

docx is null.

ArgumentException

docx is empty.

DocumentConversionException

The document could not be opened or read.

InspectAsync(Stream, CancellationToken)

Reads the comments and tracked changes the .docx in source carries. source is read to its end and is neither disposed, closed nor sought.

public static Task<DocxReviewReport> InspectAsync(Stream source, CancellationToken ct = default)

Parameters

source Stream

The document to inspect.

ct CancellationToken

Cancels before the document is read.

Returns

Task<DocxReviewReport>

Remarks

One call rather than one per kind, because the underlying walk computes both together — separate reads could return counts that disagree because they came from different passes over the same document. A document nobody has reviewed reports empty rather than failing.

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.

RejectRevisions(byte[])

A copy of docx with every tracked change discarded and its markup removed.

public static byte[] RejectRevisions(byte[] docx)

Parameters

docx byte[]

The document to discard changes from.

Returns

byte[]

Remarks

Insertions go and deletions are put back, restoring what the document said before the review — the mirror of AcceptRevisions(byte[]). The result carries no revisions at all.

This changes what the document says, and the result cannot be undone. Every insertion is gone from the bytes this returns; keep the original if that matters.

Exceptions

ArgumentNullException

docx is null.

ArgumentException

docx is empty.

DocumentConversionException

The document could not be read or written.

RejectRevisionsAsync(Stream, Stream, CancellationToken)

Writes a copy of the .docx in source to destination with every tracked change discarded. source is read to its end and destination is written; neither is disposed, closed nor sought.

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

Parameters

source Stream

The document to discard changes from.

destination Stream

Receives the resulting document.

ct CancellationToken

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

Returns

Task

Remarks

Insertions go and deletions are put back, restoring what the document said before the review — the mirror of AcceptRevisions(byte[]). The result carries no revisions at all.

This changes what the document says, and the result cannot be undone. Every insertion is gone from the bytes this returns; keep the original if that matters.

Exceptions

ArgumentNullException

source or destination is null.

ArgumentException

A stream is unusable, or source held no bytes.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The document could not be read or written.

RemoveComments(byte[])

A copy of docx with every comment removed.

public static byte[] RemoveComments(byte[] docx)

Parameters

docx byte[]

The document to clean.

Returns

byte[]

Remarks

The text a comment was anchored to is left alone — only the comment and its anchor go. This is what "clear the review notes before sending it out" means, and it is not an edit to what the document says.

Exceptions

ArgumentNullException

docx is null.

ArgumentException

docx is empty.

DocumentConversionException

The document could not be read or written.

RemoveCommentsAsync(Stream, Stream, CancellationToken)

Writes a copy of the .docx in source to destination with every comment removed. source is read to its end and destination is written; neither is disposed, closed nor sought.

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

Parameters

source Stream

The document to clean.

destination Stream

Receives the cleaned document.

ct CancellationToken

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

Returns

Task

Remarks

The text a comment was anchored to is left alone — only the comment and its anchor go. This is what "clear the review notes before sending it out" means, and it is not an edit to what the document says.

Exceptions

ArgumentNullException

source or destination is null.

ArgumentException

A stream is unusable, or source held no bytes.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The document could not be read or written.