# Blazor Report Writer for Crystal Reports XML

URL: https://flexcoreui.com/demo/reports/package-costs  
Section: Reports  
Controls: ReportWriterControl, CrystalXmlReportLoader, ReportDefinition  
Keywords: report viewer, report writer, Crystal Reports, Blazor reporting, paginated reports, report designer

Run paginated, grouped reports in a Blazor app, from code or a Crystal Reports XML export, with a group tree, search, print and export.

## Documentation

### Params

| Name | Type | Default | Description |
|---|---|---|---|
| ShowChrome | bool | true | Toolbar, group tree, tabs and the parameter dialog. False drops the bare page area into a host that has its own UI. |
| UsePositionedLayout | bool | false | Renders with the Crystal band and object geometry instead of table columns, in ShowReportAsync, the parameter dialog and refresh. |
| PdfViewerComponentType | Type? | null | The PDF viewer component used for .rpt output, for trimmed hosts that bring the Documents package. |
| PromptOptionalParameters | bool | false | Includes optional parameters in the parameter dialog. |
| TabsOrientation | TabOrientation | TabOrientation.Vertical | Layout of the report tabs (the main report and its drill-downs, shown once there are two): Vertical, a rail; HybridVertical, wrapped rows; Horizontal, one scrolling row. A right-click on the strip opens the viewer's own orientation and theme menu; the choice goes to IReportViewerSettings and is read back when the viewer first loads. |
| TabsTheme | TabTheme | TabTheme.WindowsClassic | Colors of that strip: WindowsClassic, FolderTabs, ColorfulCards, Minimal or Dark; saved and restored the same way. |
| OnClose | EventCallback |  | The toolbar's Close button. Unset with ShowChrome on, the button is still there and does nothing. |
| OnPageTitleChanged | EventCallback<string> |  | Raised by ShowReportAsync with the report's file name without extension, for a host's title bar. |

### Methods

| Name | Type | Description |
|---|---|---|
| ShowXmlReport(string xmlFilePath, Dictionary<string, object>? parameters = null, bool positioned = false) | Task | Loads a Crystal XML export through CrystalXmlReportLoader, runs it with the given values and renders it; positioned keeps the band geometry. It does not record the file, so the toolbar's Parameters button does nothing after it. |
| ShowReportAsync(string file, IReadOnlyDictionary<string, string>? seedParameters = null) | Task | The unified load for an .rpt or .xml path: prompts for required parameters the seeds do not supply, raises OnPageTitleChanged, seeds a parameter named DivisionID from the session context, and treats seeds named Filter:Table.Field as field filters. What this page calls, with Package and Season as seeds; the toolbar's Parameters button reruns it without seeds, which opens the dialog. |
| ShowSqlReport(ReportDefinition definition, Dictionary<string, object>? parameterValues = null, …) | Task | Executes a definition built in code through IReportDataExecutor and renders it. Session parameters listed in ReportOptions are filled in when the SQL names them and the caller did not. |
| ShowDataTableReport(string title, DataTable data, ReportOrientation orientation = ReportOrientation.Portrait) | Task | Renders a table you already have as a report. |
| ShowCrystalReport(string rptFilePath, …) | Task | A native .rpt file: needs IReportExporter, which renders it to PDF for the viewer. Logs a warning and shows nothing without one. |
| ShowDesignerReport(ReportDesignerDocument document, Dictionary<string, object>? parameters = null) | Task | Runs a designer document as a snapshot, subreports included, without saving it. |
| ExportCrystalReport(string format) | Task<byte[]?> | The loaded .rpt as PDF, Excel, Word, RTF or CSV bytes through IReportExporter; null when none is registered. |
| Print() | Task | Opens the browser's print dialog for the rendered report. |
| Clear() | void | Clears the report and its tabs. |
| GoToPage(int pageNum) | void | Shows that page, 1-based, of the active tab. |
| SwitchTab(int tabIndex) | void | Makes that tab active. |
| CloseTab(int tabIndex) | void | Closes a drill-down tab; the main report at index 0 cannot be closed. |
| OpenDrillDown(FxGroupNode node, List<DrillDownFilter> fullPath) | Task | Opens, or switches to, a tab that re-queries with the node's path as an extra filter and shows the detail columns. |
| SetXmlSource(string xmlFilePath) | void | Tells the control which XML a definition came from, so drill-down tabs can re-parse it. Needed only before a direct ShowSqlReport. |

### State

| Name | Type | Default | Description |
|---|---|---|---|
| IsLoading | bool | false | True while a report is being loaded or run. |
| ReportLoaded | bool | false | True once a report has rendered. |
| StatusMessage | string | "Ready" | The text in the status area. |
| ErrorMessage | string? | null | The last failure, shown in place of the pages. |
| Tabs | List<ReportTab> | new() | Open tabs; index 0 is the main report, drill-downs follow. |
| ActiveTabIndex | int | 0 | The tab on display. |
| GroupTree | List<FxGroupNode> |  | The active tab's group tree. |
| DefinitionPostProcessor | Action<ReportDefinition>? | null | Settable. Runs on every definition the control builds for a drill-down tab, so a host repeats there what it did to the main definition. |

### Services

| Name | Type | Default | Description |
|---|---|---|---|
| IReportDataExecutor | DataTable Execute(string sql, IDictionary<string, object>? parameters) | required | Runs the SQL the loader builds and returns a DataTable. The host decides the data layer. |
| IReportSessionContext | object? Get(string parameterName) | required | Turns a session parameter name into a value, for the names listed in ReportOptions.SessionAutoInjectParameters. |
| IReportPickListProvider | GetPickList(ReportParameter) / GetPickList(string) / HasPickList(string) | required | Pick-list values for the parameter dialog, by ReportParameter (preferred, runs its PickListSql) or by name. EmptyReportPickListProvider ships for hosts without lists. |
| IReportViewerSettings | Task<int> GetZoomLevelAsync() / Task SetZoomLevelAsync(int) / Task<TabOrientation?> GetTabOrientationAsync() / Task SetTabOrientationAsync(TabOrientation) / Task<TabTheme?> GetTabThemeAsync() / Task SetTabThemeAsync(TabTheme) | required | Per-user zoom, tab orientation and tab theme persistence; InMemoryReportViewerSettings ships as the default, and the four tab methods are default interface methods, so older adapters still compile. |
| IReportExporter | LoadReport, SetParameters, ExportToPdf / ExportToExcel / ExportToWord / ExportToRtf / ExportToCsv | registered | A Crystal Reports engine for native .rpt files only. Blazor cannot inject a missing service, so a host without Crystal registers a no-op. |
| ReportOptions | class | singleton | Singleton settings: SchemaPrefix (default dbo), SessionAutoInjectParameters, MaxRowsPerReport (100,000; 0 is unlimited), EagerGroupColumnsInMainQuery. |

## Examples

### Report

```razor
@using Fx.ControlKit.Reports

<div class="report-frame">
    <ReportWriterControl @ref="_writer" />
</div>
```

```csharp
private ReportWriterControl? _writer;
private readonly string[] _packages = TripPackages.All.Select(p => p.Name).ToArray();
private readonly string[] _seasons = TripPackages.Seasons;
private string _package = TripPackages.All[0].Name;
private string _season = TripPackages.Seasons[0];
private bool _running;

protected override async Task OnAfterRenderAsync(bool firstRender)
{
    if (firstRender)
    {
        // Run on first paint so visitors land on a populated report.
        await RunReport();
    }
}

private async Task RunReport()
{
    if (_writer is null) return;
    _running = true;
    StateHasChanged();
    try
    {
        var path = Path.Combine(Env.WebRootPath, "reports", "Package Cost Sheet.xml");
        await _writer.ShowReportAsync(path, new Dictionary<string, string>
        {
            ["Package"] = _package,
            ["Season"] = _season,
        });
    }
    finally
    {
        _running = false;
        StateHasChanged();
    }
}
```

