Interface IDocxCompare

Namespace

DocToolkit.Extensions.DependencyInjection

Assembly

DocToolkit.Extensions.DependencyInjection.dll

Compares two versions of a Word document and returns the later one with the differences marked as tracked changes. Registered by AddDocToolkit(IServiceCollection, Action<DocToolkitOptions>?).

public interface IDocxCompare

Remarks

The result is an ordinary .docx carrying revisions, not a report — so IDocxReview reads and resolves it without knowing where it came from. Inspect lists the revisions on the report it returns, and AcceptRevisions / RejectRevisions resolve them.

Three limits, repeated here because a DI consumer reads them at the call site and nowhere else. Only paragraph text is compared; tables are reported rather than diffed; and a formatting-only change is never detected at all. A comparison that quietly mis-marked a table would be worse than one that says what it did not look at.

Separate from IDocxEditor deliberately, on the same grounds as IDocxReview: that interface is about one document's content, and this is about the difference between two of them.

There are no Stream members here, and that is not an omission to fill in later. A comparison reads two documents, while the Stream shape this library uses throughout is source/destination. Two sources and one destination is a shape nothing else has, and inventing it in the DI layer rather than in the core package would invert the direction every other member follows — core grows the overload, the mirror follows one release later. If those overloads are wanted, they belong in core first.

Methods

Compare(byte[], byte[], string)

Returns revised with its differences from original marked as tracked insertions and deletions.

byte[] Compare(byte[] original, byte[] revised, string author)

Parameters

original byte[]

The earlier version.

revised byte[]

The later version, which the result is built from.

author string

The name recorded against each revision.

Returns

byte[]

Remarks

This overload discards the report of what was NOT compared. Prefer CompareWithReport(byte[], byte[], string) unless you already know the documents contain no tables and you do not care about formatting — a caller who cannot see what the comparison skipped has a verdict covering less than they think.

Comparing a document with itself produces no revisions, rather than a document marked entirely rewritten.

Exceptions

ArgumentNullException

Any argument is null.

ArgumentException

Either document is empty, or author is blank.

DocumentConversionException

Either package could not be opened or edited.

CompareWithReport(byte[], byte[], string)

Compares two documents and reports what the comparison did not look at.

ConversionResult<byte[]> CompareWithReport(byte[] original, byte[] revised, string author)

Parameters

original byte[]

The earlier version.

revised byte[]

The later version, which the result is built from.

author string

The name recorded against each revision.

Returns

ConversionResult<byte[]>

The marked-up document, with a warning for every construct present but not compared. HasLoss is true whenever anything was skipped, which is the signal that the verdict covers less than the document.