 In This Chapter 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 . Note SSRS programmers who have implemented custom security extensions (Chapter 26, "Writing Custom Reporting Services Extensions," discusses some details of custom extensions) should know that SSRS still checks for permissions and a valid authorization cookie before allowing URL Access to a report. In a practical sense, this means that before reports can be accessed through the URL, a call must be made to the LogonUser method in the SSRS web service, and the resulting cookie must be relayed to the client's browser.
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. Note If you deploy a solution that contains a report, the report's path would be /{Solution Name}/ {Project Name}/{Report Name} . If you deploy a project (right-click on the project and select Deploy from the shortcut menu), the report's path would be /{Project Name}/{Report Name}
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 exceptionthe 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 | Prefix | Purpose | Example | | No prefix | Treats this parameter as a report parameter. To pass a null value for a parameter, use ParameterName:isnull=true . Note: Report parameters are case sensitive. | &EmployeeID=123 &EmployeeID:isnull=true | | rc | Denotes a report control parameter. Passes device information settings to rendering extensions. In the case of HTML (HTML Viewer), it is report framing information. Note: rc parameters are not case sensitive. | &rc:DocMap=True&rc:doCmaP=true &rc:Toolbar=True | | rs | Denotes a Report Server parameter. Passes a parameter to SSRS. Note: rs parameters are not case sensitive and all have counterpart functions in the SSRS web service. | &rs:Command=Render | | dsu | Specifies a username with which to access a data source. | &dsu:MyDataSource=MyUser | | dsp | Specifies a password with which to access a data source. Subject to limitations and risks of security exposures. Basically, avoid using it whenever possible. | &dsp:MyDataSource=Password |
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 | rs: parameter | Purpose | | Command | Specifies the command to be executed. Valid commands include the following: GetdataSourceContents Displays properties of a given shared data source as XML. Example:http://localhost/ReportServer?/Samples/Adventure+Works&rs:Command=GetDataSourceContents GetresourceContents Renders a file in a browser. This is used to show images and other nonreport or data source file. Example: http://localhost/ReportServer?/Samples/flogo.jpg&rs:Command=GetResourceContents ListChildren Lists items in a folder. Example: http://localhost/ReportServer?/Samples&rs:Command=ListChildren Render Renders the specified report. Example: http://localhost/ReportServer/Pages/ReportViewer.aspx/Samples/SimpleReport&rs:Command=Render | | Format | Specifies the format in which to render a report. Common values include HTML3.2, HTML4.0, HTMLOWC, MHTML, IMAGE, EXCEL, CSV, PDF, XML, and NULL. | | ParameterLanguage | Provides a language for parameters passed in a URL. The default value is the browser language. The value can be a culture value, such as en-us or de-de. This is especially helpful for international deployments. For example, in Europe most of the countries reverse month and day position as compared with the United States. | | Snapshot | Renders a report based on a report history snapshot. |
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 | rc: parameter | Target Rendering | Value | | BookmarkID | HTML | Directs SSRS to position the report's viewing focus to the bookmark ID. | | DocMap | HTML | Directs SSRS to show or hide the report document map. Valid values are true (default) or false. | | DocMapID | HTML | Directs SSRS to position the report's viewing focus to the document map ID. | | DpiX, DpiY | IMAGE | Specifies resolution of the output device in xydirection. 96 is the default. | | EndPage, StartPage | IMAGE, PDF | Directs SSRS to render lastfirst page of the report. StartPage=0 renders all pages. Defaults: StartPage=1 , EndPage=StartPage. | | FieldDelimiter | CSV | Specifies URL-encoded delimiter string. The default value is a comma (,). | | FindString | HTML | Specifies the text to search for in the report. The default is an empty string. | | JavaScript | HTML, MHTM | Indicates JavaScript supported in the rendered report. | | HTMLFragment | HTML | Directs SSRS to return an HTML fragment instead of a full HTML document. An HTML fragment includes the report content in a TABLE element and omits the HTML and BODY elements. The default value is false. Images for a report must be retrieved separately. | | LinkTarget | HTML | Specifies a target for hyperlinks in the report. LinkTarget=_blank opens a new target window. Other valid target names include a frame name,_self, _parent, and _top. | | MarginTop, MarginBottom, MarginLeft, MarginRight | IMAGE, PDF | Specifies the margin value, in inches, for the report. It is an integer or decimal value followed by "in" (for example, 1in). Overrides the report's original settings. | | NoHeader | CSV | Indicates whether the header row is excluded from the output. The default value is false. | | OmitDocumentMap | EXCEL | Indicates whether to omit the document map for reports that support it. The default value is false. | | OmitFormulas | EXCEL | Indicates whether to omit formulas from the rendered report. The default value is false. | | OmitSchema | XML | Indicates whether to omit the schema name from the XML and to omit an XML schema. The default value is false. | | OutputFormat | IMAGE | Specifies report's rendering graphical format: BMP, EMF, GIF, JPEG, PNG, or TIFF. | | PageHeight, PageWidth | IMAGE, PDF | Specifies a report's page height/width in inches. You must include an integer or decimal value followed by "in". This value overrides the report's original settings. | | Parameters | HTML | Shows or hides the parameters area of the toolbar. Parameters=true (default) shows, Parameters=false hides the parameters area. Parameters=Collapsed hides the parameters area, but allows the end user to toggle. | | Qualifier | CSV | Specifies a string to put around results that contain strings equal to FieldDelimiter or RecordDelimiter . If the results contain the qualifier, the qualifier is repeated. The Qualifier setting must be different from the FieldDelimiter and RecordDelimiter settings. The default value is a quotation mark ("). | | RecordDelimiter | CSV | Specifies a record delimiter for the end of each record. The default value is <cr><lf> . | | RemoveSpace | EXCEL | Directs an extension to eliminate small, empty cells from the result. A valid value is an integer or decimal value followed by "in". The default value is 0.125in. | | Schema | XML | Indicates to SSRS to render the XML schema definition (XSD) versus actual XML data. A value of true indicates that an XML schema is rendered. The default value is false. | | Section | HTML | Sets the report's viewing focus page. A value greater than the number of pages in the report displays the last page, negative values display page 1. The default value: 1. | | SimplePageHeaders | EXCEL | Indicates whether the page header of the report is rendered to the Excel page header. A value of false indicates that the page header is rendered to the first row of the worksheet. The default value is false. | | SuppressLineBreaks | CSV | Directs SSRS to suppress line breaks from the output. The default value is false. If the value is true, the FieldDelimiter, RecordDelimiter, and Qualifier settings cannot be a space character. | | Toolbar | HTML | Shows or hides the toolbar. True is the default value. If the value of this parameter is false, all remaining framing options (except the document map) are ignored. The toolbar is not rendered through the SOAP API, but the Toolbar device information setting affects results of SOAP Render method. | | XSLT | XML | Specifies the path of an XSLT to apply to the XML output, for example /transforms/myxslt . The XSL file must be a published resource on the Report Server and you must access it through a Report Server item path. This transformation is applied after any XSLT that is specified in the report. When used, the OmitSchema setting is ignored. | | Zoom | HTML | Sets the report zoom value as an integer percentage ( rc:Zoom=100 is the default) or in relation to the displayed page ( Page Width (rc:Zoom=Page%20Width) or Whole Page ). Supported by Microsoft Internet Explorer 5.0 and above. |
|
