GroupDocs.Conversion for .NET 25.10 Release Notes

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

Full list of changes in this release

Major Features

• API Refactoring - Page Layout Settings: Improved API consistency by consolidating margin and size properties into dedicated settings objects (MarginSettings and SizeSettings) across conversion options classes.
• Enhanced Page Margin Control: Introduced MarginSettings property with PageMarginOptions class for unified margin configuration in PDF and WordProcessing conversion options.
• Enhanced Page Size Control: Introduced SizeSettings property with PageSizeOptions class for unified page size configuration across PDF, WordProcessing, EBook, and CAD conversion options.
• Page Layout Support in Load Options: Added support for setting page size, margins, and orientation in EmailLoadOptions, SpreadsheetOptions, TxtLoadOptions, and WordProcessingLoadOptions before conversion.

Public API and backward incompatible changes

⚠️ BREAKING CHANGES: Deprecated properties will be removed in version 26.1

This release introduces a refactoring of conversion options properties to improve API consistency and maintainability. Individual margin and size properties have been consolidated into dedicated settings objects.

Affected Classes and Deprecated Properties

20 properties deprecated across 4 classes:

1. PdfConvertOptions (7 properties):

   • MarginTop, MarginBottom, MarginLeft, MarginRight → Use MarginSettings
   • PageSize, PageWidth, PageHeight → Use SizeSettings

2. WordProcessingConvertOptions (7 properties):

   • MarginTop, MarginBottom, MarginLeft, MarginRight → Use MarginSettings
   • PageSize, PageWidth, PageHeight → Use SizeSettings

3. EBookConvertOptions (3 properties):

   • PageSize, PageWidth, PageHeight → Use SizeSettings

4. CadConvertOptions (3 properties):

   • PageSize, PageWidth, PageHeight → Use SizeSettings

New Classes Introduced

PageMarginOptions Class:

public class PageMarginOptions
{
    public float? Top { get; set; }
    public float? Bottom { get; set; }
    public float? Left { get; set; }
    public float? Right { get; set; }
}

PageSizeOptions Class:

public sealed class PageSizeOptions
{
    public PageSize PageSize { get; set; }
    public float PageWidth { get; set; }  // When set, PageSize auto-changes to PageSize.Custom
    public float PageHeight { get; set; } // When set, PageSize auto-changes to PageSize.Custom
}

Migration Guide

Migrating Page Margins

Old Approach (Deprecated):

var options = new PdfConvertOptions
{
    MarginTop = 10,
    MarginBottom = 10,
    MarginLeft = 20,
    MarginRight = 20
};

New Approach (Recommended):

var options = new PdfConvertOptions
{
    MarginSettings = new PageMarginOptions
    {
        Top = 10,
        Bottom = 10,
        Left = 20,
        Right = 20
    }
};

Migrating Page Size Settings

Old Approach (Deprecated):

// Using predefined page size
var options = new PdfConvertOptions
{
    PageSize = PageSize.A4
};

// Using custom dimensions
var customOptions = new WordProcessingConvertOptions
{
    PageWidth = 612,  // Letter width in points
    PageHeight = 792  // Letter height in points
};

New Approach (Recommended):

// Using predefined page size
var options = new PdfConvertOptions
{
    SizeSettings = new PageSizeOptions
    {
        PageSize = PageSize.A4
    }
};

// Using custom dimensions
var customOptions = new WordProcessingConvertOptions
{
    SizeSettings = new PageSizeOptions
    {
        PageWidth = 612,  // Letter width in points
        PageHeight = 792  // Letter height in points
        // PageSize automatically set to PageSize.Custom
    }
};