Aspose.Words for .NET 20.4 Release Notes

Major Features

  • Starting from 20.4 version Aspose.Words also provides DLL for .NET 4.6.1. Like .NET Standard 2.0 it supports reading PDF documents.
  • Provided ability to change Asian paragraph spacing and indents.
  • Added image interpolation option for PDF rendering (new public property PdfSaveOptions.InterpolateImages).
  • Added a new mode 3D shapes rendering.
  • Extended API of chart data labels and series.

Full List of Issues Covering all Changes in this Release

WORDSNET-15697Providing ability to change password secured VBA code (change string)New Feature
WORDSNET-20043Expose public ComparisonLevel (Granularity) optionNew Feature
WORDSNET-20001Provide API to get set Word for Chinese specific Paragraph formattingsNew Feature
WORDSNET-19913Range.Replace with substitutionNew Feature
WORDSNET-19996Add image interpolation option for PDF renderingNew Feature
WORDSNET-19873Add feature to set/get positioning of floating table (HorizontalAnchor and VerticalAnchor)New Feature
WORDSNET-20080Support subsetting OTF(CFF) fonts with composite accented glyphsNew Feature
WORDSNET-20146Implement rendering of ISO 29500 specific BorderArt stylesNew Feature
WORDSNET-19747Add feature to set/get paragraph property “Snap to grid when document grid is defined”New Feature
WORDSNET-10548Incorrect floater position when anchor is close to a tight-wrapped floaterEnhancement
WORDSNET-20042Check whether RTF format supports placing annotations at block/cell/row levelEnhancement
WORDSNET-8841Aspose.Words.Document does not load RTF contents correctlyBug
WORDSNET-11627Aspose.Words.FileCorruptedException is thrown while loading DOCX fileBug
WORDSNET-8712Add an example which demonstrates how to add PDF encryption without any user passwordBug
WORDSNET-19675The angle unit is missing in the parameter of rotate() CSS functionsBug
WORDSNET-20150Document.Compare throws System.ArgumentOutOfRangeExceptionBug
WORDSNET-20147Conversion to PDF fails with InvalidCastException: OfficeMath to type ParagraphBug
WORDSNET-19124The properties ChartDataLabel.ShowDataLabelsRange and ChartDataLabelCollection.ShowDataLabelsRange do not work correctlyBug
WORDSNET-20193Evaluation watermark appears in licensed modeBug
WORDSNET-11712A Paragraph is pushed up to the previous page in PDFBug
WORDSNET-12721Document.Revisions returns incorrect valueBug
WORDSNET-12840Saving a document as PDF moves footers into headerBug
WORDSNET-17608Bookmark.Text returns incorrect text for a rowBug
WORDSNET-18213DOCX to PDF conversion issue with text wrapping around the tableBug
WORDSNET-12318Bookmark.Text return incorrect valueBug
WORDSNET-11570BookmarkEnd is moved to next RowBug
WORDSNET-19028Canvas converts to group after re-savingBug
WORDSNET-19709ODT to DOCX conversion issue with Chart DataLabel and AxisBug
WORDSNET-20032StructuredDocumentTag comparison issueBug
WORDSNET-15550DOCX to PDF conversion issue with blank pagesBug
WORDSNET-19812DOCX to Markdown conversion issue with numbered listsBug
WORDSNET-17857Tables are shifted up and overlapped after conversion from DOCX to PDFBug
WORDSNET-20054A one row table moves to previous page in PDFBug
WORDSNET-18549DOC to PDF rendition fonts related issue - Gujarati foreign LanguageBug
WORDSNET-16041Bookmark.Text = "” merges the table’s cellBug
WORDSNET-19817Chart position is changed after DOCX to PDF conversionBug
WORDSNET-20055Fixing SonarQube issues in Reporting engineBug
WORDSNET-9159Thai language characters are not generated correctly in PDFBug
WORDSNET-2941Formatting of text is lost after setting bookmarks textBug
WORDSNET-20026DOCX to HtmlFixed/PDF conversion issue with text renderingBug
WORDSNET-20040DOCX to PDF: Layout problemBug
WORDSNET-18631Tamil Nirmala language not rendering correctly in PDFBug
WORDSNET-18610Aspose.Words Word to PDF conversion. Missing part of the documentBug
WORDSNET-19156Math equation is messed up after conversion to EMFBug
WORDSNET-20058Some data has been lost after conversion from DOCX to PDFBug
WORDSNET-19841After conversion to PDF watermark movesBug
WORDSNET-19840Image is lost after DOCX to PDF conversionBug
WORDSNET-19699Paragraph’s Keep with Next Property under Line and Page BreaksBug
WORDSNET-19752SpaceBefore and SpaceAfter return incorrect value for MS Word 2007 documentBug
WORDSNET-18976Infinite loop during call of Document.UpdatePageLayoutBug
WORDSNET-19496Memory Leak in  in multithreadingBug
WORDSNET-19907Aspose.Words do not find user-installed fonts using .NetStandard 2.0 projectBug
WORDSNET-19994BuiltInDocumentProperties.Words, Characters incorrect for hidden textBug
WORDSNET-19631Name of the style is truncated when read .md documentBug
WORDSNET-20102ActualBounds calculation for rotated shapesBug
WORDSNET-20103The width of integral is incorrect after converting to PDFBug
WORDSNET-20005Heading indent is incorrect after conversion from DOCX to PDFBug
WORDSNET-19518Problem with replacing text in BookmarksBug
WORDSNET-19757Calibri (Body) changes to Calibri or vice versa during appending documentsBug
WORDSNET-19528DOCX to fixed file format conversion issue with GroupShapeBug
WORDSNET-20011Check Aspose.Words vulnerabilitiesBug
WORDSNET-20066Word to PDF conversion issue with table’s text wrappingBug
WORDSNET-19777Issue after conversion DOCX to PDFBug
WORDSNET-19616UpdateFields feature creates wrong index of namesBug
WORDSNET-19537DOCX to PDF conversion issue with shapes positionBug
WORDSNET-20113Additional space between the N-ary operator and the argument depending on the size argumentBug
WORDSNET-20114Aspose.Words.UnsupportedFileFormatException is thrown while loading DOCBug
WORDSNET-20068Document.PageColor sets the page color to black when it is set to Color.EmptyBug
WORDSNET-19621Text is pushed down to next page after conversion from DOCX to PDFBug
WORDSNET-20057Image text is stretched after conversion from DOC to PDFBug
WORDSNET-19317System.ArgumentException occurs upon Comparing documentsBug
WORDSNET-19636Assertion in .NeT debug code related to an exception in Java codeBug
WORDSNET-19796ImportNode (Section) and AppendDocument behavior is not same when ImportFormatMode is KeepSourceFormattingBug
WORDSNET-19805System.InvalidOperationException - Expected pad cells only - RTF to HTMLBug
WORDSNET-20093Cannot obtain user-installed font on Windows 10 with .NET Standard 2.0 assemblyBug
WORDSNET-20030NodeImporter.ImportNode throws System.ArgumentOutOfRangeException when trying to import node to a document that has a specific styleBug
WORDSNET-20076Incorrect paragraph indent on conversion to fixed-page formatsBug
WORDSNET-20130UpdateFields does not process TOC fieldBug
WORDSNET-16332Bookmark.Text corrupts Table layoutBug
WORDSNET-20143Convert to PDF fails with NullReferenceExceptionBug
WORDSNET-20144Convert to PDF fails with Not expected other boolex values hereBug
WORDSNET-20145Convert to PDF fails with InvalidCastExceptionBug
WORDSNET-19645SUM fields not updated in documentBug
WORDSNET-20155Introduce a new load option for using temporary files (instead of MemoryStream) on readingBug
WORDSNET-19974LINQ Reporting Engine - InvalidOperationException is thrown on accessing an empty JSON arrayBug
WORDSNET-20083Conversion DOCX to PDF stucksBug
WORDSNET-20024Import/export compatibility settings from RTF documentBug
WORDSNET-20051Urdu italic characters are rendered as square in output PDFBug
WORDSNET-20184Replacing issue with IgnoreDeleted and IgnoreFieldsBug
WORDSNET-19981Part of the footer content missing when saving into HTMLBug
WORDSNET-19948Integral symbols are rendered incorrectly in not inline modeBug
WORDSNET-13880Document.PageCount returns incorrect value on UbuntuBug
WORDSNET-20157Paragraph is rendered on previous page in output PDFBug
WORDSNET-13655Chinese text renders on next line after conversion from Doc to fixed file formatBug
WORDSNET-19448MailMerge.Execute does not update the IF fieldBug
WORDSNET-20156Page number renders incorrectly in output PDFBug
WORDSNET-19811Vertical space between lines does not match MS Word on conversion to PDFBug
WORDSNET-20027Image is rotated after conversion from DOCX to HtmlFixedBug
WORDSNET-19995Missing content due to invalid ‘transform: rotate’ property valueBug
WORDSNET-20067Text inside a Form is not well rendered when saving as HTML(HtmlFixed)Bug

Public API and Backward Incompatible Changes

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

.NET 4.6.1 DLL Added

Starting from 20.4 version Aspose.Words also provides dll for .NET 4.6.1. Like .NET Standard 2.0 it supports reading PDF documents.

Added ability to change Asian paragraph spacing and indents

Related issue: WORDSNET-20001

The following ParagraphFormat properties were added:


/// <summary>
/// Gets or sets the left indent value (in characters) for the specified paragraphs.
/// </summary>
public int ParagraphFormat.CharacterUnitLeftIndent {get; set; }
/// <summary>
/// Gets or sets the right indent value (in characters) for the specified paragraphs.
/// </summary>
public int ParagraphFormat.CharacterUnitRightIndent {get; set; }
/// <summary>
/// Gets or sets the value (in characters) for the first-line or hanging indent.
/// <p>Use positive values to set the first-line indent, and negative values to set the hanging indent.</p>
/// </summary>
public int ParagraphFormat.CharacterUnitFirstLineIndent {get; set; }
/// <summary>
/// Gets or sets the amount of spacing (in gridlines) before the paragraphs.
/// </summary>
public int ParagraphFormat.LineUnitBefore {get; set; }
/// <summary>
/// Gets or sets the amount of spacing (in gridlines) after the paragraphs.
/// </summary>
public int ParagraphFormat.LineUnitAfter {get; set; }

Use Case:

Note, that setting unit indents and spacing will update appropriate common indent or spacing property. For example, setting ParagraphFormat.CharacterUnitLeftIndent will update ParagraphFormat.LeftIndent.


Document doc = new Document()
ParagraphFormat format = doc.FirstSection.Body.FirstParagraph.ParagraphFormat;
format.CharacterUnitLeftIndent = 10;
       // ParagraphFormat.LeftIndent will be updated
format.CharacterUnitRightIndent = 10;
      // ParagraphFormat.RightIndent will be updated
format.CharacterUnitFirstLineIndent = 20;
  // ParagraphFormat.FirstLineIndent will be updated
format.LineUnitBefore = 5;
                 // ParagraphFormat.SpaceBefore will be updated
format.LineUnitAfter= 10;
                  // ParagraphFormat.SpaceAfter will be updated

Added a new mode 3D shapes rendering

Added new public property SaveOptions.Dml3DEffectsRenderingMode:


/// <summary>
/// Gets or sets a value determining how 3D effects are rendered.
/// </summary>
/// <remarks>
/// The default value is <see cref="Saving.Dml3DEffectsRenderingMode.Basic"/>.
/// </remarks>
public Dml3DEffectsRenderingMode Dml3DEffectsRenderingMode
    get { return mDml3DEffectsRenderingMode; }
    set { mDml3DEffectsRenderingMode = value; }


/// <summary>
/// Specifies how 3D shape effects are rendered.
/// </summary>
public enum Dml3DEffectsRenderingMode
    /// <summary>
    /// A lightweight and stable rendering, based on the internal engine,
    /// but advanced effects such as lighting, materials and other additional effects
    /// are not displayed when using this mode.
    /// Please see documentation for details.
    /// </summary>
    /// <summary>
    /// Rendering of an extended list of special effects including advanced 3D effects
    /// such as bevels, lighting and materials.
    /// </summary>
    /// <remarks>
    /// The current implementation uses OpenGL.
    /// Please make sure that OpenGL library version 1.1 or higher is installed on your system before use.
    /// This mode is still under development, and some things may not be supported, so it's recommended to use
    /// the <see cref="Basic"/> mode if the rendering result is not acceptable.
    /// Please see documentation for details.
    /// </remarks>

Use Case:


Document doc = new Document(docPath);
SaveOptions saveOptions = new PdfSaveOptions();
saveOptions.Dml3DEffectsRenderingMode = Dml3DEffectsRenderingMode.Advanced;
doc.Save(pdfPath, saveOptions);

Please pay attention

For the Advanced mode to work correctly, it is necessary that the scale in the system be set to 100%.

The following table shows the differences between the modes:

The effectBasicAdvanced
Color of depth-+
Color of contour-+
Please note, that this is an experimental feature since the advanced mode is still under development, so it’s recommended to use the default mode if the rendering result is not acceptable.

The following effects are currently implemented:

  • Bevels: “Round”, “Relaxed Insert”, “Angle”, “Cross”. The following shapes do not support bevels at the moment: “Wave”, “Double Wave”, “Flowchart: Sequential Access Storage”, “Partial Circle”, “Thought Bubble: Cloud”, “Cloud”, “Frame”, “Plaque”, “Lightning Bolt”, “Moon”, “Flowchart: Stored Data”, “Sun”, “Callout: Quad Arrow”, “Arrow: Circular”, “Flowchart: Punched Tape”, “Flowchart: Multidocument”.
  • Shape fill types: “Solid”, “Gradient”, “Picture or Texture”, “Pattern”.
  • Materials: Warm Matte.
  • Lighting: Three-Point.

There are problems with some specific shapes (such as the moon), some subtypes of the gradient fill. Incorrect rendering is possible when using the maximum values that define the bevels. There may also be problems when using other special effects such as glow, reflection, etc. along with 3D effects. Various lighting problems may also occur (wrong color). It’s OK for now an will be improved in later releases.

Added a new public property SnapToGrid for Font and ParagraphFormat

Related issue: WORDSNET-19747

Added a new public property ParagraphFormat.SnapToGrid:


/// <summary>
/// Specifies whether the current paragraph should use the document grid lines per page settings
/// when laying out the contents in the paragraph.
/// </summary>
public bool SnapToGrid

and Font.SnapToGrid:


/// <summary>
/// Specifies whether the current run should use the document grid characters per line settings
/// when laying out the contents in this run.
/// </summary>
public bool SnapToGrid

Use Case:


Document doc = new Document(docPath);
Paragraph par = doc.FirstSection.Body.FirstParagraph;
par.ParagraphFormat.SnapToGrid = true;
par.Runs[0].Font.SnapToGrid = true;

Added an option that allows customers to specify comparison granularity

Related issue: WORDSNET-20043

Added the following properties:


/// <summary>
/// Specifies the granularity of changes to track when comparing two documents.
/// </summary>
public enum Granularity
/// <summary>
/// Specifies whether changes are tracked by character or by word.
/// Default value is <see cref="Granularity.WordLevel"/>.
/// </summary>
Granularity CompareOptions.Granularity { get; set; }

Use Case:


DocumentBuilder builderA = new DocumentBuilder(new Document());
DocumentBuilder builderB = new DocumentBuilder(new Document());
builderA.Writeln("This is A simple word");
builderB.Writeln("This is B simple words");
CompareOptions co = new CompareOptions();
co.Granularity = Granularity.CharLevel;
builderA.Document.Compare(builderB.Document, "author", DateTime.Now, co);

Sample output


Added feature to set positioning of floating table (HorizontalAnchor and VerticalAnchor)

Related issue: WORDSNET-19873

Setters for the following properties have been added to the Table class:


/// <summary>
/// Gets or sets the base object from which the horizontal positioning of floating table should be calculated.
/// Default value is <see cref="RelativeHorizontalPosition.Column"/>.
/// </summary>
public RelativeHorizontalPosition Table.HorizontalAnchor
/// <summary>
/// Gets or sets the base object from which the vertical positioning of floating table should be calculated.
/// Default value is <see cref="RelativeVerticalPosition.Margin"/>.
/// </summary>
public RelativeVerticalPosition Table.VerticalAnchor

Note, ONLY the following values are allowed in HorizontalAnchor setter. The ArgumentException will be thrown for any other values.



Note, ONLY the following values are allowed in VerticalAnchor setter. The ArgumentException will be thrown for any other values.



Use Case:


Document doc = new Documnet(file_with_table);
Table table = doc.FirstSection.Body.Tables[0];
table.HorizontalAnchor = RelativeHorizontalPosition.Column;
table.VerticalAnchor = RelativeVerticalPosition.Page;

Added image interpolation option for PDF rendering (new public property PdfSaveOptions.InterpolateImages)

Related issue: WORDSNET-19996

Added image interpolation option for PDF rendering which can be specified by PdfSaveOptions.InterpolateImages property.


/// <summary>
/// A flag indicating whether image interpolation shall be performed by a conforming reader.
/// When <c>false</c> is specified, the flag is not written to the output document and
/// the default behaviour of reader is used instead.
/// </summary>
/// <remarks>
/// <para>
/// When the resolution of a source image is significantly lower than that of the output device,
/// each source sample covers many device pixels. As a result, images can appear jaggy or blocky.
/// These visual artifacts can be reduced by applying an image interpolation algorithm during rendering.
/// Instead of painting all pixels covered by a source sample with the same color, image interpolation
/// attempts to produce a smooth transition between adjacent sample values.
/// </para>
/// <para>
/// A conforming Reader may choose to not implement this feature of PDF,
/// or may use any specific implementation of interpolation that it wishes.
/// </para>
/// <para>The default value is <c>false</c>.</para>
/// </remarks>
public bool InterpolateImages

Use Case:


Document doc = new Document(docPath);
PdfSaveOptions saveOptions = new PdfSaveOptions();
saveOptions.InterpolateImages = true;
doc.Save(pdfPath, saveOptions);

Added public property LoadOptions.TempFolder

This property allows using temporary files when reading a document.


/// <summary>
/// Allows to use temporary files when reading document.
/// By default this property is <c>null</c> and no temporary files are used.
/// </summary>
/// <remarks>
/// <para>The folder must exist and be writable, otherwise an exception will be thrown.</para>
/// <para>Aspose.Words automatically deletes all temporary files when reading is complete.</para>
/// </remarks>
public string TempFolder

Such an approach degrades speed but reduces memory usage.

Use Case:


LoadOptions lo = new LoadOptions();
lo.TempFolder = @"C:\TempFolder\";
Document doc = new Document(myDir + "document.docx", lo);

 Changes in API of chart data labels and series

The following changes in chart data labels API have been implemented (WORDSNET-19124):

  • The property HasDataLabels has been added to the ChartSeries class.
  • The method ClearFormat has been added to the ChartDataLabelCollection class.
  • The property Count of the ChartDataLabelCollection class returns a number of all data labels of series, not just those that have non-default formatting, as it was in the previous versions of the software.
  • The methods Add, RemoveAt and Clear are marked as obsolete. After setting Series.HasDataLabels = true, the collection contains all data labels of the series now and there is no need to add labels to it. The methods RemoveAt and Clear actually reset format of data label(s) to defaults defined in properties of a ChartDataLabelCollection object. Now the methods ChartDataLabel.ClearFormat and ChartDataLabelCollection.ClearFormat should be used instead.
  • The method ClearFormat has been added to the ChartDataLabel class.
  • The property IsHidden has been added to the ChartDataLabel class.


public class ChartSeries
    /// <summary>
    /// Gets or sets a flag indicating whether data labels are displayed for the series.
    /// </summary>
    public bool HasDataLabels { get; set; }
public class ChartDataLabelCollection
    /// <summary>
    /// Adds new <see cref="ChartDataLabel"/> at the specified index.
    /// </summary>
    [Obsolete("When ChartSeries.HasDataLabels is 'true', all data labels are available in this collection.")]
    public ChartDataLabel Add(int index);
    /// <summary>
    /// Clears format of a <see cref="ChartDataLabel"/> at the specified index.
    /// </summary>
    [Obsolete("Use the ChartDataLabel.ClearFormat method instead.")]
    public void RemoveAt(int index);
    /// <summary>
    /// Clears format of all <see cref="ChartDataLabel"/> in this collection.
    /// </summary>
    [Obsolete("Use the ClearFormat method instead.")]
    public void Clear();
    /// <summary>
    /// Clears format of all <see cref="ChartDataLabel"/> in this collection.
    /// </summary>
    public void ClearFormat();
public class ChartDataLabel
    /// <summary>
    /// Clears format of this data label. The properties are set to the default values defined in the parent data label collection.
    /// </summary>
    public void ClearFormat();
    /// <summary>
    /// Gets/sets a flag indicating whether this label is hidden.
    /// The default value is <b>false</b>.
    /// </summary>
    public bool IsHidden { get; set; }

Use Case:


Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.InsertChart(ChartType.Line, 432, 252);
Chart chart = shape.Chart;

// Delete default generated series.
ChartSeries series1 = chart.Series.Add("Series 1", 
    new string[] { "Category 1", "Category 2", "Category 3" }, 
    new double[] { 1, 5, 4 });
series1.HasDataLabels = true;
series1.DataLabels.ShowValue = true;
series1.DataLabels[1].ShowCategoryName = true;
series1.DataLabels[1].ShowValue = true;
series1.DataLabels[2].IsHidden = true;
doc.Save(dir + "DataLabels.docx");

 FindReplaceOptions class is extended with new property

Related issue: WORDSNET-19913.

The following public property was added to FindReplaceOptions class:


/// <summary>
/// Gets or sets a boolean value indicating whether to recognize and use substitutions within replacement patterns.
/// The default value is <c>false</c>. 
/// </summary>
/// <remarks>
/// For the details on substitution elements please refer to:
/// </remarks>
public bool UseSubstitutions

Use Case. Explains how to recognize and use substitutions within replacement patterns:


// Create new document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Write some text.
builder.Write("Jason give money to Paul.");
Regex regex = new Regex(@"([A-z]+) give money to ([A-z]+)");

// Replace text using substitutions.
FindReplaceOptions options = new FindReplaceOptions();
options.UseSubstitutions = true;
doc.Range.Replace(regex, @"$2 take money from $1", options);
 // The output is: Paul take money from Jason.\f

Implemented mutual conversion of several PageBorderArt names between ECMA376 and ISO29500 standard documents

Experiments show that there’s a mutual correspondence between “Tribal"* border art styles and ISO29500 specific border art styles, in the range from *“Triangle1*” to “*Shapes2*”.

In this release the direct conversion of the mentioned BorderArt style names was implemented according to the following table:


Removed obsolete properties AnnotationsAtBlockLevel and AnnotationsAtBlockLevelAsDefault of LoadOptions class

The obsolete properties LoadOptions.AnnotationsAtBlockLevel and LoadOptions.AnnotationsAtBlockLevelAsDefault have been removed (WORDSNET-19211). The mode of moving annotation nodes to inline-level is no longer supported.