ActiveReportsの構成ファイル

はじめに

ActiveReportsは、柔軟性と後方互換性を確保するために、2種類の構成フォーマットをサポートしています。

• レガシー形式：18.0J以前の旧形式

• モダン形式：20.0Jで採用した新形式

今後もレガシー形式を引き続きサポートしますが、モダン形式はよりモジュール化された構造を提供し、実行時設定とデザイン時設定を明確に分離します。

構成フォーマット

レガシー形式

18.0J以前に作成されたプロジェクト向けに、従来のフラットな構成を引き続きサポートします。この形式は、.NET標準の構成に準拠しています。

• <Configuration>

• <appSettings>

• <Extensions>

モダン形式

20.0Jで導入されたモダン形式では、ActiveReports.configファイルを再設計し、設定を専用のスコープ配下にカプセル化します。この構造により、グローバルな.NETアプリケーション設定との競合を防止しします。次の2つのセクションで構成されます。

• <ActiveReportsConfig>：すべての環境で共通の実行時構成を定義します。

• <ActiveReportsConfig.Desktop>：デスクトップおよびデザイン時環境向けの固有の構成を定義します。

構成の優先順位

スムーズな移行のために、2つの形式を共存させることができます。ただし、以下の優先順が適用されます。

1. 優先：システムは最初にモダン形式で定義された設定を探します。

2. フォールバック：モダンセクションに設定が見つからない場合、システムはレガシー構成にフォールバックします。

構成の検出と読み込み

ActiveReportsは、ホスティング環境に応じて特定の検出メカニズムを使用して構成設定を見つけます。モダン形式、レガシー形式のどちらも読み込み可能です。

グローバル構成

ActiveReportsをインストールすると、インストールフォルダにグローバル構成ファイルが配置されます（例：C:\Program Files (x86)\ActiveReportsNETxx\ActiveReports.config）。

このファイルは、Visual Studioの統合デザイナ、デザイナアプリ、およびビューワアプリによって自動的に読み取られます。

デスクトップアプリケーション

Windowsフォーム／WPFアプリケーションの場合、エンジンはアプリケーション実行ファイルと同じディレクトリにある専用の ActiveReports.config ファイルからの設定読み込みを優先します。

Webアプリケーション

Webアプリケーションでは、ミドルウェアのセットアップを使用して、構成ファイルを明示的に指定する必要があります。参照されるファイルには、モダンまたはレガシーのいずれの構成定義も含められます。

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

設定内容

以下、モダン形式の構成について説明します。

.NET標準の構成構文を使用して、設定を管理します。設定は、以下の要素で変更できま。

• <add>：新しい項目を登録します。同じキーの項目がすでに存在する場合は上書きします。

• <remove>：名前／キーで特定の項目（多くの場合は既定）を削除します。

• <clear>：コレクションに現在登録されているすべての項目を削除し、カスタムのセットを定義できるようにします。

（1）データプロバイダ

<DataProviders> セクションは、ActiveReportsエンジンで使用可能なデータコネクタを管理します。これにより、データファクトリの登録、カスタムデータプロバイダの有効化、または既定の組み込みプロバイダの上書きを行い、アプリケーションが必要なデータソースに接続できるようにします。

サンプル

<ActiveReportsConfig>
    <DataProviders>
        <!-- デフォルトのSQLプロバイダを削除 -->
        <remove name="SQL" />
        <!-- SQLITEプロバイダを追加 -->
        <add name="SQLITE"
             type="System.Data.SQLite.SQLiteFactory, System.Data.SQLite"
             displayName="SQLite Provider" />
    </DataProviders>
</ActiveReportsConfig>

設定

（2）フォント

<FontSettings> セクションは、ActiveReports エンジンがフォントを検出し解決する方法を制御します。この構成は、特にホスティング環境にデザイン時に使用した特定のフォントが存在しない場合に、異なるプラットフォーム（例：Windows、Linux、Docker）間で WYSIWYG の一貫性を確保するうえで重要です。

サンプル

<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>

設定

1. <FontFolders>

   エンジンがフォント ファイル（.ttf、.otf など）を検索するカスタム ディレクトリを登録します。これは、フォントが標準的でない場所に配置される可能性があるコンテナ環境で有用です。

• path：フォント ディレクトリへのファイル システム パス。環境変数（例：%WINDIR%）をサポートします。

• recurse：（true/false）true に設定すると、エンジンはすべてのサブディレクトリを検索してフォント ファイルを探します。

2. <FontSubstitutions>

   要求されたフォントを代替フォントにマップします。これは、レポートで特定のフォントが要求されているものの、ターゲット環境で利用できないことが分かっている場合に使用します。

• from：レポート定義で要求されるフォント名。

• to：実時に代替として使用するローカル フォント名。

3. <FallbackFonts>

   主要フォントに特定の文字のグリフがない場合に使用するフォントのグローバル優先順位リストを定義します。これは、標準的なラテン文字テキストに加えて多言語データ（例：CJK 文字）を含むレポートで重要です。

• font：試行するフォールバック フォント名。

4. <FontLinks>

   特定 のベース フォントに対して、「リンク」されたフォント チェーンを定義します。これは Windows の Font Linking 機能を模倣し、他のフォントからグリフを借用することで特定フォントの文字セットを拡張できます。

• font：拡張対象のベース フォント。

• list：ベース フォント使用時に不足するグリフを探すフォントのカンマ区切りリスト。

（3）マップ

<MapTileProviders> セクションは、Map レポートアイテムで使用される外部タイル サービスを構成します。これにより、標準サービス（Bing や Google Maps など）の認証を設定したり、完全にカスタムのタイルプロバイダを登録したりできます。

多くの商用マップ サービスでは、本番利用に有効な API キーが必要です。

• Azure Maps

• Google Maps

• MapQuest

設定

各プロバイダは <add> 要素を使用して登録します。これには、プロバイダ固有のパラメーター用に入れ子になった <Settings> コレクションを含めることができます。

サンプル

<ActiveReportsConfig>
    <MapTileProviders>
        <add name="Google" displayName="Google Tiles">
            <Settings>
                <add key="ApiKey" value="APIキーを設定します" />
                <add key="Timeout" value="5000" />
            </Settings>
        </add>
    </MapTileProviders>
</ActiveReportsConfig>

プロバイダ設定

各プロバイダは <Settings> 子要素内で構成キーの一覧を受け取れます。

• ApiKey：外部マップ サービスがリクエストを認可するために必要なアクセス トークンまたは API キー。

• Timeout：タイムアウトするまでタイルの読み込みを待機する最大時間（ミリ秒）（例：5000）。

カスタムタイルプロバイダ

カスタムタイルプロバイダを使用するには、コードでプロバイダロジックを実装し、ここで type 属性を使用して登録する必要があります。これにより、ActiveReports を拡張して、特化したマップ サービスやプライベートなマップ サービスをサポートできます。

実装の詳細については、カスタムタイルプロバイダ サンプルを参照してください。

（4）実行オプション

<ActiveReportsConfig> 内の <Settings> セクションは、レポート エンジンの中核となる実行時動作とセキュリティ ポリシーを制御します。実行ポリシー、テキスト レンダリング アルゴリズム、逆シリアル化に関連するセキュリティ制約を調整できます。

このセクションは標準のキー/値ペア形式を使用します。

• <clear />：事前に定義された設定を削除し、このセクションが実行時オプションの決定的なソースであることを保証します。

• <add key="..." value="..." />：個別の実行時設定を定義します。

設定

サンプル

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

（5）レポートウィザード

要素の有効化/無効化によってレポートウィザードをカスタマイズできます。

レポートの種類（<ReportWizardReportTypes>）

このコレクションは、レポートウィザードで使用可能なレポートの種類を設定します。

設定

• Page：ページレポート

• Section：セクションレポート

• RdlMultiSection：RDLレポート

• RdlDashboard：ダッシュボード

データソースの種類（<ReportWizardDataSourceTypes>）

このコレクションは、データソースウィザードに表示されるデータコネクタをフィルターします。

設定

• File：ファイルベースのデータソース（CSV、JSON、XML、Excel）。

• DataBase：ADO.NET プロバイダ経由のリレーショナル データベース（SQL Server、SQLite など）。

• WebAPI：HTTP ベースのデータ ソース（REST、OData）。

• Programmatic：カスタム コード（Objectプロバイダ）によって動的に提供されるデータ。

サンプル

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

（6）AIプロバイダ

<ReportDesignerAiProviders> セクションは、レポート デザイナおよびレポート ウィザードで使用される外部 AI サービスを構成します。これらの連携により、画像からレポートレイアウトを生成する機能や、生成AIを使用してデータセット構造に基づきデータ領域（テーブル、チャートなど）を自動生成する機能を利用できます。

設定

各プロバイダは <add> 要素を使用して登録します。この要素は、外部サービスとの通信を処理する特定のファクトリ型を指します。

プロバイダ設定

各プロバイダは <Settings> コレクションを介して独自の構成を定義します。一般的なキーは次のとおりです。

• ApiKey：外部 AI サービスへのアクセスに必要な認証キー。

• Endpoint：サービス URL。Azure AI Document Intelligence では必須です。

• Model：特定のモデル識別子またはデプロイ名。OpenAI、Azure OpenAI では必須です。

• Timeout：操作がキャンセルされるまでの最大リクエスト時間（ミリ秒）（例：90000）。

プロバイダの種類

• Azure AI Document Intelligence：画像からレポートレイアウトを作成します。

• OpenAI、Azure OpenAI：データ構造の分析と、レポート データ領域の自動生成に使用します。

サンプル

<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="APIキーを設定します" />
            <add key="Endpoint" value="エンドポイントのURLを設定します" />
            <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="APIキーを設定します" />
            <add key="Model" value="gpt-4o" />
            <add key="Timeout" value="90000" />
        </Settings>
    </add>
</ReportDesignerAiProviders>

（7）デザイナ、ビューワ

<ActiveReportsConfig.Desktop> 内の <Settings> セクションでは、レポート デザイナおよびレポート ビューワ コントロールの動作をカスタマイズできます。これには、印刷ダイアログ、レンダリング エンジンの構成、特定のツールボックス項目の表示/非表示の制御が含まれます。

設定（ビューワ）

以下のキーは、レポート ビューワのレンダリングおよび印刷動作を制御します。

設定（デザイナ）

以下のキーは、レポート デザイナの一般的なワークフローを制御します。

以下のキーを使用すると、デザイナ ツールボックス内の特定コントロールの表示/非表示を切り替えられます。これは、レガシー コントロールを非推奨にしたり、エンドユーザー向けに UI を簡素化したりする場合に有用です。

以下のキーはレポート ライブラリを構成します。レポート ライブラリでは、再利用可能なレポート パーツ（ヘッダー、ロゴ、チャートなど）をデザインにドラッグ＆ドロップできます。

サンプル

<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>