Data Annotation Attributes

Jul 02, 2024
13 minutes to read

DevExpress data-aware controls (GridControl, TreeList, VGridControl, PropertyGridControl and Data Layout Control) support Microsoft Data Annotation Attributes. You can apply data annotation attributes when creating a data source in code. Grid and treelist controls bound to such data sources recognize the attributes and automatically tweak columns - re-arrange columns, change header captions, apply filters, format and validate cell values, etc.

Note

A repository item assigned to a column overrides settings specified by Data Annotation Attributes.

For the Data Layout Control, even more complex UI customization is supported - certain data attributes not only allow you to apply display formats and validation rules, but to group layout items into specific groups and tabbed containers. See the Data Annotation Attributes in Data Layout Control topic to learn more.

To see a complete Data Annotation Attributes list, see this MSDN article. The tables below list the most common and frequently used attributes supported by the Grid Control and TreeList Control.

Data Display Attributes

Attribute	Parameter (if any)	Description
	Code Sample
Display	Name	Specifies the column caption for the auto-generated column. This attribute has no effect on columns created at design-time. Column captions set by this attribute can be overridden by using the GridColumn.Caption property.
	Example 1 C# VB.NET `[Display(ShortName = "Company", Name = "Company Name")] public string CompanyName { get; set; }` Example 2 (Enum Properties) C# VB.NET `[EnumDataType(typeof(ProductCategory))] public int Category { get; set; } public enum ProductCategory { Beverages = 1, Fruit = 2, Vegetables = 3, Meat = 4, Condiments = 5, Confections = 6, [Display(Name = "Dairy Products")] DairyProducts = 7, [Display(Name = "Grains Cereals")] GrainsCereals = 8, Seafood = 9 }`
	AutoGenerateField	Specifies whether a control automatically generates a column for this field.
	C# VB.NET `[Display(AutoGenerateField = false, Description = "This column isn't created")] public string AdditionalInfo { get; set; }`
	AutoGenerateFilter	Specifies whether the filter UI is automatically generated for this field. Applies to automatically generated columns only. If a column is created manually, use the OptionsColumnFilter.AllowFilter property to generate the filter UI for that column.
	C# VB.NET `[Display(AutoGenerateFilter = false)] public string Email { get; set; }`
	Order	Specifies the display order for this column (see the GridColumn.VisibleIndex property). Can be set to -1 to hide this column.
	C# VB.NET `[Display(Order = 2)] public string Country { get; set; } [Display(Order = 1)] public string City { get; set; }`
	Description	Assigns a tool-tip to this column. The GridColumn.ToolTip property overrides this attribute description.
	C# VB.NET `[Display(Description = "The amount of currently available product")] public int Quantity { get; set; }`
Editable	Specifies whether this column can be edited (see the OptionsColumn.AllowEdit property).
	C# VB.NET `[Editable(false)] public string City { get; set; }`
ReadOnly	Gets or sets whether this column is in read only mode (OptionsColumn.ReadOnly).
	C# VB.NET `[ReadOnly(true)] public double UnitPrice { get; set; }`
DisplayFormat	DataFormatString	Specifies the display format for this column’s records.
	C# VB.NET `[DisplayFormat(DataFormatString = "MMMM/yyyy")] public object Date2 { get; set; }`
	ApplyFormatInEditMode	Specifies whether the current display format for this cell should remain visible when this cell is being edited.
	C# VB.NET `[DisplayFormat(DataFormatString = "p", ApplyFormatInEditMode = true)] public object SalesVsTarget { get; set; }`
ResourceType	Allows you to specify a value from a resx file to show localized captions. C# VB.NET `[Display(ResourceType = typeof(Properties.Resources), Name = "User")] public string User { get; private set; }`

Data Type Attributes

Attribute	Parameter (if any)	Description
	Code Sample
MetadataType	Allows you to derive data annotation attributes from another class.
	C# VB.NET `[MetadataType(typeof(CompanyProductMetadata))] public class Product { public double UnitPrice { get; set; } } public class CompanyProductMetadata { [ReadOnly(true)] public double UnitPrice { get; set; } }`
DataType	Specifies the type of this column’s data. Based on this info the grid control, applies the specific formatting and chooses the appropriate editor for column cells.
	C# VB.NET `[DataType(DataType.PhoneNumber)] public string Phone { get; set; }`
EnumDataType	Allows you to replace numeric enumerator values with corresponding declarations.
	C# VB.NET `[EnumDataType(typeof(ProductCategory))] public int Category { get; set; } public enum ProductCategory { Beverages = 1, Fruit = 2, Vegetables = 3, Meat = 4, Condiments = 5, Confections = 6, DairyProducts = 7, GrainsCereals = 8, Seafood = 9 }`

Validation Attributes

Attribute	Parameter (if any)	Description
	Code Sample
StringLength	Specifies the maximum and minimum number of characters for string records within this column.
	C# VB.NET `[DataType(DataType.Password), StringLength(20, MinimumLength = 3)] public string Password { get; set; }`
Range	All numeric records of this column should lie in specific range, set by using this attribute.
	C# VB.NET `[DataType(DataType.Currency), Range(200, 5000)] public int Currency { get; set; }`
Required	If used, restricts an end-user leaving a cell within this column if this cell is currently empty.
	C# VB.NET `[DataType(DataType.PhoneNumber), Required] public string Phone { get; set; }`
Compare	Compares the field with another property. Entering values that differ from the compared column’s value is restricted.
	C# VB.NET `[DataType(DataType.Password), Display(Name = "New Password")] public string NewPassword { get; set; } [DataType(DataType.Password), Compare("NewPassword", ErrorMessage="The new and confirmation passwords do not match"), Display(Name="Confirm Password")] public string ConfirmPassword { get; set; }`

Also refer to the Data Binding topic to learn more about using Fluent API to add new and modify existing columns in Entity Framework Code First models.

Example

The solution in this example includes a DataSource file that has three classes that provide grid data - CompanyPublicInfo, CompanyPrivateInfo and Product. Properties for all three of them derive Data Annotation Attributes from the CompanyProductMetadata class by using the MetadataType attribute. End-users can use the editor at the top of the form to call one of the Get… methods that will populate the grid with sample data.

Important

To work with Data Annotation Attributes, you need to reference the System.ComponentModel.DataAnnotations library in your solution.

View Example

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.ComponentModel.DataAnnotations;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace GridDataAttributes {
    [MetadataType(typeof(CompanyProductMetadata))]
    public class CompanyPublicInfo {
        public string CompanyName { get; set; }
        public string Country { get; set; }
        public string City { get; set; }
        public string Url { get; set; }
        public string Email { get; set; }
        public string Phone { get; set; }
        public string AdditionalInfo { get; set; }
    }

    [MetadataType(typeof(CompanyProductMetadata))]
    public class CompanyPrivateInfo {
        public string Password { get; set; }
        public DateTime Date2 { get; set; }
        public double Sales { get; set; }
        public double Profit { get; set; }
        public double SalesVsTarget { get; set; }
        public double MarketShare { get; set; }
        public double CustomersSatisfaction { get; set; }
    }

    public class Product {
        [ReadOnly(true)]
        public double UnitPrice { get; set; }
        [EnumDataType(typeof(ProductCategory))]
        public int Category { get; set; }
        [Display(Description = "The amount of currently available product")]
        public int Quantity { get; set; }
        [DataType(DataType.Text), Display(Order = -1)]
        public string Text { get; set; }
        [DataType(DataType.MultilineText)]
        public string MultilineText { get; set; }
        [DataType(DataType.Currency), Range(200, 5000)]
        public int Currency { get; set; }
        [DataType(DataType.Date)]
        public DateTime Date { get; set; }
        [DataType(DataType.Time)]
        public DateTime Time { get; set; }
    }

    public class CompanyProductMetadata {
        [Display(ShortName = "Company", Name = "Company Name", AutoGenerateFilter = false)]
        public object CompanyName;
        [Display(Order = 2)]
        public object Country;
        [Display(Order = 1), Editable(false)]
        public object City;
        [DataType(DataType.Url)]
        public object Url;
        [DataType(DataType.EmailAddress)]
        public object Email;
        [DataType(DataType.PhoneNumber), Required]
        public object Phone;
        [DataType(DataType.Text), Display(Order = -1)]
        public object Text;
        [Display(AutoGenerateField = false, Description = "This column isn't created")]
        public object AdditionalInfo;
        [DataType(DataType.Password), StringLength(20, MinimumLength = 3)]
        public object Password;
        [DisplayFormat(DataFormatString = "MMMM/yyyy"), Display(Name = "Date 2")]
        public object Date2;
        [DisplayFormat(DataFormatString = "#,##0,,M")]
        public object Sales;
        [DisplayFormat(DataFormatString = "#,##0,,M")]
        public object Profit;
        [DisplayFormat(DataFormatString = "p", ApplyFormatInEditMode = true), Display(Name = "Sales vs Target")]
        public object SalesVsTarget;
        [DisplayFormat(DataFormatString = "p0", ApplyFormatInEditMode = false)]
        public object MarketShare;
        [Display(Name = "Cust Satisfaction")]
        public object CustomersSatisfaction;
    }

    public enum ProductCategory {
        Beverages = 1,
        Fruit = 2,
        Vegetables = 3,
        Meat = 4,
        Condiments = 5,
        Confections = 6,
        DairyProducts = 7,
        GrainsCereals = 8,
        Seafood = 9
    }

    public class GridSampleDataList {
        static public List<CompanyPrivateInfo> GetCompanyPrivateInfo() {
            return new List<CompanyPrivateInfo> {
                        new CompanyPrivateInfo() {
                            CustomersSatisfaction = 3.1,
                            Date2 = DateTime.Now,
                            MarketShare = 42,
                            Password = "123qwerty",
                            Profit = 4951515,
                            Sales = 311414134,
                            SalesVsTarget = 0.0277,
                        }
                    };
        }
        static public List<CompanyPublicInfo> GetCompanyPublicInfo() {
            return new List<CompanyPublicInfo> {
                        new CompanyPublicInfo() {
                            AdditionalInfo = "Some Info",
                            City = "Glendale",
                            CompanyName = "Developer Express",
                            Country = "USA",
                            Email = "info@devexpress.com",
                            Phone = "1234567890",
                            Url = "www.devexpress.com",
                        }
                    };
        }
        static public List<Product> GetProductSample() {
            return new List<Product> {
                        new Product() {
                            Currency = 1000,
                            Category = 2,
                            Date = DateTime.Now,
                            MultilineText = "Line1\r\nLine2\r\nLine3",
                            Quantity = 321,
                            Text = "Sample Text",
                            Time = DateTime.Now,
                            UnitPrice = 1800,
                        }
                    };
        }
    }
}

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Forms;
using DevExpress.XtraEditors;
using DevExpress.XtraGrid.Views.Grid;

namespace GridDataAttributes {
    public partial class Form1 : XtraForm {
        public Form1() {
            InitializeComponent();
            gridView1.OptionsView.ShowGroupPanel = false;
            gridControl1.DataSourceChanged += gridControl1_DataSourceChanged;
        }

        void gridControl1_DataSourceChanged(object sender, EventArgs e) {
            gridControl1.MainView.PopulateColumns();
            (gridControl1.MainView as GridView).BestFitColumns();
        }

        protected override void OnLoad(EventArgs e) {
            base.OnLoad(e);
            //gridControl1.DataSource = CompanyProductList.GetSampleData();
            //companyProductListBindingSource.DataSource = CompanyProductList.GetSampleData();
            //companyProductBindingSource.DataSource = CompanyProductList.GetSampleData();
        }

        private void barEditItem3_EditValueChanged(object sender, EventArgs e) {
            switch (barEditItem3.EditValue as string) {
                case "Company public info":
                    gridControl1.DataSource = GridSampleDataList.GetCompanyPublicInfo();
                    break;
                case "Company private info":
                    gridControl1.DataSource = GridSampleDataList.GetCompanyPrivateInfo();
                    break;
                case "Product info":
                    gridControl1.DataSource = GridSampleDataList.GetProductSample();
                    break;
            }
        }
    }
}

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using System.Windows.Forms;
using DevExpress.Skins;

namespace GridDataAttributes {
    static class Program {
        /// <summary>
        /// The main entry point for the application.
        /// </summary>
        [STAThread]
        static void Main() {
            SkinManager.EnableFormSkins();
            Application.EnableVisualStyles();
            Application.SetCompatibleTextRenderingDefault(false);
            Application.Run(new Form1());
        }
    }
}

Imports System
Imports System.Collections.Generic
Imports System.Linq
Imports System.Threading.Tasks
Imports System.Windows.Forms
Imports DevExpress.Skins

Namespace GridDataAttributes
    Friend NotInheritable Class Program

        Private Sub New()
        End Sub

        ''' <summary>
        ''' The main entry point for the application.
        ''' </summary>
        <STAThread> _
        Shared Sub Main()
            SkinManager.EnableFormSkins()
            Application.EnableVisualStyles()
            Application.SetCompatibleTextRenderingDefault(False)
            Application.Run(New Form1())
        End Sub
    End Class
End Namespace

Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Data
Imports System.Drawing
Imports System.Linq
Imports System.Text
Imports System.Threading.Tasks
Imports System.Windows.Forms
Imports DevExpress.XtraEditors
Imports DevExpress.XtraGrid.Views.Grid

Namespace GridDataAttributes
    Partial Public Class Form1
        Inherits XtraForm

        Public Sub New()
            InitializeComponent()
            gridView1.OptionsView.ShowGroupPanel = False
            AddHandler gridControl1.DataSourceChanged, AddressOf gridControl1_DataSourceChanged
        End Sub

        Private Sub gridControl1_DataSourceChanged(ByVal sender As Object, ByVal e As EventArgs)
            gridControl1.MainView.PopulateColumns()
            TryCast(gridControl1.MainView, GridView).BestFitColumns()
        End Sub

        Protected Overrides Sub OnLoad(ByVal e As EventArgs)
            MyBase.OnLoad(e)
            'gridControl1.DataSource = CompanyProductList.GetSampleData();
            'companyProductListBindingSource.DataSource = CompanyProductList.GetSampleData();
            'companyProductBindingSource.DataSource = CompanyProductList.GetSampleData();
        End Sub

        Private Sub barEditItem3_EditValueChanged(ByVal sender As Object, ByVal e As EventArgs) Handles barEditItem3.EditValueChanged
            Select Case TryCast(barEditItem3.EditValue, String)
                Case "Company public info"
                    gridControl1.DataSource = GridSampleDataList.GetCompanyPublicInfo()
                Case "Company private info"
                    gridControl1.DataSource = GridSampleDataList.GetCompanyPrivateInfo()
                Case "Product info"
                    gridControl1.DataSource = GridSampleDataList.GetProductSample()
            End Select
        End Sub
    End Class
End Namespace

Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.ComponentModel.DataAnnotations
Imports System.Linq
Imports System.Text
Imports System.Threading.Tasks

Namespace GridDataAttributes
    <MetadataType(GetType(CompanyProductMetadata))> _
    Public Class CompanyPublicInfo
        Public Property CompanyName() As String
        Public Property Country() As String
        Public Property City() As String
        Public Property Url() As String
        Public Property Email() As String
        Public Property Phone() As String
        Public Property AdditionalInfo() As String
    End Class

    <MetadataType(GetType(CompanyProductMetadata))> _
    Public Class CompanyPrivateInfo
        Public Property Password() As String
        Public Property Date2() As Date
        Public Property Sales() As Double
        Public Property Profit() As Double
        Public Property SalesVsTarget() As Double
        Public Property MarketShare() As Double
        Public Property CustomersSatisfaction() As Double
    End Class

    Public Class Product
        <[ReadOnly](True)> _
        Public Property UnitPrice() As Double
        <EnumDataType(GetType(ProductCategory))> _
        Public Property Category() As Integer
        <Display(Description := "The amount of currently available product")> _
        Public Property Quantity() As Integer
        <DataType(DataType.Text), Display(Order := -1)> _
        Public Property Text() As String
        <DataType(DataType.MultilineText)> _
        Public Property MultilineText() As String
        <DataType(DataType.Currency), Range(200, 5000)> _
        Public Property Currency() As Integer
        <DataType(DataType.Date)> _
        Public Property [Date]() As Date
        <DataType(DataType.Time)> _
        Public Property Time() As Date
    End Class

    Public Class CompanyProductMetadata
        <Display(ShortName := "Company", Name := "Company Name", AutoGenerateFilter := False)> _
        Public CompanyName As Object
        <Display(Order := 2)> _
        Public Country As Object
        <Display(Order := 1), Editable(False)> _
        Public City As Object
        <DataType(DataType.Url)> _
        Public Url As Object
        <DataType(DataType.EmailAddress)> _
        Public Email As Object
        <DataType(DataType.PhoneNumber), Required> _
        Public Phone As Object
        <DataType(DataType.Text), Display(Order := -1)> _
        Public Text As Object
        <Display(AutoGenerateField := False, Description := "This column isn't created")> _
        Public AdditionalInfo As Object
        <DataType(DataType.Password), StringLength(20, MinimumLength := 3)> _
        Public Password As Object
        <DisplayFormat(DataFormatString := "MMMM/yyyy"), Display(Name := "Date 2")> _
        Public Date2 As Object
        <DisplayFormat(DataFormatString := "#,##0,,M")> _
        Public Sales As Object
        <DisplayFormat(DataFormatString := "#,##0,,M")> _
        Public Profit As Object
        <DisplayFormat(DataFormatString := "p", ApplyFormatInEditMode := True), Display(Name := "Sales vs Target")> _
        Public SalesVsTarget As Object
        <DisplayFormat(DataFormatString := "p0", ApplyFormatInEditMode := False)> _
        Public MarketShare As Object
        <Display(Name := "Cust Satisfaction")> _
        Public CustomersSatisfaction As Object
    End Class

    Public Enum ProductCategory
        Beverages = 1
        Fruit = 2
        Vegetables = 3
        Meat = 4
        Condiments = 5
        Confections = 6
        DairyProducts = 7
        GrainsCereals = 8
        Seafood = 9
    End Enum

    Public Class GridSampleDataList
        Public Shared Function GetCompanyPrivateInfo() As List(Of CompanyPrivateInfo)
            Return New List(Of CompanyPrivateInfo) From { _
                New CompanyPrivateInfo() With {.CustomersSatisfaction = 3.1, .Date2 = Date.Now, .MarketShare = 42, .Password = "123qwerty", .Profit = 4951515, .Sales = 311414134, .SalesVsTarget = 0.0277} _
            }
        End Function
        Public Shared Function GetCompanyPublicInfo() As List(Of CompanyPublicInfo)
            Return New List(Of CompanyPublicInfo) From { _
                New CompanyPublicInfo() With {.AdditionalInfo = "Some Info", .City = "Glendale", .CompanyName = "Developer Express", .Country = "USA", .Email = "info@devexpress.com", .Phone = "1234567890", .Url = "www.devexpress.com"} _
            }
        End Function
        Public Shared Function GetProductSample() As List(Of Product)
            Return New List(Of Product) From { _
                New Product() With {.Currency = 1000, .Category = 2, .Date = Date.Now, .MultilineText = "Line1" & ControlChars.CrLf & "Line2" & ControlChars.CrLf & "Line3", .Quantity = 321, .Text = "Sample Text", .Time = Date.Now, .UnitPrice = 1800} _
            }
        End Function
    End Class
End Namespace

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Data Display Attributes

Example 1

Example 2 (Enum Properties)

Data Type Attributes

Validation Attributes

Example