The idea of three-tier design is that the functionality of most complete applications can be divided into three main levels (see Figure 22-1). The first level is the user interface (or presentation tier), which displays controls and receives and validates user input. All he event handlers in your web page are in this first level. The second level is the business tier, where the application-specific logic takes place. For an e-commerce site, application-specific logic includes rules such as how shipping charges are applied to an order, when certain promotions are valid, and what customer actions should be logged. It doesn't involve generic .NET details such as how to open a file or connect to a database. The third level is the data tier, where you place the logic that stores your information in files, a database, or some other data store. The third level contains logic about how to retrieve and update data, such as SQL queries or stored procedures.

Figure 22.1. Three-tier design

The important detail about three-tier design is that information travels from only one level to an adjacent level. In other words, your web page code shouldn't connect directly to the database to retrieve information. Instead, it should go through a component in the business tier that connects to the database and returns the data.

This basic organization principle can't always be adhered to, but it's a good model to follow. When you create a component, it's almost always used in the second level to bridge the gap between the data and the user interface. In other words, if you want to fill a list of product categories in a list box, your user interface code calls a component, which gets the list from the database and then returns it to your code. Your web page code is isolated from the database—and if the database structure changes, you need to change one concise component instead of every page on your site.

If three-tier design is the overall goal of component-based programming, encapsulation is the best rule of thumb. Encapsulation is the principle that you should create your application out of "black boxes" that hide information. So, if you have a component that logs a purchase on an e-commerce site, that component handles all the details and allows only the essential variables to be specified.

For example, this component might accept a user ID and an order item ID and then handle all the other details. The calling code doesn't need to worry about how the component works or where the data is coming from—it just needs to understand how to use the component. (This principle is described in a lot of picturesque ways. For example, you know how to drive a car because you understand its component interface—the steering wheel and pedals—not because you understand the low-level details about internal combustion and the engine. As a result, you're able to transfer your knowledge to many different types of automobiles, even if they have dramatically different internal workings.)

The term business object often means different things to different people. Generally, business objects are the components in the second level of your application that provide the extra layer between your code and the data source. They are called business objects because they enforce business rules. For example, if you try to submit a purchase order without any items, the appropriate business object will throw an exception and refuse to continue. In this case, no .NET error has occurred—instead, you've detected the presence of a condition that shouldn't be allowed according to your application's logic.

In this chapter's examples, business objects are also going to contain data access code. In an extremely complicated, large, and changeable system, you might want to further subdivide components and actually have your user interface code talking to a business object, which in turn talks to another set of objects that interact with the data source. However, for most programmers, this extra step is overkill, especially with the increased level of sophistication ADO.NET provides.

The term data object is also used in a variety of ways. In this book, data objects are simply packages of data that you use to send information between your web page and your business objects. For example, you might create a data class named Employee that represents the information from one record in an Employees table, complete with properties like FirstName, LastName, and DateOfBirth. A typically data object is filled with properties but provides no methods.

Technically, a component is just a collection of one or more classes (and possibly other .NET types, such as structures and enumerations) that are compiled together as a unit. For example, Microsoft's System.Web.dll is a single (but very large) component that provides the types found in many of the namespaces that start with System.Web.

So far, the code examples in this book have used only a few kinds of classes—mainly custom web page classes that inherit from System.Web.UI.Page and contain mostly event handling procedures. Component classes, on the other hand, usually won't include any user interface logic (which would limit their use unnecessarily) and don't need to inherit from an existing class.

Once you've created your class library project, you're ready to add classes in a .vb file. Class library projects begin with one file named Class1.vb, which you can use, delete, or rename. You can also add more class files simply by right-clicking the project in the Solution Explorer and choosing Add

Here's an example that creates a class named SimpleTest:

Public Class SimpleTest
    ' (Code goes here, inside one or more methods.)
End Class

Remember, a component can contain more than one class. You can create these other classes in the same file, or you can use separate files for better organization. In either case, all the classes and source code files are compiled together into one assembly:

Public Class SimpleTest
    ' (Class code omitted.)
End Class

Public Class SimpleTest2
    ' (Class code omitted.)
End Class

The classes in your component are automatically organized into a namespace that's named after your project. This namespace is known as the root namespace. For example, if you've created a project named Components, the SimpleTest and SimpleTest2 classes will be in the Components namespace, and their fully qualified names will be Components.SimpleTest and Components.SimpleTest2. You need to know the fully qualified name in order to use your classes in another application, because other applications won't share the same namespace.

If you decide that you want to change the root namespace, you can change it quite easily. First, right-click the project in the Solution Explorer and choose Properties. You'll see a multi-tabbed display of application settings. Choose the Application tab and then edit the namespace in the Root Namespace text box. You can also use the Assembly Name text box in this window to configure the name that is given to the compiled assembly file.

If you have a complex component, you might choose to subdivide it into nested namespaces. For example, you might have a namespace named Components.Database and another named Components.Validation. To create a nested namespace inside the default project namespace, you use a Namespace block like this:

Namespace Database

    Public Class SimpleDatabaseTest
        ' (Class code omitted.)
    End Class

End Namespace

Now this class has the fully qualified name Components.Database.SimpleDatabaseTest.

To add functionality to your class, add public methods or properties. The web page code can then call these members to retrieve information or perform a task.

The following example shows one of the simplest possible components, which does nothing more than return a string to the calling code:

Public Class SimpleTest

    Public Function GetInfo(ByVal param As String) As String
        Return "You invoked SimpleTest.GetInfo() with '" & _
          param & "'"
    End Function

End Class

Public Class SimpleTest2

    Public Function GetInfo(ByVal param As String) As String
        Return "You invoked SimpleTest2.GetInfo() with '" & _
          param & "'"
    End Function

End Class

In the following sections, you'll learn how to use this component in a web application. A little later, you'll graduate to a more complex, practical component.

Using the component in an actual ASP.NET page is easy. Essentially, your website needs a copy of your component in its Bin directory. ASP.NET automatically monitors this directory and makes all of its classes available to any web page in the application. To create this copy, you use a Visual Studio feature called references.

Here's how it works: First, select your website in the Solution Explorer. Then, select Website

You can take one of two approaches in the Add Reference dialog box:

Note

If you're using an assembly reference, you need to compile your component first (choose Build

Figure 22.4. Adding a project reference

Figure 22.5. Adding an assembly reference

Either way, .NET copies the compiled DLL file to the Bin subdirectory of your web application (see Figure 22-6). You'll also see a .PDB file that contains debugging information for Visual Studio.

Figure 22.6. A component in the Bin directory

Visual Studio also takes extra care to make sure that you keep using the most up-to-date version of the component. If you change the component and recompile it, Visual Studio will notice the change. The next time you run your web application, Visual Studio will automatically copy the new component to the Bin subdirectory.

If you're using a project reference, Visual Studio goes one step further. Every time you run the website project, Visual Studio checks for any changes in your component's source code files. If any of these files have been changed, Visual Studio automatically recompiles the component and copies the new version to the Bin subdirectory in your web application.

When you add a reference to a component, Visual Studio also allows you to use its classes in your code with the usual syntax checking and IntelliSense. If you don't add the reference, you won't be able to use the component classes (and if you try, Visual Studio interprets your attempts to use the class as mistakes and refuses to compile your code).

Once you've added the reference, you can use the component by creating instances of the SimpleTest or SimpleTest2 class, as shown here:

Imports Components

Public Partial Class TestPage
    Inherits System.Web.UI.Page

    Protected Sub Page_Load(ByVal sender As Object, _
      ByVal e As System.EventArgs) Handles Me.Load
        Dim testComponent As New SimpleTest()
        Dim testComponent2 As New SimpleTest2()
        lblResult.Text = testComponent.GetInfo("Hello") & "<br /><br />"
        lblResult.Text &= testComponent2.GetInfo("Bye")
    End Sub
End Class

The output for this page, shown in Figure 22-7, combines the return value from both GetInfo() methods.

Figure 22.7. The SimpleTest component output

To make this code slightly simpler, you can choose to use shared methods in the component class so that you don't need to create an instance before using the methods. A shared GetInfo() method looks like this:

Public Class SimpleTest

    Public Shared Function GetInfo(param As String) As String
        Return "You invoked SimpleTest.GetInfo() with '" & _
          param & "'"
    End Function

End Class

In this case, the web page accesses the shared GetInfo() method through the class name and doesn't need to create an object:

Protected Sub Page_Load(ByVal sender As Object, _
  ByVal e As System.EventArgs) Handles Me.Load

    lblResult.Text = SimpleTest.GetInfo("Hello")
End Sub

Tip

Remember, if you're using assembly references and your component and web application aren't in the same solution, you won't see the effect of your changes right away. Instead, you need to recompile your component assembly (choose Build

Deciding when to use instance methods and when to use shared methods is part of the art of object-oriented design, and it takes experience. Shared methods impose additional considerations—namely, your class must be stateless (a concept described in the following section), which means it can't hold on to any additional information in member variables. If it does, it risks a potential conflict if more than one piece of code uses the component at the same time.

As a rule of thumb, use instance methods if you need to be able to create several instances of your class at the same time. For example, instance methods make sense for the SqlConnection class, because you might choose to open a connection to several different databases for one operation. Instance methods are also the best choice if you want to configure an object once and use it several times. For example, the SqlConnection class lets you set the connection string and then open and close the connection as much as needed. On the other hand, consider shared methods if your methods perform a single, discrete task that doesn't require any initialization. Examples include the calculations in the Math class and the business tasks (such as registering a new customer) in a high-level business component.

Consider a stateful account class that represents a single customer account. Information is read from the database when it's first created in the constructor method, and this information can be updated using the Update() method.

Public Class CustomerAccount
    Private _accountNumber As Integer
    Private _balance As Decimal

    Public Property Balance() As Decimal
        Get
            Return _balance
        End Get
        Set(ByVal value As Decimal)
            _balance = value
        End Set
    End Property

    Public Sub New(ByVal accountNumber As Integer)
        ' (Code to read account record from database goes here.)
    End Sub

Public Sub Update()
        ' (Code to update database record goes here.)
    End Sub
End Class

If you have two CustomerAccount objects that expose a Balance property, you need to perform two separate steps to transfer money from one account to another. Conceptually, the process works like this:

' Create an account object for each account,
' using the account number.
Dim accountOne As New CustomerAccount(122415)
Dim accountTwo As New CustomerAccount(123447)
Dim amount As Decimal = 1000

' Withdraw money from one account.
accountOne.Balance -= amount

' Deposit money in the other account.
accountTwo.Balance += amount

' Update the underlying database records using the Update() method.
accountOne.Update()
accountTwo.Update()

The problem here is that if this task is interrupted halfway through by an error, you'll end up with at least one unhappy customer.

A stateless object might expose only a shared method named FundTransfer(), which performs all its work in one method:

Public Class AccountUtility
    Public Shared Sub FundTransfer(ByVal accountOne As Integer, _
      ByVal accountTwo As Integer, ByVal amount As Decimal)
        ' (The code here retrieves the two database records,
        '  changes them, and updates them.)
    End Sub
End Class

The calling code can't use the same elegant CustomerAccount objects, but it can be assured that account transfers are protected from error. Because all the database operations are performed at once, they can use a database stored procedure for greater performance and can use a transaction to ensure that the withdrawal and deposit either succeed or fail as a whole.

' Set the account and transfer details.
Dim amount As Decimal = 1000
Dim accountIDOne As Integer = 122415
Dim accountIDTwo As Integer = 123447

AccountUtility.FundTransfer(accountIDOne, accountIDTwo, _
  amount)

In a mission-critical system, transactions are often required. For that reason, classes that retain little state information are often the best design approach, even though they aren't quite as satisfying from an object-oriented perspective.

To examine the best way to create a data-access component, you'll consider a simple application that provides a classifieds page that lists items that various individuals have for sale. The database uses two tables: one is an Items table that lists the description and price of a specific sale item, and the other is a Categories table that lists the different groups you can use to categorize an item. Figure 22-8 shows the relationship.

Figure 22.8. The AdBoard database relationships

In this example, you're connecting to a SQL Server database using ADO.NET. You can create this database yourself, or you can refer to the online samples, which include a SQL script that generates it automatically. To start, the Categories table is preloaded with a standard set of allowed categories.

The data-access component is simple. It's a single class (named DBUtil), which is placed in a namespace named DatabaseComponent (which is the root namespace for the project). The DBUtil class uses instance methods and retains some basic information (such as the connection string to use), but it doesn't allow the client to change this information. Therefore, it doesn't need any property procedures. Instead, it performs most of its work in methods such as GetCategories() and GetItems(). These methods return DataSets with the appropriate database records. This type of design creates a fairly thin layer over the database—it handles some details, but the client is still responsible for working with familiar ADO.NET classes such as the DataSet.

Note

To use this example as written, you need to add a reference to the System.Configuration.dll and System.Web.dll assemblies in the class library. Otherwise, you can't use the WebConfigurationManager to dig up the connection string you need. To add these references, select Project

Imports System
Imports System.Data
Imports System.Data.SqlClient
Imports System.Web.Configuration

Public Class DBUtil

    Private connectionString As String

    Public Sub New()
        connectionString = _
          WebConfigurationManager.ConnectionStrings( _
          "AdBoard").ConnectionString
    End Sub

    Public Function GetCategories() As DataSet
        Dim query As String = "SELECT * FROM Categories"
        Dim cmd As New SqlCommand(query)
        Return FillDataSet(cmd, "Categories")

End Function

    Public Function GetItems() As DataSet
        Dim query As String = "SELECT * FROM Items"
        Dim cmd As New SqlCommand(query)
        Return FillDataSet(cmd, "Items")
    End Function

    Public Function GetItems(ByVal categoryID As Integer) As DataSet
        ' Create the Command.
        Dim query As String = "SELECT * FROM Items WHERE Category_ID=@CategoryID"
        Dim cmd As New SqlCommand(query)
        cmd.Parameters.AddWithValue("@CategoryID", categoryID)

        ' Fill the DataSet.
        Return FillDataSet(cmd, "Items")
    End Function

    Public Sub AddCategory(ByVal name As String)
        Dim con As New SqlConnection(connectionString)

        ' Create the Command.
        Dim insertSQL As String = "INSERT INTO Categories "
        insertSQL &= "(Name) VALUES @Name"
        Dim cmd As New SqlCommand(insertSQL, con)
        cmd.Parameters.AddWithValue("@Name", name)

        Try
            con.Open()
            cmd.ExecuteNonQuery()
        Finally
            con.Close()
        End Try
    End Sub

    Public Sub AddItem(ByVal title As String, ByVal description As String, _
      ByVal price As Decimal, ByVal categoryID As Integer)
        Dim con As New SqlConnection(connectionString)

        ' Create the Command.
        Dim insertSQL As String = "INSERT INTO Items "
        insertSQL &= "(Title, Description, Price, Category_ID)"
        insertSQL &= "VALUES (@Title, @Description, @Price, @CategoryID)"
        Dim cmd As New SqlCommand(insertSQL, con)
        cmd.Parameters.AddWithValue("@Title", title)
        cmd.Parameters.AddWithValue("@Description", description)
        cmd.Parameters.AddWithValue("@Price", price)
        cmd.Parameters.AddWithValue("@CategoryID", categoryID)

        Try
            con.Open()
            cmd.ExecuteNonQuery()
        Finally
            con.Close()

End Try
    End Sub

    Private Function FillDataSet(ByVal cmd As SqlCommand, ByVal tableName As String) _
      As DataSet
        Dim con As New SqlConnection(connectionString)
        cmd.Connection = con
        Dim adapter As New SqlDataAdapter(cmd)

        Dim ds As New DataSet()
        Try
            con.Open()
            adapter.Fill(ds, tableName)
        Finally
            con.Close()
        End Try
        return ds
    End Function

End Class

To use this component in a web application, you first have to make sure the appropriate connection string is configured in the web.config file, as shown here:

<configuration>

  <connectionStrings>
    <add name="AdBoard" connectionString=
"Data Source=localhostSQLEXPRESS;Initial Catalog=AdBoard;Integrated Security=SSPI" />
  </connectionStrings>
  ...
</configuration>

Next, compile and copy the component DLL file, or add a reference to it if you're using Visual Studio. The only remaining task is to add the user interface for the web page that uses the component.

To test this component, you can create a simple test page. In the example shown in Figure 22-9, this page allows users to browse the current listing by category and add new items. When the user first visits the page, it prompts the user to select a category.

Figure 22.9. The AdBoard listing

Once a category is chosen, the matching items display, and a panel of controls appears, which allows the user to add a new entry to the AdBoard under the current category, as shown in Figure 22-10.

Figure 22.10. The AdBoard listing

In order to access the component more easily, the web page imports its namespace:

Imports DatabaseComponent

The page code creates the component to retrieve information from the database and displays it by binding the DataSet to the drop-down list or GridView control:

Public Partial Class AdBoard
    Inherits System.Web.UI.Page

    Protected Sub Page_Load(ByVal sender As Object, _
      ByVal e As System.EventArgs) Handles Me.Load

        If Not Page.IsPostBack
            Dim DB As New DBUtil()

            lstCategories.DataSource = DB.GetCategories()
            lstCategories.DataTextField = "Name"
            lstCategories.DataValueField = "ID"
            lstCategories.DataBind()

pnlNew.Visible = False
        End If
    End Sub

    Protected Sub cmdDisplay_Click(ByVal sender As Object, _
      ByVal e As System.EventArgs) Handles cmdDisplay.Click

        Dim DB As New DBUtil()

        gridItems.DataSource = DB.GetItems( _
          Val(lstCategories.SelectedItem.Value))
        gridItems.DataBind()
        pnlNew.Visible = True
    End Sub

    Protected Sub cmdAdd_Click(ByVal sender As Object, _
      ByVal e As System.EventArgs) Handles cmdAdd.Click

        Dim DB As New DBUtil()

        Try
            DB.AddItem(txtTitle.Text, txtDescription.Text, _
              Val(txtPrice.Text), Val(lstCategories.SelectedItem.Value))

            gridItems.DataSource = DB.GetItems( _
              Val(lstCategories.SelectedItem.Value))
            gridItems.DataBind()
        Catch err As FormatException
            ' An error occurs if the user has entered an
            ' invalid price (non-numeric characters).
            ' In this case, take no action.
            ' Another option is to add a validator control
            ' for the price text box to prevent invalid input.
        End Try
    End Sub
End Class

One way you could enhance the component is with better support for error reporting. As it is, any database errors that occur are immediately returned to the calling code. In some cases (for example, if there is a legitimate database problem), this is a reasonable approach, because the component can't handle the problem.

However, the component fails to handle one common problem properly. This problem occurs if the connection string isn't found in the web.config file. Though the component tries to read the connection string as soon as it's created, the calling code doesn't realize a problem exists until it tries to use a database method.

A better approach is to notify the client as soon as the problem is detected, as shown in the following code example:

Public Class DBUtil
    Private connectionString As String

    Public Sub New()
        If WebConfigurationManager.ConnectionStrings("AdBoard") _
          Is Nothing Then
            Throw New ApplicationException( _
              "Missing ConnectionString variable in web.config.")
        Else
            connectionString = _
              WebConfigurationManager.ConnectionStrings( _
              "AdBoard").ConnectionString
        End If
    End Sub

    ' (Other class code omitted.)
End Class

This code throws an ApplicationException with a custom error message that indicates the problem. To provide even better reporting, you could create your own exception class that inherits from ApplicationException, as described in Chapter 7.

The component doesn't have to limit the type of information it provides to DataSets. Other information is also useful. For example, you might provide a read-only property called ItemFields that returns an array of strings representing the names for fields in the Items table. Or you might add another method that retrieves aggregate information about the entire table, such as the average cost of items in the database or the total number of currently listed items, as shown here:

Public Class DBUtil
    ' (Other class code omitted.)

    Public Function GetAveragePrice() As Decimal
        Dim query As String = "SELECT AVG(Price) FROM Items"

        Dim con As New SqlConnection(connectionString)
        Dim cmd As New SqlCommand(query, con)

        con.Open()
        Dim average As Decimal = CType(cmd.ExecuteScalar(), Decimal)
        con.Close()

        Return average
    End Function

    Public Function GetTotalItems() As Integer
        Dim query As String = "SELECT COUNT(*) FROM Items"

        Dim con As New SqlConnection(connectionString)
        Dim cmd As New SqlCommand(query, con)

        con.Open()
        Dim count As Integer = CType(cmd.ExecuteScalar(), Integer)
        con.Close()

        Return count
    End Function
End Class

These queries use some SQL that may be new to you (namely, the COUNT and AVG aggregate functions). However, these methods are just as easy to use from the client's perspective as GetItems() and GetCategories():

Dim DB As New DBUtil()
Dim averagePrice As Decimal = DB.GetAveragePrice()
Dim totalItems As Integer = DB.GetTotalItems()

It may have occurred to you that you can return information such as the total number of items through a read-only property procedure (such as TotalItems) instead of a method (in this case, GetTotalItems). Though this does work, property procedures are better left to information that is maintained with the class (in a private variable) or is easy to reconstruct. In this case, it takes a database operation to count the number of rows, and this database operation can cause an unusual problem or slow down performance if used frequently. To help reinforce that fact, a method is used instead of a property.

Essentially, the ObjectDataSource allows you to create a declarative link between your web page controls and a data access component that queries and updates data. Although the ObjectDataSource is remarkably flexible, it can't support every conceivable component you could create. In fact, for your data component to be usable with the ObjectDataSource, you need to conform to a few rules:

Fortunately, many of these rules are best practices that you should already be following. Even though the DBUtil class wasn't expressly designed for the ObjectDataSource, it meets all these criteria.

You can learn a lot about the ObjectDataSource by building the page shown in Figure 22-10. In the following sections, you'll tackle this challenge.

The first step is to create the list box with the list of categories. For this list, you need an ObjectDataSource that links to the DBUtil class and calls the GetCategories() method to retrieve the full list of category records.

To supply data to the list box, you need to define an ObjectDataSource and indicate the name of the class that contains the data access methods. You do this by specifying the fully qualified class name with the TypeName property, as shown here:

<asp:ObjectDataSource ID="sourceCategories" runat="server"
 TypeName="DatabaseComponent.DBUtil" ... />

Once you've attached the ObjectDataSource to a class, the next step is to point it to the methods it can use to select and update records.

The ObjectDataSource defines SelectMethod, DeleteMethod, UpdateMethod, and InsertMethod properties that you use to link your data access class to various tasks. Each property takes the name of the method in the data access class. In this example, you simply need to enable querying, so you need to set the SelectMethod property so it calls the GetCategories() method:

<asp:ObjectDataSource ID="sourceCategories" runat="server"
 TypeName="DatabaseComponent.DBUtil" SelectMethod="GetCategories" />

Once you've set up the ObjectDataSource, you can bind your web page controls in the same way you do with the SqlDataSource. Here's the tag you need for the list box:

<asp:DropDownList ID="lstCategories" runat="server"
  DataSourceID="sourceCategories" DataTextField="Name" DataValueField="ID">
</asp:DropDownList>

This tag shows a list of category names (thanks to the DataTextField property) and also keeps track of the category ID (using the DataValueField property).

This example works fine so far. You can run the test web page and see the list of categories in the list (as shown in Figure 22-9).

The next step is to show the list of items in the current category in the GridView underneath. As with the SqlDataSource, the ObjectDataSource can be used only for a single query. That means you'll need to create a second ObjectDataSource that's able to retrieve the list of items by calling GetItems().

The trick here is that the GetItems() method requires a single parameter (named categoryID). That means you need to create an ObjectDataSource that includes a single parameter. You can use all the same types of parameters used with the SqlDataSource to get values from the query string, other controls, and so on. In this case, the category ID is provided by the SelectedValue property of the list box, so you can use a control parameter that points to this property.

Here's the ObjectDataSource definition you need:

<asp:ObjectDataSource ID="sourceItems" runat="server" SelectMethod="GetItems"
 TypeName="DatabaseComponent.DBUtil" >
  <SelectParameters>

<asp:ControlParameter ControlID="lstCategories" Name="categoryID"
        PropertyName="SelectedValue" Type="Int32" />
  </SelectParameters>
</asp:ObjectDataSource>

Again, you use the DBUtil class, but this time it's the GetItems() method you need. Even though there are two overloaded versions of the GetItems() method (one that takes a categoryID parameter and one that doesn't), you don't need to worry. The ObjectDataSource automatically uses the correct overload by looking at the parameters you've defined.

In this case, you use a single parameter that extracts the selected category ID from the list box and passes it to the GetItems() method. Notice that the name defined in the ControlParameter tag matches the parameter name of the GetItems() method. This is an absolute requirement. The ObjectDataSource searches for the GetItems() method using reflection, and it verifies that any potential match has the number of parameters, parameter names, and data types that you've indicated. This searching process allows the ObjectDataSource to distinguish between different overloaded versions of the same method. If the ObjectDataSource can't find the method you've specified, an exception is raised at this point.

The final step is to link the GridView to the new ObjectDataSource using the DataSourceID. Here's the tag that does it:

<asp:GridView ID="gridItems" runat="server" DataSourceID="sourceItems"/>

This is all you need. You should keep the Display button, because it triggers a page postback and allows the ObjectDataSource to get to work. (If you don't want to use this button, set the AutoPostback property on the list box to True so it posts back whenever you change the selection.) You don't need to write any event handling code to react when the button is clicked. The queries are executed automatically, and the controls are bound automatically.

The final step is to provide a way for the user to add new items. The easiest way to make this possible is to use a rich data control that deals with individual records—either the DetailsView or the FormsView. The DetailsView is the simpler of the two, because it doesn't require a template. It's the one used in the following example.

Ideally, you'd define the DetailsView using a tag like this and let it generate all the fields it needs based on the bound data source:

<asp:DetailsView ID="detailsAddItem" runat="server" DataSourceID="sourceItems"/>

Unfortunately, this won't work in this example. The problem is that this approach creates too many fields. In this example, you don't want the user to specify the item ID (that's set by the database automatically) or the category ID (that's based on the currently selected category). So, neither of these details should appear. The only way to make sure this is the case is to turn off automatic field generation and define each field you want explicitly, as shown here:

<asp:DetailsView ID="detailsAddItem" runat="server"
  DataSourceID="sourceItems" AutoGenerateRows="False">
  <Fields>
    <asp:BoundField DataField="Title" HeaderText="Title" />
    <asp:BoundField DataField="Price" HeaderText="Price"/>
    <asp:BoundField DataField="Description" HeaderText="Description" />
  </Fields>
</asp:DetailsView>

You need to make a couple of other changes. To allow inserting, you need to set the AutoGenerateInsertButton to True. This way, the DetailsView creates the links that allow you to start entering a new record and then insert it. At the same time, you can set the DefaultMode property to Insert. This way, the DetailsView is always in insert mode and is used exclusively for adding records (not displaying them), much like the non-data-bound page shown earlier.

<asp:DetailsView ID="detailsAddItem" runat="server"
  DefaultMode="Insert" AutoGenerateInsertButton="True"
  DataSourceID="sourceItems" AutoGenerateRows="False">
  ...
</asp:DetailsView>

The ObjectDataSource provides the same type of support for updatable data binding as the SqlDataSource. The first step is to specify the InsertMethod, which needs to be a public method in the same class:

<asp:ObjectDataSource ID="sourceItems" runat="server"
 TypeName="DatabaseComponent.DBUtil"
 SelectMethod="GetItems" InsertMethod="AddItem" >
</asp:ObjectDataSource>

The challenge is in making sure the InsertMethod has the right signature. As with the SqlDataSource, updates, inserts, and deletes automatically receive a collection of parameters from the linked data control. These parameters have the same names as the corresponding field names. So in this case, the fields are Title, Price, and Description, which exactly match the parameter names in the AddItem() method. (The capitalization is not the same, but the ObjectDataSource is not case sensitive, so this isn't a problem.)

This still has a problem, however. When the user commits an edit, the DetailsView submits the three parameters you expect (Title, Price, and Description). However, the AddItem() method needs a fourth parameter—CategoryID. We've left that parameter out of the DetailsView fields, because you don't want the user to be able to set the category ID. However, you still need to supply it to the method.

So, where can you get the current category ID from? The easiest choice is to extract it from the list box, just as you did for the GetItems() method. All you need to do is add a ControlParameter tag that defines a parameter named CategoryID and binds it to the SelectedValue property of the list box. Here's the revised tag for the ObjectDataSource:

<asp:ObjectDataSource ID="sourceItems" runat="server" SelectMethod="GetItems"
 TypeName="DatabaseComponent.DBUtil" InsertMethod="AddItem" >
  <SelectParameters>
    ...
  </SelectParameters>
  <InsertParameters>
    <asp:ControlParameter ControlID="lstCategories" Name="categoryID"

PropertyName="SelectedValue" Type="Int32" />
  </InsertParameters>
</asp:ObjectDataSource>

Now you have all the parameters you need—the three from the DetailsView and the one extra from the list box. When the user attempts to insert a new record, the ObjectDataSource collects these four parameters, makes sure they match the signature for the AddItem() method, puts them in order, and then calls the method.

Figure 22-11 shows an insert in progress.

Figure 22.11. Inserting with the DetailsView

When you click the Insert button, quite a bit takes place behind the scenes. Here's a breakdown of what actually happens:

Because the page is always rebound after any insert and update operations are finished, you'll always see the latest information in your web controls. For example, if you add a new item, you'll see it appear immediately, complete with the unique ID value that the database server generates automatically.