Aspose.Words for .NET 22.1 Release Notes

Major Features

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

  • Implemented rendering into PDF with PDF/UA-1 compliance. This option assumes compliance with document special accessibility requirements.
  • Improved rendering of operators in MathML formulas.
  • Introduced a new option to control conflicting styles behavior upon import.
  • Added an ability to get saving progress notifications through the SaveOptions.ProgressCallback.
  • Provided dynamic text color setting using LINQ Reporting Engine.

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

KeySummaryCategory
WORDSNET-22882Provide dynamic text color setting using LINQ Reporting EngineNew Feature
WORDSNET-11575Add option to stop Document.Save method after specific timeNew Feature
WORDSNET-23246Provide list style in ApsNew Feature
WORDSNET-1506Add feature to set image as background of TextBoxNew Feature
WORDSNET-12792Add feature to set Fill.ImageBytesNew Feature
WORDSNET-6614Support of PdfCompliance PDF/UANew Feature
WORDSNET-19268Incorrect behavior of KeepSourceFormatting ImportFormatModeNew Feature
WORDSNET-18739Gather data about gradient fillsNew Feature
WORDSNET-16357Implement ability to replace shape background imageNew Feature
WORDSNET-22884Cross-reference not working in Docker after CustomXmlParts property is setEnhancement
WORDSNET-22692Compare document with content controlEnhancement
WORDSNET-22664Shape.OleFormat returns null when Excel chart is copied to Word using Option “Link & Keep Source Formatting”Enhancement
WORDSNET-23223Pass a hyperlink ScreenTip from model to ApsEnhancement
WORDSNET-20756DOCX to PDF conversion issue with accessibilityEnhancement
WORDSNET-23237RTF to DOCX - PUA characters treated as symbols instead of textBug
WORDSNET-22682After rendering a DML shape gets larger by 1 pixel than its original imageBug
WORDSNET-22853Image of a DML shape is shifted to the right after renderingBug
WORDSNET-22854Image of a DML shape is shifted to the top left after renderingBug
WORDSNET-23232NullReferenceException on cloningBug
WORDSNET-23269Remove obsolete property LayoutOptions.ShowCommentsBug
WORDSNET-22899Document compare is not working properlyBug
WORDSNET-23224Process hangs when calling UpdateFields methodBug
WORDSNET-23231Shape.Id is duplicated for watermarks inserted by Aspose.WordsBug
WORDSNET-23234NullReferenceException while re-saving documentBug
WORDSNET-17523How to determine maximum value for table borderBug
WORDSNET-22883Cross-reference not working after removing XML mappingBug
WORDSNET-23252Font is changed after open/save DOCXBug
WORDSNET-23211Setting mapping creates corrupted tableBug
WORDSNET-23213The end-of-cell marker has been removed from the new rowBug
WORDSNET-23180Section breaks are changed after inserting documentBug
WORDSNET-22845PDF Accessibility Checker (PAC 3) reports failures upon testing for PDF/UA compatibilityBug
WORDSNET-20766Structure element issues after DOCX to PDF conversionBug
WORDSNET-22919Word table formatting issue using Customer XML dataBug
WORDSNET-23220The paragraph is missing when using WordOpenXMLBug
WORDSNET-22660Compile Time error when using Aspose Words for .NET in C++/CLI projectBug
WORDSNET-23226Incorrect size and position of the minus signBug
WORDSNET-23229Fix minor rendering issueBug
WORDSNET-22526Unwanted styles appear during DOTX to DOCX conversionBug
WORDSNET-22939NullReferenceException while converting DOCX to PDFBug
WORDSNET-23212IndexOutOfRangeException at ColorSpaceDeviceRGB.ToRgbBug
WORDSNET-23194Saving RTF file hangs indefinitelyBug
WORDSNET-21205DOCX to PDF conversion issue with chart renderingBug
WORDSNET-22954Formatting of footnote is changed after re-saving documentBug
WORDSNET-23175IndexOutOfRangeException in PdfSyntaxParser.ParseArrayBug
WORDSNET-23187FileCorruptedException is thrown while loading documentBug
WORDSNET-23203NullReferenceException at PdfOperatorTj.ApplyBug
WORDSNET-23177NullReferenceException if page resources are missingBug
WORDSNET-22804Document.Compare throws System.InvalidCastExceptionBug
WORDSNET-23023FormatException at PdfTokenParser.EnterHexStringStateBug
WORDSNET-21416Strikethrough formatting in list indent is disappeared after DOCX to PDF conversionBug
WORDSNET-23171System.StackOverflowException is thrown while loading RTFBug
WORDSNET-22710Bad performance of “UpdatePageLayout”Bug
WORDSNET-23193InvalidCastException: Cannot cast PdfDictionary to PdfArrayBug
WORDSNET-23189FormatException at TimeSpanFormat.FormatCustomizedBug
WORDSNET-22981Image becomes hidden after open/save documentBug
WORDSNET-23151Wrong date format in chart after converting DOCX to PDFBug
WORDSNET-22618Percentage Values of a Vertical Axis of Chart are not PreservedBug
WORDSNET-22925Math Equation (Shape) does not render correctly in output PDFBug
WORDSNET-23041Wrong letters order for RTL text (Persian OCR)Bug
WORDSNET-23027NullReferenceException at SASLPrepAlgorithm.MapCharactersBug
WORDSNET-23192KeyNotFoundException in RomanNumber.TryParseBug
WORDSNET-23173The shape is changed while exporting from DOCX to PDF, DOC or RTFBug
WORDSNET-22127Heading style attributes are not appliedBug
WORDSNET-19692Formula converted incorrectly (DOCX to PDF)Bug
WORDSNET-23184Opening HTM file hangs indefinitelyBug
WORDSNET-23161DllNotFoundException occurs when use HarfBuzzTextShaperFactory in .NET 6.0Bug

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

KeySummaryCategory
WORDSNET-23142Support HTML color codes as color values for LINQ Reporting Engine tagsNew Feature
WORDSNET-22953Comparing documents with changes around a table cause the table to be marked as deleted and re-addedBug
WORDSNET-22436Font-size incorrectly added to paragraph tag, it should be added to span insteadBug
WORDSNET-22562Document.Compare does not ignore commentBug
WORDSNET-23215InvalidCastException is thrown upon loading documentBug
WORDSNET-22824Chart issues when converting DOCX to PDFBug
WORDSNET-22956Revision.Accept throws System.InvalidOperationExceptionBug
WORDSNET-22983Blank page is produced in output PDF where hidden content was in the original documentBug
WORDSNET-23253Exported PDF contains image with lower resolutionBug

Public API and Backward Incompatible Changes

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

A white line may appear in the corner of the particular image when rendering an image with a high resolution (scaling)- and this is a GDI+ issue. New UseTileFlipMode option has been added to fix this GDI+ issue:

/// <summary>
/// Gets or sets WrapMode to TileFlipXY. Default WrapMode results in inaccurate rendered scaled image.
/// </summary>
public bool UseTileFlipMode { get; set; }

Use Case:

Document doc = new Document("input.docx");
Shape shape = (Shape)doc.GetChild(NodeType.Shape, 0, true);
ShapeRenderer renderer = shape.GetShapeRenderer();
ImageSaveOptions so = new ImageSaveOptions(SaveFormat.Png);
so.Resolution = 500;
so.GraphicsQualityOptions = new GraphicsQualityOptions();
so.GraphicsQualityOptions.UseTileFlipMode = true;
renderer.Save("out.png", so);

Added new Chart.SourceFullName property

Related issue: WORDSNET-22664

The following public property has been added to the Chart class. If a chart is linked to an external xls/xlsx document, the property returns its file name.

/// <summary>
/// Gets the path and name of an xls/xlsx file this chart is linked to.
/// </summary>
public string SourceFullName { get; }

Use Case:

Document doc = new Document(fileName);
Shape shape = (Shape)doc.GetChild(NodeType.Shape, 0, true);
Console.WriteLine(shape.Chart.SourceFullName);

Added new ImportFormatOptions.ForceCopyStyles property

Related issue: WORDSNET-19268.

The following public property is added to ImportFormatOptions class:

/// <summary>
/// Gets or sets a boolean value indicating either to copy conflicting styles
/// in <see cref="ImportFormatMode.KeepSourceFormatting"/> mode.
/// The default value is <c>false</c>.
/// </summary>
/// <remarks>
/// <para>By default, if a matching style already exists in a destination document, the source style formatting
/// is expanded into direct node attributes and the style of this node is reset to a default.</para>
/// <para> When this option is set to <c>true</c>, the source style will be forcibly copied
/// into destination document with unique name and applied to the imported node.</para>
/// <para> Note, in this case it is not guaranteed that formatting of the imported node in destination document
/// will be preserved. </para>
/// </remarks>
public bool ForceCopyStyles { get; set; }

Use Case: Explains how to force import styles in KeepSourceFormatting mode.

// There are MyStyle1 and MyStyle2 in both source and destination document.
// Also there is style MyStyle3 that exists only in source document.
Document srcDoc = new Document("Src.docx");
Document dstDoc = new Document("Dst.docx");
 
ImportFormatOptions options = new ImportFormatOptions { ForceCopyStyles = true };
NodeImporter nodeImporter = new NodeImporter(srcDoc, dstDoc, ImportFormatMode.KeepSourceFormatting, options);
 
Console.WriteLine("Imported styles:");
ParagraphCollection paras = srcDoc.FirstSection.Body.Paragraphs;
for (int i = 0; i < paras.Count; i++)
{
    Paragraph importedPara = (Paragraph)nodeImporter.ImportNode(paras[i], true);
    Console.WriteLine(importedPara.ParagraphFormat.StyleName);
}
 
// The code produces the following output:
// Imported styles:
// MyStyle1_0
// MyStyle2_0
// MyStyle3

Added SaveOptions.ProgressCallback property

Related issue: WORDSNET-11575

The following public property is added to SaveOptions class:

/// <summary>
/// Called during saving a document and accepts data about saving progress.
/// </summary>
/// <remarks>
/// <para><see cref="SaveFormat.Docx"/>, <see cref="SaveFormat.FlatOpc"/>, <see cref="SaveFormat.Docm"/>, <see cref="SaveFormat.Dotm"/>, <see cref="SaveFormat.Dotx"/> formats supported.</para>
/// </remarks>
public IDocumentSavingCallback ProgressCallback

Supported formats are:

  • Docx
  • FlatOpc
  • Docm
  • Dotm
  • Dotx

Consumer should to implement the following interface and set instance of it to the ProgressCallback for ability to get saving progress notifications.

/// <summary>
/// Implement this interface if you want to have your own custom method called during saving a document.
/// </summary>
public interface IDocumentSavingCallback
{
     /// <summary>
     /// This is called to notify of document saving progress.
     /// </summary>
     /// <param name="args">An argument of the event.</param>
     /// <remarks>
     /// The primary uses for this interface is to allow application code to obtain progress status and abort saving process.<para/>
     /// An exception should be threw from the progress callback for abortion and it should be caught in the consumer code.<para/>
     /// </remarks>
     void Notify(DocumentSavingArgs args);
}

Structure of the accepted arguments is:

/// <summary>
/// An argument passed into <see cref="IDocumentSavingCallback.Notify(DocumentSavingArgs)"/>.
/// </summary>
public sealed class DocumentSavingArgs
{
     /// <summary>
     /// Overall estimated percentage progress.
     /// </summary>
     public double EstimatedProgress { get; }
}

Use case:

/// <summary>
/// Saving progress callback. Cancel a document saving after the "MaxDuration" seconds.
/// </summary>
public class SavingProgressCallback : IDocumentSavingCallback
{
     /// <summary>
     /// Ctr.
     /// </summary>
     public SavingProgressCallback()
     {
         mSavingStartedAt = DateTime.Now;
     }
 
     /// <summary>
     /// Callback method which called during document saving.
     /// </summary>
     /// <param name="args">Saving arguments.</param>
     public void Notify(DocumentSavingArgs args)
     {
         DateTime canceledAt = DateTime.Now;
         double ellapsedSeconds = (canceledAt - mSavingStartedAt).TotalSeconds;
         if (ellapsedSeconds > MaxDuration)
             throw new OperationCanceledException($"EstimatedProgress = {args.EstimatedProgress}; CanceledAt = {canceledAt}");
     }
 
     /// <summary>
     /// Date and time when document saving is started.
     /// </summary>
     private readonly DateTime mSavingStartedAt;
 
     /// <summary>
     /// Maximum allowed duration in sec.
     /// </summary>
     private const double MaxDuration = 100d;
}

Loading document code:

SavingProgressCallback cb = new SavingProgressCallback();
SaveOptions so = new OoxmlSaveOptions(SaveFormat.Docx);
so.ProgressCallback = cb;
 
try
{
   Document doc = new Document("bigDoc.rtf");
 
   // Do work.
   doc.Save("bigDoc.docx", so);
}
catch (OperationCanceledException ex)
{
   Console.WriteLine(ex.Message);
   // Handle saving duration issue.
}

Added saving to PDFUA-1

Related issue: WORDSNET-6614

New value added to PdfCompliance enum

public enum PdfCompliance
{
    /// <summary>
    /// The output file will comply with the PDF/UA-1 (ISO 14289-1) standard.
    /// The primary purpose of PDF/UA is to define how to represent electronic documents in the PDF format in a
    /// manner that allows the file to be accessible.
    /// </summary>
    PdfUa1
}

Several PdfSaveOptions are prohibited when saving to PDF/UA and they are automatically fixed. Also options which are prohibited for PDF/A formats are now automatically fixed instead of throwing exception. Also warning is issued when option is automatically fixed.

public class PdfSaveOptions
{
    /// <summary>
    /// Specifies whether to preserve Microsoft Word form fields as form fields in PDF or convert them to text.
    /// Default is <c>false</c>.
    /// </summary>
    /// <remarks>
    ...
    /// <para>Editable forms are prohibited by PDF/A compliance. <c>false</c> value will be used automatically
    /// when saving to PDF/A.</para>
    /// <para>Form fields are not supported when saving to PDF/UA. <c>false</c> value will be used automatically.</para>
    /// </remarks>
    public bool PreserveFormFields;
 
    /// <summary>
    /// Gets or sets the details for encrypting the output PDF document.
    /// </summary>
    /// <remarks>
    ...
    /// <para>Encryption is prohibited by PDF/A compliance. This option will be ignored when saving to PDF/A.</para>
    /// <para><see cref="PdfPermissions.ContentCopyForAccessibility"/> permission is required by PDF/UA compliance
    /// if the output document is encrypted. This permission will automatically used when saving to PDF/UA.</para>
    /// </remarks>
    public PdfEncryptionDetails EncryptionDetails;
 
    /// <summary>
    /// Specifies the font embedding mode.
    /// </summary>
    /// <remarks>
    ...
    /// <para>PDF/A and PDF/UA compliance requires all fonts to be embedded.
    /// <see cref="PdfFontEmbeddingMode.EmbedAll"/> value will be used automatically when saving to
    /// PDF/A and PDF/UA.</para>
    /// </remarks>
    public PdfFontEmbeddingMode FontEmbeddingMode
 
    /// <summary>
    /// Gets or sets a value determining whether or not to substitute TrueType fonts Arial, Times New Roman,
    /// Courier New and Symbol with core PDF Type 1 fonts.
    /// </summary>
    /// <remarks>
    ...
    /// <para>PDF/A and PDF/UA compliance requires all fonts to be embedded. <c>false</c> value will be used
    /// automatically when saving to PDF/A and PDF/UA.</para>
    /// </remarks>
    public bool UseCoreFonts
 
    /// <summary>
    /// Gets or sets a value determining the way <see cref="Document.CustomDocumentProperties"/> are exported to PDF file.
    /// </summary>
    /// <remarks>
    ...
    /// <para><see cref="PdfCustomPropertiesExport.Metadata"/> value is not supported when saving to PDF/A.
    /// <see cref="PdfCustomPropertiesExport.Standard"/> will be used instead.
    /// </para>
    /// </remarks>
    public PdfCustomPropertiesExport CustomPropertiesExport
 
    /// <summary>
    /// Gets or sets a value determining whether hyperlinks in the output Pdf document
    /// are forced to be opened in a new window (or tab) of a browser.
    /// </summary>
    /// <remarks>
    ...
    /// <para>JavaScript actions are prohibited by PDF/A compliance. <c>false</c> will be used automatically when
    /// saving to PDF/A.</para>
    /// </remarks>
    public bool OpenHyperlinksInNewWindow
 
    /// <summary>
    /// Gets or sets a value determining whether or not to export document structure.
    /// </summary>
    /// <remarks>
    /// <para>
    /// This value is ignored when saving to PDF/A-1a, PDF/A-2a and PDF/UA-1 because document structure is required for this compliance.
    /// </para>
    ...
    /// </remarks>
    public bool ExportDocumentStructure
 
    /// <summary>
    /// Specifies how the color space will be selected for the images in PDF document.
    /// </summary>
    /// <remarks>
    ...
    /// <para><see cref="PdfImageColorSpaceExportMode.SimpleCmyk"/> value is not supported when saving to PDF/A.
    /// <see cref="PdfImageColorSpaceExportMode.Auto"/> value will be used instead.</para>
    /// </remarks>
    public PdfImageColorSpaceExportMode ImageColorSpaceExportMode
 
    /// <summary>
    /// A flag specifying whether the window’s title bar should display the document title taken from
    /// the Title entry of the document information dictionary.
    /// </summary>
    /// <remarks>
    ...
    /// <para>This flag is required by PDF/UA compliance. <c>true</c> value will be used automatically when saving
    /// to PDF/UA.</para>
    ...
    /// </remarks>
    public bool DisplayDocTitle
 
    /// <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>Interpolation flag is prohibited by PDF/A compliance. <c>false</c> value will be used automatically
    /// when saving to PDF/A.</para>
    /// </remarks>
    public bool InterpolateImages
}

Provided dynamic text color setting using LINQ Reporting Engine

Related issue: WORDSNET-22882

The “Setting Text Color Dynamically” section of the engine’s documentation was updated to describe the change.

Supported HTML color codes as color values for LINQ Reporting Engine tags

Related issue: WORDSNET-23142

The following sections of the engine’s documentation were updated to describe the changes:

“Setting Chart Series Colors Dynamically” “Setting Chart Series Point Colors Dynamically” “Setting Background Color Dynamically”

Removed obsolete property LayoutOptions.ShowComments

Removes obsolete property LayoutOptions.ShowComments.

public bool ShowComments { get; set; }

Use LayoutOptions.CommentDisplayMode property instead:

Document doc = new Document("in.docx");
doc.LayoutOptions.CommentDisplayMode = CommentDisplayMode.ShowInBalloons;
doc.Save("out.pdf");