Bind a Report to JSON Data (Runtime Sample)
- 7 minutes to read
This topic describes how to bind a report to JSON data at runtime.
Tip
Online Example: How to Create a Report Bound to JsonDataSource
Create a JsonDataSource Object
Use the JsonDataSource component to bind a report to JSON-formatted data. You can retrieve data from the Web, a file or text strings.
The code sample below illustrates how to use JSON data from the Web.
using DevExpress.DataAccess.Json;
using DevExpress.XtraReports.UI;
public static JsonDataSource CreateDataSourceFromWeb() {
var jsonDataSource = new JsonDataSource();
// Specify the endpoint.
jsonDataSource.JsonSource = new UriJsonSource(
new Uri("https://raw.githubusercontent.com/DevExpress-Examples/DataSources/master/JSON/customers.json"));
// The schema is built, you do not have to call the Fill method to populate the Field List.
// The Designer calls the Fill method automatically when a document is generated for preview.
//jsonDataSource.Fill();
return jsonDataSource;
}
Tip
You can also provide the created JsonDataSource object with authentication parameters to access the specified Web Endpoint. Refer to the Provide Authentication to Access JSON Data (Runtime Sample) topic for more information.
The code sample below illustrates how to use JSON data from a file.
using DevExpress.DataAccess.Json;
using DevExpress.XtraReports.UI;
// ...
public static JsonDataSource CreateDataSourceFromFile() {
var jsonDataSource = new JsonDataSource();
// Specify the JSON file name.
Uri fileUri = new Uri("customers.json", UriKind.RelativeOrAbsolute);
jsonDataSource.JsonSource = new UriJsonSource(fileUri);
// Populate the data source with data.
jsonDataSource.Fill();
return jsonDataSource;
}
The code sample below illustrates how to use JSON data from a string variable.
using DevExpress.DataAccess.Json;
using DevExpress.XtraReports.UI;
// ...
public static JsonDataSource CreateDataSourceFromText() {
var jsonDataSource = new JsonDataSource();
// Specify a string with JSON data.
string json = "{\"Customers\":[{\"Id\":\"ALFKI\",\"CompanyName\":\"Alfreds Futterkiste\"," +
"\"ContactName\":\"Maria Anders\",\"ContactTitle\":\"Sales Representative\"," +
"\"Address\":\"Obere Str. 57\",\"City\":\"Berlin\",\"PostalCode\":\"12209\"," +
"\"Country\":\"Germany\",\"Phone\":\"030-0074321\",\"Fax\":\"030-0076545\"}]," +
"\"ResponseStatus\":{}}";
// Specify the object that retrieves JSON data.
jsonDataSource.JsonSource = new CustomJsonSource(json);
// Populate the data source with data.
jsonDataSource.Fill();
return jsonDataSource;
}
Use Data Source Parameters
Add path parameters, query parameters, or header parameters to the data source’s UriJsonSource to customize requests to a JSON web service endpoint.
- A path parameter adds a path element to a JSON endpoint’s Uri.
- A query parameter specifies a HTTP request parameter that is passed to a JSON endpoint.
- A header parameter adds a custom HTTP header to JSON endpoint requests.
You can use expressions to set parameter values. Specify an expression in the parameter’s Value property and specify that the parameter’s Type is Expression. Expressions can include report parameters. Prepend the report parameter’s name with the ? character in an expression.
The code sample below specifies a JSON endpoint and uses the date and id path parameters to identify the data record requested from the endpoint. The id parameter is bound to the ID report parameter.
using DevExpress.DataAccess;
using DevExpress.DataAccess.Json;
// ...
// Create a new JSON source.
var jsonSource = new UriJsonSource() {
Uri = new Uri(@"https://localhost:44367/api/values")
};
// Create the "date" and "id" path parameters that are appended to the JSON URI: https://localhost:44367/api/values/date/2020-01-15/id/123/.
jsonSource.PathParameters.AddRange(new[] {
new PathParameter("date", typeof(String), String.Format("{0:yyyy-MM-dd}", DateTime.Today)),
// "ID" is a report parameter whose value is used for the "id" path parameter.
new PathParameter("id", typeof(Expression), new Expression("?ID"))
});
// Assign the JSON source to the data source.
var datasource = new JsonDataSource() {
JsonSource = jsonSource
};
Define JSON Data Schema
You can specify from which JSON nodes to retrieve data. Define a schema and assign it to the JsonDataSource‘s Schema property.
using DevExpress.DataAccess.Json;
using DevExpress.XtraReports.UI;
public static JsonDataSource CreateDataSourceFromWeb() {
var jsonDataSource = new JsonDataSource();
// Specify the endpoint.
jsonDataSource.JsonSource = new UriJsonSource(
new Uri("https://raw.githubusercontent.com/DevExpress-Examples/DataSources/master/JSON/customers.json"));
var root = new JsonSchemaNode();
root.NodeType = JsonNodeType.Object;
var customers = new JsonSchemaNode() {NodeType=JsonNodeType.Array, Name="Customers", Selected=true };
customers.AddChildren(new[] {
new JsonSchemaNode(new JsonNode("CustomerID", true,
JsonNodeType.Property, typeof(string)))
{
DisplayName = "Customer ID" },
new JsonSchemaNode() {
Name = "CompanyName",
Selected = true,
NodeType = JsonNodeType.Property,
Type = typeof(string)
},
new JsonSchemaNode(new JsonNode("ContactTitle", true, JsonNodeType.Property, typeof(string))),
new JsonSchemaNode(new JsonNode("Address", false, JsonNodeType.Property, typeof(string)))
});
root.AddChildren(customers);
jsonDataSource.Schema = root;
// The schema is built, you do not have to call the Fill method to populate the Field List.
// The Designer calls the Fill method automatically when a document is generated for preview.
//jsonDataSource.Fill();
return jsonDataSource;
}
Bind the Report to the JsonDataSource
The following code snippet assigns the JsonDataSource object to the report’s DataSource property:
using DevExpress.DataAccess.Json;
using DevExpress.XtraReports.UI;
private XtraReport CreateReport() {
XtraReport report = new XtraReport() {
Bands = {
new DetailBand() {
Controls = {
new XRLabel() {
ExpressionBindings = {
new ExpressionBinding("BeforePrint", "Text", "[CompanyName]")
},
WidthF = 300
}
},
HeightF = 50
}
},
DataSource = CreateDataSourceFromWeb(),
DataMember = "Customers"
};
return report;
}
Install the Newtonsoft.json Package
The JsonDataSource object uses the open source Newtonsoft.Json library for .NET Framework platforms. Install the Newtonsoft.Json package if your application does not reference this library.
For .NET 6+ platforms, JsonDataSource uses System.Text.Json. Set the DevExpress.DataAccess.Native.Json.JsonLoaderHelper.ProcessingLibrary property to NewtonsoftJson to use the Newtonsoft.Json library instead.
Preview and Publish the Report
You can now call the CreateReport() function and invoke the End-User Report Designer with the created report. Refer to the following topics for instructions on how to do this in different platforms:
