Migrate from Data Grid to Grid
- 10 minutes to read
Why Are There Two Grid Components?
We released a new Grid component to replace the existing Data Grid. For more information on the new component’s current status, our future plans, and reasons for the change, refer to the following blog post: A New Blazor Grid Control (Preview).
Should I Switch to the New Component?
An update is not necessary if you work on a project that is almost finished and you do not expect major changes in the future.
Upgrade to the new Grid component in the following cases:
- If you start a new project.
- If you work on a project that uses the Data Grid component and you plan to actively develop it for a year or longer.
You can review the feature comparison table below. Each component includes features not available in their counterpart.
Feature Comparison
The following table compares the two components. Note that we continue to add functionality to the new component. We plan to replicate all the functionality available in the older control.
Bind to Data | New Grid | Data Grid |
|---|---|---|
Bind to Data Synchronously |
|
|
Bind to Data Asynchronously |
|
|
Large Datasets |
|
|
Large Datasets from an HTTP Service |
|
|
Unbound Columns |
|
|
Columns | New Grid | Data Grid |
Data Columns |
|
|
Command Column |
|
|
Reorder Columns |
|
|
Resize Columns |
|
|
Column Chooser |
|
|
Edit Data | New Grid | Data Grid |
Edit Data |
|
|
Validate Input |
|
|
Shape Data | New Grid | Data Grid |
Sort Data by Value |
|
|
Sort Data by Display Text |
|
|
Custom Sorting |
|
|
Group Data |
|
|
Interval Grouping |
|
|
Custom Grouping |
|
|
Total and Group Summary |
|
|
Custom Total and Group Summary |
|
|
Filter Row |
|
|
Batch Modifications |
|
|
Selection and Navigation | New Grid | Data Grid |
Row Selection |
|
|
Paging |
|
|
Horizontal and Vertical Scrolling |
|
|
Virtual Scrolling |
|
|
Handle a Row Click |
|
|
Appearance | New Grid | Data Grid |
Theme Support |
|
|
Custom Display Text |
|
|
Column Header Caption Template |
|
|
Column Cell Display Template |
|
|
Column Footer Template |
|
|
Column Group Row Template |
|
|
Column Group Footer Template |
|
|
Row Preview Template |
|
|
HTML Decoration |
|
|
Hierarchy and Layout | New Grid | Data Grid |
Master-Detail |
|
|
Save and Load Layout |
|
|
Tools | New Grid | Data Grid |
Toolbar |
|
|
Component Name
Update the component name from DxDataGrid to DxGrid.
<DxDataGrid>
@*...*@
</DxDataGrid>
<DxGrid>
@*...*@
</DxGrid>
Bind to Data Synchronously
You do not need to update your code if you bind the Data Grid to a data collection that is loaded synchronously. The Data Grid includes the DxDataGrid.Data property for synchronous data binding. The new Grid contains the property with the same name: DxGrid.Data.
<DxDataGrid Data="@Data">
@*...*@
</DxDataGrid>
@code {
IEnumerable<WeatherForecast> Data;
// ...
protected override void OnInitialized() {
Data = GetForecast();
}
}
<DxGrid Data="@Data">
@*...*@
</DxGrid>
@code {
IEnumerable<WeatherForecast> Data;
// ...
protected override void OnInitialized() {
Data = GetForecast();
}
}
Bind to Data Asynchronously
Before
The DxDataGrid.DataAsync property binds the component to a data collection that is loaded asynchronously. This property specifies an asynchronous function that returns a Task<IEnumerable<T>> object and accepts a CancellationToken object as a parameter.
@using System.Threading
<DxDataGrid DataAsync="@LoadDataAsync">
@*...*@
</DxDataGrid>
@code {
async Task<IEnumerable<WeatherForecast>> LoadDataAsync(CancellationToken token) {
return await WeatherForecastService.GetForecastAsync();
}
}
After
The new Grid has no equivalent for the DataAsync property, but you can use the DxGrid.Data property instead. Bind this property to a model field and initialize this field with data in the OnInitializeAsync lifecycle method.
<DxGrid Data="@Data">
@*...*@
</DxGrid>
@code {
object Data { get; set; }
protected override async Task OnInitializedAsync() {
Data = await WeatherForecastService.GetForecastAsync();
}
}
Large Datasets
Before
The current Data Grid can detect an IQueryable<T> collection when you use data binding properties (DxDataGrid.Data, DxDataGrid.DataAsync, or DxDataGrid.CustomData). The Data Grid uses benefits of the corresponding LINQ query providers (such as Entity Framework).
<DxDataGrid DataAsync="@RentInfoDataService.GetQueryableAreaRentInfo">
@*...*@
</DxDataGrid>
After
Use the GridDevExtremeDataSource<T> to enhance data processing performance if the component works with a large IQueryable<T> data collection.
- Create a
GridDevExtremeDataSourceclass instance and pass yourIQueryable<T>data collection as the constructor parameter. - Assign this instance to the DxGrid.Data property.
The data source implementation is based on the DevExtreme.AspNet.Data library. If you use this data source, the Grid loads only data that should be displayed on screen and delegates data processing operations to the database server.
<DxGrid Data="@Data">
@*...*@
</DxGrid>
@code {
object Data { get; set; }
protected override async Task OnInitializedAsync() {
var areaRentInfo = await RentInfoDataService.GetQueryableAreaRentInfo();
Data = new GridDevExtremeDataSource<AreaRentInfo>(areaRentInfo.AsQueryable());
}
}
Large Datasets from HTTP Services
Before
To bind the current Data Grid to a large dataset published as an HTTP service, do the following:
- Create an asynchronous DxDataGrid.CustomData delegate that processes data load options and sends HTTP requests to the specified URI.
- On the service side, implement an API controller and create action methods that use the DevExtreme.AspNet.Data library to return the result.
<DxDataGrid T="@WebApiOrder" CustomData="@LoadOrderData">
@*...*@
</DxDataGrid>
@code {
[Inject] protected HttpClient Client { get; set; }
protected async Task<LoadResult> LoadOrderData(DataSourceLoadOptionsBase options,
CancellationToken cancellationToken)
=> await LoadCustomData("https://js.devexpress.com/Demos/NetCore/api/DataGridWebApi/Orders",
options, cancellationToken);
protected async Task<LoadResult> LoadCustomData(string dataEndpointUri,
DataSourceLoadOptionsBase options, CancellationToken cancellationToken) {
using var response = await Client.GetAsync(options.ConvertToGetRequestUri(dataEndpointUri),
cancellationToken);
response.EnsureSuccessStatusCode();
using var responseStream = await response.Content.ReadAsStreamAsync();
return await JsonSerializer.DeserializeAsync<LoadResult>(responseStream,
cancellationToken: cancellationToken);
}
}
After
When you migrate to the new Grid, you do not need to change the API controller on the service side.
To load data from this service, use the GridDevExtremeDataSource<T> as follows:
- Create a
GridDevExtremeDataSourceclass instance and pass a URL to the service as the constructor parameter. - Assign this instance to the DxGrid.Data property.
The data source implementation is based on the DevExtreme.AspNet.Data library. When you use this data source, the Grid generates an HTTP request with the default parameters and sends it to the service.
<DxGrid Data="@Data">
@*...*@
</DxGrid>
@code {
[Inject] protected HttpClient Client { get; set; }
object Data { get; set; }
protected override async Task OnInitializedAsync() {
Data = new GridDevExtremeDataSource<WebApiOrder>(HttpClient,
"https://js.devexpress.com/Demos/NetCore/api/DataGridWebApi/Orders");
}
}
Columns
Declaration
Before
You can specify columns directly between the <DxDataGrid> and </DxDataGrid> tags. If you define templates (for instance, EditFormTemplate or DetailRowTemplate), you should use the DxDataGrid.Columns property to add columns.
<DxDataGrid Data="@Data">
<DxDataGridColumn ...></DxDataGridColumn>
<DxDataGridSpinEditColumn ...></DxDataGridSpinEditColumn>
@*...*@
</DxDataGrid>
After
Always use the DxGrid.Columns property to declare columns.
<DxGrid Data="@Data">
<Columns>
<DxGridDataColumn ... />
<DxGridDataColumn ... />
@*...*@
</Columns>
</DxGrid>
Column Types
The current Data Grid ships with multiple predefined data column types that correspond to commonly used data types. The new Grid includes a single class for all data types (DxGridDataColumn). Both the current Data Grid and new Grid support a command column.
The following table explains how to update columns when you migrate to the new Grid:
Data Grid | New Grid |
|---|---|
Use the DxGridDataColumn instead. | |
Use the DxGridDataColumn instead. | |
Use the DxGridDataColumn instead. | |
To imitate a look-up column, you can create an unbound DxGridDataColumn and handle the UnboundColumnData event to load column data. | |
You can use the DxGridDataColumn to display Boolean values as plain text without checkboxes or specify the CellDisplayTemplate to display checkboxes. | |
Use the DxGridCommandColumn instead. It contains only the Clear button. The Grid does not currently support data editing. |
Main Column Properties
The table below maps column properties available in the Data Grid and Grid components.
Data Grid | New Grid |
|---|---|
DisplayFormat or CustomizeCellDisplayText event | |
- | |
- | |
Editing-related properties | - |
Sorting-related properties | See Sort Data |
Grouping-related properties | See Group Data |
<DxDataGrid Data="@Data">
<DxDataGridDateEditColumn Field="Date" DisplayFormat="D" />
<DxDataGridSpinEditColumn Field="TemperatureC" Caption="@("Temp. (\x2103)")" Width="120px"
TextAlignment="DataGridTextAlign.Left" />
@*...*@
</DxDataGrid>
<DxGrid Data="@Data">
<Columns>
<DxGridDataColumn FieldName="Date" DisplayFormat="D" />
<DxGridDataColumn FieldName="TemperatureC" Caption="@("Temp. (\x2103)")" Width="120px" />
@*...*@
</Columns>
</DxGrid>
Sort Data
The current Data Grid and new Grid include similar sorting-related API. You only need to replace the DataGridColumnSortOrder enumeration with the GridColumnSortOrder enumeration for the SortOrder property.
Data Grid | New Grid |
|---|---|
|
(Accepts DataGridColumnSortOrder enum values) |
(Accepts GridColumnSortOrder enum values) |
<DxDataGrid Data="@Data" AllowSort="false">
<DxDataGridDateEditColumn Field="Date" DisplayFormat="D"
AllowSort="true"
SortOrder="DataGridColumnSortOrder.Descending"
SortIndex="0" />
@*...*@
</DxDataGrid>
<DxGrid Data="@Data" AllowSort="false">
<DxGridDataColumn FieldName="Date" DisplayFormat="D"
AllowSort="true"
SortOrder="GridColumnSortOrder.Descending"
SortIndex="0" />
@*...*@
</DxDataGrid>
Group Data
If you disable grouping in the entire Grid, replace the DxDataGrid.AllowColumnDragDrop property with the DxGrid.AllowGroup property. Use other grouping-related API without changes.
Data Grid | New Grid |
|---|---|
<DxDataGrid Data="@Data"
AllowColumnDragDrop="false"
ShowGroupPanel="true">
<DxDataGridDateEditColumn Field="Date" DisplayFormat="D"
AllowGroup="true"
GroupIndex="0" />
@*...*@
</DxDataGrid>
<DxGrid Data="@Data"
AllowGroup="false"
ShowGroupPanel="true">
<DxGridDataColumn FieldName="Date" DisplayFormat="D"
AllowGroup="true"
GroupIndex="0" />
@*...*@
</DxDataGrid>
Filter Row
Before
To display the filter row in the current Data Grid, enable the DxDataGrid.ShowFilterRow option. The filter row displays different in-place editors based on the column types. For more information, refer to the ShowFilterRow property description.
To prevent users from filtering data by individual columns, set their AllowFilter property to false.
<DxDataGrid Data="@DataSource"
ShowFilterRow="true">
@*...*@
<DxDataGridDateEditColumn Field="Date" DisplayFormat="D" />
<DxGridDataColumn Field="TemperatureC" Caption="@("Temp. (\x2103)")" Width="120px"
AllowFilter="false"/>
@*...*@
</DxDataGrid>
After
To display the filter row in the new Grid, enable the property with the same name: DxGrid.ShowFilterRow. The filter row displays a predefined text editor for all data columns. To display a custom editor in the filter row cell, define the FilterRowCellTemplate.
To prevent users from filtering data by individual columns, set their FilterRowEditorVisible property to false.
<DxGrid Data="@DataSource"
ShowFilterRow="true">
<Columns>
<DxGridDataColumn FieldName="Date" DisplayFormat="D">
<FilterRowCellTemplate>
<DxDateEdit Date="(DateTime?)context.FilterRowValue"
DateChanged="(DateTime? v) => context.FilterRowValue = v"
ClearButtonDisplayMode="DataEditorClearButtonDisplayMode.Auto" />
</FilterRowCellTemplate>
</DxGridDataColumn>
<DxGridDataColumn FieldName="TemperatureC" Caption="@("Temp. (\x2103)")" Width="120px"
FilterRowEditorVisible="false"/>
@*...*@
</Columns>
@*...*@
</DxGrid>
Summary
The new Grid, like the current Data Grid, includes the TotalSummary and GroupSummary properties used to add summary items. You should replace DxDataGridSummaryItem objects with DxGridSummaryItem objects, and update item properties as shown in the table below.
Data Grid | New Grid |
|---|---|
DxDataGridSummaryItem | DxGridSummaryItem |
|---|---|
|
(Accepts SummaryItemType enum values) |
(Accepts GridSummaryItemType enum values) |
- | |
- | |
<DxDataGrid Data="@Data" >
@*...*@
<TotalSummary>
<DxDataGridSummaryItem Field="Date"
SummaryType=SummaryItemType.Min
DisplayFormat="First: {0:D}"/>
<DxDataGridSummaryItem ShowInColumn="TemperatureC"
SummaryType=SummaryItemType.Count/>
</TotalSummary>
</DxDataGrid>
<DxGrid Data="@Data" >
@*...*@
<TotalSummary>
<DxGridSummaryItem FieldName="Date"
SummaryType=GridSummaryItemType.Min
ValueDisplayFormat="D"/>
<DxGridSummaryItem FooterColumnName="TemperatureC"
SummaryType=GridSummaryItemType.Count/>
</TotalSummary>
</DxDataGrid>
Paging
You do not need to update the code if you use the DxDataGrid.PageSize or DxDataGrid.PageIndex property. The new Grid includes the same DxGrid.PageSize or DxGrid.PageIndex properties.
The new Grid does not currently support other paging-related properties available in the Data Grid (for instance, PagerNavigationMode, ShowPager, and so on).
<DxDataGrid Data="@Data"
PageSize="7"
PagerNavigationMode="PagerNavigationMode.InputBox">
@*...*@
</DxDataGrid>
<DxGrid Data="@Data"
PageSize="7">
@*...*@
</DxGrid>
Column Display Template
Before
Use a column’s DisplayTemplate property. The Context parameter return a processed data item.
<DxDataGrid Data="@Data">
<DxDataGridColumn Field="Date">
<DisplayTemplate>
var inStock = (context as Product).Availability;
@*...*@
</DisplayTemplate>
</DxDataGridColumn>
@*...*@
</DxDataGrid>
After
Use the DxGridDataColumn.CellDisplayTemplate property. The Context parameter returns a GridDataColumnCellDisplayTemplateContext object. To obtain a field value, call the GetRowValue(String) method.
<DxGrid Data="@Data" >
<Columns>
<DxGridDataColumn FieldName="Date">
<CellDisplayTemplate>
var inStock = context.GetRowValue("Availability");
@*...*@
</CellDisplayTemplate>
</DxGridDataColumn>
</Columns>
@*...*@
</DxGrid>
The new Grid currently has no alternative for the DxDataGridColumn.EditTemplate and DxDataGrid.RowPreviewTemplate supported in the Data Grid.