Aspose.Words for .NET 22.2 Release Notes

Major Features

There are 111 improvements and fixes in this regular monthly release. The most notable are:

• AZW3 format (KF8 is another name of the format) is now supported for loading.
• Added an ability to get custom field data which is associated with the field.
• Saving progress notifications were extended for HTML-based and XAML-based flow formats.
• Provided an ability to convert Shapes to SVG images upon export to HTML, MHTML or EPUB.
• Implemented list numbering export to PDF logical structure.

Full List of Issues Covering all Changes in this Release (Reported by .NET Users)

Full List of Issues Covering all Changes in this Release (Reported by Java Users)

Public API and Backward Incompatible Changes

This section lists public API changes that were introduced in Aspose.Words 22.2. It includes not only new and obsoleted public methods, but also a description of any changes in the behavior behind the scenes in Aspose.Words which may affect existing code. Any behavior introduced that could be seen as regression and modifies the existing behavior is especially important and is documented here.

Added FieldStart.FieldData property

Related issue: WORDSNET-23198

The following public property is added to FieldStart class:

/// <summary>
/// Gets custom field data which is associated with the field.
/// </summary>
public byte[] FieldData { get; }

Use Case:

Document doc = new Document(fileName);
Field field = doc.Range.Fields[0];
Console.WriteLine(field.Start.FieldData.Length);
Console.WriteLine(Encoding.Default.GetString(field.Start.FieldData));

Added HtmlSaveOptions.SaveShapesAsSvg public property

Related issue: WORDSNET-23235

The following public property is added to HtmlSaveOptions class:

/// <summary>
/// Controls whether <see cref="Drawing.Shape"/> nodes are converted to SVG images when saving to HTML, MHTML or EPUB.
/// Default value is <c>false</c>.
/// </summary>
/// <remarks>
/// <para>
/// If this option is set to <c>true</c>, <see cref="Drawing.Shape"/> nodes are exported as &lt;svg&gt; elements.
/// Otherwise, they are rendered to bitmaps and are exported as &lt;img&gt; elements.
/// </para>
/// <para>
/// Note that this options also affects text boxes, because they are represented by <see cref="Drawing.Shape"/> nodes.
/// As a result, if this option is set to <c>true</c>, it overrides the <see cref="ExportTextBoxAsSvg"/> property
/// value and causes text boxes to be converted to SVG.
/// </para>
/// </remarks>
public bool ExportShapesAsSvg
{
    get { return mSaveImageOptions.ShapesAsSvg; }
    set { mSaveImageOptions.ShapesAsSvg = value; }
}

Use Case:

Document doc = new Document(fileName);
HtmlSaveOptions saveOptions = new HtmlSaveOptions();
saveOptions.ExportShapesAsSvg = true;
doc.Save(outputFileName, saveOptions);

AZW3 format is now supported for loading

Related issue: WORDSNET-22411

Aspose.Words can now load AZW3 documents (KF8 is another name of the format). Usually, documents in the AZW3 format have the “.azw3” or “.mobi” extension. However, a “.mobi” document may be in the older MOBI format, and some “.mobi” documents contain two versions of content - MOBI and AZW3 - for backward compatibility.

The following table explains what reader Aspose.Words uses to load MOBI and AZW3 documents in different cases:

Currently, Aspose.Words always loads all topics from an AZW3 document in the order in which they appear in the table of contents.

The following publicly visible enum values were added:

FileFormat.Azw3
LoadFormat.Azw3

The FileFormatUtil class can now be used to determine if a file is an AZW3 document. For example, the following call

FileFormatInfo info = FileFormatUtil.DetectFileFormat("book.azw3");

will return an info instance with the FileFormatInfo.LoadFormat property set to LoadFormat.Azw3.

Currently, no load options have effect when loading AZW3 documents. LoadOptions.ResourceLoadingCallback is not invoked when loading AZW3 documents, because Aspose.Words expects all referenced resource files to be stored locally in the AZW3 document. Like in the Kindle reader, references to external resource files are ignored.

As a result, the only use cases for loading AZW3 documents that is currently available is the one illustrated below:

Document doc = new Document("book.azw3");

Enabled saving progress notifications for HTML-based and XAML-based flow formats

Related issue: WORDSNET-23319

The SaveOptions.ProgressCallback is now also invoked when saving to the following HTML-based and XAML-based flow formats: Html, Mhtml, Epub, XamlFlow, and XamlFlowPack.

Breaking change – explicit Table.AutoFit() call may be required to make table structure match the specified cell widths in a builder scenario

A major update that handles tables with incorrect or missing column width data in the source document is released in Aspose.Words 22.2.

Cell/column width data and the number of columns spanned by a cell are re-calculated from table and cell properties. Column width data stored in the document are replaced by re-calculated values.

The algorithm imitates MS Word logic that does not use cell widths. (In fact, cell width is not even stored in .DOCX format used by MS Word).

The new logic may change the output for some document builder scenarios. In the following example the number of columns spanned by the cell in row 2 is no longer calculated automatically from the specified cell widths:

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// First row
builder.StartTable();

Cell cell1 = builder.InsertCell();
cell1.CellFormat.Width = 100;
builder.Write("Text in cell 1.");

Cell cell2 = builder.InsertCell();
cell2.CellFormat.Width = 100;
builder.Write("Text in cell 2.");

// End of first row
builder.EndRow();

// Second row
Cell cell3 = builder.InsertCell();
cell3.CellFormat.Width = 200;
builder.Write("Row 2 cell spans 2 columns.");

// End of second row
builder.EndRow();
builder.EndTable();

doc.UpdatePageLayout();
doc.Save("mergedCell.docx");

The behavior was changed because cell width data proved to be unreliable in a number of generated documents.

In order to preserve the specified cell widths in the above scenario and calculate the number of columns spanned by a cell from cell width, Aspose.Words should be explicitly instructed by calling Table.AutoFit() method:

...
Table table = builder.EndTable();

// Re-calculate table structure from the specified cell widths.
table.AutoFit(AutoFitBehavior.FixedColumnWidths);
doc.UpdatePageLayout();
doc.Save("mergedCell.docx");

This will also set table layout to fixed, which is better suited for preserving cell widths regardless of contents.

Removed obsolete property FieldXE.HasPageRangeBookmarkName

Removed obsolete property FieldXE.HasPageRangeBookmarkName. Please, use the FieldXE.PageRangeBookmarkName property instead.