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

   What is found	Preliminary result
   AddRazorComponents() with no AddInteractiveServerComponents() or AddInteractiveWebAssemblyComponents()	→ Static
   AddInteractiveServerComponents() only	→ Interactive Server
   AddInteractiveWebAssemblyComponents() only	→ Interactive WebAssembly (Client + Server)
   Both AddInteractiveServerComponents() + AddInteractiveWebAssemblyComponents()	→ Auto candidate; confirm in Step D

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

   Directive / parameter	Indicates
   @rendermode InteractiveServer	Interactive Server
   @rendermode InteractiveWebAssembly	Interactive WebAssembly
   @rendermode InteractiveAuto or new InteractiveAutoRenderMode(...)	Interactive Auto
   No directives and no AddInteractive* in Program.cs	Static

   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.

3. Existing viewer/designer components: search all .razor files for <DxReportViewer, <DxDocumentViewer, <DxReportDesigner, <DxWasmDocumentViewer, <DxWasmReportDesigner — note component names and file locations

4. Report sources and name resolution: search for new XtraReport(), IReportProvider, IReportProviderAsync, ReportStorageWebExtension, OpenReportAsync, Report="@, ReportName=", XtraReport loading methods (FromXmlStream, LoadLayoutFromXml, etc.) calls.

5. Data and connection strings: search appsettings.json for connection strings; search .cs files for custom data record classes used as report data sources

6. 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)

7. (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
3. 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
4. At Phase 3 merge: check for conflicts with existing setup (see anti-pattern checks C20–C23)
5. 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.

#	What to resolve	Ask when
Q1	Blazor configuration classification: Static / Interactive Server / WASM Standalone / WASM Client+Server / Interactive Auto?	Phase 1 Step 1 item 2 result is ambiguous; apply Q1 script below
Q2	Component needed: Native Viewer or JS-based Viewer?	User said "viewer" without specifying; apply Q2 script below
Q3	Report source: existing report class, by name via a service, or a new sample report is needed?	No report class, IReportProvider, or ReportStorageWebExtension found in project; apply Q3 script below
Q4	Target project for new page: In multi-project WASM setups, which project should receive the new page — server or client? Also needed for Phase 3 Step 3B navigation link addition.	User requested a new page in a multi-project solution (WASM Client+Server or Interactive Auto); apply Q4 script below

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

Component	Static	Interactive Server	WASM Standalone	WASM Client+Server	Interactive Auto
DxReportViewer	❌	✅	✅	✅	❌ not supported
DxDocumentViewer	❌	✅ (server)	✅	✅ .Client project only	✅ .Client project only
DxReportDesigner	❌	✅ (server)	✅	✅ .Client project only	✅ .Client project only
DxWasmDocumentViewer	❌	❌	❌	✅ server project only	✅ server project only
DxWasmReportDesigner	❌	❌	❌	✅ server project only	✅ server project only

If Static: No DevExpress reporting component works in static render mode. Explain the limitation and suggest enabling Interactive Server mode (AddInteractiveServerComponents() + @rendermode InteractiveServer on the page).

If DxReportViewer + Interactive Auto: Incompatible combination. Explain the limitation and offer DxDocumentViewer (in .Client) or DxReportDesigner (in .Client) as alternatives. Do not proceed with DxReportViewer integration.

If Interactive WebAssembly (Client + Server) or Interactive Auto: After selecting the component, proceed to Decision Gate D to confirm the target project before writing any code.

---

Component Family Overview

	DxReportViewer	DxDocumentViewer	DxReportDesigner	DxWasmDocumentViewer	DxWasmReportDesigner
Type	Native Blazor	JS-based	JS-based	JS-based (WASM)	JS-based (WASM)
Purpose	Viewer	Viewer	Designer + embedded Viewer	Viewer	Designer + embedded Viewer
Render mode	Server or WebAssembly	Server or Standalone WASM	Server or Standalone WASM	WebAssembly only	WebAssembly only
Customization	C# callbacks	JavaScript callbacks	JavaScript callbacks	JavaScript callbacks	JavaScript callbacks
Requires MVC controllers	No	Yes	Yes	Yes	Yes
NuGet	Blazor.Reporting.Viewer	JSBasedControls + AspNetCore.Reporting	Server: same as Viewer; WASM: JSBasedControls + Skia	Client: JSBasedControls.WebAssembly	same as DxWasmDocumentViewer

Do not mix API families. OnCustomizeToolbar/ExportModel are C# and work only on DxReportViewer. CustomizeMenuActions/CustomizeExportOptions are JavaScript callbacks and work only on JS-based components. Crossing families causes silent failures or undefined errors.

Decision Gate A — User Need → Component

User need	Component
View reports with C# customization	DxReportViewer (native)
View reports with JavaScript events / mobile support	DxDocumentViewer (or DxWasmDocumentViewer)
End-user report design and saving with an embedded viewer	DxReportDesigner (or DxWasmReportDesigner)
Design and view reports on separate pages	DxDocumentViewer (or DxWasmDocumentViewer) + DxReportDesigner (or DxWasmReportDesigner)

Decision Gate B — Hosting Model → JS-Based Viewer Architecture

Blazor hosting model	Component	Target project	Reference
Interactive Server (single project, SignalR)	DxDocumentViewer	Server	📄 references/getting-started-js-viewer-server.md
Standalone WebAssembly (no backend)	DxDocumentViewer	Only project	📄 references/getting-started-js-viewer-standalone-wasm.md
Interactive WebAssembly (Client + Server)	DxWasmDocumentViewer	Server project	📄 references/getting-started-js-viewer-interactive-wasm.md
Interactive Auto	DxDocumentViewer in .Client; or DxWasmDocumentViewer on server — see Decision Gate D	See Gate D	Same as Interactive WebAssembly (Client + Server): 📄 references/getting-started-js-viewer-interactive-wasm.md

Decision Gate C — Hosting Model → JS-Based Designer Architecture

Blazor hosting model	Component	Target project	Reference
Interactive Server (single project, SignalR)	DxReportDesigner	Server	📄 references/getting-started-js-designer-server.md
Standalone WebAssembly (no backend; Skia runs in browser)	DxReportDesigner	Only project	📄 references/getting-started-js-designer-standalone-wasm.md
Interactive WebAssembly (Client + Server)	DxWasmReportDesigner	Server project	📄 references/getting-started-js-designer-interactive-wasm.md
Interactive Auto	DxReportDesigner in .Client; or DxWasmReportDesigner on server — see Decision Gate D	See Gate D	Same as Interactive WebAssembly (Client + Server): 📄 references/getting-started-js-designer-interactive-wasm.md

Decision Gate D — Target Project in Multi-Project Solutions

Apply this gate when the configuration is Interactive WebAssembly (Client + Server) or Interactive Auto and a component has been selected.

Automatic assignment (propose and confirm — no open question needed)

Component	Target project for .razor page	Service registration	Reason
DxDocumentViewer	.Client project	.Client Program.cs	Must execute in the browser WASM context
DxReportDesigner	.Client project	.Client Program.cs	Must execute in the browser WASM context
DxWasmDocumentViewer	.Client project	Server Program.cs	Component runs in browser (.Client); backend services and HTTP endpoints on server
DxWasmReportDesigner	.Client project	Server Program.cs	Component runs in browser (.Client); backend services and HTTP endpoints on server

For automatically assigned cases, present a confirmation before proceeding:

For DxDocumentViewer or DxReportDesigner:

"For DxDocumentViewer / DxReportDesigner in Interactive WebAssembly / Auto mode, the component and its service registration go in [ClientProjectName]. Proceed?"

For DxWasmDocumentViewer or DxWasmReportDesigner:

"For DxWasmDocumentViewer / DxWasmReportDesigner in Interactive WebAssembly / Auto mode, the .razor page goes in [ClientProjectName] (component runs in the browser), but service registration and controllers go in the server Program.cs. Proceed?"

When the target project is ambiguous

If the user's project structure or component choice does not map unambiguously to the table above, ask:

"Detected [configuration type] with two projects:

• Server: [ServerProjectName]
• Client: [ClientProjectName]

[ComponentName] can be added to [server / client / either] project. Which project should receive the component?" ``

---

Decision Gate F — Custom Data Source Mapping for Deserialization

Apply when a designer component is selected, OR a viewer component with ReportStorageWebExtension is being used.

Purpose: Identify custom data source classes needing trust registration for report deserialization (both designer save/load/preview and viewer storage access).

When to apply: (DxReportDesigner / DxWasmReportDesigner / DxDocumentViewer / DxWasmDocumentViewer with ReportStorageWebExtension) is being added AND Phase 1 Step 1 item 7 found custom data source classes.

Quick check:

1. List data source classes from Phase 1 item 7 discovery
2. For each: custom class? Used in reports? Both type and array variant needed?
3. Record decision: "Classes needing trust: [list]"

Why: Unregistered custom types cause NonTrustedTypeDeserializationException at runtime when:

• Designer components save/load/preview reports containing custom data sources
• Viewer components load reports from storage (ReportStorageWebExtension or IReportProvider returning REPX)

See 📄 references/resolving-report-names.md — Data Source Trust Registration for mapping details and registration procedures.

Integration output rules for multi-project solutions

Every generated integration must:

• Register services in the correct Program.cs (server or client, per the matrix above)
• Place the .razor page or component file in the correct project
• Include the correct @rendermode directive (or note that it is inherited from a global setting)
• Add a comment explaining why each file is placed in that specific project

---

Phase 3 — Reference Loading, Validation, and Execution

After resolving Phases 1 and 2, follow all four steps below in order. Do not skip to step 4.

Step 1 — Load Reference Files

Load every file listed for your scenario. Read all of them before drafting anything.

Scenario A — Native Viewer (DxReportViewer)

1. Load 📄 references/getting-started-native-viewer.md
2. Load 📄 references/resolving-report-names.md — if using IReportProvider or if no report source was found in the project
3. Load 📄 references/customizing-native-viewer.md — if toolbar, export formats, zoom, or parameter editor customization was requested

Scenario B — JS-Based Viewer (DxDocumentViewer / DxWasmDocumentViewer)

1. From Decision Gate B, load the matching getting-started file (server / standalone-wasm / interactive-wasm — file names use -interactive-wasm suffix)
2. Load 📄 references/resolving-report-names.md — always; the viewer requires a name resolution service to load reports by string name
3. Load 📄 references/customizing-js-viewer.md — if toolbar commands, export filtering, panel visibility, or client-side events were requested

Scenario C — JS-Based Designer (DxReportDesigner / DxWasmReportDesigner)

1. From Decision Gate C, load the matching getting-started file (server / standalone-wasm / interactive-wasm — file names use -interactive-wasm suffix)
2. Load 📄 references/resolving-report-names.md — always; the designer always requires ReportStorageWebExtension (or IReportProviderAsync for standalone WASM)
3. Load 📄 references/customizing-js-designer.md — if wizard customization, toolbar, panels, or lifecycle event callbacks were requested

Mixed Scenario — Viewer + Designer in the Same Project

Load reference files for both scenarios. Identify shared setup steps (Program.cs service registration, App.razor scripts, _Imports.razor) and deduplicate them in the merged plan.

⚠ Service conflict check: If both DxReportViewer (native) and DxReportDesigner (JS-based) exist in the same project, check for an IReportProvider + ReportStorageWebExtension conflict before proceeding. See Constraint 16 and 📄 references/resolving-report-names.md.

Step 2 — Draft the Merged Plan

Merge all loaded steps into a single numbered plan ordered by execution sequence. Deduplicate shared setup steps (Program.cs, App.razor, _Imports.razor). Do not present or execute yet.

Step 3A — Anti-Pattern Gate (Mandatory Before Presenting the Plan)

Before presenting the plan to the developer, review every step of the draft against this checklist. If any item is violated, fix the draft first.

Universal checks — apply regardless of scenario: