DxComboBoxSettings.KeyFieldName Property

Specifies the key field used for data item identification when the list editor uses a business object as a value.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.v26.1.dll

Declaration

[DefaultValue(null)]
[Parameter]
public string KeyFieldName { get; set; }

Property Value

Type	Default	Description
String	null	The key field name.

Remarks

When you use the Data property to bind the editor to a data collection (Data) that stores business objects (IEnumerable<CustomType>) and you specify a business object in the Value property, set the KeyFieldName or KeyFieldNames property. The component uses the specified key fields to identify and compare data items.

If you do not specify key fields, a combo box editor uses standard .NET value equality comparison to identify and compare data items. In this case, you should override object type’s Equals and GetHashCode methods to ensure correct identification of objects. However, the best way to identify objects is to use KeyFieldName and KeyFieldNames properties.

The following code specifies the CustomerId field as a key:

<DxGrid Data="@Orders" ShowFilterRow="true" PageSize="10">
    <Columns>
        <DxGridDataColumn FieldName="@nameof(OrderLite.OrderId)" Caption="Order ID" Width="20%" />
        <DxGridDataColumn FieldName="@nameof(OrderLite.OrderDate)" DisplayFormat="d" Width="20%" />
        <DxGridDataColumn FieldName="@nameof(OrderLite.Customer)" Caption="Customer">
            <EditSettings>
                <DxComboBoxSettings Data="@Customers"
                                    KeyFieldName="@nameof(CustomerLite.CustomerId)"
                                    TextFieldName="@nameof(CustomerLite.CompanyName)" />
            </EditSettings>
        </DxGridDataColumn>
    </Columns>
</DxGrid>

@code {
    IReadOnlyList<OrderLite> Orders { get; }

    IReadOnlyList<CustomerLite> Customers { get; } = new CustomerLite[] {
        new() { CustomerId = "ALFKI", CompanyName = "Alfreds Futterkiste" },
        new() { CustomerId = "BERGS", CompanyName = "Berglunds snabbköp" },
        new() { CustomerId = "CHOPS", CompanyName = "Chop-suey Chinese" },
    };

    public KeyFieldNameSettings() {
        Orders = new OrderLite[] {
            new(1, new DateTime(2024, 1, 15), Customers[0]),
            new(2, new DateTime(2024, 1, 20), Customers[1]),
            new(3, new DateTime(2024, 2, 1),  Customers[0]),
            new(4, new DateTime(2024, 2, 10), Customers[2]),
            new(5, new DateTime(2024, 3, 5),  Customers[1]),
            new(6, new DateTime(2024, 3, 12), Customers[0]),
        };
    }

    class CustomerLite : IEquatable<CustomerLite> {
        public string CustomerId { get; init; }
        public string CompanyName { get; init; }
        public bool Equals(CustomerLite other) => other is not null && CustomerId == other.CustomerId;
        public override bool Equals(object obj) => Equals(obj as CustomerLite);
        public override int GetHashCode() => CustomerId?.GetHashCode() ?? 0;
        public override string ToString() => CompanyName;
    }

    record OrderLite(int OrderId, DateTime OrderDate, CustomerLite Customer);
}

Implements

KeyFieldName