Chapter 25. How to Use Reporting Services Web Services


In This Chapter

  • Report Management Web Service New in 2005

    (ReportService2005.asmx)

  • How to Script Reporting Services (Using the RS Utility)

  • Working with Report Parameters

  • Security When Calling a Web Service

  • Some of the Commonly Used Methods with Short Code Snippets

In the previous chapter, you learned about URL Access functionality. URL Access provided high-performance access to SSRS for report viewing and navigation. However, URL Access does not provide sufficient access to SSRS' management functionality. SSRS' web services comes to the rescue and complements URL Access by providing full access to SSRS' management and rendering functionality.

An application that needs to incorporate both report viewing and report management functionality would typically use both URL Access and the SSRS web service. Combining the two is used for a couple of reasons: URL Access provides the best performance for the report viewing experience and handles framing of a report; in contrast, SSRS web service provides comprehensive access to SSRS functionality, including management functionality, which is not available in URL Access.

Because the web service employs Simple Object Access Protocol (SOAP) over HTTP, any SOAP-aware application or development tools can communicate with the SSRS web service. Technically, you can manually generate SOAP requests (which are basically XML text written to SOAP specifications) and pass those requests to the SSRS web service. Visual Studio generates a web proxy and makes using a web service as easy as using any .NET namespace.

Let's start with a simple example. This example walks through the use of the Render() function to access the SSRS web service, and then incorporates the resulting stream into a custom application. Much like parameter commands with the same name in URL Access, Render() and ListChildren() are the most frequently used functions in the SSRS web service.

As an example, let's create a simple function that retrieves a report from SSRS. Here are the steps:

1.
Open Visual Studio 2005.

2.
Create a C# project and call it Embedded Report .

3.
Rename Form1 that Visual Studio created to MainForm .

4.
Add a reference to the Reporting Services web service by right-clicking on the project in Solution Explorer and selecting Add Web Reference from the shortcut menu, or by selecting Add Web Reference from the Project menu, as shown in Figure 25.1.

Figure 25.1. Adding web references in Visual Studio.

5.
Select the most appropriate hyperlink or enter http://<server>/ reportserver /ReportExecution2005?wsdl in the URL field of the Add Web Reference dialog box and click GO . Note <server> is the name of a server on which Report Server is installed. If development is performed on the same machine on which Report Server is installed, select the Web Services on the Local Machine hyperlink. After Visual Studio completes this operation, it presents a selection such as the one shown in Figure 25.2.

Figure 25.2. List of available web services.

Figure 25.2 is a typical list of web services for a computer that just has the Reporting Services web service. The list might be longer if there are any additional web services available on a computer. Four SSRS, which are outlined in Table 25.1, web services (or SSRS web service endpoints) are available in SSRS 2005.

Table 25.1. SSRS 2005 Web Services

Services

Typical Endpoint URL (SSRS Installed on localhost )

Functionality

ReportExecution2005 New in 2005

http://localhost/ReportServer/ReportExecution2005.asmx

Report execution endpoint contains functionality to control report processing and rendering. Not compatible with SSRS 2000.

ReportService

http://localhost/ReportServer/ReportService.asmx

SSRS 2000 backward compatibility interface.

ReportService2005 New in 2005

http://localhost/ReportServer/ReportService2005.asmx

Report and server management endpoint.


Note

To view a Web Service Description Language (WSDL) in a browser, add ?wsdl after any of SSRS endpoint's URLs, such as http://localhost/ReportServer/ReportService2005.asmx?wsdl.


6.
Select one of the web services (SSRS endpoints) after Visual Studio completes this operation (web reference is found).

7.
Replace Server Name with ReportExecution2005 in the Web Reference Name text box.

8.
Click Add Reference.

Solution Explorer now displays ReportExecution2005 as one of the web references. To permit the use of types in Reporting Services, you need to add a web proxy reference to each module that uses a web service. In a general case, the syntax of the reference looks like the following:

 using <<NamespaseUsingWebProxy>>.<<Web Reference Name Given During Proxy Creation>>; 

In this specific example, you add:

 using EmbeddedReport.ReportExecution2005; using System.Web.Services.Protocols; //to handle SOAP xceptions 

The second line is added to handle SOAP exceptions.

The following code generates XML output for a report. You can use other formats supported by rendering extensions, such as HTML.

 static string GetReportXML2005(string ReportingServicesURL,                                 string ReportPath) {     //creates a new Web service (proxy) and set its credentials      ReportExecutionService rs = new ReportExecutionService();      //windows authentication          rs.Credentials = System.Net.CredentialCache.DefaultCredentials;     //Assign Web service url. This is optional operation. Default URL     //is assigned during the creation of a proxy.     //Typically http://<<server name>>/ReportServer/ReportExecution2005.asmx     rs.Url = ReportingServicesURL;     // Setup Render() call     byte[] result = null;     string encoding, mimeType, extension;     Warning[] warnings = null;     string[] streamIDs = null;     try     {         //Should be called prior to Render() to set report's path         rs.LoadReport(ReportPath, null);            //Gets a byte stream with Comma Separated Value (XML) layout         result = rs.Render("XML", null, out extension, out encoding,                             out mimeType, out warnings, out streamIDs);         return System.Text.Encoding.ASCII.GetString(result);     }     catch (SoapException e)     {         //Return exception message, if exception occured         return e.Message;     } } 

A call to GetReportXML2005() below demonstrates an assignment of the /Samples/DemoList report in the XML form to a text box textBoxResult :

 textBoxResult.Text = GetReportXML2005(                    "http://localhost/ReportServer/ReportExecution2005.asmx",                     "/Samples/DemoList"); 

Note

If you want to incorporate the results of Render() in the web application, you can pass device information settings to retrieve an HTML fragment that does not contain a BODY element. The call would look similar to the following:


 result = rs.Render("HTML",           "<DeviceInfo><HTMLFragment>True</HTMLFragment>          </DeviceInfo>", ...); 

You might have noticed the following assignment in the code rs.Url = ReportingServicesURL; this is an optional operation because the web proxy already incorporates the URL of the server for which it was generated. This assignment is beneficial to make the code portable and enable it to access any specified SSRS web service.

Most parameters in the Render() function are optional and accept null values.

Warning[] warnings; contains an array of objects with information about errors and warnings for which SSRS did not generate exceptions. In production code, you need to make sure to incorporate handling for warnings.

The sample uses part of the information available in SoapException . SoapException has four properties:

  • Actor The code that caused exception.

  • Detail The XML describing application-specific error information. Detail is an XMLNode object and inner text from Detail can be accessed for the flow control, such as if(ex.Detail["ErrorCode"].InnerXml == "rsItemNotFound") {/*handle the error*/} .

  • HelpLink A link to a Help file associated with the error.

  • Messsage A message describing the error.

The Report Execution web service is very sensitive to the report's path, requires the path to start from " / " (slash), and does not accept URL-encoded strings. If the path is incorrect, web services returns an ItemNotFoundException exception. For example, for a report with the name My DemoList (note the space after the word My) located in the Samples directory, the URL-encoded path /Samples/My%20DemoList is not acceptable. It should cause an error with an exception similar to the following:

 System.Web.Services.Protocols.SoapException: The item '/Samples/My%20DemoList'  cannot be found.  ---> Microsoft.ReportingServices.Diagnostics.Utilities.ItemNotFoundException:  The item '/Samples/My%20DemoList' cannot be found. 

SSRS web service can raise another exception for a missing or incorrect path:

 System.Web.Services.Protocols.SoapException:  The path of the item "" is not valid.  he path must be less than 260 characters long and must start with slash. 

The proper way to enter this path is /Samples/My Demolist (no URL encoding).

Actions in GeTReportXML2005() should produce the same result as http://localhost/ReportServer/ReportExecution2005.asmx?/Samples/DemoList&rs:Command=Render&rs:Format=XML. The difference is that the web service call is not interactive, but the web service call allows an application to receive and process a report's XML internally.

The line rs.Credentials = System.Net.CredentialCache.DefaultCredentials; is very important. An application must supply credentials to the SSRS web service before it can access a report. DefaultCredentials is the Windows authentication for the user . Lack of proper credentials results in an exception:

 An unhandled exception of type 'System.Net.WebException'  occurred in system.web.services.dll. Additional information:  he request failed with HTTP status 401: Unauthorized. 

System.Text.Encoding.ASCII.GetString is used to convert a byte[] array that Render() returns to a string. Note that ASCII is an option suitable for text-based formats, such as XML and CSV. Other converters (such as Unicode) are available in the System.Text.Encoding namespace.

If you are using this book to assess SSRS 2000 web services, you need to keep in mind that ReportingServices.asmx and ReportService.asmx are the only available web services in that version. Web service call signatures in SSRS 2000 and SSRS are not always compatible. For example, the Render() method in SSRS 2000 has 12 parameters, whereas the same method in ReportExecution2005.asmx has 7 parameters. To make a SSRS 2000 style call to the Render() method, you have to select ReportingServices.asmx and add its reference in the code (here, the proxy name is ReportingServices ) as follows :

 using EmbeddedReport.ReportingServices; 

Then, you replace the inside of a try block with the following:

 ParameterValue[] reportHistoryParameters = null; result = rs.Render(ReportPath, "XML",     null, null, null, null, null,     out encoding, out mimeType,     out reportHistoryParameters, out warnings, out streamIDs); return System.Text.Encoding.ASCII.GetString(result); 



Microsoft SQL Server 2005 Reporting Services
Microsoft SQL Server 2005 Reporting Services
ISBN: 0672327996
EAN: 2147483647
Year: 2004
Pages: 254

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net