ASP.NET Dynamic Data Scaffolding

Article
12/04/2014

ASP.NET Dynamic Data lets you create extensible data-driven Web applications by using predefined elements for viewing and editing data. These elements, along with a data model, provide a flexible environment for building and customizing ASP.NET Web applications.

This topic contains the following sections:

Scaffolding
Page Templates
Field Templates
Entity Templates
Filter Templates

Scaffolding

Scaffolding refers to the Dynamic Data elements that automatically generate Web pages for each table in a database. These auto-generated Web pages provide create, read, update and delete (CRUD) operations for each table. Scaffolding consists of page templates, entity page templates, field page templates, and filter templates. These templates enable you to quickly build a functional data-driven Web site.

An integral part of scaffolding is a data model that represents database entities as common language runtime (CLR) types. Dynamic Data uses metadata from the data model to create the UI for the Web application and to manage changes that are entered by the user.

The benefits of scaffolding are following:

Little or no code is required in order to create a data-driven Web application.
Functional pages are generated automatically and include database CRUD capabilities, sorting, and paging.
ASP.NET routing (URL routing) automatically handles requests. Dynamic Data infers the template and the table to use from the request URL.
Data validation is built in, based on the database schema.
Data filters are automatically created for foreign keys, Boolean fields, and enumeration field types.
Customization is easy to change the appearance and behavior of data fields.

You can create an ASP.NET Dynamic Data Web site in Visual Studio by using the Dynamic Data Web Site template. For more information, see Walkthrough: Creating a New Dynamic Data Web Site Using Scaffolding. For information about the project structure of a Web site that uses scaffolding, see ASP.NET Dynamic Data Infrastructure.

Enabling Scaffolding

By default, the scaffolding mechanism is turned off. Enabling it should be done carefully because it can expose the whole database to unauthorized access, which poses a security risk.

You can use one of the he following approaches to enable scaffolding:

Enable scaffolding for all tables when the data context is registered. You must register the data context for the data model in order to use Dynamic Data features. You perform this task in the Global.asax file.
Enable or disable scaffolding for an individual table. To do this, you use the ScaffoldTableAttribute attribute. This approach enables you to expose only the tables required by your application instead of exposing the whole database. .
Enable scaffolding for an individual data field. To do this, you use the ScaffoldColumnAttribute attribute.

By default, Dynamic Data applies the following rules in order to decide whether to display a data field.

If a ScaffoldColumnAttribute attribute is applied to a data field, that data field is displayed. This overrides all the following rules.
If a UIHintAttribute attribute is applied to a data field, that data field is displayed. This overrides all the following rules.
If a data field is a foreign-key field, that data field is not displayed, because Dynamic Data does not display foreign-key field values.
If a data field is automatically generated in the database, that data field is not displayed. Typically these fields do not contain relevant information. If the data field must be displayed, you can apply the UIHintAttribute attribute to the data field in the data model.
If the value of the IsCustomProperty property is true, that data field is not displayed.

Page Templates

Dynamic Data uses page templates to display tables and to provide CRUD capabilities. The templates are ASP.NET (.aspx) pages. When you create a Dynamic Data Web project, Visual Studio adds a DynamicData\PageTemplates folder to the project. This folder contains the default page templates. You can modify the default page templates or create new ones in order to specify how tables are rendered.

Default Page Templates

The default page templates have the following features:

They use a master page named Site.master that is located at the root folder of the Web application. The master page defines style sheets and a basic header. It also includes a ScriptManager control to enable AJAX functionality. For debugging reasons, you might want to turn partial-page updates off by setting the EnablePartialRendering property of the ScriptManager control to false.
Each page template contains a UpdatePanel control to enable partial rendering without a postback. For more information, see UpdatePanel Control Overview.
Each page template contains a DynamicDataManager control. This control enables dynamic behavior for the data-bound and data source controls in the template.

The following table lists the default page templates provided by Dynamic Data.

Page Template	Description
Details.aspx	Provides a detailed view of a single row in the database. This is the default template for select operations. It uses a DetailsView control to display the data.
Edit.aspx	Provides a page that lets users edit a single row of a database table. This is the default template for edit operations. It uses a DetailsView control.
Insert.aspx	Provides a page that lets users insert a single row into a database table. This is the default template used for insert operations. It uses a DetailsView control.
List.aspx	Displays a list of rows from a database table. This is the default template that is used for displaying a table. This template provides DropDownList controls that let users filter data, sort, and page. It uses a GridView control.
ListDetails.aspx	Displays a list of rows from a database table. The template lets users filter data, sort, and page. The template uses a GridView control for the list of rows and uses a DetailsView control for the selected row to let users insert a new record. This template presents all-in-one functionality. Dynamic Data does not use it by default. You can change the configuration in the Global.asax file to use this template instead of using individual templates (such as List.aspx and Edit.aspx) for different operations.

Field Templates

Field templates are ASP.NET user controls. They map data types in the data model to fields in ASP.NET data-bound control. Dynamic Data uses field templates to automatically create the UI for data entities based on the database schema and data types.

Default Field Templates

ASP.NET Dynamic Data infers the data type of a data field at run time. It then uses the appropriate field template to render the data in an ASP.NET data-bound control. The field template that is used depends on the data type and whether the data control is in display, edit, or insert mode.

When you create a Dynamic Data Web project, Visual Studio adds a DynamicData\FieldTemplates folder to the project. This folder contains the default field templates. You can modify the default field templates or create new ones in order to specify how individual data fields are rendered.

The following table describes the default field templates in ASP.NET Dynamic Data projects.

Default field template	Description
Boolean.ascx	Displays Boolean data as a CheckBox control. The CheckBox control is disabled and cannot be changed.
Boolean_Edit.ascx	Enables users to edit Boolean values by using a CheckBox control.
Children.ascx	Displays fields that have a one-to-many relationship and redirects the user to the child page. Renders a HyperLink control.
Children_Insert.ascx	Prevents navigation to a page that displays child items while a parent item is being created. For example, if a new category (parent item) is created, there are no related children yet. Consequently, no navigation link can be created that directs to a page that displays a list of children.
DateTime.ascx	Displays DateTime data type as text by using a Literal control.
DateTime_Edit.ascx	Enables users to edit DateTime data by using a TextBox control. If the field in the database cannot be null or if a Required attribute is added to the data model, this control also renders a RequiredFieldValidator control. The DateTime_Edit.ascxfield template provides a DynamicValidator control that handles any exceptions that are thrown from the data model. This field template supports the Regex class.
Decimal_Edit.ascx	Enables users to edit decimal (numeric) data by using a TextBox control. Also renders a CompareValidator control that verifies that the input can be converted to a Decimal data type. If the field in the database cannot be null or if a Required attribute is added to the data model, this control also renders a RequiredFieldValidator control. If the field has a Range attribute, the field also renders a RangeValidator control. The Decimal_Edit.ascx field template provides a DynamicValidator control that handles any exceptions that are thrown from the data model. This field template uses the Regex class.
Enumeration.ascx	Displays enumeration values using a Literal control. The enumeration column type is the primitive data field type as defined in the database, or the type defined by applying the EnumDataTypeAttribute in the data model.
Enumeration_Edit.ascx	Enables users to select from a list of enumeration values by using a DropDownList control.
ForeignKey.ascx	Displays fields that have a many-to-one relationship. Renders a HyperLink control that redirects the user to the relationship page.
ForeignKey_Edit.ascx	Enables users to modify data fields that have a many-to-one relationship by using a DropDownList control.
Integer_Edit.ascx	Enables users to edit integer data by using a TextBox control. The template also renders a CompareValidator that verifies that the input in the text box can be converted to an integer. If the field in the database cannot be null, or if a Required attribute is added to the data model, this control alsorenders a RequiredFieldValidator control. If the field in the model has a Range attribute, the field also renders a RangeValidator control. Integer_Edit.ascx provides a DynamicValidator control that handles any exceptions that are thrown from the data model. This field template uses the Regex class.
Multiline_Edit.ascx	Enables users to edit database fields for certain string types. For example, if the data model maps to a SQL Server database, Multiline_Edit.ascx maps to the text, ntext, varchar(max), nvarchar(max) data types. This template renders a TextBox control whose TextMode property is set to MultiLine. If the field in the database cannot be null or if a Required attribute is added to the data model, Multiline_Edit.ascx also renders a RequiredFieldValidator control. If a RegularExpression attribute is added to the data model, the data field also renders a RegularExpressionValidator control. Multiline_Edit.ascxprovidesa DynamicValidator control that handles any exceptions that are thrown from the data model.
ManyToMany.ascx	Used to display and edit many-to-many data fields if the application's data model uses the ADO Entity Framework. This field template is not used if the data model is based on LINQ to SQL, because LINQ to SQL does not support many-to-many relationships.
ManyToMany_Edit.ascx	Enables users to edit database fields that have a many-to-many relation with another table. This template requires a pure join table.
Text.ascx	Displays string data and all numeric data types by using a Literal control.
Text_Edit.ascx	Enables users to edit string data that is not considered multi-line text by using a TextBox control whose TextMode property is set to SingleLine. If the field in the database cannot be null, or if a Required attribute is added to the data model, Text_Edit.ascx alsorenders a RequiredFieldValidator control. If the field in the database has a maximum length, the MaxLength property of the TextBox control is enforced. If there is a RegularExpression attribute on the data model, the default field template also renders a RegularExpressionValidator control. Text_Edit.ascxprovides a DynamicValidator control to handle any exceptions that are thrown from the data model.
Url.ascx	Displays URLs by using a HyperLink control. The data field type is marked as a hyperlink by marking the field in the data model with a DataTypeAttribute attribute that specifies it as a URL.

Mapping Data Types to Field Templates

You can change the field template that is used to render a data field in the following ways:

By using the UIHint attribute or the UIHint property in the markup of a page that is enabled for Dynamic Data and that includes a data control. For more information, see How to: Add Dynamic Behavior to Data-Bound Controls.
By marking a data field by using the UIHintAttribute attribute in the data model. For more information, see Walkthrough: Customizing Data Field Appearance and Behavior in the Data Model.

If you use both the markup approach and the data-model approach, and if the mappings are not the same, the markup approach takes precedence.

Rendering Field Templates

Dynamic Data renders default and custom field templates in display, edit, and insert mode. Dynamic Data uses lookup rules to determine which field template to render. The template to use depends on whether the control is in display, edit, or insert mode. For example, if the data in the column is a Boolean value and the data control is in display mode, Dynamic Data renders Boolean.ascx, the default field template that displays Boolean data types. However, if the data control is in edit mode, by default Dynamic Data renders Boolean_Edit.ascx, the field template that enables editing of Boolean data types.

Dynamic Data starts the lookup by determining the mode of the field templates.

Display-Mode Field Template Lookup

The following lists the lookup rules Dynamic Data uses to render field templates in display mode:

If a data field in the data model is marked with the UIHintAttribute attribute that specifies a custom field template, Dynamic Data looks up a control that is based on the user control name and the DataTypeAttribute defined in the UIHint and DataTypeAttribute properties. By default, Dynamic Data does not display all the data types. For example, byte-array data types such as binary, timestamp, and image types are not rendered. For information about how to display custom data types, see the DataTypeAttribute class overview.
If the field is not marked with a UIHintAttribute attribute, Dynamic Data determines the data type from the column in the database and looks up a field template based on the data type. The data type name is determined in the following order:
1. Dynamic Data looks for a field template that matches the fully qualified data type name, such as System.Int32.
2. If a field template that matches the fully qualified type name is not found, Dynamic Data looks for a field template that has the simple data type name, such as Int32.
3. If a field template that matches the simple data type name is not found, Dynamic Data looks up the special cases that are defined in the data table, as shown in the next step. For example, if a simple data type such as Int32 is not found, Dynamic Data looks up Integer, the special case defined in the data table. If the simple data type String is not found, it looks up Text, the special case for String.
4. If a special case is not found and a fallback data type exists, Dynamic Data looks up a fallback data type. The following table lists fallback data types.
  
  Data Type
  
  Fallback Data Type
  
  Float, Double
  
  Decimal
  
  Int16, Byte, Long
  
  Integer
  
  Char, Integer, Decimal, GUID, DateTime, DateTimeOffset, TimeSpan
  
  String
5. If a fallback data type does not exist, Dynamic Data displays an error message and no data is displayed.
If the field is a foreign key, Dynamic Data uses the ForeignKey.ascxtemplate for a many-to-one relationship. It uses the Children.ascx template for a one-to-many relationship.

Data Type	Fallback Data Type
Float, Double	Decimal
Int16, Byte, Long	Integer
Char, Integer, Decimal, GUID, DateTime, DateTimeOffset, TimeSpan	String

Edit-Mode Field Template Lookup

The Edit mode lookup rules are identical to the display mode rules, with one exception. If the field template is in edit mode, Dynamic Data uses all the lookup rules that it does for display mode, except that it adds "_Edit" to the name of the field template that it is looking for (for example, Text_Edit). If no field template with "_Edit" in the name is found, Dynamic Data looks for a field template without "_Edit" -- that is, it defaults to display (read-only) mode.

Insert Mode Lookup

The Insert mode lookup rules are identical to the display mode rules, with one exception. If the field template is in insert mode, Dynamic Data uses all the lookup rules that it does for display mode, except that it adds "_Insert" to the name of the field template that it is looking for (for example, Text_Insert). If no field template with "_Insert" in the name is found, Dynamic Data looks for an edit-mode field template.

Note

"_Insert.ascx" user controls are not provided by default. Therefore, by default, Dynamic Data uses edit-mode field templates for insert mode.

Data-Bound Controls That Use Field Templates

The FormView control, the ListView control, and other controls that support templates, such as the GridView and DetailsView controls, use the DynamicControl control to display and edit data in the data model.

The DynamicControl control also enables the use of templates in data columns.

For more information, see How to: Add Dynamic Behavior to Data-Bound Controls.

Entity Templates

Entity templates are user controls that let you customize the layout for a whole data row in a table. They give you better control over table layout than page templates. When you create a Dynamic Data Web project, Visual Studio adds a DynamicData\EntityTemplates folder to the project. This folder contains the default entity templates, which display data in two columns, using a label for the field name and an appropriate control for the field value.

There are entity templates for display, edit, and insert operations. Entity templates are included in the Details.aspx, Insert.aspx, and Update.aspx page templates, and you can use them in custom page templates. Entity templates use field templates to render the actual data. The entity templates are displayed on a page by using the DynamicEntity control. At run time, Dynamic Data replaces this control with the contents of the applicable entity template.

Filter Templates

Filter templates are user controls that render the UI for data filtering. Data filtering lets the user select table rows to display based on a value in a selected column. For example, a filter template can let a user select a foreign key and display the rows that match that key.

When you create a Dynamic Data Web project, Visual Studio adds a DynamicData\FilterTemplates folder to the project. This folder contains the default filter templates.

Dynamic Data enables you to use page markup to create the UI for data filtering. This approach is useful when you want to filter table rows for a column type for which Dynamic Data provides a default filter template. If a filter template does not exist for that column type, you can create a custom one and configure Dynamic Data to use it for creating the UI. You can also create the page markup to let Dynamic Data automatically generate the UI for any column type for which a filter template exists. By default, Dynamic Data creates the UI for only for Boolean, foreign-key, and enumeration column types.

Dynamic Data performs data filtering as follows:

The filter template modifies the basic query for the data source control in the page. This is to include the column value chosen by the user.
The data source control executes the modified query and returns the filtered data to the associated data-bound control for display.

You can modify the default filter templates or create new ones in order to specify how data filtering is handled.

The following table describes the default filter templates in ASP.NET Dynamic Data projects.

Default filter template	Description
Boolean.ascx	Displays Boolean data using a DropDownList control. The displayed values are All, True, and False. If the column value can be null, the filter also provides a [Not set] value.
Enumeration.ascx	Displays enumeration values by using a DropDownList control. The displayed values are All and the string representations of the enumeration values. If the column value can be null, the filter also provides a [Not set] value.
ForeignKey.ascx	Displays foreign keys by using a DropDownList control. The displayed values are All and the values from the related table. If the column value can be null, the filter also provides a [Not set] value.