Aspose.Words for .NET 17.10 Release Notes

Major Features

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

  • “Don’t add extra space for raised/lowered characters” compatibility option is supported.
  • Multiple improvements in RTL and Asian text handling.
  • LINQ Reporting Engine supports dynamic chart series removal.
  • ‘Black and white’ images with one bit per pixel format rendering implemented. PixelFormat.Format1bppIndexed was introduced.
  • An option to prevent the fonts embedding into HTML Fixed output implemented. Introduced HtmlFixedSaveOptions.UseTargetMachineFonts property.
  • Rendering of HTML fixed documents with “PRC” encoding fonts has been improved.
  • An algorithm, which mimics the behavior of MS Word when rendering of rotated VML shapes with text boxes.
  • Rendering of “Surface” and “Stock” DrawingML Charts has been improved.
  • Added CompareOptions.Target property and enumeration ComparisonTargetType.
  • Added public methods to add and remove replies to comment.
  • Ability to get and set the number of footnote layout columns.
  • Provide API similar to SignatureSet.AddSignatureLine Method (Office).
  • Expose Table.HorizontalAlignment property public.

Full List of Issues Covering all Changes in this Release

WORDSNET-11299Table column widths are not rendered correctly in PDFBug
WORDSNET-11681/non-breaking space/ DrawingMLs are not rendering on the same line in PDFBug
WORDSNET-12258Docx to Pdf conversion issue with table renderingBug
WORDSNET-12536Docx to PDF/Tiff conversion issue with text position relative to line shapeBug
WORDSNET-12916The font is not recognized in output HtmlFixed/PdfBug
WORDSNET-13270Font Substitution issue while rendering Doc to HtmlFixedBug
WORDSNET-13944Shape’s text does not render correctly in output PdfBug
WORDSNET-14212Line breaks appear in gray after ODT-HTML-ODT roundtripBug
WORDSNET-14692Document.AcceptAllRevisions does not accept all revisionsBug
WORDSNET-15217DOC to PDF conversion losing headerBug
WORDSNET-15218DOC to PDF conversion loses text formattingBug
WORDSNET-15306Japanese text and font is changed after re-saving RTFBug
WORDSNET-15417Shape’s text is rendered in two lines after Docx to Pdf conversionBug
WORDSNET-15431Opening embedded Visio Drawing issueBug
WORDSNET-15636Revisions are colored incorrectly when rendering to HTML and MHTML output.Bug
WORDSNET-15664Document.Compare generates incorrect revisions for table of contentsBug
WORDSNET-15681Document compare issue with bullet list when CompareOptions.IgnoreFormatting is usedBug
WORDSNET-15727ListFormat.ListLevel.Font does not report bold attribute properlyBug
WORDSNET-15772Open Save an RTF changes Headline when viewing via WordPad viewBug
WORDSNET-15789Charts are not rendered correctly in output PDFBug
WORDSNET-15790RTF to PDF conversion results blank documentBug
WORDSNET-15793Hebrew text does not render correctly in output PDFBug
WORDSNET-15807Page numbers are missing in resultant PDF footerBug
WORDSNET-15810Aspose.Words 17.08 Exception when saving .ott documents to .doc and .dot formatsBug
WORDSNET-15813Indent issue in DOC outputBug
WORDSNET-15819Surface chart is rendered wider than in MS Word.Bug
WORDSNET-15820Stock chart is rendered improperly.Bug
WORDSNET-15825Server hangs while saving and sending PDF document to browserBug
WORDSNET-15850ShowRevisionMarks does not work when its value is falseBug
WORDSNET-15851Text is missing in DOCX to PDF renderingBug
WORDSNET-15854Document.HasRevisions returns incorrect value after using Document.ComareBug
WORDSNET-15860Incorrect page count of an ODT DocumentBug
WORDSNET-15865DOCX to image conversion issue with Japanese text positionBug
WORDSNET-15871Document.AcceptAllRevisions throws System.InvalidOperationExceptionBug
WORDSNET-15878RTL letters order changed in rendered PDFBug
WORDSNET-15906The diagram/circle is missing.Bug
WORDSNET-15907Y-axis and grid lines of charts do not render correctly in output PDFBug
WORDSNET-15911MS Word reports that the output document is corrupted after open/save with AW.Bug
WORDSNET-1077Empty paragraphs become paragraphs with non-breaking space character during DOC-HTML-DOC roundtrip.Enhancement
WORDSNET-13098Applying simple textures (such as Color, Gradient, Picture, etc.) for 3D shapes (hardware rendering)Enhancement
WORDSNET-14505Support comments tree in HTML exportEnhancement
WORDSNET-15797Import textboxes saved by MS Word to HTMLEnhancement
WORDSNET-14671Shape.StrokeColor throws System.NullReferenceExceptionException
WORDSNET-15688DOCX to HTML conversion throws NullReferenceExceptionException
WORDSNET-15751DocumentBuilder.InsertImage throws System.IndexOutOfRangeException exception while inserting SVG into documentException
WORDSNET-15758System.InvalidCastException is thrown while loading DOC fileException
WORDSNET-15779Aspose.Words.FileCorruptedException occurs when loading a HTMLException
WORDSNET-15795System.NotSupportedException is thrown while saving DOC to PDFException
WORDSNET-15809NullReferenceException inside OdtChartToDmlConverter.Exception
WORDSNET-15823Deletion issue of bookmarks with duplicate nameException
WORDSNET-15831Document.UpdateFields throws System.ArgumentExceptionException
WORDSNET-15844Appending a large RTF file throws ArgumentExceptionException
WORDSNET-15847Converting Charts in DOCX to PDF or DOC causes System.DivideByZeroExceptionException
WORDSNET-15855System.IndexOutOfRangeException is thrown while saving DOCX to DOC/PDFException
WORDSNET-12458Support new features of MS Word 2016Feature
WORDSNET-13489Add feature to set ImageSaveOptions.PixelFormat to ‘1 bits per pixel, indexed’Feature
WORDSNET-14958Add feature to set/get footnote layout columnFeature
WORDSNET-14984Provide API similar to SignatureSet.AddSignatureLine Method (Office)Feature
WORDSNET-15342Support to modify number formatting of chartsFeature
WORDSNET-15442Dynamically add or remove series on a chart in LINQ reporting - a new template tag.Feature
WORDSNET-15739Applying a radial gradient fill (hardware rendering).Feature
WORDSNET-15740Applying a rectangular gradient fill (hardware rendering).Feature
WORDSNET-15741Applying a path gradient fill (hardware rendering).Feature
WORDSNET-15747/Don’t add extra space for raised/lowered characters/ Table data moves to next page in DOC to PDF renderingFeature
WORDSNET-15817Expose Table.HorizontalAlignment property public.Feature
WORDSNET-15880Prevent embedding fonts while saving into HTMLFeature
WORDSNET-15885Implement support of transform for radial gradient fill (hardware rendering).Feature
WORDSNET-4150Allow embedding fonts into RTF documents.Feature
WORDSNET-4151Allow embedding fonts into DOC documents.Feature
WORDSNET-4977/com/ Create a sample project which provides a wrapper for common methods that cannot be easily called from COM or scripting languagesFeature
WORDSNET-9959Provide way to add a Reply Comment in documentFeature
WORDSNET-15774The output PDF file is getting too bigPerformance
WORDSNET-15822Saving documents difference as HTML throws InvalidOperationException in 17.8Regression
WORDSNET-15869RTL text with spaces reversed after replacementRegression
WORDSNET-15872Incorrect position of a text box anchored in an RTL paragraphRegression
WORDSNET-15883Aspose.Words throws FileCorruptedException upon loading DOCM fileRegression

Public API and Backward Incompatible Changes

This section lists public API changes that were introduced in Aspose.Words 17.10. 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.

Added CompareOptions.Target Property and Enumeration ComparisonTargetType

Related issue WORDSNET-15681.

Public property added to the CompareOptions class to provide ability to determine base document upon documents comparison. 

For example, this option together with IgnoreFormatting setting determines which document has to be used as formatting source for ranges of equal text.

/// <summary>
/// Specifies which document shall be used as a target during comparison.
/// </summary>
public ComparisonTargetType Target
  get { return mTargetType; }
  set { mTargetType = value; }

Possible values described by the following enumeration

/// <summary>
/// Allows to specify base document which will be used during comparison.  Default value is <see cref="Current" />.
/// </summary>
/// <remarks>
/// Relates to Microsoft Word "Show changes in" option in "Compare Documents" dialog box.
/// </remarks>
public enum ComparisonTargetType
  /// <summary>
  /// This document is used as a base during comparison.
  /// </summary>
  /// <summary>
  /// Other document is used as a base during comparison.
  /// </summary>
// Use case.
Document docA = new Document(pathA);
Document docB = new Document(pathB);
CompareOptions options = new CompareOptions();
options.IgnoreFormatting = true;
options.Target =  ComparisonTargetType.New;
docA.Compare(docB, "am", DateTime.Now, options);

LINQ Reporting Engine Supports Dynamic Chart Series Removal

Related Issue: WORDSNET-15442

The “Using Charts to Represent Sequential Data” section of the engine’s documentation was updated to describe the change.

Added Public Methods to Add and Remove Replies to Comment

Related issue WORDSNET-9959

Implemented public API to add/remove comment replies. The following methods have been added to the Comment class:

/// <summary>
/// Adds a reply to this comment.
/// </summary>
/// <param name="author">The author name for the reply.</param>
/// <param name="initial">The author initials for the reply.</param>
/// <param name="dateTime">The date and time for the reply.</param>
/// <param name="text">The reply text.</param>
/// <returns>The created <see cref="Comment"/> node for the reply.</returns>
/// <remarks>
/// Due to the existing MS Office limitations only 1 level of replies is allowed in the document.
/// An exception of type <see cref="InvalidOperationException"/> will be raised if this method is
/// called on the existing Reply comment.
/// </remarks>
public Comment AddReply(string author, string initial, DateTime dateTime, string text);
/// <summary>
/// Removes the specified reply to this comment.
/// </summary>
/// <param name="reply">The comment node of the deleting reply.</param>
/// <remarks>All constituent nodes of the reply will be deleted from the document.</remarks>
public void RemoveReply(Comment reply);
/// <summary>
/// Removes all replies to this comment.
/// </summary>
/// <remarks>All constituent nodes of the replies will be deleted from the document.</remarks>
public void RemoveAllReplies();

UC to add/remove replies:

Document doc = new Document(fileName);
Comment comment = (Comment)doc.GetChild(NodeType.Comment, 0, true);
comment.AddReply("John Doe", "JD", new DateTime(2017, 9, 25, 12, 15, 0), "New reply");

Format1bppIndexed Added to ImageSaveOptions.PixelFormat

Related issue: WORDSNET-13489

Format1bppIndexed value was added to ImageSaveOptions.PixelFormat enum:

/// <summary>
    /// Specifies the pixel format for the generated images of document pages.
    /// </summary>
    public enum ImagePixelFormat
        /// <summary>
        /// 1 bit per pixel, Indexed.
        /// </summary>

Previously setting ImageSaveOptions.ImageColorMode.BlackAndWhite would produce black and white image but with more that one bit per pixel format. For now black and white image with one bit per pixel format could be produced.


Document doc = new Document("in.docx");
ImageSaveOptions opt = new ImageSaveOptions(SaveFormat.Png);
opt.PageIndex = 3;
opt.ImageColorMode = ImageColorMode.BlackAndWhite;
opt.PixelFormat = ImagePixelFormat.Format1bppIndexed;
doc.Save("out.png", opt);

Ability to Get and Set Number of Footnote Layout Columns is Implemented

Related issue: WORDSNET-14958

The following property has been added into the FootnoteOptions class:

/// <summary>
/// Specifies the number of columns with which the footnotes area is formatted.
/// </summary>
/// <remarks>
/// If this property has the value of 0, the footnotes area is formatted with a number of columns based on
/// the number of columns on the displayed page. The default value is 0.
/// </remarks>
public int Columns { get; set; }


Document doc = new Document(fileName);
doc.FootnoteOptions.Columns = 2;

The Document.EndnoteOptions and PageSetup.EndnoteOptions properties have been changed to be of the EndnoteOptions type. This new EndnoteOptions class has the same properties as FootnoteOptions except the Columns property:

/// <summary>
/// Represents the endnote numbering options for a document or section.
/// </summary>
public class EndnoteOptions
    /// <summary>
    /// Specifies the endnotes position.
    /// </summary>
    public EndnotePosition Position { get; set; }
    /// <summary>
    /// Specifies the number format for automatically numbered endnotes.
    /// </summary>
    public NumberStyle NumberStyle { get; set; }
    /// <summary>
    /// Specifies the starting number or character for the first automatically numbered endnotes.
    /// </summary>
    public int StartNumber { get; set; }
    /// <summary>
    /// Determines when automatic numbering restarts.
    /// </summary>
    public FootnoteNumberingRule RestartRule { get; set; }

The similar Position property of the FootnotePosition type is added into the FootnoteOptions class. The property should be used instead of the obsolete Location property.

The new public enum types FootnotePosition and EndnotePosition have the following items:

/// <summary>
/// Defines the footnote position.
/// </summary>
public enum FootnotePosition
    /// <summary>
    /// Footnotes are output at the bottom of each page.
    /// </summary>
    BottomOfPage = 1,
    /// <summary>
    /// Footnotes are output beneath text on each page.
    /// </summary>
    BeneathText = 2
/// <summary>
/// Defines the endnote position.
/// </summary>
public enum EndnotePosition
    /// <summary>
    /// Endnotes are output at the end of the section.
    /// </summary>
    EndOfSection = 0,
    /// <summary>
    /// Endnotes are output at the end of the document.
    /// </summary>
    EndOfDocument = 3

Provided API Similar to SignatureSet.AddSignatureLine Method (Office)

Related issue: WORDSNET-14984

Added public property ProviderId to the SignOptions class.

// Specifies the class ID of the signature provider.
public Guid ProviderId

And also added public property ProviderId to the SignatureLine class.

// Gets or sets signature provider identifier for this signature line.
public Guid ProviderId

UC1 - existing signature line:

Document doc = new Document("pathToDocument.docx");
SignatureLine signatureLine = doc.FirstSection.Body.Shapes[0].SignatureLine;
SignOptions signOptions = new SignOptions();
signOptions.ProviderId = signatureLine.ProviderId;
signOptions.SignatureLineId = signatureLine.Id;
CertificateHolder certHolder = CertificateHolder.Create("pathToCert.pfx", "certPassword");
DigitalSignatureUtil.Sign("pathToSrcFile.docx", "pathToDstFile.docx", certHolder, signOptions);

UC2 - creating new signature line:

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
SignatureLine signatureLine = builder.InsertSignatureLine(new SignatureLineOptions()).SignatureLine;
signatureLine.ProviderId = new Guid("{F5AC7D23-DA04-45F5-ABCB-38CE7A982553}");
SignOptions signOptions = new SignOptions();
signOptions.SignatureLineId = signatureLine.Id;
signOptions.ProviderId = signatureLine.ProviderId;
CertificateHolder certHolder = CertificateHolder.Create("pathToCert.pfx", "certPassword");
DigitalSignatureUtil.Sign("pathToSrcFile.docx", "pathToDstFile.docx", certHolder, signOptions);

UC3 - signing using special provider Id:

SignOptions signOptions = new SignOptions();
signOptions.ProviderId = new Guid("{F5AC7D23-DA04-45F5-ABCB-38CE7A982553}");
CertificateHolder certHolder = CertificateHolder.Create("pathToCert.pfx", "certPassword");
DigitalSignatureUtil.Sign("pathToSrcFile.docx", "pathToDstFile.docx", certHolder, signOptions);

Exposed Table.HorizontalAlignment Property

Related issue: WORDSNET-15817

Added new public read-only properties to the Table class.

// Gets table relative horizontal alignment.
public HorizontalAlignment RelativeHorizontalAlignment

// Gets table relative vertical alignment.
public VerticalAlignment RelativeVerticalAlignment


// It is necessary to use the appropriate properties,

// depending on the floating table or not.
if (table.TextWrapping == TextWrapping.Around)

Prevent Embedding Fonts while Saving into HTML Fixed Format.

Related issue: WORDSNET-15880

We have introduced HtmlFixedSaveOptions.UseTargetMachineFonts property.

/// <summary>
/// Flag indicates whether fonts from target machine must be used to display the document.
/// If this flag is set to true, <see cref="FontFormat"/> and <see cref="ExportEmbeddedFonts"/> properties do not have effect,
/// also <see cref="ResourceSavingCallback"/> is not fired for fonts.
/// Default is false.
/// </summary>
public bool UseTargetMachineFonts