Dataset Provider

Use the API to set a dataset on a report at run time. The Dataset provider returns a data table. All fields in the data table are available. To use the Dataset provider as a report's data source, set up a ReportDefinition and a ReportRuntime, and attach the ReportRuntime to a LocateDataSourceEventHandler.

Show Click to show or hide the code sample

//C# (See the DatasetDataSource sample for more context.)
private void LoadReport()
{
	FileInfo rptPath = new FileInfo(@"..\..\ReportFromDataSet.rdlx");
	//Create a report definition that loads an existing report.
	ReportDefinition definition = new ReportDefinition(rptPath);
	//Load the report definition into a new report runtime.
	ReportRuntime runtime = new ReportRuntime(definition);
	//Attach the runtime to an event. This line of code creates the event shell below.
	runtime.LocateDataSource += new LocateDataSourceEventHandler(runtime_LocateDataSource);
	previewControl.OpenReport(runtime, "DataSet Data Source");
}

private bool StringsAreEqual(string str1, string str2)
{
	//Allow for language-specific variances in strings.
	return string.Compare(str1, str2, true, CultureInfo.InvariantCulture) == 0;
}

//Data Dynamics Reports raises this event when it cannot locate a report's data 
//source in the usual ways.
private void runtime_LocateDataSource(object sender, LocateDataSourceEventArgs args)
{
	object data = null;
	string dataSetName = args.DataSetName;
	string dataSourceName = args.DataSourceName;
	//Select which table to return.
	if (StringsAreEqual("DataSetDataSource", dataSourceName))
	{
		if (StringsAreEqual("ProductsDataSet", dataSetName))
			data = dataLayer.Data.Tables["Products"];
		else if (StringsAreEqual("DataSet1", dataSetName))
			data = dataLayer.Data.Tables["Sales"];
	}
	args.Data = data;
}

Parent Table Fields

To request a field from a parent table, prefix the field name with the name of the relation(s) that must be traversed to navigate to the appropriate parent table. Separate field names and relations with periods.

For example, consider a main table named OrderDetails which has a parent table named Orders. A Relation named Orders_OrderDetails defines the relationship between the two tables. Use a field with the syntax below to access the OrderDate from the parent table:

Orders_OrderDetails.OrderDate

Use this same technique to traverse multiple levels of table relations. For example, consider that the Orders table used in the prior example has a parent table named Customers and a relation binding the two called Customers_Orders. If the CommandText specifies the main table as OrderDetails, use the following syntax to get the CustomerName field from the parent table:

Customers_Orders.Orders_OrderDetails.CustomerName

Note: Ambiguity can occur if a field and a relation have the same name. This is not supported.

Dataset Provider Use Cases

When using the Dataset provider, the Connection String and Query need to be set to certain values depending on how you are connecting to the report data.

To use the LocateDataSource event to bind the report data, leave the Connection String blank.
- If LocateDataSource returns a Data Set, the Query is set to the table name of the Data Set.
- If LocateDataSource returns either a Data Table or Data View, the Query is left blank.
To bind the report data to a Data Set located in a file, set the Connection String to the path on the file system where the file is located. The Query is set to the table name of the Data Set.

Limitations of the Dataset Provider

Relationship names that have periods in them are not supported.
Fields in nested relationships will only traverse parent relationships (e.g. FK_Order_Details_Orders.FK_Orders_Customers.CompanyName).

Object Provider

Use the API to bind a report data source to a collection of objects via the IEnumerable interface. The Object provider returns an IEnumerable collection. To use the Object provider as a report's data source, set up a ReportDefinition and a ReportRuntime, and attach the ReportRuntime to a LocateDataSourceEventHandler. Create a public class which sets up a property name to which the DataField can bind.

Show Click to show or hide the code sample

' VB.NET
' This code assumes a Windows form project with a ReportPreview control
' and a report named DogReport.rdlx.
Imports DataDynamics.Reports
Public Class Form1

    Inherits System.Windows.Forms.Form

#Region " Windows Form Designer generated code "
' Leave this code intact.
#End Region

' Create a class from which to call a property.
    Public Class dog
        Private _name As String
        Public Property name() As String
            Get
                Return _name
            End Get
            Set(ByVal Value As String)
                _name = Value
            End Set
        End Property
    End Class

' Create an array to contain the data.
    Dim dogArray As System.Collections.ArrayList

' Create a method to populate the data array.
    Private Sub LoadData()
        dogArray = New ArrayList
        Dim dog1 As New dog
        dog1.name = "border collie"
        dogArray.Add(dog1)
        dog1 = New dog
        dog1.name = "cocker spaniel"
        dogArray.Add(dog1)
        dog1 = New dog
        dog1.name = "golden retriever"
        dogArray.Add(dog1)
        dog1 = New dog
        dog1.name = "shar pei"
        dogArray.Add(dog1)
    End Sub

' Add code to the form load event to set up the report 
' and to add a handler for the LocateDataSource event.
    Private Sub Form1_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Load
        ' Create file info with a path to the report in your project.
        Dim fi As New System.IO.FileInfo("..\DogReport.rdlx")
        ' Create a report definition using the file info.
        Dim repDef As New ReportDefinition(fi)
        ' Create a report runtime using the report definition.
        Dim runt As New ReportRuntime(repDef)
        ' Create a LocateDataSource event for the runtime.
        AddHandler runt.LocateDataSource, AddressOf runt_LocateDataSource
        ' Display the report in the viewer. The title can be any text.
        Me.ReportPreview1.OpenReport(runt, "Dog Report")
    End Sub

' Use the LocateDataSource event to load the data from the object.
    Private Sub runt_LocateDataSource(ByVal sender As Object, ByVal args As LocateDataSourceEventArgs)
        If dogArray Is Nothing Then
            LoadData()
        End If
        args.Data = dogArray
    End Function

End Class

Object Provider Use Cases

When using the Object provider, the Connection String of the report will always be left blank as it will be using the LocateDataSource event to bind to an Object. The Query will then be set to one of three different values:

A public property name on the object provided.
A public method name on the object provided.
Blank if the object itself is to be used.

Note: The object itself only needs to be IEnumerable if the Query is left blank, if using either a property or method in the object that property or method must be IEnumerable.

Limitations of the Object Provider

Only public properties with no parameters can be used for fields.
The CommandText must be set to a Property or Method with no parameters that returns an IEnumerable object.

XML Provider

The XML provider binds the report to XML data. The report's Connection String is created using one (or more) of the following elements:

XmlDoc - refers to a specific XML file located on either the file system or in a web-accessible location.
XmlData - provides specific XML data in the Connection String itself.
TransformationDoc - refers to a specific XSLT file to apply to the XML data.

Note: The Connection String requires either XmlDoc or XmlData; use of TransformationDoc is optional. Elements in the Connection String need to be terminated with the semicolon (;) character.

Example Using XmlDoc

XmlDoc=C:\MyXmlFile.xml;

Example Using XmlData

XmlData=<people>
<person>
    <name>
      <given>John</given>
      <family>Doe</family>
    </name>
</person>
<person>
    <name>
      <given>Jane</given>
      <family>Smith</family>
    </name>
</person>
</people>;

Querying for XML Data

The XML provider supports the use of XPath 1.0 in building queries and selecting Fields. Using the XmlData example above, a query that can be used would be the following:

/people/person/name

Once this query is set, the next step is to build the Fields collection. The Fields collection using the above information would look like this:

Field Name	Type	Value
Given	Database Field	given
Family	Database Field	family

Samples

Within Visual Studio, you can use the API to provide data at run time. A DataSetDataSource sample is included with this installation that demonstrates how this may be done.

You can also create a custom data provider. See the included CustomDataProvider sample for details.

Both samples may be found in the Sample Gallery application under Features > Developers > Report API.

LocateDataSource Event

The reporting engine raises this event when it needs input on the data to use when using either the Dataset, Object, or XML Data Providers. It is always used with the Object Data Provider, and is used by either the Dataset or XML providers when there is no valid Connection String. Custom Data Providers are responsible for initiating this event if necessary.

The event passes in the following arguments:

DataSetName (a string)
DataSourceName (a string)
Report (a report runtime)

Provide the data for the report in the Data property of the event argument.

Data Dynamics Reports Online Help
DataSet, Object and XML Data Providers
See Also Support Forum