devexpress/agent-skills/devexpress-reports-aspnetcore

DevExpress ASP.NET Core Reporting — Viewer & Designer Integration

Integrates the DevExpress Web Document Viewer (read-only preview) and Web Report Designer (full end-user designer) into ASP.NET Core MVC and Razor Pages applications. The viewer renders reports in the browser via server-side document generation; the designer lets end-users create and save reports without developer involvement.

When to Use This Skill

• Add a Document Viewer to an ASP.NET Core application
• Add an End-User Report Designer to an ASP.NET Core application
• Configure Program.cs services and middleware for reporting
• Register reporting client assets — via direct <script>/<link> tags (package.json + libman.json, the default for existing apps) or npm bundling (BuildBundlerMinifier + bundleconfig.json, for greenfield/demo projects)
• Implement ReportStorageWebExtension or IReportProvider
• Customize viewer/designer toolbar, tab panel, export options, parameter editors
• Configure security: authorization, CSRF protection, CSP nonce
• Deploy reporting to Linux or macOS (Skia renderer setup)
• Troubleshoot blank viewers, HTTP errors, or script loading failures
• Set up multi-server (web farm/garden) document storage

When Not to Use This Skill

• When you need to create reports programmatically (bands, controls, data binding, expressions, export) — use the devexpress-reports-core skill or the devexpress-visual-studio-rider-report-design skill and call a separate subagent instead.
• When you need to integrate reporting into non-ASP.NET Core applications (e.g., ASP.NET MVC, ASP.NET Web Forms, WinForms, WPF, Angular, React, Vue) — use the appropriate platform-specific skill.

Component Overview

Full controller and view code for both components: Step 6 and Step 9 of references/getting-started.md (MVC) / references/getting-started-razor-pages.md (Razor Pages).

The WebDocumentViewerController descendant is never optional. ReportDesignerController/QueryBuilderController are not startup-enforced — add each only when the Designer is on a page.

Which track is this task?

Answer this first — it decides how much of this file applies to you.

Every path ends at Phase 4 — Validate. It is the same contract for all three.

Integration track Workflow — Three Phases, then Verification

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

This file contains no copyable file templates, and no symptom→fix table. Everything here is orientation — decision rules and the API index. Every file you write is transcribed from a reference file (Phase 3 — Step 3.0); every defect you diagnose is looked up in references/troubleshooting.md. If you are about to type the contents of a .json, .cs, or .cshtml file and its source reference is not in your context, stop and read it, end to end.

• Phase 1 — Search the project and ask clarifying questions for any unknowns
• Phase 2 — Apply the decision gates to select the exact component and integration pattern, then load the reference files those decisions point to
• Phase 3 — Fill in the Step 3.0 source manifest, present the merged plan, then execute. Every file is transcribed from a reference file — never reconstructed from memory or general DevExpress knowledge. Adapt only names/namespaces after transcribing; never adapt structure, settings, or file lists from recall.
• Phase 4 — Verify against the served page and report the evidence, under the no-substitute rule defined there.

Phase 1 — Preflight: Gather Context (inspect, then clarify)

Before touching any file, resolve the items below. Use whichever source answers each item — the project files or the user's prompt — and only ask a question when neither source resolves it.

Inspection — resolve silently from the project and the prompt:

• Component: Document Viewer, End-User Report Designer, or standalone Parameters Panel? Infer from the user's stated goal (e.g., "add a viewer", "add designer", "collect parameters without a preview") or from existing controllers/views. Needing a component's infrastructure controller never implies adding its page.
• Client libraries (jQuery, Knockout, Bootstrap, DevExtreme): scan _Layout.cshtml, _ViewImports.cshtml, wwwroot/, bundleconfig.json, package.json, and libman.json for existing <script>/<link> tags, bundle entries, and package references. Note which libraries are present and at what version. Settle jQuery/Bootstrap with Test-Path wwwroot/lib/jquery, wwwroot/lib/bootstrap and record the branch it names — any True ⇒ App-supplied (register neither; keep the app's own tags), all False ⇒ npm-supplied (LibMan copies npm's). That one branch governs both the libman.json entries and the _Layout.cshtml tag paths in Phase 3.
• Client-resource mechanism — record these three facts and do not choose a pattern here; the Phase 2 table owns that choice and needs facts (a) and (b) as its inputs:
• (a) Bundler present? Is BuildBundlerMinifier/bundleconfig.json, or another bundler (webpack, gulp, etc.), already there? If yes, list its existing entries, their source paths, and their include order, and judge whether it could precisely absorb the new DevExpress entries — a candidate only; reusing it requires the developer's explicit permission (clarifying question 3 below).
• (b) Application code beyond a bare `dotnet new` scaffold? yes/no. "Yes" means any of: custom controllers/Razor Pages/domain models beyond the default HomeController+Views/Home, an edited _Layout.cshtml, feature areas, EF Core DbContext/migrations, committed feature history. A stock scaffold — default HomeController, Views/Home, untouched _Layout.cshtml, Models/ErrorViewModel.cs, nothing else — is no.
• (c) Conflicting site-wide tags: <script>/<link> tags in _Layout.cshtml that could duplicate what you are about to add.
• Report-related services: check Program.cs for existing IReportProvider and ReportStorageWebExtension registrations — the two conflict (see references/report-storage.md). If one already exists and suits the Component decided above, reuse it. If none exists, default from Component: Designer present ⇒ assume storage-backed (ReportStorageWebExtension, required for save/load); Viewer-only or Parameters Panel only ⇒ assume instance binding (new MyReport()) for quickstart. State this default assumption when reporting back — don't block on it. Either resolution binds to a report class — record whether one already exists (Grep for : XtraReport and for *.Designer.cs — search by content, anywhere in the tree; the folder is often not named Reports). If none does, Step 3.1 delegates it; do not plan to write it here.
• Page framework: MVC views (Views/), Razor Pages (Pages/), or both — from project structure or the prompt.
• `_ViewImports.cshtml` location: Glob for it (**/_ViewImports.cshtml) rather than assuming a path. In standard scaffolding it lives at Views/_ViewImports.cshtml (MVC) or Pages/_ViewImports.cshtml (Razor Pages). Record its actual path so Phase 3 edits the existing file rather than creating a second one. Same rule for every file named in the Step 3.0 manifest: locate it here, don't assume its path at write time.
• DevExpress package versions: record the version-pinning style of any existing DevExpress PackageReference in the .csproj (floating 26.1.* vs. fixed 26.1.3). Every package you add must match it — all floating or all fixed, never mixed. Carry the literal string into the Step 3.0 manifest.
• Target OS: treat the target as non-Windows if any of these say so — a Linux base image in a Dockerfile, a linux-*/osx-* <RuntimeIdentifier> in the .csproj, a non-Windows CI runner in .github/workflows/*.yml or azure-pipelines.yml. If no signal exists and the prompt doesn't say otherwise, default to Windows without asking. Non-Windows requires DevExpress.Drawing.Skia on the package list (the Skia drawing engine activates automatically — no Settings.DrawingEngine call needed); without it - DllNotFoundException at render. If there's a Dockerfile or other container image definition for the app, record whether it already installs the Linux font libraries (libc6, libicu-dev/libicu, libfontconfig1/fontconfig) — if not, Step 3.0 must add that install step to the image.
• Security posture: check Program.cs for AddAuthentication/AddAuthorization calls and which scheme they configure (cookies, JWT bearer, ASP.NET Core Identity, Azure AD/Entra ID); existing [Authorize]/[AllowAnonymous] attributes on controllers; antiforgery setup (AddAntiforgery(), [ValidateAntiForgeryToken], [IgnoreAntiforgeryToken], or a global AutoValidateAntiforgeryTokenAttribute filter); CSP middleware or manual Content-Security-Policy header code; and AddCors/UseCors policies. If a posture exists, apply the same one to the new reporting controllers (see references/security.md). If no signals exist, default to no additional authorization on the reporting controllers, but explicitly flag this in the report-back (e.g., "no existing auth setup found; reporting endpoints will be unauthenticated by default — say so if authorization is required") — this is a security-relevant default and must be stated, not silently applied.
• Startup side effects (Phase 4 step 3 runs the app): does Program.cs migrate/seed the database or start hosted services, and does the default connection string point outside a local dev instance? Record both.
• Navigation menu: search _Layout.cshtml and any partial nav views for the existing menu markup (e.g., <a class="nav-link" asp-controller="..." asp-action="..."> in MVC, asp-page="..." in Razor Pages). Record the file path, one example link's attributes/CSS classes/icon markup, and the route naming convention in use.
• Custom data source classes (only when the Component i