Progress® Telerik® Reporting R3 2017

How to: Set ReportSource for Report Viewers

This article includes details how to specify the report that will be displayed by a Report Viewer. You will need a Report Source object.

Reports are processed and rendered only server-side on a Windows OS machine due to the usage of GDI+ methods. Report Viewers load the processed and rendered reports, where the rendering format depends on the type of the viewer. To request a report to be processed and rendered, it should be wrapped in a Report Source object. Settings vary per type of work of Report Viewers:

For ReportViewer controls working directly with Telerik Reporting Engine

These are viewers operating on the machine where reports are processed rendered, and they include mechanisms for resolving reports:

Each of these viewer controls has a ReportSource property of type Telerik.Reporting.ReportSource, which can be set to an instance of one of the available Report Sources.

The specified report is processed locally on the same machine where the ReportViewer control is running.

  • Set the Report Source through the Visual Studio Designer

    1. In VS Design view, right-click a report viewer to which you want to set a report source and select Properties.

    2. In its Properties, find and click ReportSource.

    3. A "Load a Report from" dialog appears which allows you to select a ReportSource.

    4. Select the type of the report source you would use and specify a report. For this example we would use a UriReportSource, click 'URL or file' option and select the report that would be shown in the viewer.

      If you have to specify parameters for the report, continue with the next step.

    5. Click Edit Parameters button - Edit Parameters dialog appears. Click New. In the Parameter Name column select the name of a report parameter in the report. In the Parameter Value, type or select the value to pass to the parameter in the report.

  • Set the Report Source programmatically

    var uriReportSource = new Telerik.Reporting.UriReportSource();
    
    // Specifying an URL or a file path
    uriReportSource.Uri = "SampleReport.trdp";
    
    // Adding the initial parameter values
    uriReportSource.Parameters.Add(new Telerik.Reporting.Parameter("OrderNumber", "SO43659"));

For Report Viewers operating via Telerik Reporting Services

The following Report Viewers are designed to work as clients of Telerik Reporting Services:

  • Silverlight ReportViewer (go to section link)

  • HTML5 Report Viewer (go to section link)

  • HTML5 ASP.NET MVC ReportViewer (go to section link)

  • HTML5 ASP.NET WebForms ReportViewer (go to section link)

  • WinForms ReportViewer (go to section link)

  • WPF ReportViewer (go to section link)

These Report Viewers do not have direct access to Telerik Reporting Engine. Reports are processed and rendered on a remote machine, and the content is delivered to the client by the corresponding Telerik Reporting Service.

How this works:

  1. The Report Viewer has a client-side ReportSource which describes the report we want to display (report description string and client parameters).

    The report description string's content should be considered with technology limitations in the size of sent messages and in the used characters. The client parameters must match by names (case sensitive) the report parameters;

  2. The Report Viewer, as a client sends, the report description string to the server, where the content is handled by the corresponding Telerik Reporting Service's Resolver. The purpose of the Resolver is to create a valid server-side Report Source.

    Important note Important

    The default resolvers used by Telerik Reporting Services can produce TypeReportSource and UriReportSource on the server (Report Sources). Each Telerik Reporting Service provides mechanism for plugging a custom resolver allowing you to create and return any of the availble Report Sources, see links at the bottom of the article. The reports' assembly or TRDX|TRDP files must be accessible on the server where the Reporting Service and Telerik Reporting Engine are running.

  3. The Report Viewer, as a client sends, the client parameters to the server. The Reporting Service applies the values on the generated in memory server-side Report Source's Parameters collection.

  4. After the Reporting Service resolves the report description string and client parameters, the Reporting Engine processes the document on the server. The Reporting Service finally returns:

    • Information about Visible parameters: The Report Viewer displays its Parameters Area and corresponding parameters editors;

    • The processed and rendered report. The rendering format depends on the viewer e.g. XAML for WPF and Silverlight ReportViewers and HTML for the HTML5 Viewer, or on the operation - export/print;

    • Information about Document Map: The Report Viewer displays its DocumentMap Area.

Setting the Client-Side ReportSource:

  • Silverlight ReportViewer control

    The Silverlight ReportViewer control has a ReportViewerReport property , which accepts a string. This is the report description string.

    The string can be a path to a TRDP or TRDX file or an assembly qualified name of a report class. For example:(Report="./DashboardReport.trdp") or (Report="Telerik.Reporting.Examples.CSharp.BarcodesReport, CSharp.ReportLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"). The string is sent to the Telerik Reporting WCF service which internally resolves it to a TypeReportSource or a UriReportSource on the machine where the service and Telerik Reporting Engine are running.

    Report parameters' values sent by the Silverlight ReportViewer are client parameters. Report parameters' values can be sent throught the viewer's Parameters Area, in code by overriding the Silverlight ReportViewer control's OnApplyParameters method or by subscribing to the ApplyParameters event.

    Tip Tip

    The Silverlight ReportViewer control works only with Telerik Reporting WCF service instances. If you need to modify a report or execute custom logic on displaying a report resulting in the usage of an InstanceReportSource or XmlReportSource, you will have to resolve manually the report description string via custom resolver for the Reporting WCF service. For more details, check How to: Implement and use custom IReportResolver.

  • HTML5 Report Viewer(JavaScript declaration)

    The HTML5 Viewer is a client-side widget which has a client-side reportSource . The reportSource.report part is a string - the report description string, that can be a path to a TRDP or TRDX file, an assembly qualified name of a report class, or other custom information set via string. For example:

    HTML
    reportSource: { 
          report: "Dashboard.trdp",
          parameters: { CultureID: "en" }
                  }

    or

    HTML
    reportSource: { 
          report: "Telerik.Reporting.Examples.CSharp.ProductCatalog, CSharp.ReportLibrary",
          parameters: { CultureID: "en" }
                  }

    The report description string is sent to the Telerik Reporting REST service which internally resolves it to a TypeReportSource or a UriReportSource on the machine where the service and Telerik Reporting Engine are running.

    The reportSource.parameters part is a collection of key-value pairs - the client parameters. Report parameters' values can be sent throught the viewer's Parameters Area or on creating the HTML5 Viewer object in JavaScript.

    To display another report or to update the client parameters' values of the current HTML5 Viewer object, you can update the HTML5 Viewer's reportSource by using the viewer object's reportSource(rs) method in JavaScript. Or you can recreate the HTML5 Report Viewer.

    Tip Tip

    The HTML5 Report Viewer works only with Telerik Reporting REST service instances or Telerik Report Server (How To: Use HTML5 Report Viewer with Report Server). If you need an InstanceReportSource or XmlReportSource, you will have to resolve manually the report description string via custom resolver for the Reporting REST service. For more details, check REST Service Report Resolver (available only if using a Telerik Reporting REST service instance).

  • HTML5 ASP.NET MVC ReportViewer

    The HTML5 ASP.NET MVC Viewer is an MVC wrapper of the HTML5 Viewer that renders a string on the page. The string contains the HTML elements and the JavaScript methods required for initializing the HTML5 Viewer JavaScript widget.

    The HTML5 ASP.NET MVC Viewer has a ReportSource method, creating a client-side report source via server-side code (C# or VB.NET):

    • ReportSource(UriReportSource uriReportSource) - the report description string is obtained from the UriReportSource.Uri property, and the client parameters from the UriReportSource.Parameters collection.

    • ReportSource(TypeReportSource typeReportSource) - the report description string is obtained from the TypeReportSource.TypeName property, and the client parameters from the TypeReportSource.Parameters collection.

    • ReportSource(string report) - The report description string is obtained from the ReportSource method's string report argument. No client parameters can be set.

    • ReportSource(string report, IDictionary<string, object> parameters) - The report description string is obtained from the ReportSource method's string report argument. The client parameters can be set through the ReportSource method's IDictionary parameters argument.

    Example:

    @{
        var typeReportSource = new TypeReportSource() { TypeName = typeof(Invoice).AssemblyQualifiedName };
        typeReportSource.Parameters.Add("OrderNumber", Model.SelectedInvoice);
    }
    
    @(
        Html.TelerikReporting().ReportViewer()
            .Id("reportViewer1")
            .ServiceUrl("/api/reports/")
            .TemplateUrl("/ReportViewer/templates/telerikReportViewerTemplate.html")
            .ReportSource(typeReportSource)
            .ViewMode(ViewMode.Interactive)
            .ScaleMode(ScaleMode.Specific)
            .Scale(1.0)
    )

    To display another report or to update the client parameters' values of the current HTML5 Viewer object, you can update the HTML5 Viewer's reportSource by using the viewer object's reportSource(rs) method in JavaScript. Or you can recreate the HTML5 ASP.NET MVC ReportViewer.

    Tip Tip

    The HTML5 ASP.NET MVC ReportViewer works only with Telerik Reporting REST service instances or Telerik Report Server (How To: Use HTML5 Report Viewer with Report Server). If you need an InstanceReportSource or XmlReportSource, you will have to resolve manually the report description string via custom resolver for the Reporting REST service. For more details, check REST Service Report Resolver (available only if using a Telerik Reporting REST service instance).

  • HTML5 ASP.NET WebForms ReportViewer

    The HTML5 ASP.NET WebForms ReportViewer control is a server-side wrapper of the HTML5 Viewer, suitable for ASP.NET WebForms applications.The control renders the HTML elements and the JavaScript methods required for initializing the HTML5 Viewer JavaScript widget.

    The ReportSource property of the HTML5 ASP.NET WebForms ReportViewer control is of type Telerik.ReportViewer.Html5.WebForms.ReportSource:

    Example of setting the client-side ReportSource in code-behind:

    var clientReportSource = new Telerik.ReportViewer.Html5.WebForms.ReportSource();
    clientReportSource.IdentifierType = IdentifierType.TypeReportSource;
    clientReportSource.Identifier = typeof(ReportCatalog).AssemblyQualifiedName;//or <namespace>.<class>, <assembly> e.g. "MyReports.Report1, MyReportsLibrary"
    clientReportSource.Parameters.Add("Parameter1", 123);
    reportViewer1.ReportSource = clientReportSource;

    Example of setting the client-side ReportSource via mark-up:

    1. Open the ASPX with the HTML5 WebForms ReportViewer.

    2. Select the HTML5 WebForms ReportViewer and navigate to its Reportsource property in Visual Studio Property grid.

    3. A "Load a Report from" dialog appears which allows you to select a ReportSource.

    4. Select the type of the report source you would use and specify a report. For this example we will use a TypeReportSource, click 'Type name' option and select the report that would be shown in the viewer.

      If you have to specify parameters for the report, continue with the next step.

    5. Click Edit Parameters button - Edit Parameters dialog appears. Click New. In the Parameter Name column select the name of a report parameter in the report. In the Parameter Value, type or select the value to pass to the parameter in the report.

    HTML
    <form runat="server">
        <telerik:ReportViewer Width="" Height=""
            ID="reportViewer1"
            runat="server">
            <ReportSource 
                IdentifierType="TypeReportSource" 
                Identifier="Telerik.Reporting.Examples.CSharp.ReportCatalog, CSharp.ReportLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null">
                <Parameters>
                    <telerik:Parameter Name="Parameter1" Value="123" />
                </Parameters>
            </ReportSource>
        </telerik:ReportViewer>
    </form>

    To display another report or to update the client parameters' values of the current HTML5 Viewer object, you can update the HTML5 Viewer's reportSource by using the viewer object's reportSource(rs) method in JavaScript. Or you can recreate the HTML5 WebForms ReportViewer.

    Tip Tip

    The HTML5 WebForms ReportViewer works only with Telerik Reporting REST service instances or Telerik Report Server (How To: Use HTML5 Report Viewer with Report Server). If you need an InstanceReportSource or XmlReportSource, you will have to resolve manually the report description string via custom resolver for the Reporting REST service. For more details, check REST Service Report Resolver (available only if using a Telerik Reporting REST service instance).

  • WinForms ReportViewer control

    The WinForms ReportViewer can be connected to a Telerik Reporting REST Service or Telerik Report Server by setting its ReportEngineConnection property - How To: Construct a string to connect to Report Engine. For more details check How To: Use Windows Forms Report Viewer with Report Server (REST Service).

    In this scenario the viewer's ReportSource property of type Telerik.Reporting.ReportSource is considered as a client-side ReportSource. The client report source can be set in the same way as if the viewer is operating locally (go to section link), where the selection is limited to TypeReportSource and UriReportSource:

    • The report description string is obtained from the TypeReportSource.TypeName|UriReportSource.Uri property, that returns a string. The report description string is sent to the Telerik Reporting REST service which internally resolves it to a TypeReportSource or a UriReportSource on the machine where the service and Telerik Reporting Engine are running.

      Tip Tip

      If you need an InstanceReportSource or XmlReportSource, you will have to send custom string as report description string, and to resolve manually the report description string via custom resolver for the Reporting REST service. For more details, check REST Service Report Resolver (available only if using a Telerik Reporting REST service instance).

    • Report parameters' values (client parameters) are obtained from the TypeReportSource.Parameters|UriReportSource.Parameters collection. The client parameters can be sent throught the viewer's Parameters Area, on creating the WinForms ReportViewer or by updating the viewer's ReportSource property.

  • WPF ReportViewer control

    The WPF ReportViewer can be connected to a Telerik Reporting REST Service or Telerik Report Server by setting its ReportEngineConnection property - How To: Construct a string to connect to Report Engine. For more details check How To: Use WPF Report Viewer with Report Server (REST Service).

    In this scenario the viewer's ReportSource property of type Telerik.Reporting.ReportSource is considered as a client-side ReportSource. The client report source can be set in the same way as if the viewer is operating locally (go to section link), where the selection is limited to TypeReportSource and UriReportSource:

    • The report description string is obtained from the TypeReportSource.TypeName|UriReportSource.Uri property, that returns a string. The report description string is sent to the Telerik Reporting REST service which internally resolves it to a TypeReportSource or a UriReportSource on the machine where the service and Telerik Reporting Engine are running.

      Tip Tip

      If you need an InstanceReportSource or XmlReportSource, you will have to send custom string as report description string, and to resolve manually the report description string via custom resolver for the Reporting REST service. For more details, check REST Service Report Resolver (available only if using a Telerik Reporting REST service instance).

    • Report parameters' values (client parameters) are obtained from the TypeReportSource.Parameters|UriReportSource.Parameters collection. The client parameters can be sent throught the viewer's Parameters Area, on creating the WPF ReportViewer or by updating the viewer's ReportSource property.

For ReportViewer controls integrated with Telerik Report Server

Important note Important

Telerik Report Server's REST Service can use only its built-in Report Resolver, capable of handling client-side UriReportSource into a server-side UriReportSource on the server (Report Sources). Reports must be serialized in TRDX files or packaged in TRDP files which can be published on Telerik Report Server - Working with Report Server Reports.

Thus the client-side ReportSource is limited to UriReportSource, where the report description string must be in a format: [CategoryName]/[ReportNameWithoutFileExtension] e.g. "Samples/Dashboard" which will request the Dashboard.trdx|trdp file that is published on Telerik Report Server under the "Samples" category.

The following Report Viewers are designed to work as clients of Telerik Report Server:

  • HTML5 Report Viewer - the client report source is set in the same way as if the viewer is connected to a Telerik Reporting REST Service (go to section link)

  • HTML5 ASP.NET MVC ReportViewer - the client report source is set in the same way as if the viewer is connected to a Telerik Reporting REST Service (go to section link)

  • HTML5 ASP.NET WebForms ReportViewer - the client report source is set in the same way as if the viewer is connected to a Telerik Reporting REST Service (go to section link)

  • WinForms ReportViewer - the client report source is set in the same way as if the viewer is connected to a Telerik Reporting REST Service (go to section link)

  • WPF ReportViewer - the client report source is set in the same way as if the viewer is connected to a Telerik Reporting REST Service (go to section link)

These Report Viewers do not have direct access to Telerik Reporting Engine. Reports are processed and rendered on a remote machine where Telerik Report Server is running, and the content is delivered to the client by Telerik Report Server's REST Service.

See Also