ASP.NET Dynamic Data Infrastructure

Article
10/22/2014

This topic describes the layout of an ASP.NET Dynamic Data Web site, and includes information about the folders and files that are created by default.

You can create an ASP.NET Dynamic Data Web site in Visual Studio 2008 by using the Dynamic Data Web Site template. This template generates the user controls, page templates, and ASP.NET Web files that Dynamic Data uses to create UI for working with data.

Data Context Class

A Dynamic Data Web application requires a MetaModel object and a registered data context. The data context can be either LINQ to SQL class (an instance of the System.Data.Linq.DataContext class) or an ADO.NET Entity Framework class. The data context class should be in the App_Code folder at the root of the application. For more information, see ASP.NET Dynamic Data Model Overview.

Folders and Files

The following table describes the files and folders that are created at the root level in an ASP.NET Dynamic Data Web site.

File or Folder	Description
Dynamic Data	Contains folders for custom controls and for pages that display data. For more information about the subfolders of the Dynamic Data folder, see DynamicData Folder Structure later in this topic.
Default.aspx	An ASP.NET page that displays the tables and views that are registered in the MetaModel instance. Each table name is rendered as a HyperLink control that displays the contents of the selected table.
Global.asax	Contains a method to register an instance of the MetaModel class and to add routes to the RouteCollection object. For more information, see Web Site Configuration later in this topic.
Site.css	A cascading style sheet that is used by Dynamic Data page templates and controls.
Site.master	The master page for the site. Default.aspx and Dynamic Data page templates use the master page.
Web.config	The configuration file for the site. For more information, see Web Site Configuration later in this topic.

Web Site Configuration

By default, a Dynamic Data Web site includes files that are typical in ASP.NET Web sites. However, the files include information or code that is specific to Dynamic Data. This section provides information about the files that Dynamic Data uses.

Global.asax File

In a Dynamic Data Web site, the Global.asax file contains a handler for the Application_Start event that is raised when the Web application starts. In the handler, the RegisterRoutes method is called. The RegisterRoutes method contains a MetaModel instance and a commented-out call to RegisterContext. To enable Dynamic Data operations, you must enable the RegisterContext method and pass to it a valid data context, such as a DataContext instance or ADO.NET Entity Framework context.

By default, the Global.asax file in a Dynamic Data Web site calls the Add(Type) method to add routing for the List.aspx, Details.aspx, Edit.aspx, and Insert.aspx pages for each action.

ListDetails.aspx Page Template

A page template is an .aspx file that includes controls that Dynamic Data can use to create UI for displaying and editing data. Routes that are defined in the Global.asax file determine which page templates Dynamic Data uses to perform List, Details, Edit and Insert actions. For more information, see ASP.NET Dynamic Data Scaffolding and Page Templates Overview.

You can change the routing to the page templates by adding and removing route definitions in the Global.asax file. (Pre-defined alternative routes are included in the Global.asax file but are commented out.) For more information, see the comments in the Global.asax file.

To make all tables viewable by using Dynamic Data, you set the ScaffoldAllTables property of the ContextConfiguration object to true. Alternatively, you can set the ScaffoldTableAttribute attribute to true in the partial class that represents the table to be displayed. The ScaffoldTableAttribute attribute lets you selectively display tables by using Dynamic Data.

Site.master File

The Site.master file is the master page for the Dynamic Data Web site. It is used by all Dynamic Data page templates. The Site.master file contains a System.Web.UI.ScriptManager control whose EnablePartialRendering property is set to true. For more information, see ASP.NET Master Pages Overview.

Note When the EnablePartialRendering property is set to true, exceptions that are thrown by the database server result in a run-time error in the browser. For example, if you try to update a row that has a column constraint that is defined in the database, and the update data violates the constraint, the browser will display a run-time error. When the EnablePartialRendering property is set to false, the browser does not display a detailed exception message. Instead, the browser displays an HTTP 500 error that indicates that a problem has occurred during server processing. For more information, see Adding AJAX and Client Capabilities Roadmap.

Web.config File

The Visual Studio Dynamic Data Web Site template generates a Web.config file that contains elements that are specific to Dynamic Data, in addition to those used for all ASP.NET Web sites. In the assemblies section, the following DLLs are added:

System.Web.Abstractions
System.Web.Routing
System.ComponentModel.DataAnnotations
System.Web.DynamicData
System.Data.Linq

The tag prefix "asp:" is registered for the System.Web.DynamicData namespace and assembly.

The following controls from the System.Web.DynamicData assembly are used by controls in the FieldTemplates folder.

The URL routing module UrlRoutingModule is added to the httpModules element and the system.webServer section.

DynamicData Folder Structure

The following table describes the subfolders in the DynamicData folder.

File or folder	Description
Content	By default, contains the Images folder and two controls (GridViewPager.ascx and FilterUserControl.ascx). The Images folder contains graphics files that are used as icons for the pager control. FilterUserControl.ascx is an ASP.NET user control that is used to filter foreign key columns. For more information, see Dynamic Data Web Server Controls in this document.
CustomPages	Container folder for custom page templates. Custom page templates are used to override the page templates that are defined in DynamicData\PageTemplates. For example, if the data context contains a table named Products, you can create a DynamicData\CustomPages\Products folder and add .aspx pages in the new folder that are used to display Products data. An easy way to start is to copy the pages from the DynamicData\PageTemplates folder into the new DynamicData\CustomPages\Products, and then to modify the templates. For more information about custom page templates, see How to: Customize the Layout of an Individual Table By Using a Custom Page Template.
FieldTemplates	Contains the Dynamic Data user controls that map to data types from the data model. For more information, see ASP.NET Dynamic Data Field Templates Overview andASP.NET Dynamic Data Field Templates Overview.
PageTemplates	Container folder for page templates that produce UI that is used to view and edit data. For more information, see ASP.NET Dynamic Data Scaffolding and Page Templates Overview.

GridViewPager Control

The GridViewPager.ascx file is a user control that derives from WebControl. It is used to enhance paging when there is more than one page of data for a table. The GridViewPager user control is used in the List.aspx and ListDetails.aspx page templates.

FilterUserControl Control

The FilterUserControl.ascx file is an ASP.NET user control that is used to filter foreign keys and Boolean columns. The FilterUserControl control is used in the List.aspx and ListDetails.aspx page templates. It is initialized one time for each foreign key and for each Boolean column in the table.

For example, in a Dynamic Data Web site that uses the AdventureWorksLT database, you can request a page that displays data from the Product table. The Product table contains the ProductCategoryID foreign-key column that references the ProductCategory table. Dynamic Data infers that the ProductCategoryID foreign key corresponds to the Name field in the ProductCategory table. It then substitutes the Name field from the ProductCategory tables for the ProductCategoryID field.

When the Product table of the AdventureWorksLT database is displayed, the FilterUserControl is used to create a DropDownList control for the ProductCategoryID foreign key, by using the inferred name for the ProductCategoryID field. You can select a product category in order to display only the rows in the table that contain the selected product category. For example, if you select Mountain Bikes, only the rows whose product category is Mountain Bikes are displayed.

A FilterUserControl is also added for each Boolean column in a table. For Boolean columns, you can select all fields or just those that are marked true or false.

Limitations of the FilterUserControl Control

The FilterUserControl is most useful for Boolean columns and foreign-key columns that have relatively few rows in the referenced table.