Configure ActiveReports using Config File

Introduction

ActiveReports supports two distinct configuration formats to ensure flexibility and backward compatibility: the Legacy format (used prior to v20) and the Modern format (introduced in v20). While the Legacy format remains fully supported, the Modern format provides a more modular structure that clearly separates runtime and design-time settings.

Configuration Formats

1. Modern Format (v20+)

Introduced in ActiveReports 20, this format redesigns the ActiveReports.config file to encapsulate settings under dedicated scopes. This structure prevents conflicts with global .NET application settings and improves long-term maintainability. The configuration is organized into two primary sections:

• <ActiveReportsConfig>: Defines common runtime configuration shared by all hosting environments.

• <ActiveReportsConfig.Desktop>: Defines specific configuration for desktop and design-time environments (WinForms, WPF, and the Desktop Report Designer).

2. Legacy Format (Pre-v20)

For projects established before v20, ActiveReports continues to support the traditional flat configuration structure. This format relies on standard .NET configuration sections:

• <Configuration>

• <appSettings>

• <Extensions>

Configuration Precedence

ActiveReports allows both formats to coexist within an application to facilitate a smooth migration. However, the system enforces a specific priority order when resolving settings:

1. Primary: The system first looks for settings defined in the Modern (v20+) format.

2. Fallback: If a setting is not found in the modern sections, the system falls back to the Legacy configuration.

Configuration Discovery and Loading

ActiveReports uses specific discovery mechanisms to locate configuration settings depending on the hosting environment. In all cases, the engine can load either the Modern (v20+) or Legacy format from the discovered file.

Global Configuration

When ActiveReports is installed, a global configuration file is placed in the installation folder (e.g., C:\Program Files (x86)\MESCIUS\ActiveReports 20\ActiveReports.config).

This file is automatically read by the Visual Studio Integrated Designer, the Standalone Designer Application, and the Standalone Report Viewer to apply default settings.

Desktop Applications

For Windows (WinForms) and WPF applications, the engine prioritizes loading settings from a dedicated ActiveReports.config file located in the same directory as the application executable.

Web Applications

Web applications must explicitly point to the configuration file using the ActiveReports Middleware setup. The referenced file can contain either Modern or Legacy configuration definitions.

using GrapeCity.ActiveReports.Aspnetcore.Viewer;
app.UseReportViewer(config =>
{
    config.UseConfig(Path.Combine(builder.Environment.ContentRootPath, "Config", "ActiveReports.config"));
});

Configuration sections

The following sections apply to the Modern (v20+) configuration format.

Many of these sections manage collections of settings (such as data providers or custom items) using standard .NET configuration syntax. You can modify these collections using the following elements:

• <add>: Registers a new item. If an item with the same key already exists, this will override it.

• <remove>: Removes a specific item (often a default) by its name/key.

• <clear>: Removes all currently registered items from the collection, allowing you to define a completely custom set.

Data Providers

The <DataProviders> section manages the data connectors available to the ActiveReports engine. This allows you to register data factories, enable custom data providers, or override the default built-in providers to ensure your application can connect to required data sources.

<ActiveReportsConfig>
    <DataProviders>
        <!-- Removing the default SQL provider -->
        <remove name="SQL" />
        <!-- Adding SQLITE providers -->
        <add name="SQLITE"
             type="System.Data.SQLite.SQLiteFactory, System.Data.SQLite"
             displayName="SQLite Provider" />

    </DataProviders>
</ActiveReportsConfig>

Attributes

Custom Report Items

The <CustomReportItems> section registers custom controls for use in reports.

In the Modern format, this registration is split into two distinct scopes. This separation ensures that runtime environments (such as web or cloud services) load only the rendering logic, while heavy UI and design-time assemblies are restricted to desktop environments.

Subsections

• <RuntimeComponents>: Located within the <ActiveReportsConfig> scope, this section registers the core implementation of the custom control used for processing and rendering the report.

• <DesignComponents>: Located within the <ActiveReportsConfig.Desktop> scope, this section registers the metadata, designer behavior, and UI elements required by the Report Designer.

Configuration Example

<Configuration>
    <ActiveReportsConfig>
        <CustomReportItems>
            <RuntimeComponents>             
                <clear />
                <add name="RadarChart" type="MESCIUS.ActiveReports.Samples.Radar.RadarChart, RadarChart" />
            </RuntimeComponents>
        </CustomReportItems>
    </ActiveReportsConfig>

    <ActiveReportsConfig.Desktop>
        <CustomReportItems>
            <DesignComponents>             
                <clear />
                <add name="RadarChart"
                     type="MESCIUS.ActiveReports.Samples.Radar.RadarDesigner, RadarDesigner" toolboxIcon="MESCIUS.ActiveReports.Samples.Radar.RadarIcon.png" />
            </DesignComponents>
        </CustomReportItems>
    </ActiveReportsConfig.Desktop>
</Configuration>

Attributes

Example Reference

For a complete implementation of a custom control, see the Custom Chart Sample.

Font Settings

The <FontSettings> section controls how the ActiveReports engine discovers and resolves fonts. This configuration is critical for ensuring WYSIWYG consistency across different platforms (e.g., Windows, Linux, Docker), especially when the hosting environment lacks the specific fonts used during design time.

Configuration Example

<ActiveReportsConfig>
    <FontSettings>
        <FontFolders>
            <add path="%WINDIR%/Fonts" recurse="true"/>
            <add path="%USERPROFILE%/AppData/Local/Microsoft/Windows/Fonts" recurse="true"/>
        </FontFolders>

        <FontSubstitutions>
            <add from="Arabic Transparent" to="Arial"/>
        </FontSubstitutions>

        <FallbackFonts>
            <add font="Microsoft Sans Serif"/>
            <add font="MS UI Gothic" />
            <add font="Arial" />
        </FallbackFonts>

        <FontLinks>
            <add font="Lucida Sans Unicode"
                 list="MS UI Gothic,PMingLiU,SimSun,Gulim,Yu Gothic UI,Microsoft JhengHei UI,Microsoft YaHei UI,Malgun Gothic" />
        </FontLinks>
    </FontSettings>
</ActiveReportsConfig>

Subsections and Attributes

1. <FontFolders>

Registers custom directories where the engine should search for font files (.ttf, .otf, etc.). This is useful for containerized environments where fonts might reside in non-standard locations.

• path: The file system path to the font directory. Supports environment variables (e.g., %WINDIR%).

• recurse: (true/false) If set to true, the engine searches all subdirectories for font files.

2. <FontSubstitutions>

Maps a requested font to a replacement font. This is used when a specific font is requested by the report but is known to be unavailable in the target environment.

• from: The name of the font requested in the report definition.

• to: The name of the local font to use as a substitute at runtime.

3. <FallbackFonts>

Defines a global priority list of fonts to use when the primary font lacks a glyph for a specific character. This is essential for reports containing multi-language data (e.g., CJK characters) mixed with standard Latin text.

• font: The name of the fallback font to attempt.

4. <FontLinks>

Defines a "linked" chain of fonts for a specific base font. This mimics the Windows Font Linking feature, allowing you to extend the character set of a specific font by borrowing glyphs from others.

• font: The base font being extended.

• list: A comma-separated list of fonts to check for missing glyphs when the base font is used.

Map Tile Providers

The <MapTileProviders> section configures the external tile services used by the Map report item. This allows you to set up authentication for standard services (like Bing or Google Maps) or register completely custom tile providers.

Most commercial map services require a valid API key for production use. Common providers include:

• Azure Maps: Azure Maps Product Page

• Google Maps: Requires a Google Developer Account

• MapQuest: Requires a MapQuest Developer Network Account

Configuration Structure

Each provider is registered using an <add> element, which may contain a nested <Settings> collection for provider-specific parameters.

Attributes

Configuration Example

<ActiveReportsConfig>
    <MapTileProviders>
        <add name="Google" displayName="Google Tiles">
            <Settings>
                <add key="ApiKey" value="<Here is your API key>" />
                <add key="Timeout" value="5000" />
            </Settings>
        </add>
    </MapTileProviders>
</ActiveReportsConfig>

Provider Settings

Each provider can accept a list of configuration keys within a <Settings> child element.

• ApiKey: The access token or API key required by the external map service to authorize requests.

• Timeout: The maximum time (in milliseconds) to wait for a tile to load before timing out (e.g., 5000).

Custom Tile Providers

To use a custom tile provider, you must implement the provider logic in code and register it here using the type attribute. This allows you to extend ActiveReports to support specialized or private map services.

For implementation details, refer to the Custom Tile Provider Sample.

Runtime Settings

The <Settings> section within <ActiveReportsConfig> controls the core runtime behavior and security policies of the reporting engine. It allows you to fine-tune execution policies, text rendering algorithms, and security constraints related to deserialization.

Configuration Structure

This section uses the standard key-value pair format.

• <clear />: Removes any previously defined settings, ensuring that the current section is the definitive source for runtime options.

• <add key="..." value="..." />: Defines an individual runtime setting.

Available Settings

Configuration example

<ActiveReportsConfig>
    <Settings>
        <clear />
        <add key="ScriptExecutionPolicy" value="Enabled" /> <!-- Enabled or Disabled -->
        <add key="LineBreakingAlgorithm" value="Unicode" /> <!-- Unicode or Legacy -->
        <add key="SkipReportValidation" value="false" />
        <add key="EnableLegacyDeserialization" value="false" />
        <add key="EnableBinaryFormatterDeserialization" value="false" />
    </Settings>
</ActiveReportsConfig>

Report Wizard Customization

These settings allow you to customize Report Wizard UI by enabling and disabling its elements.

1. Report Types (<ReportWizardReportTypes>)

This collection defines the list of report types available in the "New Report" wizard and determines which one is pre-selected.

Attributes

Available Values

• RdlMultiSection: RDL Multi-Section reports (modern, responsive layout).

• Section: Traditional Section reports (banded layout).

• Page: Page reports (fixed-page layout).

• RdlDashboard: Dashboard-style RDL reports.

• SampleReports: Enables the "Samples" tab in the wizard, allowing users to select from pre-built templates.

2. Data Source Types (<ReportWizardDataSourceTypes>)

This collection filters the categories of data connectors displayed in the Data Source Wizard.

Available Values

• File: File-based sources (CSV, JSON, XML, Excel).

• DataBase: Relational databases (SQL Server, SQLite, etc.) via ADO.NET providers.

• WebAPI: HTTP-based data sources (REST, OData).

• Programmatic: Data supplied dynamically by custom code (Object providers).

General Behavior

Both collections use standard configuration logic:

• <clear />: Removes all default options. Use this first if you want to define a strictly limited list of available types.

• <add name="..." />: Adds a specific type to the allowed list. Only the types explicitly added here will appear in the UI.

Example configuration

<ActiveReportsConfig.Desktop>
    <ReportWizardReportTypes>
        <clear />
        <add name="RdlMultiSection" default="true" />
        <add name="Section" />
        <add name="Page" />
        <add name="RdlDashboard" />
        <add name="SampleReports" />
    </ReportWizardReportTypes>
    <ReportWizardDataSourceTypes>
        <clear />
        <add name="File" />
        <add name="DataBase" />
        <add name="WebAPI" />
        <add name="Programmatic" />
    </ReportWizardDataSourceTypes>    
</ActiveReportsConfig.Desktop>

AI Providers

The <ReportDesignerAiProviders> section configures the external AI services used by the Report Designer and Report Wizard. These integrations enable advanced features such as generating report layouts from images (OCR) and using Generative AI to automatically build data regions (tables, charts, etc.) based on your dataset structure.

Configuration Structure

Each provider is registered using an <add> element, which points to a specific factory type that handles the communication with the external service.

Attributes

Provider Settings

Each provider defines its own configuration via the <Settings> collection. Common keys include:

• ApiKey: The authentication key required to access the external AI service.

• Endpoint: The service URL (specifically required for Azure AI Document Intelligence).

• Model: The specific model identifier or deployment name (required for OpenAI or Azure OpenAI).

• Timeout: The maximum request duration in milliseconds (e.g., 90000) before the operation is cancelled.

Supported Integrations

• Azure AI Document Intelligence: Used for OCR-based layout generation (converting an image into a report layout).

• OpenAI / Azure OpenAI: Used for analyzing data structures and generating report data regions automatically.

Example configuration

<ReportDesignerAiProviders>
    <clear />
    <add name="ReportWizard.OCR.AzureAiDocumentIntelligence" type="GrapeCity.ActiveReports.Design.AI.AzureAI.DocumentIntelligence.ReportFromImage.ReportImageAnalyzerFactory, MESCIUS.ActiveReports.Design.AI.AzureAI.DocumentIntelligence">
        <Settings>
            <add key="ApiKey" value="<Azure AI API key here>" />
            <add key="Endpoint" value="<service URL here>" />
            <add key="Timeout" value="90000" />
        </Settings>
    </add>
    <add name="ReportWizard.DataRegionsBuilder.OpenAI" type="GrapeCity.ActiveReports.Design.AI.OpenAI.OpenAIDataRegionsBuilderFactory, MESCIUS.ActiveReports.Design.AI.OpenAI">
        <Settings>
            <add key="ApiKey" value="<OpenAI API Key here>" />
            <add key="Model" value="gpt-4o" />
            <add key="Timeout" value="90000" />
        </Settings>
    </add>
</ReportDesignerAiProviders>

Designer and Viewer Settings

The <Settings> section within <ActiveReportsConfig.Desktop> allows you to customize the behavior of the Report Designer and Report Viewer controls. This includes configuring print dialogs, rendering engines, and controlling the visibility of specific toolbox items.

Report Viewer Settings

These keys control the rendering and printing behavior of the Report Viewer.

Designer Behavior

These keys control the general workflow of the Report Designer.

Toolbox Visibility

These keys allow you to show or hide specific controls in the Designer Toolbox. This is useful for deprecating legacy controls or simplifying the UI for end-users.

Report Library Settings

These keys configure the Report Library, which allows users to drag and drop re-usable report parts (like headers, logos, or charts) into their designs.

Configuration Example

<ActiveReportsConfig.Desktop>
    <Settings>
        <add key="Viewer.EnableFontSmoothing" value="false" />

        <add key="Viewer.PrintDialogStyle" value="Advanced" />
        <add key="Viewer.PrintingSystem" value="Auto" />

        <add key="Designer.AutoInvokeDataRegionWizard" value="true" />

        <add key="Designer.Toolbox.EnableOleObject" value="false" />
        <add key="Designer.Toolbox.EnableMatrix" value="false" />
        <add key="Designer.Toolbox.EnableChartClassic" value="false" />
        <add key="Designer.Toolbox.EnableChart" value="true" />

        <add key="Designer.Controls.ShowReportsLibrary" value="false" />
        <add key="Designer.Controls.ReportPartsDirectory" value="%MyDocuments%/ReportsLibrary" />
    </Settings>
</ActiveReportsConfig.Desktop>