Breaking changes and upgrading
Upgrading within 1.x is normally one step: raise the version of every DocWright.* package to the same number. This page lists the exceptions, newest first.
The compatibility promise
- No public member has been removed or changed from 1.3.0 to 1.12.0. Code that compiled against an older 1.x compiles against a newer one. Each release is checked against a recorded copy of every package's public API.
- All
DocWright.*packages are released together with one version. Mixing versions is not supported: upgrade them as a set. - What can change is behaviour (a fix that corrects what a call does), diagnostics (a code's severity or wording) and output (layout that moved closer to Word). Those are what the sections below list.
Output that changes between versions
Each release measures more of Word's behaviour and follows it. After an upgrade a line can break at a different word, a page at a different line, and rendered pixels can differ. If you compare DocWright's output with files you stored from an older version (PDF bytes, page images, page counts), regenerate those files when you upgrade and review the difference once.
Within one version, output is deterministic: the same input and options give the same bytes.
1.12
Nothing to change.
Worth knowing:
- A document saved by DocWright now writes its document defaults exactly as they were read. A
.docxthat Word wrote with empty default run or paragraph properties is saved with them, where 1.11 dropped them. The saved bytes of such a document differ from 1.11's, and the file opens in Word with the fonts and spacing it had.
1.11
Check code that filters or reads diagnostics.
| Change | Who is affected | What to do |
|---|---|---|
DXP3001 for a metric-compatible font substitution (Carlito for Calibri, Caladea for Cambria, the Liberation faces) is now Information, not Warning. |
Code that fails a conversion, or counts problems, on any warning. | Nothing if the lower severity suits you. To keep hearing about these substitutions, look for the code rather than the severity, or ask for the font preflight with WarnOnFontSubstitution. |
DXP2003 messages are reworded in plain language, and are no longer raised for parts DocWright reads (document properties, the font table, custom XML). |
Code that matches on the message text, or expects a fixed number of DXP2003 notes. |
Match on the code, not the text. |
| A paragraph's text frame now merges onto its style's frame attribute by attribute, as Word does. | Documents whose paragraphs state part of a frame and take the rest from a style. | Nothing: such paragraphs are now placed where Word places them. |
1.10
Three fixes change what existing code sees.
| Change | Who is affected | What to do |
|---|---|---|
XlsxCellValue.Number(double) writes very small values (below 1E-14 in magnitude) in scientific notation with 15 significant digits. They were written as 0 or with fewer digits. |
Workbooks generated with very small numbers. | Nothing: the cells now hold the value you gave. Stored files from 1.9 differ. |
Disposing a WordDocument.Clone(), or a CompareResult.Document, no longer disposes the original's images. Disposing the original still ends the clone's access. |
Code that worked around the old behaviour by keeping clones alive. | The workaround can go. |
A failed Load disposes the document it never returned. Your own input stream stays open, as before. |
Nobody needs to change code. | Nothing. |
The two font switches added in this release, IncludeSystemFontDirectories and IncludeBundledMetricFonts, default to true, so conversions behave as before unless you turn one off.
1.4 to 1.9
Nothing to change.
1.3.0
A positioned text box is its own node.
Before 1.3.0 the DOCX reader represented a positioned text box as an ImageRef with the content type application/vnd.docwright.textbox, and a page number inside it as the marker text <<DOCWRIGHT:FIELD:PAGE>>.
From 1.3.0 the reader builds a PositionedTextBox whose content is a list of TextBoxSegments: text, and page numbers carrying the result the document last stored.
| If your code | Change it to |
|---|---|
Finds text boxes by looking through ImageRefs for that content type |
Look for PositionedTextBox nodes. |
| Looks for the marker text inside a box | Read the box's segments; a page number is a segment of its own. |
A model you built yourself with the old representation still draws as it did.