Working with Report Parameters

Report parameters are encapsulated by two classes: The ParameterValue class allows developers to set and retrieve report parameter values and the ReportParameter class is used to Get and Set properties of a parameter. Both ParameterValue and ReportParameter are necessary to get complete information about a parameter. However, the ParameterValue class is sufficient to set and retrieve values of a parameter. The following code snippet shows how to pass parameters to render a function. You can incorporate this code into the GetReportXML2005() function written earlier in this chapter by replacing the inside of the TRy block with the following code:

 ParameterValue[] parameters = new ParameterValue[1]; parameters[0] = new ParameterValue(); parameters[0].Name = "SalesOrderNumber"; parameters[0].Value = "SO43659"; rs.SetExecutionParameters(parameters, "en-us"); result = rs.Render(format, devInfo, out extension,                     out encoding, out mimeType,                     out warnings, out streamIDs); return System.Text.Encoding.ASCII.GetString(result); 

In the previous example, you can see two out of three string properties of the ParameterValue class: Name and Value . The third property is a Label and is used as an alternate name for a parameter.

Note the usage of the SetExecutionParameters() function that assigns the parameter and parameter's language (because this is optional, you can pass null ) to the current execution of a report.

ReportParameter is used in conjunction with GeTReportParameters() and SetReportParameters() . GeTReportParameters() retrieves a report's parameters properties ( ReportParameter class) and can validate if an array of ParameterValue values passed to this function are acceptable for a report; SetReportParameters() sets properties of parameters. Commonly used public properties of the ReportParameter class are outlined in Table 25.2.

Table 25.2. Commonly Used Public Properties of the ReportParameter Class

Name	Description
AllowBlank	Indicates whether an empty string is a valid value for the parameter
DefaultValues	Gets or sets the default value of the parameter
DefaultValuesQueryBased	Indicates whether the default values of the parameter are based on a query
ErrorMessage	Indicates the error message returned when a parameter value has failed Validation
MultiValue	Indicates whether the parameter is a multivalued parameter
Name	Gets or sets the name of a parameter
Nullable	Indicates whether the value of the parameter can be null
Prompt	Gets or sets the text that prompts the user for parameter values
PromptUser	Indicates whether the user is prompted for the value of the parameter
QueryParameter	Indicates whether the parameter is used in a query
ValidValues	Indicates the available ValidValues objects for the parameter
ValidValuesQueryBased	Indicates whether the parameter's valid values are based on a query

As you can probably tell, the ReportParameter class properties directly correspond to the report parameter properties that were set during the design phase. See Chapter 10, "Report Parameters."