The SSRS 2005 Web service is an XML-based Web service. It uses the SOAP API to allow you to call a variety of methods on the report server and interact with them using a rich set of objects provided by the service.
Web Services Method Categories
The Report Server Web service can control every aspect of the report server and consists of several categories of methods, as listed in Table 6-6.
Table 6-6. Categories of the Report Server Web Services Methods
Category Manages
Namespace management Folders and items on the server and their properties Authorization Tasks, roles, and policies
Data source connections Data source connections and credentials Report parameters Setting the retrieval parameters for reports Rendering and execution Report execution, rendering, and caching Report history Snapshot creation and history
Scheduling Shared schedule creation and modification Subscription and delivery Subscription creation and modification Linked reports Linked report creation and management
The Report Server Web service uses many of these methods to control aspects of SSRS 2005 that aren’t directly related to rendering reports, so we won’t cover them in this chapter. How-ever, you should be aware of the level of control your custom application can have over SSRS 2005 and the types of functions that can be performed, because you might want to provide a user interface to them from your application. Keep in mind that Microsoft built the main SSRS 2005 report server application using ASP.NET and these Web services.
For the SSRS Viewer RVC, you are using the ReportViewer control to render the report, but you want to provide a custom Windows Forms–based user interface to allow users to enter their report parameters. The rest of this chapter concentrates on using methods from the report parameters category listed in Table 6-6. You’ll use these methods to obtain a list of the param-eters that the report expects and also to find the possible values for those paramparam-eters. You’ll use this information to create and populate combo boxes that allow the users to enter their choices from a Windows Forms dialog box.
Creating the GetParameters Form
You already have a form (ViewerRVC.cs) to render and display the report in the embedded ReportViewer control. You’ll now add a second form to the project that you’ll use to display the report and rendering parameters and to allow the users to make their selections.
So, add aGetParametersform to your project by selecting Project ➤Add Windows Form.
Name the form GetParameters.cs. Onto this form, add two controls from the Toolbox; add aFlowLayoutPanelcontrol named parameterPanel, and add one button control named buttonOK.
Then set the text for the button to OK. When you’re done, the form should look like Figure 6-7.
You now need to add a reference to the SSRS 2005 Web service to your project. You do this by selecting Project ➤Add Web Reference or by right-clicking the references in the Solution Explorer and selecting Add Web Reference. When the dialog box appears, enter the following URL:
http://localhost/reportserver/reportservice2005.asmx
Substitute the name of your server for localhost. Then click the Go button. You’ll see a dialog box similar to Figure 6-8.
Figure 6-7. SSRS Viewer RVC GetParametersform
Figure 6-8. Adding an SSRS 2005 Web service reference
In the Web Reference Name textbox, enter SSRSWebService, which is the name by which you’ll refer to your Web service in your code.
Once this dialog box is closed, you will add the following usingstatement to the top of your code in the GetParametersclass. Note that if your project name is different from SSRS Viewer RVC, you should change the reference to reflect the name of your project.
using SSRS_Viewer_RVC.SSRSWebService;
Now you can reference the methods and properties exposed by the Web service much more easily because you won’t have to enter the fully qualified namespace. Also, add the fol-lowing directives:
using System.Web.Services.Protocols;
using System.Collections;
Doing this will allow you to access the members of these namespaces without needing to type the full namespace each time you use a method or property from that namespace.
Because you’ll use this form as a dialog box to display the report parameters and their possible values, and allow the user to select them, you need a way to communicate between the two forms.
Coding the Report Parameters Form
When you instantiate the report parameters form (GetParameters), you do so by passing in the URL of the report the user has entered in the viewer form (ViewerRVC.cs). You use this URL to determine the report server name and the specific report the user wants to run. You need to know both of these for the calls to the report server Web service. Because you’ll use this information throughout the rest of the code, in this class you store them in some class-level private variables, as shown in Listing 6-4.
In the form constructor, break the report server and report name into two separate fields.
To break down the URL into the server and report name, use the string splitmethod and create a constructor that looks like Listing 6-5.
Listing 6-5. Report Parameters Form Constructor
The GetParameters_Load Event
Now you get to where the real work for this dialog box takes place: the Form_Loadevent. First, create aReportingServiceobject so that you can access SSRS 2005 through the Web service that you added as a reference earlier. Next, set your Windows credentials as the credentials to be used for calling the Web service, like so:
rs = new ReportingService2005();
rs.Credentials = System.Net.CredentialCache.DefaultCredentials;
■ Note
You can also use Basic authentication using rs.Credentials = new System.Net.Network-Credential("username", "password", "domain");. The method you use depends on the security settings for the report server virtual directory. By default, it’s configured to use Windows authentication.
Calling the Web Services GetReportParameters Method The GetReportParametersmethod takes five parameters:
• Report: The full path name of the report.
• ForRendering: A Boolean value that indicates how the parameter values should be used.
You must set it to trueto get a list of the possible values for each parameter.
• HistoryID: The ID of the report history snapshot. You set it to nullbecause you aren’t running the report from a snapshot.
• ParameterValues: The parameter values (ParameterValue[]objects) that can be validated against the parameters of the report that are managed by the report server. Set this to nullfor this example.
• Credentials: The data source credentials (DataSourceCredential[]objects) that can be used to validate query parameters. Set this to nullfor this example.
The GetReportParametersmethod returns an array of ReportParameter[]objects that con-tain the parameters for the report. You use this information to render combo boxes that allow the users to select the parameter values they want to use when running the report.
The following code sets up the variables you need to use and then calls the
GetReportParametersmethod to retrieve a list of reports that the report expects, as shown in Listing 6-6.
Once you have the list of parameters from SSRS 2005, you loop through them using the values to create labels as you create your combo box for each parameter, like so:
foreach (ReportParameter rp in parametersSSRS)
Each ReportParameterobject has a read-only property calledValidValues. You can use the ValidValuesproperty, which returns an array of ValidValueobjects to populate the items in each combo box, as shown in Listing 6-7.
Listing 6-7. Iterating Through the ValidValueObjects if (rp.ValidValues != null)
So, for each ReportParameter, you see whether any ValidValuesproperties exist. If so, you loop through them, adding each item to the combo box. Because you want to retrieve the display name and the actual value for each item in the combo box, you have to create a combo box item class and bind the objects to the combo box. Listing 6-8 shows the GetParameters_Load event, and Listing 6-9 shows the ComboItemclass.
Listing 6-8. Get Report Parameters and Possible Values, and Display Them in Combo Boxes private void GetParameters_Load(object sender, System.EventArgs e)
try
// now create a label for the combo box below Label lbl = new Label();
}
Upon loading, you’ll see a form like Figure 6-9 that displays a series of combo boxes, each containing the valid values for the report parameters.