Aspose.Words for .NET 17.2.0 Release Notes

Major Features

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

  • Export fonts to HTML in Base64 encoding
  • Added HtmlSaveOptions.ResourceFolder and HtmlSaveOptions.ResourceFolderAlias public properties
  • Exposed access to Height/Width of Text Frames
  • Improved control over BiDi text direction elements
  • Non-bidi fields that contain hided bidi whitespaces are properly resolved

Full List of Issues Covering all Changes in this Release

KeySummaryCategory
WORDSNET-12975Math equation’s alignment is changed in output PdfBug
WORDSNET-13516Document.Compare returns incorrect revisionsBug
WORDSNET-13568Left indentation of list items is incorrect in generated ODTBug
WORDSNET-13719pic:pic element is not written during RTF to DOCX conversionBug
WORDSNET-13993Cell’s background-colors is not correct in output Html/Docx/PdfBug
WORDSNET-14008Footnote line renders higher in PDFBug
WORDSNET-14076/hidden cell break/ When Converted To PDF, text in output file is not on same page like in original Word document.Bug
WORDSNET-14393Page break is lost after re-saving WordML documentBug
WORDSNET-14464Attributes related to FitText are improperly read into the model of the .DOC document.Bug
WORDSNET-14481Docx to Pdf conversion issue with TOC item renderingBug
WORDSNET-14537Single Solid-line in word document converts double border for the images in HTMLBug
WORDSNET-14553Docx to HtmlFixed conversion issue with table’s bordersBug
WORDSNET-14595StyleCollection.addCopy - Breaking the Multi Level List numbering for Heading stylesBug
WORDSNET-14606A text overlaps on top left logo image in PDFBug
WORDSNET-14654Extra TOC entry is rendered in output PdfBug
WORDSNET-14670Bookmark missing after open and resave document using Aspose.WordsBug
WORDSNET-14674Header contents are lost after conversion from Docx to PdfBug
WORDSNET-14676Docx to Pdf conversion issue with hyperlinksBug
WORDSNET-14678When DOCX is saved as PDF by using a FileStream or MemoryStream, then the output document is missing some elements.Bug
WORDSNET-14684Position of SmartArt elements are changed in output PdfBug
WORDSNET-14685Docx to Pdf conversion issue with hyperlinksBug
WORDSNET-14686Document.Compare increases the Table’s cellsBug
WORDSNET-14689List numberings changes from alphabets to numbers during renderingBug
WORDSNET-14698UpdateFields truncates text in bookmark cross-referenceBug
WORDSNET-14703A formula errors to “divide by zero” when calling UpdateFieldsBug
WORDSNET-14717Charts become invisible in output HtmlFixedBug
WORDSNET-14728Word to PDF conversion create “double encodes” hyperlinksBug
WORDSNET-14732Some text content is repeated in rendered documentBug
WORDSNET-14749Rtf to Doc conversion issue with page numbers of TOC field.Bug
WORDSNET-14752When open document, a Aspose.Words.FileCorruptedException occurs.Bug
WORDSNET-14761HTML document has no <link> to external CSS file when callback is usedBug
WORDSNET-14768Horizontal Axis of chart does not render correctly in output PNGBug
WORDSNET-14792Document.Compare does not work for CheckBox (FormField)Bug
WORDSNET-11771Support the dir and the bdo elementsEnhancement
WORDSNET-14579Date Field with mixed bidi/non-bidi formatting.Enhancement
WORDSNET-14589Add CssFolder property to HtmlSaveOptionsEnhancement
WORDSNET-14590Discrepancy between HtmlSaveOptions and HtmlFixedSaveOptions regarding ImagesFolder and FontsFolder properties.Enhancement
WORDSNET-14713More horizontal spacing between paragraphs of the same style when exporting to HTMLEnhancement
WORDSNET-14741Review when Word ignores strokes with weight less that 1 ptEnhancement
WORDSNET-14636Aspose.Words.FileCorruptedException occurs upon loading a DOCXException
WORDSNET-14642Document.Save method throws System.InvalidOperationException whend document is re-savedException
WORDSNET-14702FileCorruptedException caused by chartsException
WORDSNET-14746NullReferenceException while mailmergeException
WORDSNET-14762Export fonts to HTML in Base64 encodingFeature
WORDSNET-5645Expose (Height/Width) access to Text FramesFeature
WORDSNET-6833OutOfMemoryException occurs during rendering DOCX to PDFPerformance

Public API and Backward Incompatible Changes

This section lists public API changes that were introduced in Aspose.Words 17.2.0. 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 a regression and modifies existing behavior is especially important and is documented here.

WORDSNET-14589 and WORDSNET-14590 - Added public properties HtmlSaveOptions.ResourceFolder and HtmlSaveOptions.ResourceFolderAlias

New public properties ResourceFolder and ResourceFolderAlias are added into the HtmlSaveOptions class:

/// <summary>
/// Specifies a physical folder where all resources like images, fonts, and external CSS are saved when a document
/// is exported to HTML. Default is an empty string.
/// </summary>
/// <remarks>
/// <p><see cref="ResourceFolder"/> is the simplest way to specify a folder where all resources should be written.
/// Another way is to use individual properties <see cref="FontsFolder"/>, <see cref="ImagesFolder"/>,
/// and <see cref="CssStyleSheetFileName"/>.</p>
///
/// <p><see cref="ResourceFolder"/> has a lower priority than folders specified via <see cref="FontsFolder"/>,
/// <see cref="ImagesFolder"/>, and <see cref="CssStyleSheetFileName"/>. For example, if both <see cref="ResourceFolder"/>
/// and <see cref="FontsFolder"/> are specified, fonts will be saved to <see cref="FontsFolder"/>, while images and CSS
/// will be saved to <see cref="ResourceFolder"/>.</p>
///
/// <p>If the folder specified by <see cref="ResourceFolder"/> doesn't exist, it will be created automatically.</p>
///
/// <seealso cref="FontsFolder"/>
/// <seealso cref="ImagesFolder"/>
/// <seealso cref="CssStyleSheetFileName"/>
/// </remarks>
public string ResourceFolder
{
    get { return mResourceFolder; }
    set
    {
        ArgumentUtil.CheckNotNull(value, "ResourceFolder");
        mResourceFolder = value;
    }
}
/// <summary>
/// Specifies the name of the folder used to construct URIs of all resources written into an HTML document.
/// Default is an empty string.
/// </summary>
/// <remarks>
/// <p><see cref="ResourceFolderAlias"/> is the simplest way to specify how URIs for all resource files should be
/// constructed. Same information can be specified for images and fonts separately via <see cref="ImagesFolderAlias"/>
/// and <see cref="FontsFolderAlias"/> properties, respectively. However, there is no individual property for CSS.</p>
///
/// <p><see cref="ResourceFolderAlias"/> has lower priority than <see cref="FontsFolderAlias"/>
/// and <see cref="ImagesFolderAlias"/>. For example, if both <see cref="ResourceFolderAlias"/>
/// and <see cref="FontsFolderAlias"/> are specified, fonts' URIs will be constructed using <see cref="FontsFolderAlias"/>,
/// while URIs of images and CSS will be constructed using <see cref="ResourceFolderAlias"/>.</p>
///
/// <p>If <see cref="ResourceFolderAlias"/> is empty, the <see cref="ResourceFolder"/> property value will be used
/// to construct resource URIs.</p>
///
/// <p>If <see cref="ResourceFolderAlias"/> is set to '.' (dot), resource URIs will contain file names only, without
/// any path.</p>
///
/// <seealso cref="ResourceFolder"/>
/// <seealso cref="FontsFolderAlias"/>
/// <seealso cref="ImagesFolderAlias"/>
/// </remarks>
public string ResourceFolderAlias
{
    get { return mResourceFolderAlias; }
    set
    {
        ArgumentUtil.CheckNotNull(value, "ResourceFolderAlias");
        mResourceFolderAlias = value;
    }
}

Behavior of properties FontsFolder, FontsFolderAlias, ImagesFolder, ImagesFolderAlias and CssStyleSheetFileName are not changed.

Note that CssStyleSheetFileName properties is used both for specifying folder name and file name.

Order of priority in which Aspose.Words decides into what folder to write external CSS style sheet:

  1. Folder specified in CssStyleSheetFileName property.
  2. Folder specified in ResourceFolder property.
  3. Output folder where HTML document is saved

Order of priority in which Aspose.Words decides what name external CSS style sheet has:

  1. File name specified in CssStyleSheetFileName property.
  2. Output HTML file name with “.css” extension.

Order of priority in which Aspose.Words decides into what folder to write fonts:

  1. Folder specified in FontsFolder property.
  2. Folder specified in ResourceFolder property.
  3. Folder where code assembly is located.

Order of priority in which Aspose.Words decides into what folder to write images:

  1. Folder specified in ImagesFolder property.
  2. Folder specified in ResourceFolder property.
  3. Folder where code assembly is located.

Note that when relative path is specified, FontsFolder and ImagesFolder are relative to folder where code assembly is located, ResourceFolder and CssStyleSheetFileName are relative to output folder where HTML document is located.

Here are some use cases. In examples below input test document has name Test.docx, output HTML document has name Test.html. Input document has one image Test.001.png and one font Test.calibril.ttf. By default external CSS style sheet has name Test.css.

  1. Simplest scenario. Use it if you want to save all external resources in one folder.
Document doc = new Document(@"C:\Test.docx");
HtmlSaveOptions saveOptions = new HtmlSaveOptions();
saveOptions.CssStyleSheetType = CssStyleSheetType.External;
saveOptions.ExportFontResources = true;
saveOptions.ResourceFolder = @"C:\Resources";
doc.Save(@"C:\Test.html", saveOptions);

Output

C:\Test.html
C:\Resources\Test.001.png
C:\Resources\Test.calibril.ttf
C:\Resources\Test.css
Document doc = new Document(@"C:\Test.docx");
HtmlSaveOptions saveOptions = new HtmlSaveOptions();
saveOptions.ResourceFolder = @"C:\Resources";
doc.Save(@"C:\Test.html", saveOptions);

Output

C:\Test.html
C:\Resources\Test.001.png

Fonts and CSS style sheet are not written as external resources.

Document doc = new Document(@"C:\Test.docx");
HtmlSaveOptions saveOptions = new HtmlSaveOptions();
saveOptions.CssStyleSheetType = CssStyleSheetType.External;
saveOptions.ExportFontResources = true;
saveOptions.ResourceFolder = "Resources";
doc.Save(@"C:\Test.html", saveOptions);

Output

C:\Test.html
C:\Resources\Test.001.png
C:\Resources\Test.calibril.ttf
C:\Resources\Test.css

When ResourceFolder specifies relative path this path is relative to output folder, where HTML document is saved.

Document doc = new Document(@"C:\Test.docx");
HtmlSaveOptions saveOptions = new HtmlSaveOptions();
saveOptions.CssStyleSheetType = CssStyleSheetType.External;
saveOptions.ExportFontResources = true;
saveOptions.ResourceFolder = @"C:\Resources";
saveOptions.ResourceFolderAlias = "https://www.example.com/resources";
doc.Save(@"C:\Test.html", saveOptions);

Output

C:\Test.html
C:\Resources\Test.001.png
C:\Resources\Test.calibril.ttf
C:\Resources\Test.css

In this scenario https://www.example.com/resources alias is used to construct URIs of all resources.

Document doc = new Document(@"C:\Test.docx");
HtmlSaveOptions saveOptions = new HtmlSaveOptions();
saveOptions.CssStyleSheetType = CssStyleSheetType.External;
saveOptions.ExportFontResources = true;
saveOptions.ResourceFolderAlias = "https://www.example.com/resources";
doc.Save(@"C:\Test.html", saveOptions);

Output

C:\Test.html
C:\Test.001.png
C:\Test.calibril.ttf
C:\Test.css

In this scenario https://www.example.com/resources alias is used to construct URIs of all resources.

Document doc = new Document(@"C:\Test.docx");
HtmlSaveOptions saveOptions = new HtmlSaveOptions();
saveOptions.CssStyleSheetType = CssStyleSheetType.External;
saveOptions.CssStyleSheetFileName = @"C:\Css\";
saveOptions.ExportFontResources = true;
saveOptions.ResourceFolder = @"C:\Resources";
doc.Save(@"C:\Test.html", saveOptions);

Output

C:\Test.html
C:\Css\Test.css
C:\Resources\Test.001.png
C:\Resources\Test.calibril.ttf
Document doc = new Document(@"C:\Test.docx");
HtmlSaveOptions saveOptions = new HtmlSaveOptions();
saveOptions.CssStyleSheetType = CssStyleSheetType.External;
saveOptions.ExportFontResources = true;
saveOptions.FontsFolder = @"C:\Fonts";
saveOptions.ResourceFolder = @"C:\Resources";
doc.Save(@"C:\Test.html", saveOptions);

Output

C:\Test.html
C:\Fonts\Test.calibril.ttf
C:\Resources\Test.001.png
C:\Resources\Test.css
Document doc = new Document(@"C:\Test.docx");
HtmlSaveOptions saveOptions = new HtmlSaveOptions();
saveOptions.CssStyleSheetType = CssStyleSheetType.External;
saveOptions.ExportFontResources = true;
saveOptions.ImagesFolder = @"C:\Images";
saveOptions.ResourceFolder = @"C:\Resources";
doc.Save(@"C:\Test.html", saveOptions);

Output

C:\Test.html
C:\Images\Test.001.png
C:\Resouces\Test.calibril.ttf
C:\Resources\Test.css
Document doc = new Document(@"C:\Test.docx");
HtmlSaveOptions saveOptions = new HtmlSaveOptions();
saveOptions.CssStyleSheetType = CssStyleSheetType.External;
saveOptions.CssStyleSheetFileName = "MyStyleSheet.css";
saveOptions.ExportFontResources = true;
saveOptions.ResourceFolder = @"C:\Resources";
doc.Save(@"C:\Test.html", saveOptions);

Output

C:\Test.html
C:\Resouces\Test.001.png
C:\Resouces\Test.calibril.ttf
C:\Resouces\MyStyleSheet.css

WORDSNET-14762 - Added Public Property HtmlSaveOptions.ExportFontsAsBase64.

Check the detailed article on Export fonts to HTML in Base64 encoding

New public property ExportFontsAsBase64 is added into the HtmlSaveOptions class:

/// <summary>
/// Specifies whether fonts resources should be embedded to HTML in Base64 encoding.
/// Default is <c>false</c>.
/// </summary>
/// <remarks>
/// <p>By default, fonts are written to separate files. If this option is set to <c>true</c>, fonts will be embedded
/// into the document's CSS in Base64 encoding.</p>
/// </remarks>
public bool ExportFontsAsBase64 {
    get { return mExportFontsAsBase64; }
    set { mExportFontsAsBase64 = value; }
}

The property affects only HTML format and doesn’t affect EPUB and MHTML. This is an extension to HtmlSaveOptions.ExportFontResources option and ExportFontsAsBase64 will work only if this property set to true.

UC

HtmlSaveOptions saveOptions = new HtmlSaveOptions();
saveOptions.ExportFontResources = true;
saveOptions.ExportFontsAsBase64 = true;
doc.Save(fileName, saveOptions);