Chapter 24. How to Integrate URL Access

URL Access is one of the easiest methods available to developers to incorporate SSRS functionality into custom applications. URL Access is designed to provide the highest level of performance when used to view and navigate reports. URL Access achieves this performance by bypassing the web service interface and communicating directly with the Report Server. On the other hand, because URL Access does not access the web service, URL Access’ functionality is limited to viewing and navigating reports.

URL Access accepts various parameters that affect the report’s rendering. For example, some parameters affect the framing of a report and specify whether the toolbar and document map are displayed. Other parameters specify a report’s output format (HTML, IMAGE, EXCEL, CSV, PDF, XML). A set of commonly used parameters is discussed further in this chapter.

You can use URL Access to render a report in a browser by typing the URL Access command in the address bar or embed URL Access into applications that you develop.

Let’s start from a simple example of a URL Access. One of the methods to discover what is possible through URL Access is to actually navigate through the Report Viewer (Report Server web UI) and see how it works. Let’s start at http://localhost/ReportServer (generic syntax would be http://<server>/ReportServer, where <server> is a NetBIOS name, fully qualified domain name, or an IP address of a server on which Report Server is installed). When a developer uses Report Designer to deploy a report, the name of the project becomes the name of the folder on a Report Server.

For example, if you create a project with the name Generic, Report Designer creates a Generic folder. When you navigate to the Generic folder, the address changes to: http://localhost/ReportServer?/Generic&rs:Command=ListChildren. As it can be inferred from Command=ListChildren, this command renders a list of children, such as reports, data sources, or any other items located in the Generic folder.

You do not have to URL encode a URL Access string passed to a browser. Browsers should automatically encode it. The most common encoding is the space is replaced with “+” (plus sign) or an escape sequence “%20”, “/” (slash) is replaced with an escape sequence“%2f”, and “;” semicolon in any portion of the string is replaced with an escape sequence “%3A”.

URL Access commands have corresponding calls in the Reporting Services web service. This case is no exception—the URL Access command Command=ListChildren corresponds to the ListChildren() method call of the SSRS web service. When a user clicks on one of the reports (let’s use SimpleReport as a name of the report) in the SSRS web interface, you see the following URL address in a browser: http://localhost/ReportServer/Pages/ReportViewer.aspx?%2fGeneric%2fSimpleReport&rs:Command=Render.

Render perhaps is one of the most frequently used commands and also has a corresponding web method call in the SSRS web service called Render(). Render is called to generate a stream of data (this stream is a rendered report) in the format specified by a parameter. By default, a browser receives an HTML stream.

When appropriate for a particular rendering, URL Access uses implicit defaults. For example, by default a report is rendered with a toolbar. However, you do not see anything mentioning the toolbar in the URL address of the browser.

URL Access uses the following syntax http[s]://<RSserver>/<RSpath>?/<Parameters>.

<RSserver> is a NetBIOS name, fully qualified domain name (FQDN), or an IP address of a server on which Report Server is installed.

<RSpath> is a virtual directory path on which Report Server is installed (by default, it is installed to the ReportServer virtual directory).

<Parameters> can consists of a relative path of an item (report or other resource) in relation to the SSRS virtual directory followed by one or more parameters with the syntax &prefix:parameter=value. Valid prefix values are shown in Table 24.1 and valid parameters are shown in Table 24.2.

Table 24.1. Valid Parameter Prefixes

Syntax requires each prefix to be followed by a parameter. Report parameters do not have prefixes and this is how URL Access determines that a particular parameter should be treated as a report parameter. If a URL Access command includes a report parameter that does not match any of the parameters defined in the report, SSRS reports an rsUnknownReportParameter error.

On the other hand, SSRS is very lenient with prefixed parameters and uses a default value when the value specified in URL Access is invalid. For example, rs:Command= Reindeer (note intentional misspell of Render) defaults to rs:Command=Render. This is a mixed blessing as it might not be immediately clear why a certain URL Access command does not work as you would have expected. However this handling minimizes errors.

Command is the most frequently used parameter and is used in almost all URL Access commands. Command’s details and other available rs: parameters are shown in Table 24.2.

Table 24.2. rs:—Report Server Parameters

Table 24.3 shows partial set of Report Control parameters. Report Control parameters target HTML Viewer to provide framing and the look and feel for a rendered report. More details on this topic are available in SQL Server Books Online.

Table 24.3. rc:—Report Control Parameters

How to Integrate URL Access in an Application

You can use URL Access to incorporate reports into Windows and web applications.

Several methods are available for web applications. The most common method is to use a URL Access command string as a source or IFRAME. In a simple case scenario, this could be an HTML file with the following code:

  <IFRAME

         NAME="Frame1" SRC="http://localhost/ReportServer?/Samples/SimpleReport&

         rc:Toolbar=false&rc:LinkTarget= Frame1", width = 50%, height = 50%>

  </IFRAME>

The preceding code creates a frame on the page that is located in the upper-left corner and takes 50% of the page’s “real estate.” The frame changes size as the browser window changes size. The purpose of &rc:LinkTarget= Frame1 is to make sure that all of the report’s navigation happens inside of the frame called Frame1.

You can also add a link to a report in a web application or leverage the rc:HTMLFragment parameter.

You can also call SSRS web services to obtain needed information and then incorporate the returned stream into the application’s HTML stream. More details on working with SSRS web service can be found in Chapter 25, “How to Use Reporting Services Web Services.”

URL Access methods for web applications described above, such as using URL Access command as a source for IFRAME, have a common downside. They all use the HTTP GET method, which is an equivalent to a form submission where METHOD=“GET”.

There are a couple of potential issues with the GET method.

First, it might be easy to hack the URL string and make changes that would allow a malicious user to potentially get some proprietary information. A report’s security restricts a user’s access to a whole report, but does not prevent someone from experimenting with the parameters of a report.

By contrast, when you use URL Access with METHOD=“POST”, you can use hidden fields to prevent users from changing parameters used in URL Access.

Second, the URL GET request’s length is limited to the maximum allowed by the browser. Some browsers have this limit as low as 256 characters.

Internet Explorer’s maximum URL request length is 2,083 characters, with 2,048 maximum path length. This limit applies to both GET and POST methods. POST, however, is not affected by this limitation for submitting name/value pairs, because they are transferred in the header and not the URL.

For more details, see the following Microsoft Knowledge Base Article: http://support.microsoft.com/default.aspx?scid=kb;en-us;208427.

Changing the GET method to the POST method is fairly easy; for example, the following URL Access GET method

   http://localhost/ReportServer?/Samples/SimpleReport&rs:Command=Render
     &rc:LinkTarget=main&rs:Format=HTML4.0& EmployeeID=0947834

can be translated to the following POST method:

   <FORM id="frmRender" action="http://localhost/ReportServer?/Samples/SimpleReport"

       METHOD="POST" target="_self">

       <INPUT type="hidden" name="rs:Command" value="Render">

       <INPUT type="hidden" name="rc:LinkTarget" value="main">

       <INPUT type="hidden" name="rs:Format" value="HTML4.0">

       <INPUT type="hidden" name="EmployeeID" value="0947834">

       <INPUT type="submit" value="Button">

  </FORM>

To integrate URL Access in a Windows application, you can embed a web browser control in a Windows form. An old-style COM component from the Internet Controls Library (shdocview.dll) can be used with Visual Studio versions prior to VS2005.

VS2005 is sporting a new .NET web browser control. Simply drag and drop this control from the Visual Studio 2005 Toolbox on your Windows form, and then set the URL property of a control to a URL Access string. It’s that simple.

Summary

URL Access provides simple and efficient access to a report’s rendering functionality. URL Access can be used through a simple HTML link, as a source of an IFRAME, through web browser control in Windows and web applications, and in SharePoint web parts.

URL Access is designed to provide the highest level of performance when used to view and navigate reports. URL Access achieves this performance by bypassing the web service interface and communicating directly with Report Server. On the other hand, because URL Access does not access the web service, URL Access’ functionality is limited to viewing and navigating reports.