Programming the CrystalReportViewer Control

As mentioned earlier in this chapter, the viewer control should only be used to modify the display properties of the viewer and shouldn’t be relied upon to make report changes. However, the viewer does have this functionality built into it, so we’ll cover it here so that you know how to use it if the need arises.

Programming with the viewer has some similarities to programming with the ReportDocument class, but there are differences. From a high level, the viewer is similar because you have to get a reference to the parameter object and assign a value to its CurrentValues collection. From an implementation standpoint, the viewer is different because the names of the parameter classes are different.

The viewer is also different in how you assign the current/default value collection. It requires that you override the existing values collection with the new values collection. The ReportDocument class has you call the ApplyCurrentValue() method to do this.

The viewer uses the ParameterFields collection to manage the properties of each parameter in a report. The ParameterFields collection manages the ParameterField object.

Programming with the CrystalReportViewer consists of 8 steps:

Assign the report to the ReportSource property of the viewer.
Get a reference to the ParameterField object via the ParameterFieldInfo collection.
Instantiate a parameter value object. This will either be the ParameterDiscreteValue class or the ParameterRangeValue class.
Set the properties of the new parameter value object.
Use the ParameterValues.Add() method to add the parameter value to collection of values.
Override the CurrentValues collection with the new ParameterValues collection.
In Step 2 (getting a reference to the ParameterField object), if you are using the viewer object and programming in C#, then the parameter name is case sensitive. Passing a string to the ParameterFieldInfo() indexer that doesn’t match the parameter name casing results in the error System.ArgumentOutOfRange being raised.

Listing 16-8 illustrates these steps. It creates a parameter that is a range value and assigns it to the CurrentValues collection. The in-line comments explain the steps that are taking place.

Listing 16-8. Use the viewer to modify a range parameter.
[VB.NET]
Dim myParameterValues as New CrystalDecisions.Shared.ParameterValues
Dim myParameterField As CrystalDecisions.Shared.ParameterField
Dim myParameterRangeValue As CrystalDecisions.Shared.ParameterRangeValue
'Step 1: Assign the report object to the viewer
CrystalReportViewer1.ReportSource = Server.MapPath("Invoice.rpt")
'Step 2: Reference the ParameterField object
myParameterField = CrystalReportViewer1.ParameterFieldInfo("DateRange")
'Step 3: Create a ParameterValue object.
myParameterRangeValue = New CrystalDecisions.Shared.ParameterRangeValue
'Step 4: Assign a value to the object
myParameterRangeValue.StartValue = DateTime.Parse("1/4/1997")
myParameterRangeValue.EndValue = DateTime.Parse("2/2/1997")
'Step 5: Add the ParameterValue object to the values collection
myParameterValues.Add(myParameterRangeValue)
'Step 6: Override the CurrentValues collection with the new values collection
myParameterField.CurrentValues = myParameterRangeValue
[C#]
CrystalDecisions.Shared.ParameterFields ParameterFields;
CrystalDecisions.Shared.IParameterField ParameterField;
CrystalDecisions.Shared.ParameterRangeValue ParameterRangeValue;
//Step 1: Assign the report object to the viewer
CrystalReportViewer1.ReportSource = Server.MapPath("Invoice.rpt");
//Step 2: Reference the ParameterField object
ParameterFields = crystalReportViewer1.ParameterFieldInfo["DateRange"];
//Step 3: Create a ParameterValue object
ParameterRangeValue = new CrystalDecisions.Shared.ParameterRangeValue();
//Step 4: Assign a value to the object
ParameterRangeValue.StartValue = DateTime.Parse("1/4/1997");
ParameterRangeValue.EndValue = DateTime.Parse("1/20/1997");
//Step 6: Override the CurrentValues collection with the new values collection
ParameterField.CurrentValues = ParameterRangeValue;