ASP.NET Dynamic Data Scaffolding and Page Templates Overview

A recurring task in software development is to display and edit data. ASP.NET Dynamic Data enables you to create data-driven applications with minimal or no code. The scaffolding mechanism is an important feature in Dynamic Data that enables you to quickly generate these applications.

This topic contains:

• Scaffolding

• Page Templates

Scaffolding

Scaffolding is a mechanism that takes the power and functionality of the existing ASP.NET page framework and enhances it by dynamically displaying pages based on the data model without a physical page behind the scenes.

The benefits of using the scaffolding mechanism are as follows:

• Minimal or no code to create a data-driven Web application.

• Quick development time.

• Pages are completely functional. They include all database operations (view, insert, edit and delete), and also sorting and paging functionalities.

• Built-in data validation based on the database schema.

• Automatic filters are created for each foreign key or Boolean field.

Dynamic Data uses URL routing to match and handle requests. The scaffolding mechanism infers the view and the table a user wishes to see from the URL requested. The benefit of using the routing mechanism is that the URL requested does not have to match the physical path in the application.

Enabling the scaffolding mechanism

By default, the scaffolding mechanism is turned off. Enabling the scaffolding mechanism should be done carefully because it poses a security risk because it can expose the whole data model for display, edit, insert and delete capabilities.

You can use the following approaches to enable the scaffolding mechanism:

• Enabling in the data context registration.

• By using the ScaffoldTableAttribute attribute.

• By using the ScaffoldColumnAttribute attribute.

You are required to register the data context that will use Dynamic Data features, even if you are not going to use the scaffolding mechanism. This registration is made in the global.asax file by using the RegisterContext method. The RegisterContext method accepts a ContextConfiguration object as a parameter. In order to enable the scaffolding mechanism while registering the data context, you set the ScaffoldAllTables property of the ContextConfiguration object to true. This will enable the scaffolding mechanism for the whole data model. In other words, it will expose all the tables in the data model for display, edit, insert and delete capabilities. If you must hide some tables from the scaffolding mechanism, you can achieve this by using the ScaffoldTableAttribute attribute.

The following example shows how to enable the scaffolding mechanism for all tables in the data model while registering the data context for the AdventureWorksLT database.

model.RegisterContext(GetType(AdventureWorksLTDataContext), _
                      New ContextConfiguration() With {.ScaffoldAllTables = True})

model.RegisterContext(typeof(AdventureWorksLTDataContext),
    new ContextConfiguration() { ScaffoldAllTables = true });

If you want more control on which tables are being exposed, you can use the ScaffoldTableAttribute attribute to enable or disable the scaffolding mechanism for a given table. Instead of exposing the whole data model and hiding the tables that do not have to be exposed, you can expose only the ones required by the application. In order to apply the ScaffoldTableAttribute attribute, you must create a partial class that has the same name of the entity class in the data model and then apply the attribute to the partial class.

The following example shows how to enable the scaffolding mechanism for an individual table.

Imports System.ComponentModel.DataAnnotations

<ScaffoldTable(True)> _
Partial Public Class Product
End Class

using System.ComponentModel.DataAnnotations;

[ScaffoldTable(true)]
public partial class Product {
}

If you want more control on which data fields are being exposed, you can use the ScaffoldColumnAttribute attribute to enable or disable the scaffolding mechanism for a given data field.

By default, not all data fields are displayed by Dynamic Data. The following are some important rules that are used by Dynamic Data to display or not a data field:

• If a ScaffoldColumnAttribute attribute is applied to the data field, the data field is displayed. This rule overrides all the following rules.

• If a UIHintAttribute attribute is applied to the data field, the data field is displayed. This rule overrides all the following rules.

• If a data field is a foreign-key field, the data field is not displayed. This occurs because Dynamic Data handles foreign-key fields in a different way and will not typically display the foreign-key field value.

• If the data field is automatically generated in the database, the data field is not displayed. Typically these kind of field do not contain relevant information. Make sure that you apply the UIHintAttribute attribute to the data field, if the data field must be displayed.

If the value of the IsCustomProperty property is true, the data field is not displayed.

In order to apply the ScaffoldColumnAttribute attribute, you must create an associated metadata class where you will apply the ScaffoldColumnAttribute attribute to the data field and you must create a partial class that has the same name of the entity class in the data model. Then, you must associate these two classes by applying the MetadataTypeAttribute attribute to the partial class.

The following example shows how to hide specific data fields, PasswordHash and PasswordSalt, from the scaffolding mechanism.

Imports System.ComponentModel.DataAnnotations

<MetadataType(GetType(Customer_Metadata))> _
Partial Public Class Customer

End Class

Public Class Customer_Metadata
    <ScaffoldColumn(False)> _
    Public PasswordHash As Object

    <ScaffoldColumn(False)> _
    Public PasswordSalt As Object
End Class

using System.ComponentModel.DataAnnotations;

[MetadataType(typeof(Customer_Metadata))]
public partial class Customer
{
}

public class Customer_Metadata
{
    [ScaffoldColumn(false)]
    public object PasswordHash;

    [ScaffoldColumn(false)]
    public object PasswordSalt;
}

Page Templates

The ASP.NET Dynamic Data scaffolding mechanism uses templates to provide the default views of data. The templates are regular ASP.NET pages, which means that you can change the templates and affect the appearance and behavior of the generated pages across the Web application.

When you create an ASP.NET Dynamic Data application, the project template adds a DynamicData folder to your project. The following table lists the page templates provided by Dynamic Data in the DynamicData\PageTemplates folder:

Page Template Name	Description
Details.aspx	Provides a detailed view of a single row in the database. It uses a DetailsView control to display the data. This is the default template that is used for select operation.
Edit.aspx	Provides an interface for editing a single row of a database table. It uses a DetailsView control to edit data. This is the default template that is used for edit operation.
Insert.aspx	Provides an interface for inserting a single row into a database table. It uses a DetailsView control to insert data. This is the default template that is used for insert operation.
List.aspx	Displays a list of rows from a database table. It provides DropDownList controls for filtering data for each foreign key or boolean columns and sorting and paging capabilities. It uses a GridView control for the list of rows. This is the default template that is used for display operation.
ListDetails.aspx	Displays a list of rows from a database table. It provides DropDownList controls for filtering data for each foreign key or boolean columns and sorting and paging capabilites. The template uses a GridView control for the list of rows, and a DetailsView control for the selected row and inserting a new record. This is a template that presents an all-in-one functionality. It is not used by default, but you can change the configuration in the Global.asax file to use this template instead.

All the default templates provided by Dynamic Data have in common the following features:

• They use a master page named Site.master that is located at the root folder. The master page defines style sheets and a basic header, and also includes a ScriptManager control to enable AJAX functionality to the Web site. For debugging reasons, you might want to turn partial-page updates off, by setting the EnablePartialRendering property of the ScriptManager control to false. For more information, see Adding AJAX and Client Capabilities Roadmap.

• Each one of the page templates contains an UpdatePanel control to enable partial rendering without a postback. For more information, see UpdatePanel Web Server Control Declarative Syntax.

• Each one of the page templates also contains a DynamicDataManager control to add dynamic behavior to the data-bound and data source controls present in the template.

Customizing the page templates

Dynamic Data enables you to customize the templates provided. There are two ways of achieving this:

• Customizing the built-in page templates.

• Customizing the layout for a particular table.

You can customize the built-in page templates by changing the pages located in the DynamicData\PageTemplates folder. The changes that you make in this location affect the appearance and behavior of the generated pages that are using the scaffolding mechanism across the Web application.

It is possible to use the scaffolding mechanism and create custom pages for specific tables. In order to do that, you must create a folder under the DynamicData\CustomPages folder that has the same of the entity table name in the data model. Under this new folder, you add a page with the same name of the page template that is being used globally. For example, if you want to create a specific details page for a table, name the page as Details.aspx. You can use the built-in page template as a starting point for your custom page. For an example, see How to: Customize the Layout of an Individual Table By Using a Custom Page Template.

Customizing the routes

As mentioned earlier, Dynamic Data uses ASP.NET routing to match and handle URL requests. The routes are defined in the global.asax file. By default, Dynamic Data uses a different page template for each operation (display, select, edit and insert). The delete functionality is displayed in both List and Details pages, because you do not need a page template specific for the delete operation.

You can customize the routes to display different URLs, but you can also use them to specify different page templates, remove the file extension from the URL or even pass parameters using routes instead of using query string values. For more information about routes, see ASP.NET Routing.

The following example shows how to specify the routes to use only one page template for all operations. The first route enables all operations in one page for a given table. The second route enables a page to navigate to the details of a record, such as navigating to a relationship table when you have a foreign key field.

routes.Add(New DynamicDataRoute("{table}/ListDetails.aspx") With { _
  .Action = PageAction.List, _
  .ViewName = "ListDetails", _
  .Model = model})

routes.Add(New DynamicDataRoute("{table}/ListDetails.aspx") With { _
  .Action = PageAction.Details, _
  .ViewName = "ListDetails", _
  .Model = model})

routes.Add(new DynamicDataRoute("{table}/ListDetails.aspx")
{
    Action = PageAction.List,
    ViewName = "ListDetails",
    Model = model
});

routes.Add(new DynamicDataRoute("{table}/ListDetails.aspx")
{
    Action = PageAction.Details,
    ViewName = "ListDetails",
    Model = model
});

You can also create specific routes for specific tables, by specifying a different page template than the one used by the rest of the tables. The routes are analyzed in the order they are defined. You must first define the more specific routes and then define the generic ones.

The following example shows how to specify a different page template for the Products table of the AdventureWorks database and then define a generic one for the other tables of the database.

routes.Add(New DynamicDataRoute("Products/{action}.aspx") With { _
  .ViewName = "ListDetails", _
  .Table = "Products", _
  .Model = model})

routes.Add(New DynamicDataRoute("{table}/{action}.aspx") With { _
  .Constraints = New RouteValueDictionary( _
    New With {.Action = "List|Details|Edit|Insert"}), _
  .Model = model})

routes.Add(new DynamicDataRoute("Products/{action}.aspx")
{
    ViewName = "ListDetails",
    Table = "Products",
    Model = model
});

routes.Add(new DynamicDataRoute("{table}/{action}.aspx")
{
    Constraints = new RouteValueDictionary(
      new { action = "List|Details|Edit|Insert" }),
    Model = model
});

See Also

Concepts

ASP.NET Dynamic Data Overview

ASP.NET Routing

Change History

Date	History	Reason
July 2008	Added topic for new feature.	SP1 feature change.