GroupDocs.Conversion for .NET 24.10 Release Notes

There are 10+ features, improvements, and bug fixes in this release.

Full list of changes in this release

Major features

• 3D to 3MF Conversion: Added support for converting 3D formats to 3MF.
• Converter API Enhancements: Simplified Converter API with context classes and reduced overloads.
• Improved Thread Safety: Enhanced thread safety for stable multi-threaded usage.
• Transparency Conversion Fixes: Fixed transparency issues in PSD, EPS, and PNG conversions.

Public API and backward incompatible changes

The Converter class has been updated to enhance usability by consolidating constructors and Convert methods. Obsolete methods and constructors are scheduled for removal in v25.1, set for release in January 2025. Below is the updated list of new methods and constructors, along with the obsolete methods they replace.

New Constructors

Converter(Func<Stream> sourceStreamProvider, Func<LoadContext, LoadOptions> loadOptions, Func<ConverterSettings> settings = null)

• Replaces Obsolete Constructors:
  • Converter(Func<Stream> sourceStreamProvider, Func<LoadOptions> loadOptions)
  • Converter(Func<Stream> sourceStreamProvider, Func<FileType, LoadOptions> loadOptions)
  • Converter(Func<Stream> sourceStreamProvider, Func<string, FileType, Stream, LoadOptions> loadOptions)
• Parameters:
  • sourceStreamProvider: A delegate providing a readable stream of the source document.
  • loadOptions: A delegate providing load options based on the document’s load context.
  • settings (optional): A delegate for custom conversion settings.

Converter(string filePath, Func<LoadContext, LoadOptions> loadOptions, Func<ConverterSettings> settings = null)

• Replaces Obsolete Constructors:
  • Converter(string filePath, Func<LoadOptions> loadOptions)
  • Converter(string filePath, Func<FileType, LoadOptions> loadOptions)
  • Converter(string filePath, Func<string, FileType, Stream, LoadOptions> loadOptions)
• Parameters:
  • filePath: The path to the source document.
  • loadOptions: A delegate providing load options based on the document’s load context.
  • settings (optional): A delegate for custom conversion settings.

New Convert Methods

Convert(ConvertOptions convertOptions, Action<ConvertedContext> documentCompleted, CancellationToken cancellationToken = default)

• Replaces Obsolete Methods:
  • Convert(Func<Stream> document, Func<string, FileType, ConvertOptions> convertOptionsProvider, CancellationToken cancellationToken)
• Description: Converts and saves the document, invoking a completion callback.
• Parameters:
  • convertOptions: Conversion options for the target type.
  • documentCompleted: Callback delegate triggered after successful conversion.
  • cancellationToken (optional): Token to cancel the operation.

Convert(ConvertOptions convertOptions, Action<ConvertedPageContext> documentCompleted, CancellationToken cancellationToken = default)

• Replaces Obsolete Methods:
  • Convert(Func<int, Stream> document, Func<string, FileType, ConvertOptions> convertOptionsProvider, CancellationToken cancellationToken)
• Description: Converts and saves the document page by page, with a completion callback for each page.
• Parameters:
  • convertOptions: Conversion options for the target type.
  • documentCompleted: Callback invoked for each converted page.
  • cancellationToken (optional): Token to cancel the operation.

Convert(Func<SavePageContext, Stream> targetStreamProvider, ConvertOptions convertOptions, CancellationToken cancellationToken = default)

• Replaces Obsolete Methods:
  • Convert(Func<int, Stream> document, ConvertOptions convertOptions, CancellationToken cancellationToken)
• Description: Converts and saves the document page by page.
• Parameters:
  • targetStreamProvider: A delegate providing the stream for each page’s conversion.
  • convertOptions: Conversion options for the desired target format.
  • cancellationToken (optional): Token to cancel the operation.

Convert(Func<ConvertContext, ConvertOptions> convertOptionsProvider, Action<ConvertedContext> documentCompleted, CancellationToken cancellationToken = default)

• Replaces Obsolete Methods:
  • Convert(Func<Stream> document, Action<string, FileType, Stream> documentCompleted, Func<string, FileType, ConvertOptions> convertOptionsProvider, CancellationToken cancellationToken)
• Description: Converts and saves the document, triggering a callback upon completion.
• Parameters:
  • convertOptionsProvider: A delegate providing context-specific conversion options.
  • documentCompleted: Callback delegate executed after conversion.
  • cancellationToken (optional): Token to cancel the operation.

Convert(Func<SaveContext, Stream> targetStreamProvider, ConvertOptions convertOptions, CancellationToken cancellationToken = default)

• Replaces Obsolete Methods:
  • Convert(Func<Stream> targetStreamProvider, ConvertOptions convertOptions, CancellationToken cancellationToken)
• Description: Converts and saves the document entirely.
• Parameters:
  • targetStreamProvider: Delegate providing the output stream.
  • convertOptions: Options specific to the target file format.
  • cancellationToken (optional): Token to cancel the operation.

Summary of Changes in Converter Class

In this release, the Converter class has been significantly refined to simplify usage, consolidate constructors and Convert methods, and improve usability:

• Constructor Reduction:

  • Original: 14 constructors
  • Updated: 6 streamlined constructors that handle most use cases via flexible delegates
  • Reduction: From 14 to 6 constructors, achieving an 57% reduction in constructor options, simplifying setup and configuration.

• Method Reduction:

  • Original: 17 Convert methods, covering a variety of parameter combinations for document- and page-level conversion
  • Updated: 9 Convert methods that now manage:
    • Whole document and page-by-page conversion
    • Standardized use of delegates for various contexts, including:
      • SaveContext and SavePageContext for output stream management
      • ConvertContext for general conversion parameters
      • LoadContext for load options
      • ConvertedContext and ConvertedPageContext for completion callbacks at document and page levels
  • Reduction: From 17 to 9 methods, resulting in a 47% reduction in method overloads, simplifying the API with clearer, more consistent usage patterns.

Total API Streamlining

By consolidating and reducing both constructors and methods, the Converter class now offers 51% fewer overloads (from 31 down to 15), yielding a more user-friendly API design. This reduction enhances usability, improves maintainability, and allows for easier extensibility in future development.