Using report parameters in local mode

What are report parameters used for?

The most common use of report parameters is to specify a criterion for subsetting data. The value of the parameter may be set programmatically by the host application, or one report may pass a parameter to another report.

When you drillthrough from one report to another, the main report passes the id of the item the user clicked on to the drillthrough report as a report parameter. The drillthrough report then uses the parameter value to only display data corresponding to the item the user clicked on.

When a master-detail report is implemented using subreports, the main report passes the id of the master item to the subreport as a report parameter. The subreport uses the parameter value to only display detail rows corresponding to the specified master item.

Subsetting data can be done in two ways: (a) The host application can examine the value of the parameter being passed to a subreport or drillthrough report (in the corresponding event handlers) and only supply the subset of data corresponding to the parameter value to ReportViewer. Or (b) the host application can supply the entire data to ReportViewer, and in the RDL file specify a filter that only lets in values that match the parameter value (see screenshot).

Report parameters can be used for other purposes too. In the example below a report parameter is used to control the visiblity of a textbox.

Defining a report parameter

To add a parameter to a report, from the menu choose Report > Report Parameters command. Press Add to add a parameter.

The value of a parameter can be used in expressions as Parameters!Foo.Value where Foo is the name of the parameter.

Parameter Prompting

When operating in remote mode ReportViewer automatically prompts the user for parameter values unless told not to do so.

When operating in local processing mode, ReportViewer does not prompt for parameter values. The rationale is as follows: The most common use of report parameters is to pass to queries as values of query parameters. But unlike the Report Server, the ReportViewer control does not execute queries itself. Rather, queries are executed by the host application, and the result is passed to the ReportViewer control. So the ReportViewer control does not have the opportunity to set query parameters.

In local mode the host application must handle parameter prompting, as seen in the example below.

Example

In the example below, the application (an RSS Browser) has a textbox for specifying news items of interest, and a checkbox for turning descriptions on or off. Note that this textbox, checkbox, the url dropdown and the load button are all implemented by the host application. UI features of the ReportViewer control such as toolbar have been turned off in this application.

The ability to turn descriptions on or off, and the ability to filter news items are implemented using report parameters.

In the RDL the visibility of the description textbox is controlled using a boolean report parameter, like this:

        <Textbox Name="Description">
          <Visibility>
            <Hidden>=not(Parameters!ShowDescriptions.Value)</Hidden>
          </Visibility>
          ....
          ....
        </Textbox>
The host application then sets the value of the ShowDescriptions parameter based on the value of the checkbox, like this:
        private void checkBox1_CheckedChanged(object sender, EventArgs e)
        {
            ReportParameter p = new 
                      ReportParameter("ShowDescriptions", checkBox1.Checked ? "true" : "false");
            this.reportViewer1.LocalReport.SetParameters(new ReportParameter[] { p });
            this.reportViewer1.RefreshReport();
        }

Download source code for this demo application.


Descriptions on

Descriptions off