How to Integrate PerpetuumSoft Viewers with SSRS — Step‑by‑StepThis guide walks through integrating PerpetuumSoft report viewers with Microsoft SQL Server Reporting Services (SSRS). It covers prerequisites, installation, configuration, embedding the viewer into a .NET application, configuring data sources and report handling, deployment tips, and troubleshooting common issues.
What are PerpetuumSoft Viewers and why use them with SSRS?
PerpetuumSoft Viewers are .NET UI controls and web components for rendering, navigating, and exporting reports created with various reporting engines. When paired with SSRS, these viewers can provide richer embedded viewing experiences, custom UI controls, additional export formats, and more flexible integration options than the default SSRS viewer.
Key benefits
- Customizable UI and embedding options
- Support for additional export formats and workflows
- Tighter control over rendering, interaction, and printing
Prerequisites
- A working SSRS instance (Native or SharePoint mode) and access to its report server.
- Visual Studio (2017/2019/2022) or another .NET development environment compatible with the target framework.
- .NET Framework / .NET Core version supported by PerpetuumSoft Viewers (check specific product docs for exact supported frameworks).
- PerpetuumSoft Viewers installer or NuGet package and valid license for deployment.
- Administrative access to the application project and IIS (if deploying a web app).
Step 1 — Install PerpetuumSoft Viewers
- Obtain the PerpetuumSoft Viewers package:
- Download the installer from PerpetuumSoft or get the appropriate NuGet packages for your project.
- Run the installer or add NuGet references:
- For WinForms/WPF apps: install the desktop viewer package(s).
- For ASP.NET MVC/WebForms/Core web apps: install the web viewer package.
- Add license key(s):
- If the product requires a license file or key, follow the vendor instructions to register it in development and production environments.
Notes:
- Confirm which assemblies (DLLs) your project needs (viewer UI, export engines, rendering engines).
- If using NuGet, ensure package versions match across projects (server and client components).
Step 2 — Plan integration approach
Decide which integration pattern fits your scenario:
- Embedded viewer in a desktop application (WinForms/WPF) that connects to SSRS.
- Embedded viewer in a web application (ASP.NET MVC, WebForms, or ASP.NET Core) that fetches reports from SSRS and renders them in-browser.
- A server-side rendering approach where your app requests rendered output (PDF, image, HTML) from SSRS and passes it to the PerpetuumSoft viewer or custom UI.
Choose based on:
- Deployment environment (desktop vs. web).
- Security model (how users authenticate to SSRS).
- Performance considerations (client-side interactivity vs. server-side rendering).
Step 3 — Configure SSRS access and security
- Confirm SSRS endpoint and mode:
- For native SSRS, note the Report Server Web Service URL (e.g., http://yourserver/reportserver).
- For SharePoint integrated mode, identify the SharePoint report library and access endpoint.
- Authentication:
- Use Windows Authentication, Basic, or custom tokens as appropriate.
- For web apps, configure the application pool or HTTP client to pass credentials to SSRS.
- For cross-domain scenarios, enable CORS or set up a server proxy to avoid client-side credential exposure.
- Permissions:
- Ensure the account used by the application has at least Browser permissions on the reports and folders it needs to access.
- Test connectivity by browsing the report server endpoint and previewing a report in the SSRS web portal.
Step 4 — Accessing SSRS reports programmatically
You can get reports from SSRS in a few ways:
A. Request raw RDL/RDLC files (if you maintain local copies) and let PerpetuumSoft render them.
B. Use SSRS Web Service (ReportExecution2005/ReportExecution2010 SOAP/REST API) to render reports server-side into formats (PDF, Excel, HTML, image) and stream them to the viewer.
C. Use SSRS URL access to get rendered output directly (for example, adding rs:Format=PDF to the report URL).
Example — calling SSRS REST rendering (conceptual):
- Authenticate to the SSRS REST API.
- POST or GET a render request for a given report and format.
- Receive binary output (PDF, HTML fragment, images) and feed it to your app/viewer.
Which to choose:
- Use server-side rendering (B/C) for reliable rendering and simpler security.
- Use RDL parsing and client-side rendering (A) for maximum interactivity if the viewer supports parsing RDL.
Step 5 — Integrate PerpetuumSoft viewer in a web app (ASP.NET example)
Below is a high-level pattern for an ASP.NET MVC/Core application that embeds a PerpetuumSoft web viewer and requests rendered reports from SSRS.
- Add the PerpetuumSoft viewer NuGet package and client scripts/styles to your project.
- Create a controller endpoint that acts as a proxy between the browser and SSRS:
- The endpoint authenticates with SSRS (using server-side credentials).
- Requests report rendering via SSRS REST or SOAP API (HTML or PDF recommended).
- Streams the output back to the browser or returns JSON containing resource URLs.
- On the client page, initialize the PerpetuumSoft viewer and point it to the controller endpoint or to the local report source (RDL) if using client rendering.
- Implement parameter passing:
- Pass report parameters from the web UI to the controller, then to SSRS render calls.
- Implement paging, export, and printing handlers via PerpetuumSoft viewer APIs so those actions call back to your server endpoints.
Minimal conceptual code flow (controller pseudocode):
GET /Reports/View?name=SalesByRegion¶ms=... validate request build SSRS render request with parameters call SSRS REST/SOAP to render HTML or PDF stream response back to client with proper content-type Client pseudocode:
initialize PerpetuumSoft viewer with source = "/Reports/View?name=SalesByRegion" viewer.load() Step 6 — Integrate in desktop apps (WinForms/WPF)
- Add PerpetuumSoft viewer control to your form/window.
- In code, create a report source:
- Option A: Provide local RDL/RDLC file and set data sources locally.
- Option B: Request rendered output from SSRS (PDF/HTML) and use the viewer’s document loading APIs to display it.
- Handle report parameters and refresh actions by calling SSRS render API and reloading the viewer.
Example WinForms flow:
- User selects a report and sets parameters.
- App HTTP-authenticates to SSRS and requests a rendered PDF or HTML.
- Viewer.LoadDocument(stream) displays the received report.
Step 7 — Handling data sources and parameters
- If your reports use shared SSRS data sources, you typically do not need to change them; SSRS will manage connections.
- If you want the application to supply data:
- Use local RDL/RDLC and set data sources programmatically before rendering.
- Or create a web service endpoint that SSRS can call (if using report server with custom data extensions or if reports use web service data sources).
- For parameters:
- Validate and sanitize user inputs.
- Map UI controls to SSRS parameter names and pass them in render requests.
- Consider default values and cascading parameter logic.
Step 8 — Exporting and printing
- Use PerpetuumSoft’s export features for client-side export if the viewer loaded the document.
- If server-side rendering is used, call SSRS render endpoint with rs:Format=PDF/EXCEL/IMAGE to get exports from SSRS, then stream those to the user.
- For printing:
- PerpetuumSoft viewers often provide print dialogs that either print client-side or send a print job to a server endpoint.
- For precise print fidelity, render to PDF server-side and send the PDF to client or print server.
Step 9 — Deployment considerations
- Include required PerpetuumSoft assemblies and license files in deployment packages.
- Ensure the production app can authenticate to SSRS (service account, managed identity, or credential store).
- Configure firewall and network rules to allow your app server to reach the SSRS endpoint.
- For web deployments, consider caching rendered pages or generated PDFs for expensive reports.
- Monitor memory/CPU when rendering large reports; server-side rendering can be resource-intensive.
Step 10 — Troubleshooting common issues
- Viewer shows blank page:
- Verify the app actually received report content (log response length and status).
- Check for JavaScript client errors (web viewer).
- Confirm content-type and encoding match what the viewer expects.
- Authentication failures:
- Test SSRS calls from the server using the same credentials.
- Ensure domain accounts and delegation (Kerberos) are correctly configured if needed.
- Parameter or data errors:
- Test the same report and parameters in the SSRS web portal to isolate whether the issue is SSRS-side or integration-side.
- Missing export features:
- Confirm required PerpetuumSoft export modules are installed and licensed.
- Performance problems:
- Paginate or limit report result size.
- Use server-side caching and schedule heavy reports during off-peak times.
Example: Basic ASP.NET Core controller to proxy SSRS PDF render
This is conceptual pseudocode; adapt to your SSRS URL, authentication, and PerpetuumSoft viewer initialization.
[HttpGet("Reports/RenderPdf")] public async Task<IActionResult> RenderPdf(string reportPath, string param1) { // Build SSRS render URL var ssrsUrl = $"http://ssrsserver/reportserver?/Reports{reportPath}¶m1={WebUtility.UrlEncode(param1)}&rs:Format=PDF"; // Use HttpClient with proper credentials (Windows auth may require special handling) var response = await httpClient.GetAsync(ssrsUrl); if (!response.IsSuccessStatusCode) return StatusCode((int)response.StatusCode); var bytes = await response.Content.ReadAsByteArrayAsync(); return File(bytes, "application/pdf", $"{Path.GetFileName(reportPath)}.pdf"); } Security checklist
- Do not expose SSRS admin endpoints to the public.
- Use server-side proxy endpoints rather than letting clients call SSRS directly when credentials are required.
- Validate and encode report parameter inputs.
- Protect license keys and assemblies in deployment pipelines.
Final notes
Integration complexity depends on whether you use client-side RDL rendering or server-side rendered outputs from SSRS. For most scenarios, the pragmatic approach is to let SSRS render PDFs/HTML server-side and have PerpetuumSoft viewers or your UI display those results, which simplifies authentication and guarantees rendering consistency. If you need deeper interactivity, use the viewer’s client rendering capabilities and ensure RDL compatibility and required PerpetuumSoft modules are present.
If you want, tell me which platform you’re targeting (ASP.NET Core, WinForms, WPF) and whether you prefer server-side or client-side rendering — I’ll provide a tailored code example and configuration steps.
Leave a Reply