Introducing Web Forms

What is ASP.NET Web Forms?

Writing Your First Web Forms Page
Using ASP <%%> Render Blocks
Introduction to Server Controls
Handling Server Control Events
Using Custom Server Controls
Lists, Data, and Databinding
Form Validation Controls
Code-Behind Web Forms
Section Summary

What is ASP.NET Web Forms?

The ASP.NET Web Forms page framework is a scalable common language runtime programming model that can be used on the
server to dynamically generate Web pages.
Intended as a logical evolution of ASP (ASP.NET provides syntax compatibility with existing pages), the ASP.NET Web Forms
framework has been specifically designed to address a number of key deficiencies in the previous model. In particular, it
provides:

• The ability to create and use reusable UI controls that can encapsulate common functionality and thus reduce the amount
of code that a page developer has to write.
• The ability for developers to cleanly structure their page logic in an orderly fashion (not "spaghetti code").
• The ability for development tools to provide strong WYSIWYG design support for pages (existing ASP code is opaque to
tools).

This section of the QuickStart provides a high-level code walkthrough of some key ASP.NET Web Forms features. Subsequent
sections of the QuickStart drill down into more specific details.

Writing Your First Web Forms Page

ASP.NET Web Forms pages are text files with an .aspx file name extension. They can be deployed throughout an IIS virtual root
directory tree. When a browser client requests .aspx resources, the ASP.NET runtime parses and compiles the target file into a
.NET Framework class. This class can then be used to dynamically process incoming requests. (Note that the .aspx file is
compiled only the first time it is accessed; the compiled type instance is then reused across multiple requests).
An ASP.NET page can be created simply by taking an existing HTML file and changing its file name extension to .aspx (no
modification of code is required). For example, the following sample demonstrates a simple HTML page that collects a user's
name and category preference and then performs a form postback to the originating page when a button is clicked:

VB Intro1.aspx

[Run Sample] | [View Source]

Important: Note that nothing happens yet when you click the Lookup button. This is because the .aspx file contains only static
HTML (no dynamic content). Thus, the same HTML is sent back to the client on each trip to the page, which results in a loss of
the contents of the form fields (the text box and drop-down list) between requests.

Using ASP <% %> Render Blocks

ASP.NET provides syntax compatibility with existing ASP pages. This includes support for <% %> code render blocks that can be
intermixed with HTML content within an .aspx file. These code blocks execute in a top-down manner at page render time.
The below example demonstrates how <% %> render blocks can be used to loop over an HTML block (increasing the font size
each time):

VB Intro2.aspx
 [Run Sample] | [View Source]
Important: Unlike with ASP, the code used within the above <% %> blocks is actually compiled--not interpreted using a script
engine. This results in improved runtime execution performance.
ASP.NET page developers can utilize <% %> code blocks to dynamically modify HTML output much as they can today with ASP.
For example, the following sample demonstrates how <% %> code blocks can be used to interpret results posted back from a
client.

VB Intro3.aspx

[Run Sample] | [View Source]

Important: While <% %> code blocks provide a powerful way to custom manipulate the text output returned from an ASP.NET
page, they do not provide a clean HTML programming model. As the sample above illustrates, developers using only <% %>
code blocks must custom manage page state between round trips and custom interpret posted values.

Introduction to ASP.NET Server Controls

In addition to (or instead of) using <% %> code blocks to program dynamic content, ASP.NET page developers can use ASP.NET
server controls to program Web pages. Server controls are declared within an .aspx file using custom tags or intrinsic HTML tags
that contain a runat="server" attribute value. Intrinsic HTML tags are handled by one of the controls in the
System.Web.UI.HtmlControls namespace. Any tag that doesn't explicitly map to one of the controls is assigned the type of
System.Web.UI.HtmlControls.HtmlGenericControl.
The following sample uses four server controls: <form runat=server>, <asp:textbox runat=server>,
<asp:dropdownlist runat=server>, and <asp:button runat=server>. At run time these server controls automatically
generate HTML content.

VB Intro4.aspx

[Run Sample] | [View Source]

Important: Note that these server controls automatically maintain any client-entered values between round trips to the server.
This control state is not stored on the server (it is instead stored within an <input type="hidden"> form field that is round-
tripped between requests). Note also that no client-side script is required.
In addition to supporting standard HTML input controls, ASP.NET enables developers to utilize richer custom controls on their
pages. For example, the following sample demonstrates how the <asp:adrotator> control can be used to dynamically display
rotating ads on a page.

VB Intro5.aspx

[Run Sample] | [View Source]

Important: A detailed listing of all built-in server controls can be found in the Web Forms Control Reference section of this
QuickStart.

Handling Server Control Events

Each ASP.NET server control is capable of exposing an object model containing properties, methods, and events. ASP.NET
developers can use this object model to cleanly modify and interact with the page.
The following example demonstrates how an ASP.NET page developer can handle the OnClick event from the <asp:button
runat=server> control to manipulate the Text property of the <asp:label runat=server> control.
 VB Intro6.aspx

[Run Sample] | [View Source]

This simple sample is functionally equivalent to the "Intro3" sample demonstrated earlier in this section. Note, however, how
much cleaner and easier the code is in this new server-control-based version.

Using Custom Server Controls

ASP.NET ships with 45 built-in server controls that can be used out of the box (for details, see Web Forms Controls Reference).
In addition to using the built-in ASP.NET controls, developers also can use controls developed by third-party vendors.
The following sample shows a simple calendar control. The Calendar control is declared within the page using an
<acme:calendar runat=server> tag. Note that the <% Register %> directive at the top of the page is responsible for
registering the "Acme" XML tag prefix with the "Acme" code namespace of the control implementation. The ASP.NET page parser
will then utilize this namespace to load the Calendar control class instance at run time.

VB Intro7.aspx

[Run Sample] | [View Source]

The Calendar control in this sample has been designed to perform "uplevel-like" processing on Internet Explorer 5.5 and
"downlevel" processing on all other browsers. This browser sniffing is nowhere near as complex as that provided by the ASP.NET
built-in server controls. For Internet Explorer 5.5 browsers it generates DHTML output. This DHTML output does not require
round trips back to the server when doing day selections and month navigations. For all other browsers the control generates
standard HTML 3.2. This HTML 3.2 does require round trips back to the server to handle client-side user interactions.
Important: The code that a page developer writes is identical regardless of whether an "uplevel" or "downlevel" browser is used
to access the page. The Calendar control itself encapsulates all of the logic required to handle the two scenarios.

Lists, Data, and Data Binding

ASP.NET ships with a built-in set of data grid and list controls. These can be used to provide custom UI driven from queries
against a database or other data source. For example, the following sample demonstrates how a <asp:datagrid
runat=server> control can be used to databind book information collected using a SQL database query.

VB Intro8.aspx

[Run Sample] | [View Source]

The <asp:datagrid runat=server> DataGrid control provides an easy way to quickly display data results using a traditional
grid-control UI. Alternatively, ASP.NET developers can use the <asp:DataList runat=server> DataList control and a custom
ItemTemplate template to customize data information, as in the following sample.

VB Intro9.aspx

[Run Sample] | [View Source]

Note that the <asp:datalist runat=server> control enables end users to exactly control the structure and layout of each item
within the list (using the ItemTemplate template property). The control also automatically handles the two-column wrapping of
content (users can control the number of columns using the RepeatColumns property on the data list).
The following sample provides an alternate view of the <asp:datalist runat=server> control.

VB Intro10.aspx

[Run Sample] | [View Source]

Note that the control, data model, and page user in this example are exactly the same as those in the previous sample. The only
difference is that, here, alternative templates are declaratively supplied to the code.

Form Validation Controls

The ASP.NET Web Forms page framework provides a set of validation server controls that provide an easy-to-use but powerful
way to check input forms for errors, and, if necessary, display messages to the user.
Validation controls are added to an ASP.NET page like other server controls. There are controls for specific types of validation,
such as range checking or pattern matching, plus a RequiredFieldValidator that ensures that a user does not skip an entry
field.
The following example demonstrates how to use two <asp:requiredfieldvalidator runat=server> controls on a page to
validate the contents of the TextBox and DropDownList controls.

VB Intro11.aspx

[Run Sample] | [View Source]

Note that the validation controls have both uplevel and downlevel client support. Uplevel browsers perform validation on the
client (using JavaScript and DHTML) and on the server. Downlevel browsers perform the validation only on the server. The
programming model for the two scenarios is identical.
Note that ASP.NET page developers can optionally check the Page.IsValid property at run time to determine whether all
validation server controls on a page are currently valid. This provides a simple way to determine whether or not to proceed with
business logic. For example, the following sample performs a Page.IsValid check before executing a database lookup on the
specified category.

VB Intro12.aspx

[Run Sample] | [View Source]

Code-Behind Web Forms

ASP.NET supports two methods of authoring dynamic pages. The first is the method shown in the preceding samples, where the
page code is physically declared within the originating .aspx file. An alternative approach--known as the code-behind method--
enables the page code to be more cleanly separated from the HTML content into an entirely separate file.
The following sample demonstrates the use of the code-behind method of writing ASP.NET page code.

VB Intro13.aspx
 [Run Sample] | [View Source]

Section Summary

1. ASP.NET Web Forms provide an easy and powerful way to build dynamic Web UI.
2. ASP.NET Web Forms pages can target any browser client (there are no script library or cookie requirements).
3. ASP.NET Web Forms pages provide syntax compatibility with existing ASP pages.
4. ASP.NET server controls provide an easy way to encapsulate common functionality.
5. ASP.NET ships with 45 built-in server controls. Developers can also use controls built by third parties.
6. ASP.NET server controls can automatically project both uplevel and downlevel HTML.
7. ASP.NET templates provide an easy way to customize the look and feel of list server controls.
8. ASP.NET validation controls provide an easy way to do declarative client or server data validation.
Working with Server Controls

Declaring Server Controls

Manipulating Server Controls
Handling Control Action Events
Handling Multiple Control Action Events
Performing Page Navigation (Scenario 1)
Performing Page Navigation (Scenario 2)

This section of the QuickStart illustrates some common core concepts and common actions performed by end users when using
ASP.NET server controls within a page.

Declaring Server Controls

ASP.NET server controls are identified within a page using declarative tags that contain a runat="server" attribute. The
following example declares three <asp:label runat="server"> server controls and customizes the text and style properties of
each one individually.

VB Controls1.aspx

[Run Sample] | [View Source]

Manipulating Server Controls

You can programmatically identify an individual ASP.NET server control within a page by providing it with an id attribute. You can
use this id reference to programmatically manipulate the server control's object model at run time. For example, the following
sample demonstrates how a page developer could programmatically set an <asp:label runat="server"> control's Text
property within the Page_Load event.

VB Controls2.aspx

[Run Sample] | [View Source]

Handling Control Action Events

ASP.NET server controls can optionally expose and raise server events, which can be handled by page developers. A page
developer may accomplish this by declaratively wiring an event to a control (where the attribute name of an event wireup
indicates the event name and the attribute value indicates the name of a method to call). For example, the following code
example demonstrates how to wire an OnClick event to a button control.

VB Controls3.aspx

[Run Sample] | [View Source]

Handling Multiple Control Action Events

Event handlers provide a clean way for page developers to structure logic within an ASP.NET page. For example, the following
sample demonstrates how to wire and handle four button events on a single page.
 VB Controls4.aspx

[Run Sample] | [View Source]

Performing Page Navigation (Scenario 1)

Page navigation among multiple pages is a common scenario in virtually all Web applications. The following sample demonstrates
how to use the <asp:hyperlink runat=server> control to navigate to another page (passing custom query string parameters
along the way). The sample then demonstrates how to easily get access to these query string parameters from the target page.

VB Controls5.aspx

[Run Sample] | [View Source]

Performing Page Navigation (Scenario 2)

Not all page navigation scenarios are initiated through hyperlinks on the client. Client-side page redirects or navigations can also
be initiated from the server by an ASP.NET page developer by calling the Response.Redirect(url) method. This is typically
done when server-side validation is required on some client input before the navigation actually takes place.
The following sample demonstrates how to use the Response.Redirect method to pass parameters to another target page. It
also demonstrates how to easily get access to these parameters from the target page.

VB Controls6.aspx

[Run Sample] | [View Source]

Applying Styles to Controls

Applying Styles to HTMLControls

Applying Styles to Web Controls
Section Summary

The Web is a flexible environment for user interfaces, with extreme variations in the look and feel of different Web sites. The
widespread adoption of cascading style sheets (CSS) is largely responsible for the rich designs encountered on the Web. All of
ASP.NET's HTML server controls and Web server controls have been designed to provide first-class support for CSS styles. This
section discusses how to use styles in conjunction with server controls and demonstrates the very fine control over the look and
feel of your Web Forms that they provide.

Applying Styles to HTML Controls

Standard HTML tags support CSS through a style attribute, which can be set to a semicolon-delimited list of attribute/value pairs.
For more information about the CSS attributes supported by the Internet Explorer browser, see MSDN Web Workshop's CSS
Attributes Reference page. All of the ASP.NET HTML server controls can accept styles in exactly the same manner as standard
HTML tags. The following example illustrates a number of styles applied to various HTML server controls. If you view the source
code on the page returned to the client, you will see that these styles are passed along to the browser in the control's rendering.

VB Style1.aspx

[Run Sample] | [View Source]

CSS also defines a class attribute, which can be set to a CSS style definition contained in a <style>...</style> section of the
document. The class attribute makes it easy to define styles once and apply them to several tags without having to redefine the
style itself. Styles on HTML server controls also can be set in this manner, as demonstrated in the following sample.

VB Style2.aspx

[Run Sample] | [View Source]

When an ASP.NET page is parsed, the style information is populated into a Style property (of type CssStyleCollection) on the
System.Web.UI.HtmlControls.HtmlControl class. This property is essentially a dictionary that exposes the control's styles as
a string-indexed collection of values for each style-attribute key. For example, you could use the following code to set and
subsequently retrieve the width style attribute on an HtmlInputText server control.

<script language="VB" runat="server" >

Sub Page_Load(Sender As Object, E As EventArgs)

MyText.Style("width") = "90px"
Response.Write(MyText.Style("width"))
End Sub

</script>

<input type="text" id="MyText" runat="server"/>

 C# VB JScript
This next sample shows how you can programmatically manipulate the style for an HTML server control using this Style
collection property.

VB Style3.aspx

[Run Sample] | [View Source]

Applying Styles to Web Server Controls

Web server controls provide an additional level of support for styles by adding several strongly typed properties for commonly
used style settings, such as background and foreground color, font name and size, width, height, and so on. These style
properties represent a subset of the style behaviors available in HTML and are represented as "flat" properties exposed directly
on the System.Web.UI.WebControls.WebControl base class. The advantage of using these properties is that they provide
compile-time type checking and statement completion in development tools such as Microsoft Visual Studio .NET.
The following sample shows a WebCalendar control with several styles applied to it (a calendar without styles applied is
included for contrast). Note that when setting a property that is a class type, such as Font, you need to use the subproperty
syntax PropertyName-SubPropertyName .

VB Style4.aspx

[Run Sample] | [View Source]

The System.Web.UI.WebControls namespace includes a Style base class that encapsulates common style attributes
(additional style classes, such as TableStyle and TableItemStyle, inherit from this common base class). Many Web server
controls expose properties of this type for specifying the style of individual rendering elements of the control. For example, the
WebCalendar exposes many such style properties: DayStyle, WeekendDayStyle, TodayDayStyle, SelectedDayStyle,
OtherMonthDayStyle, and NextPrevStyle. You can set individual properties of these styles using the subproperty syntax
PropertyName-SubPropertyName, as the following sample demonstrates.

VB Style5.aspx

[Run Sample] | [View Source]

A slightly different syntax allows each Style property to be declared as a child element nested within Web server control tags.
<ASP:Calendar ... runat="server">
<TitleStyle BorderColor="darkolivegreen" BorderWidth="3"
BackColor="olivedrab" Height="50px" />
</ASP:Calendar>
The following sample shows alternative syntax but is functionally equivalent to the preceding one.

VB Style6.aspx
 [Run Sample] | [View Source]
As with HTML server controls, you can apply styles to Web server controls using a CSS class definition. The WebControl base
class exposes a String property named CssClass for setting the style class:

VB Style7.aspx

[Run Sample] | [View Source]

If an attribute is set on a server control that does not correspond to any strongly typed property on the control, the attribute and
value are populated in the Attributes collection of the control. By default, server controls will render these attributes unmodified
in the HTML returned to the requesting browser client. This means that the style and class attributes can be set on Web server
controls directly instead of using the strongly typed properties. While this requires some understanding of the actual rendering of
the control, it can be a flexible way to apply styles as well. It is especially useful for the standard form input controls, as
illustrated in the following sample.

VB Style8.aspx

[Run Sample] | [View Source]

Web server control styles can also be set programmatically, using the ApplyStyle method of the base WebControl class, as in
the following code.

<script language="VB" runat="server">

Sub Page_Load(Src As Object, E As EventArgs)
Dim MyStyle As New Style
MyStyle.BorderColor = Color.Black
MyStyle.BorderStyle = BorderStyle.Dashed
MyStyle.BorderWidth = New Unit(1)

MyLogin.ApplyStyle (MyStyle)
MyPassword.ApplyStyle (MyStyle)
MySubmit.ApplyStyle (MyStyle)
End Sub
</script>

Login: <ASP:TextBox id="MyLogin" runat="server" />/<p/>

Password: <ASP:TextBox id="MyPassword" TextMode="Password" runat="server" />
View: <ASP:DropDownList id="MySelect" runat="server"> ... </ASP:DropDownList>

C# VB JScript
The following sample demonstrates the code above.
 VB Style9.aspx

[Run Sample] | [View Source]

Section Summary

1. ASP.NET's HTML server control and Web server control families provide first-class support for CSS styles.
2. Styles may be applied by setting either the style or the class attributes of a control. These settings are accessible
programmatically through the control's Attributes collection. In the case of HTML server controls, individual values for
style-attribute keys can be retrieved from the control's Style collection.
3. Most commonly used style settings are exposed on Web server controls as strongly typed properties of the control
itself.
4. The System.Web.UI.WebControls namespace includes a Style base class that encapsulates common style
attributes. Many Web server controls expose properties of this type to control individual rendering elements.
5. Styles may be set programmatically on Web server controls using the ApplyStyle method of the WebControl base
class.
Server Control Form Validation

Introduction to Validation
Types of Validation Controls
Client-Side Validation
Displaying Validation Errors
Working with CompareValidator
Working with RangeValidator
Working with Regular Expressions
Performing Custom Validation
Bringing It All Together
Section Summary

Introduction to Validation
The Web Forms framework includes a set of validation server controls that provide an easy-to-use but powerful way to check
input forms for errors and, if necessary, display messages to the user.
Validation controls are added to a Web Forms page like other server controls. There are controls for specific types of validation,
such as range checking or pattern matching, plus a RequiredFieldValidator that ensures that a user does not skip an entry
field. You can attach more than one validation control to an input control. For example, you might specify both that an entry is
required and that it must contain a specific range of values.
Validation controls work with a limited subset of HTML and Web server controls. For each control, a specific property contains the
value to be validated. The following table lists the input controls that may be validated.
Control Validation Property
HtmlInputText Value
HtmlTextArea Value
HtmlSelect Value
HtmlInputFile Value
TextBox Text
ListBox SelectedItem.Value
DropDownList SelectedItem.Value
RadioButtonList SelectedItem.Value

Types of Validation Controls

The simplest form of validation is a required field. If the user enters any value in a field, it is valid. If all of the fields in the page
are valid, the page is valid. The following example illustrates this using the RequiredFieldValidator.

VB Validator1.aspx

[Run Sample] | [View Source]

There are also validation controls for specific types of validation, such as range checking or pattern matching. The following table
lists the validation controls.
Control Name Description
RequiredFieldValidator Ensures that the user does not skip an entry.
Compares a user's entry with a constant value or a property
CompareValidator value of another control using a comparison operator (less
than, equal to, greater than, and so on).
Checks that a user's entry is between specified lower and
upper boundaries. You can check ranges within pairs of
RangeValidator
numbers, alphabetic characters, or dates. Boundaries can be
expressed as constants.
Checks that the entry matches a pattern defined by a regular
RegularExpressionValidator expression. This type of validation allows you to check for
predictable sequences of characters, such as those in social
 security numbers, e-mail addresses, telephone numbers,
postal codes, and so on.
Checks the user's entry using validation logic that you code
CustomValidator yourself. This type of validation allows you to check for values
derived at run time.
Displays the validation errors in summary form for all of the
ValidationSummary
validators on a page.

Client-Side Validation
The validation controls always perform validation checking in server code. However, if the user is working with a browser that
supports DHTML, the validation controls can also perform validation using client script. With client-side validation, any errors are
detected on the client when the form is submitted to the server. If any of the validators are found to be in error, the submission
of the form to the server is cancelled and the validator's Text property is displayed. This permits the user to correct the input
before submitting the form to the server. Field values are revalidated as soon as the field containing the error loses focus, thus
providing the user with a rich, interactive validation experience.
Note that the Web Forms page framework always performs validation on the server, even if the validation has already been
performed on the client. This helps prevent users from being able to bypass validation by impersonating another user or a
preapproved transaction.
Client-side validation is enabled by default. If the client is capable, uplevel validation will be performed automatically. To disable
client-side validation, set the page's ClientTarget property to "Downlevel" ("Uplevel" forces client-side validation).

VB Validator2.aspx

[Run Sample] | [View Source]

Displaying Validation Errors

When the user's input is processed (for example, when the form is submitted), the Web Forms page framework passes the user's
entry to the associated validation control or controls. The validation controls test the user's input and set a property to indicate
whether the entry passed the validation test. After all validation controls have been processed, the IsValid property on the page
is set; if any of the controls shows that a validation check failed, the entire page is set to invalid.
If a validation control is in error, an error message may be displayed in the page by that validation control or in a
ValidationSummary control elsewhere on the page. The ValidationSummary control is displayed when the IsValid property
of the page is false. It polls each of the validation controls on the page and aggregates the text messages exposed by each. The
following example illustrates displaying errors with a ValidationSummary control.

VB Validator3.aspx

[Run Sample] | [View Source]

Working with CompareValidator

The CompareValidator server control compares the values of two controls. CompareValidator uses three key properties to
perform its validation. ControlToValidate and ControlToCompare contain the values to compare. Operator defines the type
of comparison to perform--for example, Equal or Not Equal. CompareValidator performs the validation by evaluating these
properties as an expression, as follows:
( ControlToValidate ControlToCompare )
If the expression evaluates true, the validation result is valid.
The following sample shows how to use the CompareValidator control.
 VB Validator4.aspx

[Run Sample] | [View Source]

Working with RangeValidator

The RangeValidator server control tests whether an input value falls within a given range. RangeValidator uses three key
properties to perform its validation. ControlToValidate contains the value to validate. MinimumValue and MaximumValue
define the minimum and maximum values of the valid range.
This sample shows how to use the RangeValidator control.

VB Validator5.aspx

[Run Sample] | [View Source]

Working with Regular Expressions

The RegularExpressionValidator server control checks that the entry matches a pattern defined by a regular expression. This
type of validation allows you to check for predictable sequences of characters, such as those in social security numbers, e-mail
addresses, telephone numbers, postal codes, and so on.
RegularExpressionValidator uses two key properties to perform its validation. ControlToValidate contains the value to
validate. ValidationExpression contains the regular expression to match.
These samples illustrates using the RegularExpressionValidator control.

VB Validator6.aspx

[Run Sample] | [View Source]

VB Validator7.aspx

[Run Sample] | [View Source]

Performing Custom Validation

The CustomValidator server control calls a user-defined function to perform validations that the standard validators can't
handle. The custom function can execute on the server or in client-side script, such as JScript or VBScript. For client-side custom
validation, the name of the custom function must be identified in the ClientValidationFunction property. The custom function
must have the form
function myvalidator(source, arguments)
Note that source is the client-side CustomValidator object, and arguments is an object with two properties, Value and
IsValid. The Value property is the value to be validated and the IsValid property is a Boolean used to set the return result of
the validation.
For server-side custom validation, place your custom validation in the validator's OnServerValidate delegate.
The following sample shows how to use the CustomValidator control.

VB Validator8.aspx

[Run Sample] | [View Source]

Bringing It All Together

This sample shows a typical registration form, using the variations of validation controls discussed in this topic.

VB Validator9.aspx

[Run Sample] | [View Source]

Section Summary

1. Validator controls can be used to validate input on any Web Forms page.
2. More than one control can be used on a given input field.
3. Client-side validation may be used in addition to server validation to improve form usability.
4. The CustomValidator control lets the user define custom validation criteria.
Web Forms User Controls

Introduction to User Controls

Exposing User Control Properties
Encapsulating Events in a User Control
Creating User Controls Programmatically
Section Summary

Introduction to User Controls

In addition to the built-in server controls provided by ASP.NET, you can easily define your own controls using the same
programming techniques that you have already learned for writing Web Forms pages. In fact, with just a few modifications,
almost any Web Forms page can be reused in another page as a server control (note that a user control is of type
System.Web.UI.UserControl, which inherits directly from System.Web.UI.Control). A Web Forms page used as a server
control is named a user control for short. As a matter of convention, the .ascx extension is used to indicate such controls. This
ensures that the user control's file cannot be executed as a standalone Web Forms page (you will see a little that there are a few,
albeit important, differences between a user control and a Web Forms page). User controls are included in a Web Forms page
using a Register directive:
<%@ Register TagPrefix="Acme" TagName="Message" Src="pagelet1.ascx" %>
The TagPrefix determines a unique namespace for the user control (so that multiple user controls with the same name can be
differentiated from each other). The TagName is the unique name for the user control (you can choose any name). The Src
attribute is the virtual path to the user control--for example "MyPagelet.ascx" or "/MyApp/Include/MyPagelet.ascx". After
registering the user control, you may place the user control tag in the Web Forms page just as you would an ordinary server
control (including the runat="server" attribute):
<Acme:Message runat="server"/>
The following example shows a user control imported into another Web Forms page. Note that the user control in this case is just
a simple static file.

VB Pagelet1.aspx

[Run Sample] | [View Source]

Exposing User Control Properties

When a Web Forms page is treated as a control, the public fields and methods of that Web Form are promoted to public
properties (that is, tag attributes) and methods of the control as well. The following example shows an extension of the previous
user control example that adds two public String fields. Notice that these fields can be set either declaratively or
programmatically in the containing page.

VB Pagelet2.aspx

[Run Sample] | [View Source]

In addition to promoting public fields to control properties, the property syntax may be used. Property syntax has the advantage
of being able to execute code when properties are set or retrieved. The following example demonstrates an Address user control
that wraps the text properties of TextBox controls within it. The benefit of doing this is that the control inherits the automatic
state management of the TextBox control for free.
Notice that there are two Address user controls on the containing Web Forms page that set the Caption property to "Billing
Address" and "Shipping Address", respectively. The real power of user controls is in this type of reusability.
 VB Pagelet3.aspx

[Run Sample] | [View Source]

Another useful user control is a Login control for collecting user names and passwords.

VB Pagelet4.aspx

[Run Sample] | [View Source]

In this example, form validation controls are added to the Login user control.

VB Pagelet5.aspx

[Run Sample] | [View Source]

Encapsulating Events in a User Control

User controls participate in the complete execution lifecycle of the request, much the way ordinary server controls do. This means
that a user control can handle its own events, encapsulating some of the page logic from the containing Web Forms page. The
following example demonstrates a product-listing user control that internally handles its own postbacks. Note that the user
control itself has no wrapping <form runat="server"> control. Because only one form control may be present on a page
(ASP.NET does not allow nested server forms), it is left to the containing Web Forms page to define this.

VB Pagelet6.aspx

[Run Sample] | [View Source]

Creating User Controls Programmatically

Just as ordinary server controls can be created programmatically, so user controls can be. The page's LoadControl method is
used to load the user control, passing the virtual path to the user control's source file:

Dim c1 As Control = LoadControl("pagelet7.ascx")

CType(c1, (Pagelet7VB)).Category = "business"
Page.Controls.Add(c1)

C# VB JScript
The type of the user control is determined by a ClassName attribute on the Control directive. For example, a user control
saved with the file name "pagelet7.ascx" is assigned the strong type "Pagelet7CS" as follows:
<%@ Control ClassName="Pagelet7CS" %>
Because the LoadControl method returns a type of System.Web.UI.Control, it must be cast to the appropriate strong type in
order to set individual properties of the control. Finally, the user control is added to the base page's ControlCollection.
 VB Pagelet7.aspx

[Run Sample] | [View Source]

Important The strong type for a user control is available to the containing Web Forms page only if a Register directive is
included for the user control (even if there are no user control tags actually declared).

Section Summary

1. User controls allow developers to easily define custom controls using the same programming techniques as for writing
Web Forms pages.
2. As a matter of convention, an .ascx file name extension is used to indicate such controls. This ensures that a user
control file cannot be executed as a standalone Web Forms page.
3. User controls are included into another Web Forms page using a Register directive, which specifies a TagPrefix,
TagName, and Src location.
4. After the user control has been registered, a user control tag may be placed in a Web Forms page as an ordinary
server control (including the runat="server" attribute).
5. The public fields, properties, and methods of a user control are promoted to public properties (tag attributes) and
methods of the control in the containing Web Forms page.
6. User controls participate in the complete execution lifecycle of every request and can handle their own events,
encapsulating some of the page logic from the containing Web Forms page.
7. User controls should not contain any form controls but should instead rely on their containing Web Forms page to
include one if necessary.
8. User controls may be created programmatically using the LoadControl method of the System.Web.UI.Page class.
The type of the user control is determined by the ASP.NET runtime, following the convention filename_extension.
9. The strong type for a user control is available to the containing Web Forms page only if a Register directive is
included for the user control (even if there are no user control tags actually declared).
Data Binding Server Controls

Data Binding Overview and Syntax

Binding to Simple Properties
Binding to Collections & Lists
Binding Expressions or Methods
DataBinder.Eval()
Section Summary

Data Binding Overview and Syntax

ASP.NET introduces a new declarative data binding syntax. This extremely flexible syntax permits the developer to bind not only
to data sources, but also to simple properties, collections, expressions, and even results returned from method calls. The
following table shows some examples of the new syntax.
Simple
Customer: <%# custID %>
property
Collection Orders: <asp:ListBox id="List1" datasource='<%# myArray %>' runat="server">

Expression Contact: <%# ( customer.First Name + " " + customer.LastName ) %>

Method result Outstanding Balance: <%# GetBalance(custID) %>

Although this syntax looks similar to the ASP shortcut for Response.Write -- <%= %> -- its behavior is quite different. Whereas
the ASP Response.Write shortcut syntax was evaluated when the page was processed, the ASP.NET data binding syntax is
evaluated only when the DataBind method is invoked.
DataBind is a method of the Page and all server controls. When you call DataBind on a parent control, it cascades to all of the
children of the control. So, for example, DataList1.DataBind() invokes the DataBind method on each of the controls in the
DataList templates. Calling DataBind on the Page -- Page.DataBind() or simply DataBind() -- causes all data binding
expressions on the page to be evaluated. DataBind is commonly called from the Page_Load event, as shown in the following
example.

Protected Sub Page_Load(Src As Object, E As EventArgs)

DataBind()
End Sub

C# VB JScript
You can use a binding expression almost anywhere in the declarative section of an .aspx page, provided it evaluates to the
expected data type at run time. The simple property, expression, and method examples above display text to the user when
evaluated. In these cases, the data binding expression must evaluate to a value of type String. In the collection example, the
data binding expression evaluates to a value of valid type for the DataSource property of ListBox. You might find it necessary
to coerce the type of value in your binding expression to produce the desired result. For example, if count is an integer:
Number of Records: <%# count.ToString() %>

Binding to Simple Properties

The ASP.NET data binding syntax supports binding to public variables, properties of the Page, and properties of other controls
on the page.
The following example illustrates binding to a public variable and simple property on the page. Note that these values are
initialized before DataBind() is called.

VB DataBind1.aspx

[Run Sample] | [View Source]

The following example illustrates binding to a property of another control.
 VB DataBind2.aspx

[Run Sample] | [View Source]

Binding to Collections and Lists

List server controls like DataGrid, ListBox and HTMLSelect use a collection as a data source. The following examples illustrate
binding to usual common language runtime collection types. These controls can bind only to collections that support the
IEnumerable, ICollection, or IListSource interface. Most commonly, you'll bind to ArrayList, Hashtable, DataView and
DataReader.
The following example illustrates binding to an ArrayList.

VB DataBind3.aspx

[Run Sample] | [View Source]

The following example illustrates binding to a DataView. Note that the DataView class is defined in the System.Data
namespace.

VB DataBind4.aspx

[Run Sample] | [View Source]

The following example illustrates binding to a Hashtable.

VB DataBind5.aspx

[Run Sample] | [View Source]

Binding Expressions or Methods

Often, you'll want to manipulate data before binding to your page or a control. The following example illustrates binding to an
expression and the return value of a method.

VB DataBind6.aspx

[Run Sample] | [View Source]

DataBinder.Eval
The ASP.NET framework supplies a static method that evaluates late-bound data binding expressions and optionally formats the
result as a string. DataBinder.Eval is convenient in that it eliminates much of the explicit casting the developer must do to
coerce values to the desired data type. It is particularly useful when data binding controls within a templated list, because often
both the data row and the data field must be cast.
Consider the following example, where an integer will be displayed as a currency string. With the standard ASP.NET data binding
syntax, you must first cast the type of the data row in order to retrieve the data field, IntegerValue. Next, this is passed as an
argument to the String.Format method.

<%# String.Format("{0:c}", (CType(Container.DataItem, DataRowView)("IntegerValue"))) %>

C# VB JScript
This syntax can be complex and difficult to remember. In contrast, DataBinder.Eval is simply a method with three arguments:
the naming container for the data item, the data field name, and a format string. In a templated list like DataList, DataGrid, or
Repeater, the naming container is always Container.DataItem. Page is another naming container that can be used with
DataBinder.Eval.

<%# DataBinder.Eval(Container.DataItem, "IntegerValue", "{0:c}") %>

C# VB JScript
The format string argument is optional. If it is omitted, DataBinder.Eval returns a value of type object, as shown in the
following example.

<%# CType(DataBinder.Eval(Container.DataItem, "BoolValue"), Boolean) %>

C# VB JScript
It is important to note that DataBinder.Eval can carry a noticeable performance penalty over the standard data binding syntax
because it uses late-bound reflection. Use DataBinder.Eval judiciously, especially when string formatting is not required.

VB DataBind7.aspx

[Run Sample] | [View Source]

Section Summary

1. The ASP.NET declarative data binding syntax uses the <%# %> notation.
2. You can bind to data sources, properties of the page or another control, collections, expressions, and results returned
from method calls.
3. List controls can bind to collections that support the ICollection, IEnumerable, or IListSource interface, such as
ArrayList, Hashtable, DataView, and DataReader.
4. DataBinder.Eval is a static method for late binding. Its syntax can be simpler than the standard data binding syntax,
but performance is slower.
Server-Side Data Access

Introduction to Server-Side Data

Connections, Commands, and DataSets
Accessing SQL-based Data
Binding SQL Data to a DataGrid
Performing a Parameterized Select
Inserting Data in a SQL Database
Updating Data in a SQL Database
Deleting Data in a SQL Database
Sorting Data from a SQL Database
Working with Master-Detail Relationships
Writing and Using Stored Procedures
Accessing XML-based Data
Section Summary

Introduction to Server-Side Data

Data access is the heart of any real-world application, and ASP.NET provides a rich set of controls that are well-integrated with
the managed data access APIs provided in the common language runtime. This section walks through several iterations of a
sample that uses the ASP.NET DataGrid control to bind to the results of SQL queries and XML data files. This section assumes
some familiarity with database fundamentals and the SQL query language.
Server-side data access is unique in that Web pages are basically stateless, which presents some difficult challenges when trying
to perform transactions such as inserting or updating records from a set of data retrieved from a database. As you'll see in this
section, the DataGrid control can help manage these challenges, allowing you to concentrate more on your application logic and
less on the details of state management and event handling.

Connections, Commands, and Datasets

The common language runtime provides a complete set of managed data access APIs for data-intensive application development.
These APIs help to abstract the data and present it in a consistent way regardless of its actual source (SQL Server, OLEDB, XML,
and so on). There are essentially three objects you will work with most often: connections, commands, and datasets.

• A connection represents a physical connection to some data store, such as SQL Server or an XML file.
• A command represents a directive to retrieve from (select) or manipulate (insert, update, delete) the data store.
• A dataset represents the actual data an application works with. Note that datasets are always disconnected from their
source connection and data model and can be modified independently. However, changes to a dataset can be easily
reconciled with the originating data model.

For a more detailed walkthrough of the managed data access solution in the common language runtime, please read the
ADO.NET Overview section of this tutorial.

Accessing SQL-based Data

An application typically needs to perform one or more select, insert, update, or delete queries to a SQL database. The following
table shows an example of each of these queries.
Query Example
Simple Select SELECT * from Employees WHERE FirstName = 'Bradley';
SELECT * from Employees E, Managers M WHERE E.FirstName =
Join Select
M.FirstName;
INSERT into Employees VALUES ('123-45-
Insert
6789','Bradley','Millington','Program Manager');
UPDATE Employees SET Title = 'Development Lead' WHERE
Update
FirstName = 'Bradley';
Delete DELETE from Employees WHERE Productivity < 10;
To give your page access to the classes you will need to perform SQL data access, you must import the System.Data and
System.Data.SqlClient namespaces into your page.
<%@ Import Namespace="System.Data" %>
<%@ Import Namespace="System.Data.SqlClient" %>
To perform a select query to a SQL database, you create a SqlConnection to the database passing the connection string, and
then construct a SqlDataAdapter object that contains your query statement. To populate a DataSet object with the results
from the query, you call the command's Fill method.
Dim myConnection As New
SqlConnection("server=(local)\NetSDK;database=pubs;Trusted_Connection=yes")
Dim myCommand As New SqlDataAdapter("select * from Authors", myConnection)

Dim ds As New DataSet()

myCommand.Fill(ds, "Authors")

C# VB JScript
As mentioned earlier in this section, the benefit of using a dataset is that it gives you a disconnected view of the database. You
can operate on a dataset in your application, and then reconcile your changes with the actual database later. For long-running
applications this is often the best approach. For Web applications, you are usually performing short operations with each request
(commonly to simply display the data). You often don't need to hold a DataSet object over a series of several requests. For
situations like these, you can use a SqlDataReader.
A SqlDataReader provides a forward-only, read-only pointer over data retrieved from a SQL database. To use a
SqlDataReader, you declare a SqlCommand instead of a SqlDataAdapter. The SqlCommand exposes an ExecuteReader
method that returns a SqlDataReader. Note also that you must explicitly open and close the SqlConnection when you use a
SqlCommand. After a call to ExecuteReader, the SqlDataReader can be bound to an ASP.NET server control, as you'll see in
the next section.

Dim myConnection As SqlConnection = New

SqlConnection("server=(local)\NetSDK;database=pubs;Trusted_Connection=yes")
Dim myCommand As SqlCommand = New SqlCommand("select * from Authors", myConnection)

myConnection.Open()

Dim dr As SqlDataReader = myCommand.ExecuteReader()

...

myConnection.Close()

C# VB JScript
When performing commands that do not require data to be returned, such as inserts, updates, and deletes, you also use a
SqlCommand. The command is issued by calling an ExecuteNonQuery method, which returns the number of rows affected.
Note that the connection must be explicitly opened when you use the SqlCommand; the SqlDataAdapter automatically
handles opening the connection for you.

Dim myConnection As New

SqlConnection("server=(local)\NetSDK;database=pubs;Trusted_Connection=yes")
Dim myCommand As New SqlCommand( _
"UPDATE Authors SET phone='(800) 555-5555' WHERE au_id = '123-45-6789'", _
myConnection)

myCommand.Connection.Open()
myCommand.ExecuteNonQuery()
myCommand.Connection.Close()

C# VB JScript
Important: Always remember to close the connection to the data model before the page finishes executing. If you do not close
the connection, you might inadvertently exhaust the connection limit while waiting for the page instances to be handled by
garbage collection.

Binding SQL Data to a DataGrid

The following sample shows a simple select query bound to a DataGrid control. The DataGrid renders a table containing the
SQL data.

VB DataGrid1.aspx

[Run Sample] | [View Source]

Like the DropDownList shown in the Data Binding section, the DataGrid control supports a DataSource property that takes
an IEnumerable or ICollection, as well as a DataSet. You can use a DataSet by assigning the DefaultView property of a
table contained in the DataSet to the name of the table you wish to use within the DataSet. The DefaultView property
represents the current state of a table within a DataSet, including any changes which have been made by application code (row
deletions or value changes, for example). After setting the DataSource property, you call DataBind() to populate the control.

MyDataGrid.DataSource=ds.Tables("Authors").DefaultView
MyDataGrid.DataBind()

C# VB JScript
An alternative syntax is to specify both a DataSource and a DataMember. In this case, ASP.NET automatically gets the
DefaultView for you.

MyDataGrid.DataSource=ds
MyDataGrid.DataMember="Authors"
MyDataGrid.DataBind()

C# VB JScript
You can also bind directly to a SqlDataReader. In this case you are only displaying data, so the forward-only nature of the
SqlDataReader is perfectly suited to this scenario, and you benefit from the performance boost that SqlDataReader provides.

VB DataGrid1.1.aspx

[Run Sample] | [View Source]

Note: For the remainder of this section, only the DataSet model of data access is shown; however, any of these samples could
be re-written to take advantage of SQLDataReader as well.

Performing a Parameterized Select

You can also perform a parameterized select using the SqlDataAdapter object. The following sample shows how you can
modify the data selected using the value posted from a select HtmlControl.
 VB DataGrid2.aspx

[Run Sample] | [View Source]

The SqlDataAdapter maintains a Parameters collection that can be used to replace variable identifiers (denoted by an "@" in
front of the name) with values. You add a new SqlParameter to this collection that specifies the name, type, and size of the
parameter, and then set its Value property to the value of the select.

myCommand.SelectCommand.Parameters.Add(New SqlParameter("@State", SqlDbType.NVarChar,

2))
myCommand.SelectCommand.Parameters("@State").Value = MySelect.Value

C# VB JScript
Important: Note that the DataGrid's EnableViewState property has been set to false. If the data will be populated in each
request, there is no benefit to having the DataGrid store state information to be sent through a round trip with form posts.
Because the DataGrid stores all of its data when maintaining state, it is important to turn it off when appropriate to improve the
performance of your pages.
DataGrid2.aspx statically populates the values of the select box, but this will not work well if those values ever change in the
database. Because the select HtmlControl also supports an IEnumerable DataSource property, you can use a select query to
dynamically populate the select box instead, which guarantees that the database and user interface are always in sync. The
following sample demonstrates this process.

VB DataGrid3.aspx

[Run Sample] | [View Source]

Inserting Data in a SQL Database

To insert a row into the database, you can add a simple input form to the page, and execute an insert command in the form
submit event handler. Just as in the previous two samples, you use the command object's Parameters collection to populate the
command's values. Note that you also check to make sure the required values are not null before attempting to insert into the
database. This prevents an accidental violation of the database's field constraints. You also execute the insert command inside of
a try/catch block, just in case the primary key for inserted row already exists.

VB DataGrid4.aspx

[Run Sample] | [View Source]

Instead of explicitly checking the input values, you could have just as easily used the validator controls provided with ASP.NET.
The following sample shows how to do that. Note that using the RegEx Validator provides the additional benefit of checking the
format for the author ID, zip code, and phone number fields.
 VB DataGrid5.aspx

[Run Sample] | [View Source]

Updating Data in a SQL Database

Updating a database can often be tricky in Web applications. The DataGrid control provides some built-in support for this
scenario that makes updates easier. To allow rows to be edited, the DataGrid supports an integer EditItemIndex property,
which indicates which row of the grid should be editable. When this property is set, the DataGrid renders the row at that index
as text input boxes instead of simple labels. A value of -1 (the default) indicates that no rows are editable. The page can enclose
the DataGrid in a server-side form and get access to the edited data through the DataGrid's object model.
To figure out which row should be editable, you need a way to accept some input from the user about which row they would like
to edit. The DataGrid can contain an EditCommandColumn that renders links for firing three special events: EditCommand,
UpdateCommand, and CancelCommand. The EditCommandColumn is declaratively added to the DataGrid's Columns
collection, as shown in the following example.
<ASP:DataGrid id="MyDataGrid" runat="server"
...
OnEditCommand="MyDataGrid_Edit"
OnCancelCommand="MyDataGrid_Cancel"
OnUpdateCommand="MyDataGrid_Update"
DataKeyField="au_id"
>

<Columns>
<asp:EditCommandColumn EditText="Edit" CancelText="Cancel" UpdateText="Update" />
</Columns>

</ASP:DataGrid>
On the DataGrid tag itself, you wire event handlers to each of the commands fired from the EditCommandColumn. The
DataGridCommandEventArgs argument of these handlers gives you direct access to the index selected by the client, which
you use to set the DataGrid's EditItemIndex. Note that you need to re-bind the DataGrid for the change to take effect, as
shown in the following example.

Public Sub MyDataGrid_Edit(sender As Object, E As DataGridCommandEventArgs)

MyDataGrid.EditItemIndex = E.Item.ItemIndex
BindGrid()
End Sub

C# VB JScript
When a row of the DataGrid is being edited, the EditCommandColumn renders the Update and Cancel links. If the client
selects Cancel, you simply set the EditItemIndex back to -1. If the client selects Update, however, you need to execute your
update command to the database. Performing an update query requires that you know the primary key in the database for the
row you wish to update. To support this, the DataGrid exposes a DataKeyField property that you can set to the field name for
the primary key. In the event handler wired to the UpdateCommand, you can retrieve the key name from the DataGrid's
DataKeys collection. You index into this collection using the ItemIndex of the event, as shown in the following example.
myCommand.Parameters("@Id").Value = MyDataGrid.DataKeys(CType(E.Item.ItemIndex, Integer))

C# VB JScript
At the end of the Update event handler, you set the EditItemIndex back to -1. The following sample demonstrates this code in
action.

VB DataGrid6.aspx

[Run Sample] | [View Source]

One problem with the preceding example is that the primary key field (au_id) also renders as a text input box when a row is
editable. You don't want the client to change this value, because you need it to determine which row to update in the database.
Fortunately, you can disable this column from rendering as a text box by specifying exactly what each column looks like for the
editable row. You do this by defining each row in the DataGrid's Columns collection, using the BoundColumn control to assign
data fields with each column. Using this technique gives you complete control over the order of the columns, as well as their
ReadOnly properties. For the au_id column you set the ReadOnly property to true. When a row is in edit mode, this column
will continue to render as a Label. The following sample demonstrates this technique.

VB DataGrid7.aspx

[Run Sample] | [View Source]

BoundColumn controls aren't the only controls you can set in the DataGrid's Columns collection. You can also specify a
TemplateColumn, which gives you complete control over the contents of the column. The template is just arbitrary content;
you can render anything you like, including server controls, inside the DataGrid's columns. The following sample demonstrates
using the TemplateColumn control to render the "State" column as a drop-down list and the "Contract" column as a check box
HtmlControl. The ASP.NET data binding syntax is used to output the data field value within the template. Note that there is a bit
of tricky logic to make the drop-down list and check box reflect the state of the data inside the row.

VB DataGrid8.aspx

[Run Sample] | [View Source]

Just as you can place a drop-down list or check box HtmlControl in a TemplateColumn, you can also place other controls there.
The following sample adds Validator controls to the columns to check the client input before attempting to perform the update.

VB DataGrid9.aspx

[Run Sample] | [View Source]

Deleting Data in a SQL Database

Deleting from a database is very similar to an update or insert command, but you still need a way to determine the particular row
of the grid to delete. Another control that can be added to the DataGrid's Columns collection is the ButtonColumn control,
which simply renders a button control. ButtonColumn supports a CommandName property that can be set to Delete. On the
DataGrid, you wire an event handler to the DeleteCommand, where you perform the delete operation. Again, you use the
DataKeys collection to determine the row selected by the client. The following sample demonstrates this process.

VB DataGrid10.aspx

[Run Sample] | [View Source]

Sorting Data from a SQL Database

A common requirement for any grid is the ability to sort the data it contains. While the DataGrid control doesn't explicitly sort its
data for you, it does provide a way to call an event handler when the user clicks a column header, which you can use to sort the
data. When the DataGrid's AllowSorting property is set to true, it renders hyperlinks for the column headers that fire a Sort
command back to the grid. You set the OnSortCommand property of the DataGrid to the handler you want to call when the
user clicks a column link. The name of the column is passed as a SortExpression property on the
DataGridSortCommandEventArgs argument, which you can use to set the Sort property of the DataView bound to the
grid. The following example demonstrates this process.

<script>
Protected Sub MyDataGrid_Sort(Src As Object, E As DataGridSortCommandEventArgs)
...
DataView Source = ds.Tables("Authors").DefaultView
Source.Sort = E.SortExpression
MyDataGrid.DataBind()
End Sub
</script>

<form runat="server">
<ASP:DataGrid id="MyDataGrid" OnSortCommand="MyDataGrid_Sort" AllowSorting="true"
runat="server" />
</form>

C# VB JScript
The following sample shows this code in action.

VB DataGrid11.aspx

[Run Sample] | [View Source]

When using BoundColumn controls, you can explicitly set the SortExpression property for each column, as demonstrated in
the following sample.
 VB DataGrid12.aspx

[Run Sample] | [View Source]

Working with Master-Detail Relationships

Often your data model will contain relationships that cannot be represented using just a single grid. A very common Web-based
interface is one in which a row of data can be selected that navigates the client to a "details" page, which displays detailed
information about the selected row. To accomplish this using the DataGrid, you can add a HyperLinkColumn to the Columns
collection, which specifies the details page to which the client will navigate when the link is clicked. You use the format string
syntax to substitute a field value in this link, which is passed as a querystring argument. The following example demonstrates this
process.
<ASP:DataGrid id="MyDataGrid" runat="server">

<Columns>
<asp:HyperLinkColumn
DataNavigateUrlField="au_id"
DataNavigateUrlFormatString="datagrid13_details.aspx?id={0}"
Text="Get Details"
/>
</Columns>

</ASP:DataGrid>
On the details page, you retrieve the querystring argument and perform a join select to obtain details from the database. The
following sample demonstrates this scenario.

VB DataGrid13.aspx

[Run Sample] | [View Source]

Writing and Using Stored Procedures

In general, performing ad hoc queries comes at the expense of performance. Using stored procedures can reduce the cost of
performing heavy database operations in an application. A stored procedure is easy to create, and can even be done using a SQL
statement. The following code example creates a stored procedure that simply returns a table.
CREATE Procedure GetAuthors AS
SELECT * FROM Authors
return
GO
You can create stored procedures that accept parameters as well. For example:
CREATE Procedure LoadPersonalizationSettings (@UserId varchar(50)) AS
SELECT * FROM Personalization WHERE UserID=@UserId
 return
GO
Using a stored procedure from an ASP.NET page is just an extension of what you've learned so far about the SqlCommand
object. The CommandText is just the name of the stored procedure instead of the ad hoc query text. You indicate to the
SqlCommand that the CommandText is a stored procedure by setting the CommandType property.

myCommand.SelectCommand.CommandType = CommandType.StoredProcedure

C# VB JScript
The following sample demonstrates a call to a stored procedure to fill the DataSet.

VB DataGrid14.aspx

[Run Sample] | [View Source]

Parameters to stored procedures are passed just as they are for ad hoc queries, as shown in the following samples.

VB DataGrid15.aspx

[Run Sample] | [View Source]

VB DataGrid16.aspx

[Run Sample] | [View Source]

Accessing XML-based Data

At the beginning of this section it was mentioned that the DataSet was designed to abstract data in a way that is independent of
the actual data source. You can see this by changing the focus of your samples from SQL to XML. The DataSet supports a
ReadXml method that takes a FileStream object as its parameter. The file you read in this case must contain both a schema
and the data you wish to read. The DataSet expects data to be in the form, as shown in the following example.
<DocumentElement>
<TableName>
<ColumnName1>column value</ColumnName1>
<ColumnName2>column value</ColumnName2>
<ColumnName3>column value</ColumnName3>
<ColumnName4>column value</ColumnName4>
</TableName>
<TableName>
<ColumnName1>column value</ColumnName1>
 <ColumnName2>column value</ColumnName2>
<ColumnName3>column value</ColumnName3>
<ColumnName4>column value</ColumnName4>
</TableName>
</DocumentElement>
Each TableName section corresponds to a single row in the table. The following sample shows reading schema and data from
an XML file using the ReadXml method of the DataSet. Note that after the data is read into the DataSet it is indistinguishable
from SQL data -- the DataGrid binds to it just the same, as shown in the following sample.

VB DataGrid17.aspx

[Run Sample] | [View Source]

You can also read the data and schema separately, using the ReadXmlData and ReadXmlSchema methods of the DataSet,
as shown in the following sample.

VB DataGrid18.aspx

[Run Sample] | [View Source]

Just as the DataSet supports reader methods for XML data, it also supports writing the data. The following sample implements a
tool for selecting data from SQL and writing the result as XML data or schema text.

VB XMLGen.aspx

[Run Sample] | [View Source]

Section Summary

1. The common language runtime's managed data access APIs abstract data and present it in a consistent way regardless
of its actual source (SQL Server, OLEDB, XML, and so on).
2. To give your page access to the classes you will need to perform SQL data access, you must import the System.Data
and System.Data.SqlClient namespaces into your page.
3. Populating a dataset from a SQL query involves creating a SqlConnection, associating a SqlDataAdapter object with
the connection that contains your query statement, and filling the dataset from the command.
4. The DataGrid control supports a DataSource property that takes an IEnumerable (or ICollection) type. You can
set this to the result of a SQL query by assigning the DataSet's DefaultView property, which is of type DataView.
5. The SqlDataAdapter maintains a Parameters collection that can be used to replace variable identifiers (denoted by an
"@" in front of the name) with values.
6. When performing commands that do not require data to be returned, such as inserts, updates, and deletes, you use a
SqlCommand instead of the SqlDataAdapter. The command is issued by calling an ExecuteNonQuery method,
which returns the number of rows affected.
7. The SqlConnection must be explicitly opened when you use the SqlCommand (the SqlDataAdapter automatically
handles opening the connection for you). Always remember to close the SqlConnection to the data model before the
page finishes executing. If you do not close the connection, you migh inadvertantly exhaust the connection limit while
waiting for the page instances to be released to garbage collection.
8. To allow rows to be edited, the DataGrid supports an integer EditItemIndex property, which indicates which row of
the grid should be editable. When this property is set, the DataGrid renders the row at that index as text input boxes
instead of simple labels.
9. The DataGrid exposes a DataKeyField property that you can set to the field name for the primary key. In the event
handler wired to the UpdateCommand, you can retrieve the key name from the DataGrid's DataKeys collection.
10. Using BoundColumn controls in the DataGrid gives you complete control over the order of the columns, as well as
their ReadOnly properties.
11. Using TemplateColumn controls in the DataGrid gives you complete control over the contents of the column.
12. The ButtonColumn control can be used to simply render a button control in each row for that column, which can be
associated with an event.
13. A HyperLinkColumn can be added to the DataGrid's Columns collection, which supports navigating to another page
when the link is clicked.
14. When the DataGrid's AllowSorting property is set to true, it renders hyperlinks for the column headers that fire a
Sort command back to the grid. You set the OnSortCommand property of the DataGrid to the handler you want to
call when the user clicks a column link.
15. The DataSet supports ReadXml, ReadXmlData, and ReadXmlSchema methods that take a FileStream as a
parameter, which can be used to populate a DataSet from an XML file.
16. Using stored procedures can reduce the cost of performing heavy database operations in an application.
Data Access and Customization

Introduction to Templated Controls

Handling Postbacks from a Template
Using Select and Edit Templates
Finding a Control Inside a Template
Section Summary

Introduction to Templated Controls

While the DataGrid server control demonstrated in the previous section is suitable for many Web application scenarios where a
grid-like representation of data is appropriate, many times the presentation of data needs to be much richer. ASP.NET offers two
controls, DataList and Repeater, that give you greater flexibility over the rendering of list-like data. These controls are
template-based, and so have no default rendering of their own. The way data is rendered is completely determined by the your
implementation of the control's templates, which describe how to present data items.
Like the DataGrid control, DataList and Repeater support a DataSource property, which can be set to any ICollection,
IEnumerable, or IListSource type. The data in this DataSource is bound to the control using its DataBind method. Once the
data is bound, the format of each data item is described by a template.
The ItemTemplate property controls the rendering of each item in the DataSource collection. Inside an ItemTemplate, you
can define any arbitrary presentation code (HTML or otherwise). Using the ASP.NET data binding syntax, you can insert values
from the data bound to the DataList or Repeater control, as shown in the following example.
<ASP:Repeater id="MyRepeater" runat="server">

<ItemTemplate>
Hello <%# DataBinder.Eval(Container.DataItem, "name") %> !
</ItemTemplate>

</ASP:Repeater>
The Container represents the first control in the immediate hierarchy that supports the System.Web.UI.INamingContainer
marker interface. In this case, the Container resolves to an object of type System.Web.UI.WebControls.RepeaterItem,
which has a DataItem property. As the Repeater iterates over the DataSource collection, the DataItem contains the current
item in this collection. For example, if the data source is set to an ArrayList of Employee objects, the DataItem is of type
Employees. When bound to a DataView, the DataItem is of type DataRowView.
The following example demonstrates a Repeater control bound to a DataView (returned from a SQL query). HeaderTemplate
and FooterTemplate have also been defined and render at the beginning and end of the list, respectively.

VB DataList1.aspx

[Run Sample] | [View Source]

The Repeater control just iterates over the bound data, rendering the ItemTemplate once for each item in the DataSource
collection. It does not render anything besides the elements contained in its templates. While the Repeater is a general purpose
iterator, the DataList provides some additional features for controlling the layout of the list. Unlike the Repeater, DataList
renders additonal elements, like table rows and cells and spans containing style attributes, outside of the template definition to
enable this richer formatting. For example, DataList supports RepeatColumns and RepeatDirection properties that specify
whether data should be rendered in multiple columns, and in which direction (vertical or horizontal) the data items should be
rendered. DataList also supports style attributes, as shown in the following example.
<ASP:DataList runat="server" DataSource="<%#MyData%>"
RepeatColumns="2"
RepeatDirection="Horizontal"
ItemStyle-Font-Size="10pt"
ItemStyle-Font-Name="Verdana"
>
...
</ASP:DataList>
Note: The remainder of this section concentrates on the many features of the DataList control. For more information about the
Repeater control, refer to the Repeater topic in the Web Forms Controls Reference section of this tutorial.
The following sample demonstrates the use of the DataList control. Note that the look of the data items has been changed from
the previous example, simply by changing the contents of the control's ItemTemplate property. The RepeatDirection and
RepeatColumns properties determine how the ItemTemplates are laid out.

VB Datalist2.aspx

[Run Sample] | [View Source]

The following example further demonstrates the infinite flexibility of templates by changing the ItemTemplate yet again. This
time, one of the DataItem values has been substituted for the "src" attribute of an <img> tag. The format String parameter
of DataBinder.Eval has also been used to substitute a DataItem value in the query string for a URL.

VB Datalist3.aspx

[Run Sample] | [View Source]

Handling Postbacks from a Template

As in the DataGrid, you can fire a command from inside a DataList template that is passed to an event handler wired to the
DataList itself. For example, a LinkButton inside the ItemTemplate might fire a Select command. By setting the
OnSelectedIndexChanged property of the DataList, you can call an event handler in response to this command. The
following example demonstrates this process.
<ASP:DataList id="MyDataList" OnSelectedIndexChanged="MyDataList_Select" runat="server">

<ItemTemplate>

<asp:linkbutton CommandName="Select" runat="server">

<%# DataBinder.Eval(Container.DataItem, "title") %>
</asp:linkbutton>

</ItemTemplate>

</ASP:DataList>
The following sample demonstrates this code in action. In the MyDataList_Select event handler, you populate several other
server controls with the details about the particular selected item.

VB Datalist4.aspx
 [Run Sample] | [View Source]
Note that while the DataList recognizes a few special commands such as Select and Edit/Update/Cancel, the command
string fired inside a template can be any arbitrary string. For all commands, the DataList's OnItemCommand is fired. You can
wire this event to a handler as in the previous example; the following example shows how to do this.

<script runat="server">

Protected Sub MyDataList_ItemCommand(Sender As Object, E As DataListCommandEventArgs)

Dim Command As String = E.CommandName

Select Case Command

Case "Discuss"
ShowDiscussions(E.Item.DataItem)
Case "Ratings"
ShowRatings(E.Item.DataItem)
End Select
End Sub

</script>

<ASP:DataList id="MyDataList" OnItemCommand="MyDataList_ItemCommand" runat="server">

<ItemTemplate>

<asp:linkbutton CommandName="Ratings" runat="server">

View Ratings
</asp:linkbutton>
|
<asp:linkbutton CommandName="Discuss" runat="server">
View Discussions
</asp:linkbutton>

</ItemTemplate>

</ASP:DataList>

C# VB JScript
Note that because more than one command can fire this event handler, you must employ a switch statement to determine the
particular command that was fired. The following sample demonstrates this code in action.
 VB Datalist5.aspx

[Run Sample] | [View Source]

Using Select and Edit Templates

In addition to handling the Select command using a page-level event handler, the DataList can respond to this event internally.
If a SelectedItemTemplate is defined for the DataList, the DataList renders this template for the item that fired the Select
command. The following example uses the SelectedItemTemplate to make the title of the selected book bold.

VB Datalist6.aspx

[Run Sample] | [View Source]

DataList also supports an EditItemTemplate for rendering an item whose index is equal to the DataList's EditItemIndex
property. For details about how editing and updating works, refer to the Updating Data topic of the Data Access section of this
tutorial.

VB Datalist7.aspx

[Run Sample] | [View Source]

Finding a Control Inside a Template

Sometimes it is necessary to locate a control contained inside a template. If a control is given an ID in a template, that control
can be retrieved from its container (the first control in the parent hierarchy that supports INamingContainer). In this case, the
container is the DataListItem control. Note that even though there are several controls with the same ID (by virtue of the
DataList's repetition), each is contained logically in the namespace of the DataListItem container control.
You can go through the DataList's Items collection to retrieve the DataListItem for a given index, and then call the
DataListItem's FindControl method (inherited from the base Control class) to retrieve a control with a particular ID.

<script runat="server">

Public Sub Page_Load(sender As Object, E As EventArgs))

' set datasource and call databind here

For I=0 To MyDataList.Items.Count-1

Dim IsChecked As String = MyDataList.Items(i).FindControl("Save").Checked.ToString()
If IsChecked = "True" Then
...
End If
Next
End Sub
</script>
<ASP:DataList id="MyDataList" runat="server">

<ItemTemplate>
<asp:CheckBox id="Save" runat="server"/> <b>Save to Favorites</b>
</ItemTemplate>

</ASP:DataList>

C# VB JScript
The following sample demonstrates this code in action.

VB Datalist8.aspx

[Run Sample] | [View Source]

Section Summary

1. The DataList and Repeater controls provide developers fine-tuned control over the rendering of data-bound lists.
2. Rendering of bound data is controlled using a template, such as the HeaderTemplate, FooterTemplate, or
ItemTemplate.
3. The Repeater control is a general-purpose iterator, and does not insert anything in its rendering that is not contained
in a template.
4. The DataList control offers more control over the layout and style of items, and outputs its own rendering code for
formatting.
5. The DataList supports the Select, Edit/Update/Cancel, and Item Command events, which can be handled at the
page level by wiring event handlers to the DataList's Command events.
6. DataList supports a SelectedItemTemplate and EditItemTemplate for control over the rendering of a selected or
editable item.
7. Controls can be programmatically retrieved from a template using the Control.FindControl method. This should be
called on a DataListItem retrieved from the DataList's Items collection.
Web Forms Syntax Reference

ASP.NET Web Forms Syntax Elements

Rendering Code Syntax
Declaration Code Syntax
ASP.NET Server Control Syntax
ASP.NET Html Server Control Syntax
Databinding Syntax
Object Tag Syntax
Server Side Comment Syntax
Server Side Include Syntax

ASP.NET Web Forms Syntax Elements

An ASP.NET Web Forms page is a declarative text file with an .aspx file name extension. In addition to static content, you can
use eight distinct syntax markup elements. This section of the QuickStart reviews each of these syntax elements and provides
examples demonstrating their use.

Rendering Code Syntax: <% %> and <%= %>

Code rendering blocks are denoted with <% ... %> elements, allow you to custom-control content emission, and execute during
the render phase of Web Forms page execution. The following example demonstrates how you can use them to loop over HTML
content.

<% For I=0 To 7 %>

<font size="<%=i%>"> Hello World! </font> <br>
<% Next %>

C# VB JScript

VB Reference1.aspx

[Run Sample] | [View Source]

Code enclosed by <% ... %> is just executed, while expressions that include an equal sign, <%= ... %>, are evaluated and the
result is emitted as content. Therefore <%="Hello World" %> renders the same thing as the C# code <%
Response.Write("Hello World"); %>.
Note: For languages that utilize marks to end or separate statements (for example, the semicolon (;) in C#), it is important to
place those marks correctly depending on how your code should be rendered.
C# code
<% Response.Write("Hello World"); %> A semicolon is necessary to end the statement.

<%="Hello World"; %> Wrong: Would result in "Response.Write("Hello World";);".

<%="Hello World" %> A semicolon is not necessary.

Declaration Code Syntax: <script runat="server">

Code declaration blocks define member variables and methods that will be compiled into the generated Page class. These blocks
can be used to author page/navigation logic. The following example demonstrates how a Subtract method can be declared
within a <script runat="server"> block, and then invoked from the page.

<script language="VB" runat=server>

Function Subtract(num1 As Integer, num2 As Integer) As Integer
 Return(num1 - num2)
End Function
</script>

<%
...
number = subtract(number, 1)
...
%>

C# VB JScript

VB Reference2.aspx

[Run Sample] | [View Source]

Important: Unlike ASP -- where functions could be declared within <% %> blocks -- all functions and global page variables
must be declared in a <script runat=server> tag. Functions declared within <% %> blocks will now generate a syntax
compile error.

ASP.NET Server Control Syntax

Custom ASP.NET server controls enable page developers to dynamically generate HTML user interface (UI) and respond to client
requests. They are represented within a file using a declarative, tag-based syntax. These tags are distinguished from other tags
because they contain a "runat=server" attribute. The following example demonstrates how an <asp:label runat="server">
server control can be used within an ASP.NET page. This control corresponds to the Label class in the
System.Web.UI.WebControls namespace, which is included by default.
By adding a tag with the ID "Message", an instance of Label is created at run time:
<asp:label id="Message" font-size=24 runat="server"/>
The control can then be accessed using the same name. The following line sets the Text property of the control.

Message.Text = "Welcome to ASP.NET"

C# VB JScript

VB Reference3.aspx

[Run Sample] | [View Source]

ASP.NET HTML Server Control Syntax

HTML server controls enable page developers to programmatically manipulate HTML elements within a page. An HTML server
control tag is distinguished from client HTML elements by means of a "runat=server" attribute. The following example
demonstrates how an HTML <span runat=server> server control can be used within an ASP.NET page.
As with other server controls, the methods and properties are accessible programmatically, as shown in the following example.
<script language="VB" runat="server">
Sub Page_Load(sender As Object, e As EventArgs)
Message.InnerHtml = "Welcome to ASP.NET"
End Sub
</script>
...
<span id="Message" style="font-size:24" runat="server"/>

C# VB JScript

VB Reference4.aspx

[Run Sample] | [View Source]

Data Binding Syntax: <%# %>

The data binding support built into ASP.NET enables page developers to hierarchically bind control properties to data container
values. Code located within a <%# %> code block is only executed when the DataBind method of its parent control container
is invoked. The following example demonstrates how to use the data binding syntax within an <asp:datalist runat=server>
control.
Within the datalist, the template for one item is specified. The content of the item template is specified using a data binding
expression and the Container.DataItem refers to the data source used by the datalist MyList.
<asp:datalist id="MyList" runat=server>
<ItemTemplate>
Here is a value: <%# Container.DataItem %>
</ItemTemplate>
</asp:datalist>
In this case the data source of the MyList control is set programmatically, and then DataBind() is called.

Sub Page_Load(sender As Object, e As EventArgs)

Dim items As New ArrayList()

items.Add("One")
items.Add("Two")
items.Add("Three")

MyList.DataSource = items
MyList.DataBind()
End Sub

C# VB JScript
Calling the DataBind method of a control causes a recursive tree walk from that control on down in the tree; the DataBinding
event is raised on each server control in that hierarchy, and data binding expressions on the control are evaluated accordingly.
So, if the DataBind method of the page is called, then every data binding expression within the page will be called.

VB Reference5.aspx

[Run Sample] | [View Source]

Object Tag Syntax: <object runat="server" />

Object tags enable page developers to declare and create instances of variables using a declarative, tag-based syntax. The
following example demonstrates how the object tag can be used to create an instance of an ArrayList class.
<object id="items" class="System.Collections.ArrayList" runat="server"/>
The object will be created automatically at run time and can then be accessed through the ID "items".

Sub Page_Load(sender As Object, e As EventArgs)

items.Add("One")
items.Add("Two")
items.Add("Three")
...
End Sub

C# VB JScript

VB Reference6.aspx

[Run Sample] | [View Source]

Server-Side Comment Syntax: <%-- Comment --%>

Server-side comments enable page developers to prevent server code (including server controls) and static content from
executing or rendering. The following sample demonstrates how to block content from executing and being sent down to a client.
Note that everything between <%-- and --%> is filtered out and only visible in the original server file, even though it contains
other ASP.NET directives.

<%--
<asp:calendar id="MyCal" runat=server/>
<% For I=0 To 44 %>
Hello World <br>
<% Next %>
--%>
 C# VB JScript

VB Reference7.aspx

[Run Sample] | [View Source]

Server-Side Include Syntax: <-- #Include File="Locaton.inc" -->

Server-side #Includes enable developers to insert the raw contents of a specified file anywhere within an ASP.NET page. The
following sample demonstrates how to insert a custom header and footer within a page.
<!-- #Include File="Header.inc" -->
...
<!-- #Include File="Footer.inc" -->

VB Reference8.aspx

[Run Sample] | [View Source]