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. |
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);