devexpress/agent-skills/devexpress-reports-blazor

DevExpress Blazor Reporting — Viewer & Designer Integration

Integrates DevExpress report viewing and designing into Blazor applications. Five components across three families cover every Blazor hosting model.

This skill covers Blazor UI component integration only. For creating reports programmatically (bands, controls, data binding, export), use the devexpress-reports-core skill.

Skill boundary — hard stop: This skill does NOT generate XtraReport subclasses, band declarations (DetailBand, GroupHeaderBand), or control code (XRLabel, XRTable, etc.). If a report class is needed, switch to devexpress-reports-core for that part, get the class name or instance, then return here to wire it into the viewer.

Agent Workflow — Three Required Phases

Do not write any code until all three phases are complete. This ensures you load the correct reference files and generate a single coherent step-by-step plan.

• Phase 1 — Search the project and ask clarifying questions for any unknowns
• Phase 2 — Apply the decision gates to select the exact component and architecture
• Phase 3 — Load the matching reference files, merge their steps, present the plan, then execute

Phase 1 — Preflight: Gather Context

Step 1 — Automated Discovery (Do Before Asking Anything)

Run these searches in the project before asking the developer:

1. Installed packages: dotnet list package → look for DevExpress.Blazor.Reporting.* and their versions
2. Blazor configuration classification — follow this 4-step algorithm and record the result before selecting any component:

Step A — Solution structure: Find all .csproj files. Is there a .Client project (name suffix or a <ProjectReference> from a server project pointing to a client project)?

Step B — Server `Program.cs` (look for AddRazorComponents call chain):

Step C — Client `Program.cs`: presence of WebAssemblyHostBuilder.CreateDefault(args) confirms a WASM client project. If this file exists without a server Program.cs that calls MapRazorComponents → Interactive WebAssembly Standalone.

Step D — `@rendermode` in `.razor` files (search App.razor, Routes.razor, all @page components):

> Key rule: Both AddInteractiveServerComponents() + AddInteractiveWebAssemblyComponents() in Program.cs does not alone mean Auto mode. Final classification uses the @rendermode directives actually present in components.

Final result — record one of: Static | Interactive Server | Interactive WebAssembly Standalone | Interactive WebAssembly (Client + Server) | Interactive Auto. If ambiguous, ask the user for the Visual Studio template name or the dotnet new command used to create the project.

1. Existing viewer/designer components: search all .razor files for <DxReportViewer, <DxDocumentViewer, <DxReportDesigner, <DxWasmDocumentViewer, <DxWasmReportDesigner — note component names and file locations
2. Report sources and name resolution: search for new XtraReport(), IReportProvider, IReportProviderAsync, ReportStorageWebExtension, OpenReportAsync, Report="@, ReportName=", XtraReport loading methods (FromXmlStream, LoadLayoutFromXml, etc.) calls.
3. Data and connection strings: search appsettings.json for connection strings; search .cs files for custom data record classes used as report data sources
4. Navigation menu structure:

• Search for navigation components: NavMenu.razor, NavBar.razor, or any .razor file with <NavLink> tags
• Typical location: Components/, Layouts/, or root
• Record the exact file path and one example <NavLink> element (copy its attributes, CSS classes, icon structure)
• Identify the pattern: flat list vs. grouped categories
• Record the route naming convention used (e.g., /viewer, /reports, /designer)

1. (Custom data source discovery) — only if a document viewer with storage or a designer component is found or requested:

• Search report class files for [DataSource], ObjectDataSource, List<T>, IList properties
• Extract class names used as data sources (e.g., SalesData, ProductRecord)
• Record which classes need trust registration (see Phase 2 Decision Gate F)

Record findings. Use them to answer questions below without prompting the developer.

After Discovery: New Component Evaluation

Apply this evaluation immediately after completing items 1–5 above — before asking any clarifying questions.

Using the results from item 3 above, determine:

If existing reporting components were found (item 3) AND the user is requesting a new component (different from what is already there):

1. Record the new component name explicitly — e.g., "User is adding DxReportDesigner; project already has DxReportViewer + DxWasmDocumentViewer"
2. Do NOT assume the existing setup applies — each component has distinct requirements. For example:

• Report Viewer: no controllers required
• Document Viewers: 1 controller (WebDocumentViewerController)
• Designers: 3 controllers (WebDocumentViewerController + ReportDesignerController + QueryBuilderController)
• Different component families require different AddDevExpress*() registrations

1. Run the rest of Phase 1–3 for the new component alone, as if it were a first integration — then merge with the existing setup only at Phase 3 Step 2
2. At Phase 3 merge: check for conflicts with existing setup (see anti-pattern checks C20–C23)
3. Extract the page route from the new page's @page directive (e.g., @page "/reports/viewer") — use this for the navigation link in Phase 3 Step 3B

If no existing components were found, or the user is adding the same component type again: proceed normally.

Step 2 — Clarifying Questions (Ask Only for Unknowns)

Ask only for items that automated discovery could not determine. Combine unresolved items into one message — do not ask one question at a time.

Q1 Script — Ambiguous Blazor Configuration

When Phase 1 Step 1 item 2 (4-step classification algorithm) cannot determine the hosting mode unambiguously, ask the developer directly to identify their target configuration and the project for component integration:

"I couldn't auto-detect your Blazor configuration. Which hosting model applies?

Static / Interactive Server / Interactive WebAssembly Standalone / Interactive WebAssembly (Client + Server) / Interactive Auto

For multi-project options (Client + Server or Auto): should the viewer/designer page go in the Server or Client project?"

Use the developer's responses to immediately confirm the hosting mode and target project, bypassing the need for further investigation.

Q2 Script — Viewer Ambiguity

When the user requests "a report viewer" without naming a component, present this choice explicitly:

"There are two viewer options — which fits your needs?

- Native Blazor Viewer (DxReportViewer) — pure C# customization, no JavaScript required, works on Blazor Server and WebAssembly

- JS-Based Document Viewer (DxDocumentViewer / DxWasmDocumentViewer) — JavaScript callbacks, mobile-friendly, includes rich export panel, requires MVC middleware

Which would you like?"

Q3 Script — No Reports Found in Project

When no report class, IReportProvider, or ReportStorageWebExtension is found:

"No reports were found in the project. How would you like to provide one?

1. Create a new sample report — I'll use the devexpress-reports-core skill to generate a report class

2. Use an existing `.repx` file — point me to it and I'll wire it in via a report storage or provider

3. Implement a report provider — I'll create the report myself"

If the developer chooses option 1: immediately load the `devexpress-reports-core` skill (or launch a subagent using that skill if the environment supports runSubagent). Confirm the generated report class name with the developer before proceeding with viewer integration. Do not proceed until a report class name is available.

Q4 Script — Target Project for New Page in Multi-Project Solutions

When the user requests a new page to be added to the project and the configuration is Interactive WebAssembly (Client + Server) or Interactive Auto, confirm the target project. Use the automatic assignment table from Decision Gate D if the component family is already known, or ask explicitly:

"Your project has a server project ([ServerProjectName]) and a client project ([ClientProjectName]). Which project should receive the new viewer/designer page?

- Server project — for DxWasmDocumentViewer, DxWasmReportDesigner, DxReportViewer (not available in Interactive Auto) or if you prefer server-side report processing

- Client project — for DxDocumentViewer, DxReportDesigner, DxReportViewer (not available in Interactive Auto) or if you prefer client-side WASM execution"

If the component is already determined (e.g., user explicitly said "DxDocumentViewer"), use the automatic assignment from Decision Gate D and confirm:

"For DxDocumentViewer in Interactive WebAssembly mode, the page belongs in [ClientProjectName]. Proceed?"

Phase 2 — Component and Architecture Selection

Decision Gate 0 — Blazor Configuration × Component Compatibility (Mandatory First Step)

Use the Blazor configuration result from Phase 1, Step 1 item 2. Before selecting any component, apply the matrix below to filter the valid options.

Hosting Mode × Component Compatibility