JsonDataSource Class
The read-only data source that retrieves and provides JSON data.
Namespace: DevExpress.DataAccess.Json
Assembly: DevExpress.DataAccess.v24.1.dll
NuGet Packages: DevExpress.DataAccess, DevExpress.Win.PivotGrid, DevExpress.Win.TreeMap
Declaration
[ToolboxBitmap(typeof(JsonDataSource), "JsonDataSource.bmp")]
[ToolboxSvgImage("DevExpress.DataAccess.Images.JsonDataSource.svg,DevExpress.DataAccess.v24.1, Version=24.1.99.0, Culture=neutral, PublicKeyToken=c38a27d2243c2672")]
[ToolboxTabName("DX.24.1: Data & Analytics")]
[XRDesigner("DevExpress.DataAccess.UI.Design.XRJsonDataSourceDesigner,DevExpress.DataAccess.v24.1.UI, Version=24.1.99.0, Culture=neutral, PublicKeyToken=c38a27d2243c2672", typeof(IDesigner))]
public class JsonDataSource :
DataComponentBase,
ITypedList,
IListAdapter,
IList,
ICollection,
IEnumerable,
IBindingList,
ISupportFillAsync,
IListAdapterAsync,
IDynamicLookupSettingsDataProviderRemarks
The JsonDataSource class allows you to obtain JSON data from a web service endpoint, text file, or JSON string. Use this class in Reports or WinForms data-aware controls (for instance, Data Grid) to provide JSON data to them.
Note
In Dashboards, use the DashboardJsonDataSource component instead.
JsonDataSource and DashboardJsonDataSource are read-only data sources.
You can create a JsonDataSource object at design time or at runtime.
Design Time
Use one of the options below to create a JsonDataSource.
Add the JsonDataSource** component from the Toolbox (for WinForms controls)
See the Bind to JSON Data at Design Time section for more information.
Invoke the Data Source Configuration Wizard (for WinForms controls)
See the Bind WinForms Controls to JSON Data topic for more information.
Invoke the Report Data Source Wizard (for XtraReports)
The Report Data Source Wizard allows you to specify the JSON data location, configure parameters, and customize the schema.
Report Data Source Wizard - Select JSON Data Source.
Report Data Source Wizard - Specify JSON Data Location.
Report Data Source Wizard - Configure the Endpoint Request.
Report Data Source Wizard - Save the Connection String.
Report Data Source Wizard - Specify the Schema.
See the Bind a Report to JSON Data topic for more information.
After a JsonDataSource class instance is created, you can access and customize this instance in the Properties window.
Runtime
Follow the steps below to configure a JsonDataSource class instance:
Use the JsonDataSource.JsonSource property to specify the JSON data location.
(Optionally) Use the JsonDataSource.Schema property to specify from which JSON nodes to retrieve data.
Use the JsonDataSource.Fill or JsonDataSource.FillAsync method to fill the JsonDataSource with data. Handle the FillError event (or catch the JsonDataSourceException exception) to ensure that the data source has been populated successfully.
The code sample below illustrates how to retrieve 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"));
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;
}
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;
}
See also:
- Bind a Report to JSON Data (Runtime Sample)
- Provide Authentication to Access JSON Data (Runtime Sample)
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.