windowsforms-18273-common-features-data-binding-data-annotation-attributes.md
DevExpress data-aware controls (GridControl, TreeList, VGridControl, PropertyGridControl, Data Layout Control, etc.) support Microsoft Data Annotation Attributes. You can apply these attributes when you create a data source in code.
When bound to such data sources, grid and tree list controls recognize attributes and automatically adjust column settings and layout (for example, set column captions, apply filters and data formats, apply validation rules, etc.).
Note
A repository item assigned to a column overrides attribute settings.
The following sections describe attributes most commonly used in GridControl and TreeListControl. To see the full list of Microsoft Data Annotation Attributes, visit the MSDN documentation.
The Display attribute specifies the column caption for auto generated columns.
This attribute does not effect columns created at design-time. The GridColumn.Caption property overrides the attribute value.
[Display(ShortName = "Company", Name = "Company Name")]
public string CompanyName { get; set; }
<Display(ShortName := "Company", Name := "Company Name")>
Public Property CompanyName() As String
The following code snippet applies the Display attribute to specific enumeration values:
[EnumDataType(typeof(ProductCategory))]
public int Category { get; set; }
public enum ProductCategory {
Beverages = 1,
Fruit = 2,
[Display(Name = "Dairy Products")]
DairyProducts = 3,
[Display(Name = "Grains Cereals")]
GrainsCereals = 4
}
<EnumDataType(GetType(ProductCategory))>
Public Property Category() As Integer
Public Enum ProductCategory
Beverages = 1
Fruit = 2
<Display(Name := "Dairy Products")>
DairyProducts = 3
<Display(Name := "Grains Cereals")>
GrainsCereals = 4
End Enum
The AutoGenerateField attribute specifies whether a control automatically creates a column for this field.
[Display(AutoGenerateField = false, Description = "This column isn't created")]
public string AdditionalInfo { get; set; }
<Display(AutoGenerateField := False, Description := "This column isn't created")>
Public Property AdditionalInfo() As String
The AutoGenerateFilter attribute enables or disables automatic filter UI generation for this field. This attribute applies only to auto generated columns. For columns created manually, use the OptionsColumnFilter.AllowFilter property.
[Display(AutoGenerateFilter = false)]
public string Email { get; set; }
<Display(AutoGenerateFilter:= False)>
Public Property Email() As String
The Order attribute specifies the column display order (see GridColumn.VisibleIndex).
[Display(Order = 2)]
public string Country { get; set; }
[Display(Order = 1)]
public string City { get; set; }
<Display(Order := 2)>
Public Property Country() As String
<Display(Order := 1)>
Public Property City() As String
Tip
Set the Order attribute to -1 to hide the column.
The Description attribute specifies a tooltip for the column.
The GridColumn.ToolTip property overrides the attribute value.
[Display(Description = "The amount of currently available product")]
public int Quantity { get; set; }
<Display(Description := "The amount of currently available product")>
Public Property Quantity() As Integer
The Editable attribute specifies whether a user can edit column values (see OptionsColumn.AllowEdit).
[Editable(false)]
public string City { get; set; }
<Editable(False)>
Public Property City() As String
The ReadOnly attribute sets the column to read only mode (OptionsColumn.ReadOnly).
[ReadOnly(true)]
public double UnitPrice { get; set; }
<[ReadOnly](True)>
Public Property UnitPrice() As Double
The DisplayFormat attribute specifies how the column displays formatted values.
DataFormatString
Specifies the display format for this column’s records.
[DisplayFormat(DataFormatString = "MMMM/yyyy")]
public object Date2 { get; set; }
<DisplayFormat(DataFormatString := "MMMM/yyyy")>
Public Date2 As Object
ApplyFormatInEditMode
Specifies whether the display format for a cell should remain visible when the cell is being edited.
[DisplayFormat(DataFormatString = "p", ApplyFormatInEditMode = true)]
public object SalesVsTarget { get; set; }
<DisplayFormat(DataFormatString := "p", ApplyFormatInEditMode := True)>
Public SalesVsTarget As Object
ResourceType
Retrieves localized captions from a resource file.
[Display(ResourceType = typeof(Properties.Resources), Name = "User")]
public string User { get; private set; }
Private privateUser As String
<Display(ResourceType := GetType(Properties.Resources), Name := "User")>
Public Property User() As String
Get
Return privateUser
End Get
Private Set(ByVal value As String)
privateUser = value
End Set
End Property
The MetadataType attribute inherits data annotation attributes from another class.
[MetadataType(typeof(CompanyProductMetadata))]
public class Product {
public double UnitPrice { get; set; }
}
public class CompanyProductMetadata {
[ReadOnly(true)]
public double UnitPrice { get; set; }
}
<MetadataType(GetType(CompanyProductMetadata))>
Public Class Product
Public Property UnitPrice() As Double
End Class
Public Class CompanyProductMetadata
<[ReadOnly](True)>
Public Property UnitPrice() As Double
End Class
The DataType attribute specifies the data type.
The control selects the appropriate editor and formatting automatically.
[DataType(DataType.PhoneNumber)]
public string Phone { get; set; }
<DataType(DataType.PhoneNumber)>
Public Property Phone() As String
The EnumDataType attribute replaces numeric enum values with their text labels.
[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
}
<EnumDataType(GetType(ProductCategory))>
Public Property Category() As Integer
Public Enum ProductCategory
Beverages = 1
Fruit = 2
Vegetables = 3
Meat = 4
Condiments = 5
Confections = 6
DairyProducts = 7
GrainsCereals = 8
Seafood = 9
End Enum
The StringLength attribute specifies the minimum and maximum allowed length for string values.
[DataType(DataType.Password), StringLength(20, MinimumLength = 3)]
public string Password { get; set; }
<DataType(DataType.Password), StringLength(20, MinimumLength := 3)>
Public Property Password() As String
The Range attribute specifies a valid numeric range.
[DataType(DataType.Currency), Range(200, 5000)]
public int Currency { get; set; }
<DataType(DataType.Currency), Range(200, 5000)>
Public Property Currency() As Integer
The Required attribute marks the column as mandatory. Users cannot leave the cell empty.
[DataType(DataType.PhoneNumber), Required]
public string Phone { get; set; }
<DataType(DataType.PhoneNumber), Required>
Public Property Phone() As String
The Compare attribute compares the field value to another property. If values differ, the editor shows a validation error.
[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; }
<DataType(DataType.Password), Display(Name := "New Password")>
Public Property NewPassword() As String
<DataType(DataType.Password), Compare("NewPassword",
ErrorMessage:="The new and confirmation passwords do not match"),
Display(Name:="Confirm Password")>
Public Property ConfirmPassword() As String
See the following help topic for information about Fluent API in Entity Framework Code First models: Fluent API Support — Data Binding.
The Data Layout Control supports advanced customization.
You can use attributes to group layout items and create tab containers. See the following help topic for more information: Data Annotation Attributes in Data Layout Control.
The following example defines a data source that uses attributes to describe columns, apply validation rules and formatting.