# Breaking Changes

Learn the breaking changes from ActiveReports 12 to ActiveReports 18, control changes, other changes, classes in different namespaces, namespace changes, etc.

## Content

The following changes in ActiveReports 20 may require updates to your existing applications. Please review these items before upgrading.

## New Enums for Export Settings

**Summary**
To standardize export settings, new public enumerations have been introduced to replace internal or scattered enum types.

* A new [PrintLayoutMode](/activereportsnet/api/v20.1/MESCIUS.ActiveReports/GrapeCity.ActiveReports.PrintLayoutMode.html){:target="_blank"} enum was added to `MESCIUS.ActiveReports.dll`.
* A new [PaddingType](/activereportsnet/api/v20.1/MESCIUS.ActiveReports.Export.Xml/GrapeCity.ActiveReports.Export.Xml.Text.Page.PaddingType.html){:target="_blank"} enum was added to `MESCIUS.ActiveReports.Export.Xml.dll`.

**Impact**
This affects projects referencing the following properties, as their types have changed:

* **PDF & Image Export:** `PrintLayoutMode` in `GrapeCity.ActiveReports.Export.[Pdf|Image].Page.Settings`.
* **XML Export:** `HorizontalPaddings` in `GrapeCity.ActiveReports.Export.Text.Page.Settings`.

**Migration**
Update your code to use the new enumeration types as shown below:

| Property Location | Old Type | New Type |
| :---------------- | :------- | :------- |
| `Export.Image.Page.Settings` | `GrapeCity.ActiveReports.ImageRenderers.PageControl.PrintLayoutMode` | **`GrapeCity.ActiveReports.PrintLayoutMode`** |
| `Export.Pdf.Page.Settings` | `GrapeCity.ActiveReports.ImageRenderers.PageControl.PrintLayoutMode` | **`GrapeCity.ActiveReports.PrintLayoutMode`** |
| `Export.Text.Page.Settings` | `GrapeCity.ActiveReports.Export.Text.Page.PaddingType` | **`GrapeCity.ActiveReports.Export.Xml.Text.Page.PaddingType`** |

***

## Direct2D Rendering Enabled by Default

**Summary**
The Direct2D rendering engine is now the default for desktop controls. This applies to:

* Page and RDLX reports.
* Section reports running in `CrossPlatform` compatibility mode.

**Impact**
This change may affect applications that rely on specific behavior of the legacy GDI printer wrapper (e.g., manual manipulation of `PageDocument.Printer` or `SectionDocument.Printer` properties/events).
**Migration**
If your application requires the legacy GDI rendering behavior, you must explicitly configure the `Viewer.PrintingSystem` to "GDI" in your `ActiveReports.config` file:

```xml
<Configuration>
    <ActiveReportsConfig.Desktop>
        <Settings>
            <add key="Viewer.PrintingSystem" value="GDI" />
        </Settings>
    </ActiveReportsConfig.Desktop>
</Configuration>
```

***

## Configuration File Standardization

**Summary**
The ActiveReports configuration schema has been updated to follow standard .NET configuration rules, replacing the previous proprietary section logic.
**Impact**
This affects all projects relying on `ActiveReports.config` or `app.config` to configure the reporting engine. The legacy configuration schema keeps working, but, strict adherence to the new schema is required for guaranteed stability.
**Migration**
Update your configuration file to match the new .NET-compliant schema. Please refer to the [Configure ActiveReports using Config file](/activereportsnet/docs/v20.1/devops/customization/configure-ar){:target="_blank"} documentation for the full specification.

***

## Designer Assembly Refactoring

**Summary**
The monolithic `MESCIUS.ActiveReports.Designer.Win` assembly has been split into three specialized assemblies:

1. **`MESCIUS.ActiveReports.Designer.Win`**: The core designer functionality.
2. **`MESCIUS.ActiveReports.Editor.Net`**: The code editor (formerly QWhale), now built from sources with specific fixes.
3. **`MESCIUS.ActiveReports.Advanced.Win`**: The End-User Designer (EUD) components.

**Impact**
This specifically affects the process of localizing the designer. You can no longer build a single resource assembly; you must now build separate resource assemblies for the components you are using.
**Migration**
Split your localization resources into separate satellite assemblies corresponding to the new assembly names listed above.

***

## Removal of MESCIUS.ActiveReports.Serializer.VS2022 Package

**Summary**
The `MESCIUS.ActiveReports.Serializer.VS2022` NuGet package has been deprecated and is no longer required. Its functionality has been merged or superseded by other assemblies.
**Impact**
Projects explicitly referencing this package will fail to restore NuGet packages or build.
**Migration**
Remove the reference to `MESCIUS.ActiveReports.Serializer.VS2022` from your project dependencies.

***

## Updated Signature for `PageDocument.Render`

**Summary**
The [Render](/activereportsnet/api/v20.1/MESCIUS.ActiveReports/GrapeCity.ActiveReports.Document.PageDocument.Render.html){:target="_blank"} method signature has been updated. The `progress` argument previously used an internal type but now uses a public type from the `GrapeCity.ActiveReports.Document` namespace.
**Impact**
This affects code calling `PageDocument.Render` with a progress reporter.
**Migration**
Update your `using` directives or fully qualified names to use the new type location.

* **Old:** `GrapeCity.ActiveReports.Core.Rendering.ProgressInfo` (Internal)
* **New:** `GrapeCity.ActiveReports.Document.ProgressInfo`

***

## HTML Export Settings Enum Changes

**Summary**
The `RenderMode` and `RenderingEngine` properties in `GrapeCity.ActiveReports.Export.Html.Page.Settings` have changed types. They now use enums defined directly in the HTML Export namespace rather than the Core namespace.
**Impact**
This affects code that exports report to HTML.
**Migration**
Update your code to reference the enums in `GrapeCity.ActiveReports.Export.Html.Page`. If namespace conflicts occur, update your `using` directives or use fully qualified names.

***

## PageDocument API Refactoring (Parameters & Interactivity)

**Summary**
Internal types previously exposed in the public API have been replaced with new public wrappers in the `GrapeCity.ActiveReports.Document` namespace.

* `PageDocument.Parameters`: Now returns `GrapeCity.ActiveReports.Document.ParameterCollection`.
* `PageDocument.ApplyInteractivity`: Now accepts `GrapeCity.ActiveReports.Document.InteractiveActions`.

**Impact**
This affects code that accesses report parameters or handles interactivity actions using types from `GrapeCity.ActiveReports.Core.Rendering.*`.
**Migration**
Remove references to `GrapeCity.ActiveReports.Core.Rendering.ReportParameters` or `Interactivity`. Update your code to use the equivalent types in the `GrapeCity.ActiveReports.Document` namespace.

***

## Data Collection Type Changes

**Summary**
The collection type for several properties in the `GrapeCity.ActiveReports.Extensibility.Data` and `SchemaModel` namespaces has been standardized. The custom `IItemCollection<T>` interface has been replaced with the standard .NET `System.Collections.Generic.IReadOnlyList<T>`.
**Affected Properties:**

* `DataTable`: `Rows`, `Columns`
* `Table`: `Columns`
* `ForeignKey`: `SourceColumns`, `DestinationColumns`

**Impact**
This affects code that implements custom Data Providers or working with the Schema Model. Code explicitly referencing `IItemCollection<T>` or using the `.ToItemCollection()` extension method will fail to compile.
**Migration**

* Update variable declarations to use `IReadOnlyList<T>`, `IList<T>`, or `var`.
* Replace calls to `.ToItemCollection()` with standard LINQ methods such as `.ToList()` or `.ToArray()`.

## Report Designer and Viewer Theme Initialization
To allow for more flexible theme management, the initialization API for the Report Designer and Report Viewer has been updated. The top-level `theme` property is now deprecated and has been replaced by a `themes` configuration object. Existing initialization code using the `theme` property must be updated to use the new `themes` object structure to ensure future compatibility.
### Migration Details
The new `themes` object supports the following properties:
*   **initialTheme**: (Required) The ID of the theme to apply on load.
*   **themeSelector**: (Optional) Configuration for the UI theme selection component.

### Comparison: JavaScript Report Viewer
**Old Syntax (Deprecated)**
```
import { createViewer } from './jsViewer.min.js';

const viewer = createViewer({
  element: '#viewerContainer',
  theme: 'activeReports' // Directly assigned string
});
```
**New Syntax**
```js
import { createViewer } from './jsViewer.min.js';

const viewer = createViewer({
  element: '#viewerContainer',
  themes: {
    initialTheme: 'activeReports' // Wrapped in the themes object
  }
});
```

### Detailed Documentation
For full property definitions and configuration options, refer to the following initialization guides:
* [JS Report Viewer Initialization Options](/activereportsnet/api/v20.1/jsviewer/interfaces/InitializationOptions#themes)
* [Blazor Report Viewer Initialization Options](/activereportsnet/api/v20.1/MESCIUS.ActiveReports.Blazor.Viewer/GrapeCity.ActiveReports.Blazor.Viewer.InitializationOptions.html)
* [Web Report Designer Theme Settings](/activereportsnet/api/v20.1/jsdesigner/type-aliases/DesignerThemesSettings)