Troubleshooting Common Issues in Stimulsoft Reports Designer.Web (Performance & Rendering)

How to Integrate Stimulsoft Reports Designer.Web into ASP.NET Core ProjectsIntegrating Stimulsoft Reports Designer.Web into an ASP.NET Core project gives you a powerful, browser-based report designer that your users can use to create, edit, and preview reports without installing desktop software. This guide walks through planning, installation, server- and client-side setup, authentication and security considerations, data binding, exporting, deployment, and common troubleshooting tips.

Overview and prerequisites

Stimulsoft Reports Designer.Web is a web-based reporting designer component that works well with ASP.NET Core (both .NET Core and .NET 5/6/7/8+). Before you start, ensure you have:

Visual Studio ⁄₂₀₂₃ or VS Code with the .NET SDK installed.
Target framework: .NET 6 or later is recommended, but .NET Core 3.1+ can also work depending on the Stimulsoft version.
A Stimulsoft license (trial or full) and access to the Stimulsoft assemblies/resources for web.
Basic knowledge of ASP.NET Core middleware, static files, and routing.

1. Choose integration approach

You can integrate Designer.Web in one of two common ways:

Host the Stimulsoft JavaScript client and use Stimulsoft’s backend components for handling server-side operations (saving/loading reports, exporting, or rendering).
Use only the client-side designer and implement your own server APIs for persistence and data retrieval (more flexible; you handle security and business logic).

Most enterprise apps use a hybrid approach: Stimulsoft client plus lightweight server endpoints for file storage and dataset delivery.

2. Create the ASP.NET Core project

Create a new ASP.NET Core Web App (MVC or Razor Pages). Example CLI:
```
dotnet new mvc -n StimulsoftDemo cd StimulsoftDemo 
```
Add folders for client assets and reports:

wwwroot/stimulsoft (for Stimulsoft JS/CSS)
App_Data or a Reports folder (for saving .mrt report files)

3. Install Stimulsoft files

Stimulsoft provides NuGet packages and downloadable JS/CSS bundles. Common methods:

NuGet packages (server-side helpers):
- Stimulsoft.Reports (core)
- Stimulsoft.Reports.Web (server integrations)
  Use NuGet in Visual Studio or CLI:
```
dotnet add package Stimulsoft.Reports --version x.y.z dotnet add package Stimulsoft.Reports.Web --version x.y.z 
```
Client-side assets:
- Copy the Stimulsoft JavaScript and CSS bundles to wwwroot/stimulsoft. Typically these include:
  - stimulsoft.reports.desktop.office2013.white.js (or the modern web designer bundle)
  - stimulsoft.viewer.js, stimulsoft.designer.js (names depend on version)
  - necessary CSS and fonts

Check Stimulsoft docs for exact filenames for your version.

4. Configure Startup (Program.cs) for static assets and middleware

Ensure static files are enabled (default in web templates). If you use server-side rendering/export features, register any required services in Program.cs. Example for minimal Program.cs (.NET 6+):

var builder = WebApplication.CreateBuilder(args); builder.Services.AddControllersWithViews(); // If using Stimulsoft server components that require license initialization, // initialize them here (per Stimulsoft instructions). var app = builder.Build(); app.UseStaticFiles(); app.UseRouting(); app.UseAuthentication(); app.UseAuthorization(); app.MapDefaultControllerRoute(); app.Run();

Follow Stimulsoft docs if their server package requires specific initialization or stream implementations.

5. Add Designer page and client scripts

Create a page (e.g., Reports/Designer) and add the Stimulsoft designer initialization code. The client script initializes the designer, loads a report (or a template), and wires save/load/export endpoints.

Example Razor view (Reports/Designer.cshtml):

@{     Layout = "_Layout"; } <div id="designerHost"></div> <link href="~/stimulsoft/stimulsoft.designer.css" rel="stylesheet" /> <script src="~/stimulsoft/stimulsoft.reports.js"></script> <script src="~/stimulsoft/stimulsoft.designer.js"></script> <script>     // Initialize Stimulsoft license if required:     // Stimulsoft.Base.StiLicense.key = "YOUR_LICENSE_KEY";     // Create a designer instance     var options = new Stimulsoft.Designer.StiDesignerOptions();     var designer = new Stimulsoft.Designer.StiDesigner(options, 'StiDesigner', false);     designer.renderHtml('designerHost');     // Load a report from the server     fetch('/Reports/LoadReport?name=default.mrt')       .then(r => r.text())       .then(text => {           var report = new Stimulsoft.Report.StiReport();           report.load(text);           designer.report = report;       });     // Save report to the server     function saveReport() {       var report = designer.report;       var reportXml = report.saveToString();       fetch('/Reports/SaveReport', {         method: 'POST',         headers: {'Content-Type': 'application/json'},         body: JSON.stringify({name: 'default.mrt', content: reportXml})       }).then(r => { if (r.ok) alert('Saved'); });     }     // Optionally attach save button </script>

Adjust filenames and initialization calls to the exact API of your Stimulsoft version.

6. Implement server endpoints for load/save/export

Create a ReportsController with actions to read/write report files and, if desired, to render/export reports server-side.

Example controller (simplified):

using Microsoft.AspNetCore.Mvc; using System.IO; using System.Threading.Tasks; public class ReportsController : Controller {     private readonly string _reportsPath = Path.Combine(Directory.GetCurrentDirectory(), "Reports");     [HttpGet]     public IActionResult LoadReport(string name)     {         var file = Path.Combine(_reportsPath, name);         if (!System.IO.File.Exists(file)) return NotFound();         var content = System.IO.File.ReadAllText(file);         return Content(content, "text/xml");     }     [HttpPost]     public async Task<IActionResult> SaveReport([FromBody] SaveReportModel model)     {         var file = Path.Combine(_reportsPath, model.Name);         await System.IO.File.WriteAllTextAsync(file, model.Content);         return Ok();     }     public class SaveReportModel { public string Name { get; set; } public string Content { get; set; } } }

For exports (PDF, Excel), either:

Use Stimulsoft server-side rendering API to load the .mrt, register data, and export to a stream; return File(stream, mime).
Or perform client-side export in the browser.

If using Stimulsoft server APIs, ensure you register any datasets the report expects (DataSet/DataTable) before rendering.

7. Data binding and providing data to reports

Reports can use:

Built-in data sources embedded in the .mrt (static during design).
External data via registered DataSets or JSON at runtime.

Common patterns:

Provide REST endpoints that return JSON data; in the designer you can add data sources by URL.
On export, server loads the .mrt, creates a DataSet/DataTable from your database or API, calls report.RegData(…) and then report.Render(false) before exporting.

Example server-side:

var report = new Stimulsoft.Report.StiReport(); report.Load(reportFilePath); var dataSet = GetDataSetFromDatabase(); // your method report.RegData("MyData", dataSet); report.Render(false); var stream = new MemoryStream(); report.ExportDocument(Stimulsoft.Report.Export.StiExportFormat.Pdf, stream); stream.Position = 0; return File(stream, "application/pdf", "report.pdf");

8. Authentication, authorization, and security

Restrict designer access to authenticated users using [Authorize] or middleware.
Validate and sanitize uploaded .mrt files if users can upload reports.
Store reports in a secure location (not wwwroot); serve them through controller endpoints requiring authorization.
If client-side designer exposes server endpoints (save/load/export), protect those endpoints with CSRF tokens or require authenticated API calls and validate input sizes to avoid DOS.
Never expose internal connection strings or credentials within client-side code; register data on the server.

9. Licensing and initialization

Stimulsoft requires license initialization for commercial use. Typically you set the license key in JavaScript:

Stimulsoft.Base.StiLicense.key = "YOUR_LICENSE_KEY";

Or call server-side license initialization per their documentation. Always follow the license placement guidance to avoid watermarking.

10. Localization and theming

Designer.Web supports localization — include proper resource files and set the culture in the designer options.
Use available themes (Office2013, Modern) by including the corresponding CSS/JS bundles.

Example:

options.appearance = Stimulsoft.Designer.StiAppearance( /* theme options */ ); Stimulsoft.Base.StiOptions.WebDesigner.Theme = 'office2013.white';

11. Export options and client vs server rendering

Client-side export: faster, less server CPU; depends on JS capabilities and browser.
Server-side export: full control, can access server-side data, better for heavy exports or if you need to combine multiple data sources securely.

Choose based on load, data sensitivity, and performance needs.

12. Deployment considerations

Include all Stimulsoft static assets in your published wwwroot (JS/CSS/fonts).
Ensure file system permissions for the folder where reports are saved.
If running behind a reverse proxy, ensure proper routes and static file access.
Monitor memory/CPU if you do server-side rendering; consider queuing or background jobs for large batch exports.

13. Troubleshooting common issues

Blank designer or missing controls: confirm JS/CSS files are correctly referenced and loaded (check browser console).
Watermarks: usually means license key not set or invalid.
Data not appearing at preview: ensure data is registered with the exact name used in the report.
Export errors: inspect server logs; check that required assemblies are present and licenses initialized.

Example: Minimal end-to-end flow

Copy Stimulsoft JS/CSS to wwwroot/stimulsoft.
Add ReportsController with LoadReport and SaveReport endpoints (authorized).
Create Reports/Designer view and initialize the designer, loading a template via /Reports/LoadReport.
Implement Save button that POSTs to /Reports/SaveReport.
For exports, call a server action that loads the .mrt, registers data from DB, renders, and returns File(…) PDF/Excel.

Further resources

Stimulsoft official documentation and API reference for the exact method names and file bundles for your version.
ASP.NET Core docs on static files, authentication, and secure file handling.

If you want, I can: provide a copy-paste starter project (Program.cs, ReportsController, cshtml) tailored to a specific .NET version and Stimulsoft release — tell me your target .NET version and whether you prefer client- or server-side exporting.