Setting ReportSource to Report Viewers Overview
To display a report in a Report Viewer, specify the Report Source object. This article explains how to configure a Report Source for each of the following Report Viewer types:
- Report Viewer controls that work with the Telerik Reporting Engine - for example, WinForms, WPF, and the WinUI Report Viewer controls;
- Report Viewers that operate via the Telerik Reporting Services - for example, HTML5, HTML5 ASP.NET MVC, HTML5 ASP.NET WebForms, WinForms, WPF, and the WinUI Report Viewers;
- Report Viewer controls that are integrated with Telerik Report Server - for example, HTML5, HTML5 ASP.NET MVC, HTML5 ASP.NET WebForms Report Viewers, WinForms, WPF, and the WinUI Report Viewer controls.
Report Viewers load reports that have been processed and rendered server-side. To request processing and rendering, wrap the report in a Report Source object. The rendering format and Report Source settings vary depending on the viewer type. The sections below explain both Report Source types and how to configure each viewer.
The Telerik Reporting Engine accepts only Server-Side ReportSources. A server-side ReportSource contains either an instance of the report definition (InstanceReportSource) or information about where to find and how to instantiate it (TypeReportSource, UriReportSource, XmlReportSource). For example, TypeReportSource references a C# or VB.NET class that is instantiated via reflection from its assembly-qualified name set in the TypeName property.
A client-side reportSource contains only a string identifying the report definition. For example, the reportSource of the HTML5 Report Viewer exposes the report property as a report definition identifier. This string cannot be passed directly to the Reporting Engine because the engine does not know how to create a report instance from it. The identifier is resolved to a server-side ReportSource in the Resolve method of the ReportSource Resolver configured in the Telerik Reporting REST Service that web-based viewers require.
The Report Parameter values in both server-side and client-side Report Source are a Dictionary with a string key and object value.
Set up Report Viewer controls that work with Telerik Reporting Engine
These are viewers that operate on the same machine where reports are processed and rendered. These viewers include mechanisms for resolving reports:
- WinForms Report Viewer — processes and renders reports on the local machine, unless configured to connect to a remote Reporting REST Service or Telerik Report Server.
- WPF Report Viewer — processes and renders reports on the local machine, unless configured to connect to a remote Reporting REST Service or Telerik Report Server.
- WinUI Report Viewer — processes and renders reports on the local machine, unless configured to connect to a remote Reporting REST Service or Telerik Report Server.
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 Report Viewer control is running.
-
Set the Report Source through the Visual Studio Designer
- In VS Design view, right-click a report viewer to which you want to set a report source and select Properties.
- In its Properties, find and click ReportSource.
- A "Load a Report from" dialog appears which allows you to select a ReportSource.
- Select the type of ReportSource to use and specify a report. To use a UriReportSource, click the URL or file option and select the report to display. To pass parameters to the report, continue with the next step.
- 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"));Set up Report Viewers that operate via Telerik Reporting Services
The following Report Viewers are designed to work as clients of Telerik Reporting Services:
- HTML5 Report Viewer (go to section HTML5 Viewer)
- Angular Report Viewer (go to section Angular Viewer)
- React Report Viewer (go to section React Viewer)
- Blazor Report Viewer (go to section Blazor Viewer)
- Native Blazor Report Viewer (go to section Native Blazor Viewer)
- HTML5 ASP.NET MVC Report Viewer (go to section MVC Viewer)
- HTML5 ASP.NET WebForms Report Viewer (go to section WebForms Viewer)
- WinForms Report Viewer (go to section WinForms Viewer)
- WPF Report Viewer (go to section WPF Viewer)
- WinUI Report Viewer (go to section WinUI Viewer)
These Report Viewers do not have direct access to the 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:
-
The Report Viewer sends a client-side ReportSource to the Reporting Service: a report description string and client parameters. The report description string must comply with technology limits on message size and character encoding. The client parameters must match report parameter names exactly (case-sensitive).
-
The Reporting Service passes the report description string to its Report Source Resolver, which creates a valid server-side Report Source.
The default resolvers produce
TypeReportSourceorUriReportSource. Each Telerik Reporting Service supports a custom resolver to return any available Report Source type. Report assembly or TRDX or TRDP files must be accessible on the server where the Reporting Service is running. -
The Reporting Service applies the client parameters to the server-side Report Source's Parameters collection in memory.
-
The Reporting Engine processes the document on the server. The Reporting Service then returns the following:
- Information about Visible parameters - the Report Viewer displays its Parameters Area and corresponding parameter editors;
- The processed and rendered report - the rendering format depends on the viewer, e.g., XAML for WPF Report Viewers 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:
HTML5 Report Viewer
The HTML5 Report Viewer control is a client-side widget that 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:
reportSource: {
report: "Product Catalog.trdp",
parameters: { CultureID: "en" }
}
or
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 resolves it to a TypeReportSource or UriReportSource on the machine where the service is running.
To display a different report or update the current client parameters, call the reportSource(rs) method on the viewer object in JavaScript, or recreate the viewer.
The HTML5 Report Viewer supports only
UriReportSourceandTypeReportSource. To use anInstanceReportSourceorXmlReportSource, implement a custom Report Source Resolver for the Reporting REST Service. For details, see REST Service Report Source Resolver.
Angular Report Viewer
The Angular Report Viewer control is an Angular wrapper of the HTML5 Viewer. It works in the same way as the pure HTML5 Report Viewer and requires jQuery. It exposes an identical client-side reportSource. For example:
<tr-viewer #viewer1
[reportSource]="{
report: 'Product Catalog.trdp',
parameters: { CultureID: 'en' }
}">
</tr-viewer>
or
<tr-viewer #viewer2
[reportSource]="{
report: 'Telerik.Reporting.Examples.CSharp.ProductCatalog, CSharp.ReportLibrary',
parameters: { CultureID: 'en' }
}">
</tr-viewer>
React Report Viewer
The React Report Viewer control is a React wrapper of the HTML5 Viewer. It works in the same way as the pure HTML5 Report Viewer and requires jQuery. It exposes an identical client-side reportSource. For example:
export function ReportViewer() {
const reportSource = {
report: 'Product Catalog.trdp',
parameters: { CultureID: 'en' }
};
return (
<TelerikReportViewer
serviceUrl="https://demos.telerik.com/reporting/api/reports/"
reportSource={reportSource} />
)
}
or
export function ReportViewer() {
const reportSource = {
report: 'Telerik.Reporting.Examples.CSharp.ProductCatalog, CSharp.ReportLibrary',
parameters: { CultureID: 'en' }
};
return (
<TelerikReportViewer
serviceUrl="https://demos.telerik.com/reporting/api/reports/"
reportSource={reportSource} />
)
}
Blazor Report Viewer
The Blazor Report Viewer control is a Blazor wrapper of the HTML5 Viewer. It works in the same way as the pure HTML5 Report Viewer and requires jQuery. It exposes an identical client-side reportSource through the model ReportSourceOptions:
<ReportViewer ViewerId="rv1"
ReportSource="@(new ReportSourceOptions
{
Report = "Product Line Sales.trdp",
//or Report = "Telerik.Reporting.Examples.CSharp.ProductLineSales, CSharp.ReportLibrary",
Parameters = new Dictionary<string, object>
{
{ "ProductCategory", "Clothing" },
{ "ProductSubcategory", new [] { "Caps", "Gloves" } }
}
})" />
Native Blazor Report Viewer
The Native Blazor Report Viewer control is a native Blazor widget built on top of Telerik UI for Blazor components. Its ReportSource is defined through the same ReportSourceOptions model as the Blazor wrapper of the HTML5 Viewer:
<ReportViewer
@bind-ReportSource="@ReportSource"
>
</ReportViewer>
@code {
public ReportSourceOptions ReportSource { get; set; } =
new ReportSourceOptions(
"Product Line Sales.trdp",
//or "Telerik.Reporting.Examples.CSharp.ProductLineSales, CSharp.ReportLibrary",
new Dictionary<string, object>
{
{ "ProductCategory", "Clothing" },
{ "ProductSubcategory", new [] { "Caps", "Gloves" } }
});
}
HTML5 ASP.NET MVC Report Viewer
The HTML5 ASP.NET MVC Report Viewer control 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 a different report or update the current client parameters, call the reportSource(rs) method on the viewer object in JavaScript, or recreate the ASP.NET MVC Report Viewer.
The HTML5 ASP.NET MVC Report Viewer supports only
UriReportSourceandTypeReportSource. To use anInstanceReportSourceorXmlReportSource, implement a custom Report Source Resolver for the Reporting REST Service. For details, see REST Service Report Source Resolver.
HTML5 ASP.NET WebForms Report Viewer
The HTML5 ASP.NET WebForms Report Viewer control is a server-side wrapper of the HTML5 Viewer, suitable for ASP.NET WebForms applications.
- The report description string is obtained from the Telerik.ReportViewer.Html5.WebForms.ReportSource.Identifier property, which accepts a string. The value can be a path to a TRDP or TRDX file, an assembly-qualified name of a report class, or a custom string. For example:
Identifier="./DashboardReport.trdp"orIdentifier="Telerik.Reporting.Examples.CSharp.BarcodesReport, CSharp.ReportLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null". - Report parameters are set through the ReportSource.Parameters property (the client parameters).
- The Telerik.ReportViewer.Html5.WebForms.ReportSource.IdentifierType property indicates which resolver to use for resolving the report description string on the server.
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 markup:
- Open the ASPX page that contains the HTML5 WebForms Report Viewer.
- Select the HTML5 WebForms Report Viewer and navigate to its ReportSource property in the Visual Studio Properties grid.
- A "Load a Report from" dialog appears. Select a ReportSource type.
- Select the type of ReportSource to use and specify a report. To use a TypeReportSource, click the Type name option and select the report to display. To pass parameters to the report, continue with the next step.
- Click the Edit Parameters button. In the Edit Parameters dialog, click New. In the Parameter Name column, select a report parameter name. In the Parameter Value column, type or select the value to pass.
<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 a different report or update the current client parameters, call the reportSource(rs) method on the viewer object in JavaScript, or recreate the HTML5 WebForms Report Viewer.
The HTML5 WebForms Report Viewer supports only
UriReportSourceandTypeReportSource. To use anInstanceReportSourceorXmlReportSource, implement a custom Report Source Resolver for the Reporting REST Service. For details, see REST Service Report Source Resolver.
WinForms Report Viewer
The WinForms Report Viewer control 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 Set up Report Viewer controls that work with Telerik Reporting Engine), 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.
To use an
InstanceReportSourceorXmlReportSource, send a custom report description string and implement a custom Report Source Resolver for the Reporting REST Service. For details, see REST Service Report Source Resolver. -
Report parameters (client parameters) are obtained from
TypeReportSource.ParametersorUriReportSource.Parameters. Pass them through the viewer's Parameters Area, when creating the WinForms Report Viewer, or by updating the viewer'sReportSourceproperty.
Example of setting the ReportSource in code-behind:
private void Form1_Load(object sender, EventArgs e)
{
var typeReportSource = new Telerik.Reporting.TypeReportSource();
typeReportSource.TypeName = "Telerik.Reporting.Examples.CSharp.ListBoundReport, CSharp.ReportLibrary";
this.reportViewer1.ReportSource = typeReportSource;
reportViewer1.RefreshReport();
}WPF Report Viewer
The WPF Report Viewer control 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.
-
The report description string is obtained from
TypeReportSource.TypeNameorUriReportSource.Uriand sent to the Telerik Reporting REST Service, which resolves it to aTypeReportSourceorUriReportSourceon the machine where the service is running.To use an
InstanceReportSourceorXmlReportSource, send a custom report description string and implement a custom Report Source Resolver for the Reporting REST Service. For details, see REST Service Report Source Resolver. -
Report parameters (client parameters) are obtained from
TypeReportSource.ParametersorUriReportSource.Parameters. Pass them through the viewer's Parameters Area, when creating the WPF Report Viewer, or by updating the viewer'sReportSourceproperty.
Example of specifying the ReportSource declaratively
<Window x:Class="WpfApplication1.Window1"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
Title="Window1" Height="451" Width="683"
xmlns:telerik="clr-namespace:Telerik.ReportViewer.Wpf;assembly=Telerik.ReportViewer.Wpf"
xmlns:telerikReporting="clr-namespace:Telerik.Reporting;assembly=Telerik.Reporting">
<Grid>
<telerik:ReportViewer Name="reportViewer1">
<telerik:ReportViewer.ReportSource>
<telerikReporting:TypeReportSource TypeName="Telerik.Reporting.Examples.CSharp.Invoice, CSharp.ReportLibrary">
<telerikReporting:ReportSource.Parameters>
<telerikReporting:Parameter Name="OrderNumber" Value="SO51085"/>
<telerikReporting:Parameter Name="ForYear" Value="2003"/>
</telerikReporting:ReportSource.Parameters>
</telerikReporting:TypeReportSource>
</telerik:ReportViewer.ReportSource>
</telerik:ReportViewer>
</Grid>
</Window>
Example of setting the ReportSource at runtime using the Window.Loaded event handler:
<Window x:Class="WpfApplication1.Window3"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
Title="Window3" Height="328" Width="618" xmlns:my="clr-namespace:Telerik.ReportViewer.Wpf;assembly=Telerik.ReportViewer.Wpf" Loaded="Window_Loaded">
<Grid>
<my:ReportViewer Name="reportViewer1" />
</Grid>
</Window><Window x:Class="Window3"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
Title="Window3" Height="489" Width="687" xmlns:my="clr-namespace:Telerik.ReportViewer.Wpf;assembly=Telerik.ReportViewer.Wpf" Name="Window3">
<Grid>
<my:ReportViewer Name="ReportViewer1" />
</Grid>
</Window>WinUI Report Viewer
The WinUI Report Viewer control 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.
The configuration is identical to the WPF Report Viewer configuration.
Example of specifying the ReportSource declaratively
<telerikReportViewer:ReportViewer x:Name="reportViewer" Grid.Row="1" ReportEngineConnection="engine=RestService;uri=http://localhost:59655/api/reports">
<telerikReportViewer:ReportViewer.ReportSource>
<telerikReportingCore:UriReportSource Uri="MyReport.trdp">
<telerikReportingCore:ReportSource.Parameters>
<telerikReportingCore:Parameter Name="ParameterName_01" Value="ParameterValue_01"/>
<telerikReportingCore:Parameter Name="ParameterName_02" Value="ParameterValue_02"/>
</telerikReportingCore:ReportSource.Parameters>
</telerikReportingCore:UriReportSource>
</telerikReportViewer:ReportViewer.ReportSource>
</telerikReportViewer:ReportViewer>
In the code above:
* telerikReportViewer represents the namespace Telerik.ReportViewer.WinUI
* telerikReportingCore represents the namespace Telerik.Reporting
Set up Report Viewer controls that are integrated with Telerik Report Server
Telerik Report Server's REST Service can use only its built-in Report Source 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:
For all supported viewers, configure the client report source the same way as when connecting to a Telerik Reporting REST Service, with one difference: set the report description string in the format CategoryName/ReportNameWithoutFileExtension, for example "Samples/Dashboard". This requests the Dashboard.trdx or Dashboard.trdp file published on Telerik Report Server under the Samples category.
The following viewers support this configuration:
- HTML5 Report Viewer
- Angular Report Viewer
- React Report Viewer
- Blazor Report Viewer
- Native Blazor Report Viewer
- HTML5 ASP.NET MVC Report Viewer
- HTML5 ASP.NET WebForms Report Viewer
- WinForms Report Viewer
- WPF Report Viewer
- WinUI Report Viewer
These Report Viewers do not have direct access to the 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.