Aspose.Words for .NET 24.6 Release Notes

Major Features

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

• Enhanced Charting Capabilities: Now you can create a wider variety of charts, including Treemaps, Sunbursts, Histograms, Pareto charts, Box & Whisker charts, Waterfalls, and Funnels. This allows for a more diverse and informative way to visualize your data.
• Color Control for Shadow Formatting: Gain finer control over the visual appearance of your documents by accessing the shadow colors.
• Advanced Comparison Options: Streamline your data analysis workflows with improved comparison functionality. This includes the new “IgnoreStoreItemId” option and a redesigned interface for advanced comparisons.
• Enhanced Comment Management: The new Comment.DateTimeUtc property provides a more accurate timestamp for comments, improving organization and traceability.
• Performance Boost for Background Rendering: Experience significantly faster rendering times for backgrounds containing small elements thanks to native tiling technology.
• Realistic Gradients for Shapes: Create DML shapes with nonlinear gradients, mimicking the visual style of MS Word for a more polished look.
• LINQ Reporting Engine Improvements: Selectively remove empty paragraphs and define custom messages for missing object members, leading to cleaner and more informative reports.

Full List of Issues Covering all Changes in this Release

Public API and Backward Incompatible Changes

This section lists public API changes that were introduced in Aspose.Words 24.6. 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 ability to create Treemap, Sunburst, Histogram, Pareto, Box & Whisker, Waterfall and Funnel charts

Related issue: WORDSNET-23967

An ability to create Treemap, Sunburst, Histogram, Pareto, Box & Whisker, Waterfall and Funnel charts has been implemented. The corresponding items are added to the ChartType enumeration type. Additional methods are provided in the ChartSeriesCollection class for creating series of the new chart types.

public enum ChartType
{
    ...

    /// <summary>
    /// Treemap chart.
    /// </summary>
    Treemap,

    /// <summary>
    /// Sunburst chart.
    /// </summary>
    Sunburst,

    /// <summary>
    /// Histogram chart.
    /// </summary>
    Histogram,

    /// <summary>
    /// Pareto chart.
    /// </summary>
    Pareto,

    /// <summary>
    /// Box and Whisker chart.
    /// </summary>
    BoxAndWhisker,

    /// <summary>
    /// Waterfall chart.
    /// </summary>
    Waterfall,

    /// <summary>
    /// Funnel chart.
    /// </summary>
    Funnel
}

public class ChartSeriesCollection
{
    ...

    /// <summary>
    /// Adds new <see cref="ChartSeries"/> to this collection.
    /// Use this method to add series that have multi-level data categories.
    /// </summary>
    /// <returns>Recently added <see cref="ChartSeries"/> object.</returns>
    public ChartSeries Add(string seriesName, ChartMultilevelValue[] categories, double[] values);

    /// <summary>
    /// Adds new <see cref="ChartSeries"/> to this collection.
    /// Use this method to add series to Histogram charts.
    /// </summary>
    /// <remarks>
    /// For chart types other than Histogram, this method adds a series with empty Y values.
    /// </remarks>
    /// <returns>Recently added <see cref="ChartSeries"/> object.</returns>
    public ChartSeries Add(string seriesName, double[] xValues);

    /// <summary>
    /// Adds new <see cref="ChartSeries"/> to this collection.
    /// Use this method to add series to Waterfall charts.
    /// </summary>
    /// <remarks>
    /// For chart types other than Waterfall, <paramref name="isSubtotal"/> values are ignored.
    /// </remarks>
    /// <param name="seriesName">A name of the series to be added.</param>
    /// <param name="categories">Category names for the X axis.</param>
    /// <param name="values">Y-axis values.</param>
    /// <param name="isSubtotal">Values indicating whether the corresponding Y value is a subtotal.</param>
    /// <returns>Recently added <see cref="ChartSeries"/> object.</returns>
    public ChartSeries Add(string seriesName, string[] categories, double[] values, bool[] isSubtotal);
}

This use case explains how to create a BoxAndWhisker chart:

This use case explains how create a Funnel chart:

This use case explains how to create a Histogram chart:

This use case explains how to create a Pareto chart:

This use case explains how to create a Sunburst chart:

This use case explains how to create a Treemap chart:

This use case explains how to create a Waterfall chart:

Added an ability to get a color of ShapeBase.ShadowFormat

Related issue: WORDSNET-26555

Implemented new public property in Aspose.Words.Drawing.ShadowFormat class:

/// <summary>
/// Gets a <see cref="System.Drawing.Color"/> object that represents the color for the shadow.
/// The default value is <see cref="System.Drawing.Color.Black"/>.
/// </summary>
public Color Color {get;}

This use case explains how get ShadowFormat color:

Added new comparison option IgnoreStoreItemId and advanced comparison option redesing

Related feature: WORDSNET-26971

New AdvancedCompareOptions class has beend added, new AdvancedCompareOptions.IgnoreStoreItemId option property has been added and option IgnoreUniqueDmlId property previously located in CompareOptions class has been moved to the newly created AdvancedCompareOptions class.

/// <summary>
/// Allows to set advanced compare options.
/// </summary>
/// <remarks>
/// These options have no equivalence in Microsoft Word and might help to produce more precise comparison result.
/// </remarks>
public class AdvancedCompareOptions
{
    /// <summary>
    /// Specifies whether to ignore difference in DrawingML unique Id.
    /// </summary>
    /// <remarks>
    /// Default value is <c>false</c>.
    /// </remarks>
    public bool IgnoreDmlUniqueId { get; set; }

    /// <summary>
    /// Specifies whether to ignore difference in StructuredDocumentTag store item Id.
    /// </summary>
    /// <remarks>
    /// Default value is <c>false</c>.
    /// </remarks>
    public bool IgnoreStoreItemId { get; set; }
}

New IgnoreStoreItemId option allows to control case when content of StructuredDocumentTag being compared is the same but StructuredDocumentTags itself have a difference in internal details, in this case this is StructuredDocumentTag.XmlMapping.StoreItemId difference.

Microsoft Word considers these SDTs to be different for any reason and this might confuse customers because they see that equal content is marked with edit revisions. By default we mimic MS Word here and this option allows to control the logic and produce more logical and readable comparison result.

Additionally we decided to extract all these experimental options into separate AdvancedCompareOptions class to avoid having mess. All options that have no equivalence in Microsoft Word will be published in AdvancedCompareOptions class. Thats why IgnoreDmlUniqueId property previously located in CompareOptions class was also moved into AdvancedCompareOptions class.

This use case explains how to use AdvancedCompareOptions:

Added public property Comment.DateTimeUtc

Related issue: WORDSNET-26923

An ability to get comment UTC datetime has been implemented. If a comment does not contain such information, a value of the Comment.DateTime property converted to UTC time is returned.

public class Comment
{
    ...

    /// <summary>
    /// Gets the UTC date and time that the comment was made.
    /// </summary>
    /// <remarks>
    /// The default value is DateTime.MinValue.
    /// </remarks>
    public DateTime DateTimeUtc { get; }
}

This use case explains how to get comment UTC datetime:

Supported selective removal of paragraphs becoming empty for LINQ Reporting Engine

Related issue: WORDSNET-26515

In addition to removal of all paragraphs becoming empty after template syntax tags are processed, LINQ Reporting Engine introduces an ability to remove such paragraphs selectively using the following template syntax:

<<!tag_name ...>>

For a tag with its name prepended with an exclamation mark, the engine checks whether a corresponding paragraph or paragraphs become empty after the tag is processed, and if they do, removes them. Paragraphs corresponding to the rest of tags are kept intact by the engine.

This use case explains how to remove empty paragraphs selectively:

Added an ability to specify a message for missing object members for LINQ Reporting Engine

Related issue: WORDSNET-26749

Starting from Aspose.Words 24.6, you can specify a message to be printed instead of a template expression that represents a plain reference to a missing member of an object when using LINQ Reporting Engine. The following code snippet shows how to achieve this.

Consider the following template example.

Prefix <<[missing]>> suffix.

This use case explains how to specify a message to be printed instead of a template expression that represents a plain reference to a missing member: