Programming the CrystalReportViewer Control

Programming with the viewer has some similarities to programming with the report document, but there differences. From a high level, the viewer is similar to the report object 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 it uses different parameter classes. You’ll find it easier to program parameters using the viewer control than using the report document.

The viewer uses the ParameterFields collection to manage the properties of each parameter in a report. The ParameterFields collection manages the ParameterField object. It is easier to work with the ParameterField object (compared to the ParameterFieldDefinition object of the report document) because the ParameterField object lets you reference the CurrentValues collection directly. This makes more sense conceptually and it saves you some coding.

The viewer also requires you to assign the report object to the ReportSource property first. The viewer examines the report object and builds a list of parameters in the report. It has to build this list before you can reference the individual parameter objects. The last step is to assign a value to the parameter object’s CurrentValues collection.

Programming with the CrystalReportViewer consists of 8 steps:

Declare and instantiate a ReportDocument object variable.
Assign the ReportDocument object to the ReportSource property of the viewer control.
Get a reference to the viewer’s ParameterFields collection.
Get a reference to the ParameterField object you are modifying.
Instantiate a parameter value object. This will either be of the ParameterDiscreteValue class or the ParameterRangeValue class.
Set the properties of the new parameter value object.
Use the Add() method to add the parameter value object to the CurrentValues collection.
Repeat steps 4-6 for each parameter value object.
In Step 4 (getting a reference to the ParameterField object), the parameter name is case sensitive. Passing a string to the ParameterFields[] indexer that doesn’t match the parameter name results in the error System.ArgumentOutOfRange being raised. Note that this rule only applies when using the viewer object. The ParameterFieldDefinitions collection of the ReportDocument class is not case sensitive.

Listing 16-3 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-3. Use the viewer to modify a range parameter.
Dim ParameterFields As CrystalDecisions.Shared.ParameterFields
Dim ParameterField As CrystalDecisions.Shared.ParameterField
Dim ParameterRangeValue As CrystalDecisions.Shared.ParameterRangeValue
'Step 1: Assign the report object to the viewer
Dim MyReport As New CrystalReport1
CrystalReportViewer1.ReportSource = MyReport
'Step 2: Reference the ParameterFields collection
ParameterFields = CrystalReportViewer1.ParameterFieldInfo
'Step 3: Reference the ParameterField object
ParameterField = ParameterFields("DateRange")
'Step 4: Create a ParameterValue object.
'This example uses a RangeValue object
ParameterRangeValue = New CrystalDecisions.Shared.ParameterRangeValue
'Step 5: Assign a value to the object
ParameterRangeValue.StartValue = "1/4/1997"
ParameterRangeValue.EndValue = "2/2/1997"
'Step 6: Add the ParameterValue object to either the
'CurrentValues or DefaultValues collection
ParameterField.CurrentValues.Add(ParameterRangeValue)
If you are programming the viewer control with C#, there is a serious bug you need to be aware of. The ParameterField object model doesn’t expose all the properties and methods that it is supposed to. Many of the properties are hidden and won’t appear when using Intellisense. To fix this you have to declare parameter field variables using the IParameterField interface. If you look at the classes with the Object Browser you’ll see that the ParameterField class implements the IParameterField interface but it doesn’t expose all its properties. Compare the properties of the ParameterField class listed in the Object Browser to the properties listed in the help file you’ll see that they look like totally different classes. Fortunately, the work-around only requires a minor change to the code, but it’s very important nonetheless. See C# Listing 16-3.
Remember that this bug only applies for C# when using the viewer. VB.NET has access to all the documented properties.