The Render() method requires only two parameters: Report and Format. The Report parameter contains the full path to the report, starting at the root. The Format parameter contains a string that maps to a rendering extension that generates the specified export format. You'll usually choose one of these formats: Acrobat (PDF), Microsoft Excel (EXCEL), Web Archive (MHTML), HTML with Office Web Components (HTMLOWC), or Image (IMAGE).
You can also render reports in XML and comma-separated value (CSV) formats, but because the output for these formats is only text, you should use these formats only in special situations, such as when you use the raw data from these formats in an application or when you load the data into a database. Reporting Services also supports HTML 3.2 (HTML3.2) and HTML 4.0 (HTML4.0) output, but these formats often contain references to external resources such as images and therefore can't be saved into a single file. Listing 2 uses the Render() method to render a report in PDF format.
When the report is in a byte array, use the following code to save it in a file:
FileStream stream =
File.OpenWrite
(@"C:\My Report.pdf");
stream.Write(results, 0,
results.Length);
stream.Close();
This sample code doesn't show how to populate the reportParameters array. The ParameterValue argument is optional if the report doesn't use any parameters or if all the parameters are defined with default values. But if your report contains parameter values that differ from default values or you want to generate a report with a specific set of parameters, you must create an array of ParameterValue objects and populate it with the appropriate values.
Let's assume that the report referenced in Listing 2, My Report.pdf, requires a parameter called Year. Listing 3 shows a modified declaration of the ParameterValue object. First you create an array of the same size as the number of parameters in the report, then you populate the Name and Value attributes.
SQL Server 2000 Reporting Services doesn't support multivalue parameters, so you can specify only one value for each parameter if you use that version of Reporting Services. However, SQL Server 2005 Reporting Services does support multivalue parameters. Say that you want to render the same report with SQL Server 2005 and include the year 2004 in the report. In that case, you'd create two parameter values instead of one, use the same parameter name, and populate each Value property with a distinct value, as Listing 4 shows.
Your application's requirements determine how you should handle report parameters in code. For example, you might have situations in which you want your application to display parameters so that the user can select one or more parameters for rendering the report. Or your application might be scheduled to run without any user interaction and render a report based on static predefined parameters or on dynamic parameters read from an external resource. There are many ways to pass a set of parameters—configuration files, XML files, command-line parameters, or even database tables. The method you choose depends on your preference and on the application architecture. In some reports, the report parameters are naturally static and you can hard-code parameter values, such as Month or Quarter, into the application. Or you might have parameters whose values change from time to time (e.g., Year). Reporting Services lets you define dynamic parameters such as those based on database queries.
If you have report parameters that will change on each report, you can use the SOAP API and call the GetReportParameters() method to retrieve parameters defined in the report. Listing 5 contains some of the code from the demo application and shows this approach.
The code retrieves parameters for the Employee Sales Summary report using the GetReportParameters() method and populates three list boxes with lists of parameter value descriptions. The GetReportParameters method returns an array of ReportParameter objects. Each object contains an array of ValidValue objects in the ValidValues property. The ValidValue object has two properties: Label and Value. Label contains the descriptive name (e.g., January, February), and Value contains the internal value that the report uses (e.g., 1,2). The internal value often contains numbers, codes, or database IDs.
Be careful when you use the Label property in code. If you define a report parameter with the same value for both the Value and Label fields, the GetReportParameters() method populates the Value property but not the Label property.You then might get an error if you try to use the label in the code, because its value is null. Listing 5 shows how you can safely handle this concern in code. The Year parameter in the report is defined with the same value for both Label and Value (e.g., 2002, 2003). Because you'd get an error if you tried to use Label, the code that populates theYear list box checks the Label property. When that property isn't null, the code uses its value; otherwise it uses the Value property's value, as the code at callout B in Listing 5 shows.
When you use the GetReportParameters() method to retrieve valid parameter values and one or more parameters are based on queries, make sure you set the Boolean value of the ForRendering parameter to true. Otherwise, the method won't run the query that retrieves valid values for the query-based parameter and the internal value of ValidValues will be null, which can lead to errors in your application if your code tries to access those values. Because the Employee parameter in Listing 5 is based on a query, the code sets the value of ForRendering to true before calling GetReportParameters(), as you can see at callout A.
If your report uses hierarchical parameters, you must add code to retrieve all combinations of valid parameter values. Hierarchical parameters, where the value of the parent parameter determines which values are valid for the child parameter, are a feature of Reporting Services. For example, suppose you have a report where the first parameter holds a list of regions within the United States and the second parameter holds a list of states within each region. You can define a hierarchical relationship between these two parameters so that when you view the report and change the value in the region list, Report Manager automatically refreshes the screen and shows only the states that belong to the selected region.
Prev. page
1
[2]
3
next page 
