Using Transactions With Business Objects

If your business rule is updating records in multiple database tables then consider using transactions to ensure atomicity of data operations.

Business objects generated by premium projects are not providing an explicit support for transactions and are relying on transaction plumbing available in ADO.NET. Learn more about System.Transaction.TransactionScope to better understand transaction control options available to developers.

Here is a quick example.

Generate a Data Aquarium project from Northwind database and add System.Transactions.dll reference to your project.

Enter the following code in your web form code-behind or modify the code appropriately to be used in your business rules.

C#:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using MyCompany.Data.Objects;
using System.Transactions;

public partial class Demo : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        using (TransactionScope trn = new TransactionScope())
        {
            // create a new shipper
            Shippers s = new Shippers();
            s.CompanyName = "Code OnTime";
            s.Phone = "877-467-6340";
            if (s.Insert() != 1)
                throw new Exception("Failed to create a shipper");
            trn.Complete();
        }
    }
}

VB:

Imports System.Collections.Generic
Imports MyCompany.Data.Objects
Imports System.Transactions

Partial Class Demo
    Inherits System.Web.UI.Page

    Protected Sub Page_Load(ByVal sender As Object, _
                            ByVal e As System.EventArgs) Handles Me.Load
        ' create a new shipper
        Using trn As TransactionScope = New System.Transactions.TransactionScope()
            Dim s As Shippers = New Shippers()
            s.CompanyName = "Code OnTime"
            s.Phone = "877-467-6340"
            If s.Insert() <> 1 Then
                Throw New Exception("Failed to create a shipper")
            End If
            trn.Complete()
        End Using
    End Sub
End Class

Method Complete will commit all changes.

If an exception is raised then the entire set of changes performed in the scope of transaction prior to the error will be canceled.

ObjectDataSource vs. ControllerDataSource

Data Aquarium Framework features automatic data binding and presentation that are performed by the client-side JavaScript library interpreting the content of server-side data controller definitions to produce interactive grids and forms.

Sometimes your project may require a custom functionality that is not supported by the user interface components of the framework. You can still take advantage of excellent support for filtering, sorting and paging of very large data sets via standard ObjectDataSource component available in .NET Framework or ControllerDataSource component that comes with the premium versions Data Aquarium Framework.

The examples described below are based on an application generated with Data Aquarium premium project from sample Northwind database with business objects enabled.

Overview of Business Objects

Business objects generated as a part of your project are needed if you plan to develop custom web forms with ObjectDataSource components or if you would like to have a programmatic API on top of your database tables.

Business objects are placed in MyCompany.Data.Objects namespace where MyCompany is the namespace of your project. Each object name is matched with the name of the database table and is accompanied by a Factory class.

The default naming of CRUD methods will yield the following methods for each business object: Select, SelectSingle, Insert, Update, and Delete. Here is a sample signature of Select method of Shippers business object.

C#:

public static List<Shippers> Select(
    Nullable<int> shipperID, 
    string companyName, 
    string phone)

VB:

Public Overloads Shared Function [Select]( _
    ByVal shipperID As Nullable(Of Integer), _
    ByVal companyName As String, _
    ByVal phone As String) As List(Of Shippers)

Here are a few examples that show how the business objects can be used to manipulate database information.  Developers can create new records; retrieve records by primary key, by example, or by individual field values specified as parameters. Updating and deleting existing objects is a snap.

C#:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using MyCompany.Data.Objects;

public partial class Demo : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        // create a new shipper
        Shippers s = new Shippers();
        s.CompanyName = "Code OnTime";
        s.Phone = "877-467-6340";
        if (s.Insert() != 1)
            throw new Exception("Failed to create a shipper");
        // find a shipper by ID
        Shippers s2 = Shippers.SelectSingle(s.ShipperID);
        if (s2 == null)
            throw new Exception("Shipper not found");
        // find a list of matching shippers by example
        Shippers query = new Shippers();
        query.Phone = "877-467-6340";
        List<Shippers> list = Shippers.Select(query);
        if (list.Count == 0)
            throw new Exception("Shippers not found");
        // find a list of matching shippers by values
        List<Shippers> list2 = Shippers.Select(null, "code", null);
        if (list2.Count == 0)
            throw new Exception("Shippers not found");
        // update shipper
        list[0].CompanyName = "My Company";
        if (list[0].Update() != 1)
            throw new Exception("Failed to update shipper");
        // delete shipper
        if (list2[0].Delete() != 1)
            throw new Exception("Failed to delete shipper");
    }
}

VB:

Imports System.Collections.Generic
Imports MyCompany.Data.Objects

Partial Class Demo
    Inherits System.Web.UI.Page

    Protected Sub Page_Load(ByVal sender As Object, _
                            ByVal e As System.EventArgs) Handles Me.Load
        ' create a new shipper
        Dim s As Shippers = New Shippers()
        s.CompanyName = "Code OnTime"
        s.Phone = "877-467-6340"
        If s.Insert() <> 1 Then
            Throw New Exception("Failed to create a shipper")
        End If
        ' find a shipper by ID
        Dim s2 As Shippers = Shippers.SelectSingle(s.ShipperID)
        If s2 Is Nothing Then
            Throw New Exception("Shipper not found")
        End If
        ' find a list of matching shippers by example
        Dim query As Shippers = New Shippers()
        query.Phone = "877-467-6340"
        Dim list As List(Of Shippers) = Shippers.Select(query)
        If list.Count = 0 Then
            Throw New Exception("Shippers not found")
        End If
        ' find a list of matching shippers by values
        Dim list2 As List(Of Shippers) = _
            Shippers.Select(Nothing, "code", Nothing)
        If list2.Count = 0 Then
            Throw New Exception("Shippers not found")
        End If
        ' update shipper
        list(0).CompanyName = "My Company"
        If list(0).Update() <> 1 Then
            Throw New Exception("Failed to update shipper")
        End If
        ' delete shipper
        If list2(0).Delete() <> 1 Then
            Throw New Exception("Failed to delete shipper")
        End If
    End Sub
End Class

Business object is nothing more than a shell that provides placeholders to all fields of underlining data set. Data manipulation methods are simply passing the parameters to the corresponding methods of object factories.

The purpose of factories is to interact with the Controller class of Data Aquarium Framework. This very class is executing all operations requested by AJAX scripts that constitute the other half of the framework. The implication of this is that the XML data controller descriptors are driving the behavior of business objects as well.

As a matter of fact, business objects are selecting data by imitating requests of JavaScript components of the framework. This allows complete reuse of business logic and rules that are linked to data controllers of your application.

JavaScript client components are always retrieving the exact number of data fields that are declared in the data controller views. Business objects are automatically configured to use the very first view of the corresponding controller. If your business object has a couple of dozen fields and you select data as described in this article then only the fields that are defined in the first view of the controller are retrieved. You can change that by creating a custom view that lists all fields that you do need and making this view first in the data controller definition. You can also add missing fields to the existing first view of the data controller and mark them as “hidden” if you don’t want these fields to be displayed in the user interface and only indent to manipulate the fields in your business logic.

This might seem as an overhead but is done to provide maximum efficiency and code reuse. Continue reading to learn how to benefit from the framework capabilities when building custom web forms.

Business Objects And Data Sources

If you don’t plan to write custom business rules then your only reason to generate business objects is to take advantage of ObjectDataSource data binding features of ASP.NET. Business object factories are constructed to fully support filtering, sorting, paging, and editing via ObjectDataSource.

You don’t need business objects if you take advantage of ControllerDataSource component that comes with Data Aquarium Framework. This component implements a generic factory and interacts with Controller of your application as custom business object factories do. It means that you are taking advantage of data controller descriptors and gain the same great features. You can filter, sort, page, and edit very large data sets without writing any code at all. You will still be required to list all fields that need to be retrieved by modifying view definitions in the corresponding data controller files.

Simple Data Binding

Let’s take a look at data binding with both data source components.

Here is the markup of a grid bound to ControllerDataSource.

<asp:GridView ID="GridView1" runat="server" DataSourceID="Cds1" />
<aquarium:ControllerDataSource ID="Cds1" runat="server" 
    DataController="Products" DataView="grid1" />

The following presentation will be rendered.

Here is how you can link an ObjectDataSource component to a grid view and take advantage of ProductsFactory class generated as a part of business object library of your application. Open a web form in design mode and select New data source option when choose source of data.

A wizard will show up. Select Object and click OK button.

Select MyCompany.Data.Objects.ProductsFactory as a business object.

Wizard will automatically select appropriate Select, Update, Insert, and Delete methods thanks to the data attributes that are applied to the appropriate factory class methods.

Finish the remaining wizard steps without making any further changes. This is the markup generated by wizard.

<asp:GridView ID="GridView1" runat="server" AutoGenerateColumns="False" 
    DataKeyNames="ProductID" DataSourceID="ObjectDataSource1" >
    <Columns>
        <asp:BoundField DataField="ProductID" HeaderText="ProductID" 
            InsertVisible="False" ReadOnly="True" SortExpression="ProductID" />
        <asp:BoundField DataField="ProductName" HeaderText="ProductName" 
            SortExpression="ProductName" />
        <asp:BoundField DataField="SupplierID" HeaderText="SupplierID" 
            SortExpression="SupplierID" />
        <asp:BoundField DataField="SupplierCompanyName" 
            HeaderText="SupplierCompanyName" SortExpression="SupplierCompanyName" />
        <asp:BoundField DataField="CategoryID" HeaderText="CategoryID" 
            SortExpression="CategoryID" />
        <asp:BoundField DataField="CategoryCategoryName" 
            HeaderText="CategoryCategoryName" SortExpression="CategoryCategoryName" />
        <asp:BoundField DataField="QuantityPerUnit" HeaderText="QuantityPerUnit" 
            SortExpression="QuantityPerUnit" />
        <asp:BoundField DataField="UnitPrice" HeaderText="UnitPrice" 
            SortExpression="UnitPrice" />
        <asp:BoundField DataField="UnitsInStock" HeaderText="UnitsInStock" 
            SortExpression="UnitsInStock" />
        <asp:BoundField DataField="UnitsOnOrder" HeaderText="UnitsOnOrder" 
            SortExpression="UnitsOnOrder" />
        <asp:BoundField DataField="ReorderLevel" HeaderText="ReorderLevel" 
            SortExpression="ReorderLevel" />
        <asp:CheckBoxField DataField="Discontinued" HeaderText="Discontinued" 
            SortExpression="Discontinued" />
    </Columns>
</asp:GridView>
<asp:ObjectDataSource ID="ObjectDataSource1" runat="server" 
    DataObjectTypeName="MyCompany.Data.Objects.Products" DeleteMethod="Delete" 
    InsertMethod="Insert" OldValuesParameterFormatString="original_{0}" 
    SelectMethod="Select" TypeName="MyCompany.Data.Objects.ProductsFactory" 
    UpdateMethod="Update">
    <SelectParameters>
        <asp:Parameter Name="productID" Type="Int32" />
        <asp:Parameter Name="productName" Type="String" />
        <asp:Parameter Name="supplierID" Type="Int32" />
        <asp:Parameter Name="supplierCompanyName" Type="String" />
        <asp:Parameter Name="categoryID" Type="Int32" />
        <asp:Parameter Name="categoryCategoryName" Type="String" />
        <asp:Parameter Name="quantityPerUnit" Type="String" />
        <asp:Parameter Name="unitPrice" Type="Decimal" />
        <asp:Parameter Name="unitsInStock" Type="Int16" />
        <asp:Parameter Name="unitsOnOrder" Type="Int16" />
        <asp:Parameter Name="reorderLevel" Type="Int16" />
        <asp:Parameter Name="discontinued" Type="Boolean" />
    </SelectParameters>
</asp:ObjectDataSource>

At first glance the markup of ObjectDataSource component seems to be more verbose but will be comparable in size if you define grid view fields for ControllerDataSource as well.

The web form will render virtually identically in a web browser with the exception of the field order.

Sorting and Paging

All available product records are being retrieved by both data source configurations.

Let’s enable sorting and paging. We will start with ControllerDataSource.

Select the grid view and enable sorting and paging.

Here is the changed markup.

<asp:GridView ID="GridView1" runat="server" DataSourceID="Cds1" 
    AllowPaging="True" AllowSorting="True" />
<aquarium:ControllerDataSource ID="Cds1" runat="server" 
    DataController="Products" DataView="grid1" />

Save and open the page in a web browser.

Paging and sorting is instantly available.

Note that the exact number of visible rows is now retrieved from the database every time you sort or page through the records. This allows you to sort and page through very large data sets. The default page size of GridView component is ten.  ControllerDataSource will never retrieve more than 10 records as configured. Standard SqlDataSource component is not able to deliver such performance.

Paging in the ObjectDataSource example is configured in a similar fashion. The markup changes are exactly the same. Sorting option is not available though and the entire set of records is automatically retrieved from the database instead of just the records that are rendered on the page.

ObjectDataSource component requires additional instructions to support sorting and perform efficient data retrieval operations.

Select ObjectDataSource component and bring up the data source configuration wizard.

Choose the second Select method on the second step of the wizard and complete the remaining steps

The second method is similar to the first one but features additional parameters sort, maximumRows, startRowIndex and dataView. The three of these parameters are needed to support sorting and efficient record retrieval as dictated by ObjectDataSource requirements for high performance business objects. The last parameter allows you to choose the data controller view of Data Aquarium Framework application that must be used as a source of data.

Continue making change to the ObjectDataSource. Use Properties Window of Visual Studio to change SortParameterName, EnablePaging, and SelectCountMethod of the component. Change them to sort, True, and SelectCount accordingly.

The sort parameter has been added to the data source markup by wizard. Paging is supported by the extended Select method of ProductsFactory via maximumRows and startRowIndex parameters. Method SelectCount is available in ProductsFactory. 

Select the grid and enable sorting.

Now paging and sorting in the grid linked to ObjectDataSource are efficient and will never read more records from the database than are needed for presentation.

Filtering

Data filtering is an important element of any application. From the developer’s prospective filtering must translate into SQL statements with WHERE clause to be considered efficient. Filtering supported in the standard SqlDataSource is performed only by retrieving all records from the database, which does not match this criterion of efficiency.

Both, ControllerDataSource and ObjectDataSource filtering implementations in Data Aquarium Framework applications are efficient.

Change the markup of ControllerDataSource sample web form as shown below.

<%@ Page Title="" Language="C#" MasterPageFile="~/MasterPage.master" 
    AutoEventWireup="true" CodeFile="Demo.aspx.cs" Inherits="Demo" %>

<asp:Content ID="Content1" ContentPlaceHolderID="head" runat="Server">
</asp:Content>
<asp:Content ID="Content2" ContentPlaceHolderID="Header1Placeholder" 
    runat="Server">
    ObjectDataSource vs. ControllerDataSource
</asp:Content>
<asp:Content ID="Content3" ContentPlaceHolderID="Header2Placeholder" 
    runat="Server">
    Northwind
</asp:Content>
<asp:Content ID="Content4" ContentPlaceHolderID="BodyPlaceholder" runat="Server">
    <table>
        <tr>
            <td>
                Product:<br />
                <asp:TextBox ID="ProductName" runat="server" />
            </td>
            <td>
                Supplier:<br />
                <aquarium:DataViewLookup ID="SupplierLookup" runat="server" 
                    DataController="Suppliers" />
            </td>
            <td>
                <br />
                <asp:Button ID="Button1" runat="server" Text="Go" />
            </td>
        </tr>
    </table>
    <asp:GridView ID="GridView1" runat="server" DataSourceID="Cds1" AllowPaging="True"
        AllowSorting="True" AutoGenerateColumns="False" DataKeyNames="ProductID">
        <Columns>
            <asp:BoundField DataField="ProductName" HeaderText="Product Name" 
                SortExpression="ProductName" />
            <asp:BoundField DataField="SupplierCompanyName" 
                HeaderText="Supplier Company Name"
                ReadOnly="True" SortExpression="SupplierCompanyName" />
            <asp:BoundField DataField="CategoryCategoryName" 
                HeaderText="Category Category Name"
                ReadOnly="True" SortExpression="CategoryCategoryName" />
            <asp:BoundField DataField="QuantityPerUnit" HeaderText="Quantity Per Unit" 
                SortExpression="QuantityPerUnit" />
            <asp:BoundField DataField="UnitPrice" HeaderText="Unit Price" 
                SortExpression="UnitPrice" />
            <asp:BoundField DataField="UnitsInStock" HeaderText="Units In Stock" 
                SortExpression="UnitsInStock" />
            <asp:BoundField DataField="UnitsOnOrder" HeaderText="Units On Order" 
                SortExpression="UnitsOnOrder" />
            <asp:BoundField DataField="ReorderLevel" HeaderText="Reorder Level" 
                SortExpression="ReorderLevel" />
            <asp:CheckBoxField DataField="Discontinued" HeaderText="Discontinued" 
            SortExpression="Discontinued" />
        </Columns>
    </asp:GridView>
    <aquarium:ControllerDataSource ID="Cds1" runat="server" DataController="Products"
        DataView="grid1">
        <FilterParameters>
            <asp:ControlParameter Name="ProductName" ControlID="ProductName" />
            <asp:ControlParameter ControlID="SupplierLookup" Name="SupplierID" 
                PropertyName="SelectedValue" />
        </FilterParameters>
    </aquarium:ControllerDataSource>
</asp:Content>

You can modify filter parameters visually in Properties Window of Visual Studio if you select the ControllerDataSource component and edit FilterParameters properties.

Run application and try data filtering in actions.

You can bind filter parameters to any ASP.NET components available to you. This sample is using standard TextBox and DataViewLookup component found in Data Aquarium Framework.

If you copy the markup for the table of filtering parameters to the ObjectDataSource sample and set parameter binding in the object data source configuration wizard then you will achieve exactly the same capability. There is a slight difference in configuring parameters. All available parameters of ProductsFactory.Select method are listed in parameter configuration step of the wizard.

 

Update, Insert, Delete

Update and Delete operations are automatically enabled for both data source components if you enable support for these features in the grid view. Here is the ControllerDataSource sample application with Classic auto-formatting applied to it.

 

Use standard DetailsView component if you want to be able to insert new records. Here is the ObjectDataSource sample with DetailsView component that has Classic auto-formatting applied to it.

Conclusion

Data Aquarium Framework does not stop with AJAX-enabled user interfaces. Any ASP.NET components supporting the data source architecture of Microsoft.NET will benefit from paging, sorting, and filtering of data sets of any size available in Data Aquarium application.

Business objects generated as a part of application are not mandatory and can be replaced with any external data access engine or library available to you.

In-Place Creation of Lookup Items

Data Aquarium Framework features on-demand creation of lookup items.

See it in Action

On the screen shot below a user has selected Edit command in context menu of a grid row that lists products from Northwind sample database.

The row is now displayed in edit mode. You can see that supplier company name field has an icon  right next to the lookup box.

A click on this icon will bring up New Suppliers modal dialog that allows entering a supplier in-place. The supplier is automatically selected in the lookup when user clicks OK button.

You can try this online at http://dev.codeontime.com/demo/nwblob.

Controlling Access to This Feature

The feature is extremely useful but shall not be left uncontrolled. Typically only certain categories of users are allowed to create new lookup items.

This is how the creation of new lookup items is turned on in the data controller definition files.

<field name="SupplierID" type="Int32" label="Supplier#">
  <items style="Lookup" dataController="Suppliers" newDataView="createForm1" />
</field>

Attribute newDataView of items element specifies the view defined in data controller identified by dataController attribute. The attribute value is automatically assigned by Code OnTime Generator. You can define a custom view in Suppliers data controller to provide an alternative form to create new suppliers.

If you don’t want in-place lookup item creation to to be enabled then simply delete the attribute.

Controlling in-place lookups With Roles

A better solution is to allow only certain user roles to create new lookup items.

Open data controller ~/Controllers/Suppliers.xml and modify New Suppliers action as follows:

<actionGroup scope="ActionBar" headerText="New">
  <action commandName="New" commandArgument="createForm1" 
        headerText="New Suppliers" 
        description="Create a new Suppliers record."  
        roles="Administrators"/>
</actionGroup>

Attribute roles will enable this action to be executed by users with Administrators role only. The framework will make sure that there is an action with New command in Suppliers data controller with an argument matched to the view specified by newDataView attribute of items element. If such action is not available then in-place creation of lookup items is automatically disabled.

Our sample application has been generated with ASP.NET Membership enabled. Here is how the row will look if we sign in a user with the standard name user. This user belongs to the role Users and is not authorized to create new suppliers.

You can see that the icon that allows creating new suppliers is gone. The user still can create new categories.

The centralized business logic and definitions of Data Aquarium Framework ensure that any other references to the Suppliers lookup in the application are affected as well.

This is how the supplier screen will look when displayed to the same user. Notice that New option is not available on the action bar anymore.

Conclusion

ASP.NET declarative security if fully integrated into Data Aquarium Framework and allows easy control over AJAX web applications of any complexity.

Creating Projects Outside “My Documents”

Code OnTime Generator will automatically generate projects to My Documents folder. You will find your projects code broken down by project type name under root  [My Documents]\Code OnTime.

This might introduce a problem with running your code under ASP.NET Development Server if your network policy has mapped this folder to a network drive.

Code OnTime Generator is built as an open code generation platform and allows free alterations to the code generation script.

For example, you can redirect the project output folder for Data Aquarium projects to you local folder C:\Data\MyProjects by modifying [My Documents]\Code OnTime\Projects\Data Aquarium\CodeOnTime.Projects.xml code generation script.

You can download the code generator script for Data Aquarium premium project at http://dev.codeontime.com/CodeOnTime.Project.zip. This script is current as of the date of publication of this article.

Open [My Documents]\Code OnTime\Projects\Data Aquarium\CodeOnTime.Projects.xml in your favorite XML editor and scroll all the way to the bottom.

        ........
        <load path="DataAquarium.Project.xml">
            <if test="a:project/a:webServer/@run='true'">
                <execute fileName="$CommonProgramFiles\microsoft shared\DevServer\9.0\WebDev.WebServer.EXE" arguments="/port:{a:project/a:webServer/@port} /path:&quot;$ProjectPath&quot; /vpath:&quot;/$ProjectName&quot;" mode="nowait"/>
                <execute fileName="http://localhost:{a:project/a:webServer/@port}/$ProjectName/default.aspx" arguments="-new" mode="nowait"/>
            </if>
        </load>
    </build>
    <actions>
        <action name="browse" toolTip="View &quot;{0}&quot; in a web browser.">
            <load path="DataAquarium.Project.xml">
                <execute fileName="$CommonProgramFiles\microsoft shared\DevServer\9.0\WebDev.WebServer.EXE" arguments="/port:{a:project/a:webServer/@port} /path:&quot;$ProjectPath&quot; /vpath:&quot;/$ProjectName&quot;" mode="nowait"/>
                <execute fileName="http://localhost:{a:project/a:webServer/@port}/$ProjectName/default.aspx" arguments="-new" mode="nowait"/>
            </load>
        </action>
    </actions>
</project>

Replace this code with the following:

    <load path="$ProjectPath">
        <variable name="MyProjectPath" select="'C:\data\MyProjects'"/>
        <forEach select="//file">
            <copy input="$ProjectPath\{@path}" output="$MyProjectPath\{@path}"/>
        </forEach>
    </load>
    <load path="DataAquarium.Project.xml">
        <if test="a:project/a:webServer/@run='true'">
            <execute fileName="$CommonProgramFiles\microsoft shared\DevServer\9.0\WebDev.WebServer.EXE" arguments="/port:{a:project/a:webServer/@port} /path:&quot;$MyProjectPath&quot; /vpath:&quot;/$ProjectName&quot;" mode="nowait"/>
            <execute fileName="http://localhost:{a:project/a:webServer/@port}/$ProjectName/default.aspx" arguments="-new" mode="nowait"/>
        </if>
    </load>
</build>
<actions>
    <action name="browse" toolTip="View &quot;{0}&quot; in a web browser.">
        <load path="DataAquarium.Project.xml">
            <variable name="MyProjectPath" select="'C:\data\MyProjects'"/>
            <execute fileName="$CommonProgramFiles\microsoft shared\DevServer\9.0\WebDev.WebServer.EXE" arguments="/port:{a:project/a:webServer/@port} /path:&quot;$MyProjectPath&quot; /vpath:&quot;/$ProjectName&quot;" mode="nowait"/>
            <execute fileName="http://localhost:{a:project/a:webServer/@port}/$ProjectName/default.aspx" arguments="-new" mode="nowait"/>
        </load>
    </action>
</actions>

The script in introducing a new variable $MyProjectPath, which is set to c:\data\MyProjects.

The variable is used to copy the generated code from [My Documents] location to the one specified by the variable and then ASP.NET Development Server is directed to use this location when executing the project.

Tracking User Actions

Tracking of user activities is a common requirement for many business applications. Data Aquarium Framework support Microsoft ASP.NET Membership via an advanced user management and login/logout user interface components. You can quickly create business rules to track user actions.

Sample Application

Generate a Data Aquarium project with the membership option enabled. Here is a typical screen shot of a Northwind database sample after the user with the name user has signed in.

Task 1

You want to keep a journal of user activities. The built-in .NET diagnostics facility will play a role of a journal where we will be keeping all activity records.

Solution

Create a business rules class Class1 and create method OrdersAfterUpdate as shown below. Link the business rules class to ~/Controllers/Orders.xml data controller as explained here.

C#

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using MyCompany.Data;

public class Class1 : BusinessRules
{
    [ControllerAction("Orders", "Update", ActionPhase.After)]
    protected void OrdersAfterUpdate(int orderId, FieldValue shipAddress)
    {
        System.Diagnostics.Debug.WriteLine(String.Format(
            "Order #{0} has been updated by '{1}' on {2}", 
            orderId, Context.User.Identity.Name, DateTime.Now));
        if (shipAddress.Modified) 
            System.Diagnostics.Debug.WriteLine(String.Format(
                 "Address has changed from '{0}' to '{1}.",
                 shipAddress.OldValue, shipAddress.NewValue));
    }
}

VB

Imports Microsoft.VisualBasic
Imports MyCompany.Data

Public Class Class1
    Inherits BusinessRules

    <ControllerAction("Orders", "Update", ActionPhase.After)> _
    Protected Sub OrdersAfterUpdate(ByVal orderId As Integer, _
                                    ByVal shipAddress As FieldValue)
        System.Diagnostics.Debug.WriteLine(String.Format( _
            "Order #{0} has been updated by '{1}' on {2}", _
            orderId, Context.User.Identity.Name, DateTime.Now))
        If (shipAddress.Modified) Then
            System.Diagnostics.Debug.WriteLine(String.Format( _
                 "Address has changed from '{0}' to '{1}.", _
                 shipAddress.OldValue, shipAddress.NewValue))
        End If
    End Sub

End Class

Open application in a web browser and select Orders data controller from the drop down in the top left corner. Start editing any order in the grid or form view and make sure to change Ship Address field. This field is the last visible field in the screen shot.

Hit OK button and the business method rule will intercept the action as soon as a successful database update has been completed. The first line of code will report the order ID and the user’s identity. The second line of code will detect the change in the address field.

Property Context provides business rules developers with the same Request, Response, User, Application, Session, and Server properties that are available  to web form developers.

The first two properties shall not be used since they provide information related to a current web service request and cannot be used to influence the user interface presentation.

Use the other properties as you if you were writing a typical web form.

Replace System.Diagnostics.Debug with a business object that is designed to keep track of user activities in a permanent data store such as a database table.

Task 2

All records in a database of orders must be marked with a reference to a user. User information will be utilized to filter data and for data analysis and reporting purposes.

Solution

Alter table [Northwind][.dbo].[Orders] to include new field UserName by executing the following SQL statement.

alter table Orders
add UserName varchar(50)
go

Modify command command1 in the data controller ~/Controllers/Orders.xml to select the new field twice. Once the field is selected under its own name and the other time we are selecting this very field under alias UserNameReadOnly. The reason for that is explained later.

        <command id="command1" type="Text">
            <text>
                <![CDATA[
select
    "Orders"."OrderID" "OrderID"
    ....................
    ,"Orders"."UserName" "UserName"
    ,"Orders"."UserName" "UserNameReadOnly"
from "dbo"."Orders" "Orders"
  ................
]]>
            </text>
        </command>

Add two field definitions for UserName instances in SQL statement to the list of data controller fields.

<fields>
    ...........
    <field name="UserName" type="String" label="User Name"/>
    <field name="UserNameReadOnly" type="String" label="User Name" readOnly="true"/>
</fields>

Let’s add the new read-only version of the field and a hidden version of the field to the list of data fields of views grid1 and editForm1.

<dataField fieldName="UserNameReadOnly"/>
<dataField fieldName="UserName" hidden="true"/>

Modify view createForm1 to include field UserName as a single hidden field.

<dataField fieldName="UserName" hidden="true"/>

We will silently assign a user name when a new record is created to the data controller field UserName. The captured value will be displayed when users review existing records but will be drawn from UserNameReadOnly for display purposes instead.

Add the following business rule to class Class1.

C#

[ControllerAction("Orders", "Update", ActionPhase.Before)]
[ControllerAction("Orders", "Insert", ActionPhase.Before)]
protected void OrdersBeforeUpdate(FieldValue userName)
{
    userName.NewValue = Context.User.Identity.Name;
    userName.Modified = true;
}

VB

    <ControllerAction("Orders", "Update", ActionPhase.Before)> _
    <ControllerAction("Orders", "After", ActionPhase.Before)> _
    Protected Sub OrdersBeforeUpdate(ByVal userName As FieldValue)
        userName.NewValue = Context.User.Identity.Name
        userName.Modified = True
    End Sub

This method will be automatically invoked whenever an order is about to be updated or inserted into database.

The first line will assign name of the currently logged-in user to the UserName field.

The second line will indicate that the field has actually changed. The framework is using Modified property of FieldValue instances to determine if a field shall be included in automatically generated SQL statement to update or insert a record.

You can also do an update on your own without relying on the framework. The best place for that sort of updates is in business rules methods with ActionPhase.After specifies as a parameter of ControllerAction attribute.

Here is how the grid of orders will look if you update a few records. The right-most column is displaying the name of the user.

The two fields UserName and UserNameReadOnly are required since read-only fields are never transferred to the server from the client web page. Hidden fields are never displayed but always travel from the client to the server and back. By introducing two versions of the same field we overcome this limitation imposed by the framework’s optimization logic.

Conclusion

Business rules in Data Aquarium Framework provide an excellent place to universally track user activities.

Filtering And Business Rules

Data Aquarium Framework offers a unique approach to creating reusable business rules and logic for ASP.NET applications. Today we will explore filtering with business rules.

All code samples are built for a Data Aquarium application generated from Northwind database.

Task 1

You want to enhance the customer lookup capability of Northwind application to display only USA customers when users are editing orders in a grid view and have a UK customer list when users are editing orders in form view. This should not affect any other views that are presenting customers.

Solution

Create new class Class1 and add property Country as shown in example below.

C#

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using MyCompany.Data;

public class Class1 : BusinessRules
{
    public Class1()
    {
    }

    [RowFilter("Customers", "grid1", "Country")]
    public string Country
    {
        get
        {
            RowFilter.Canceled = String.IsNullOrEmpty(
                RowFilter.LookupContextController);
            if (RowFilter.LookupContextController == "Orders" && 
                    RowFilter.LookupContextView == "editForm1")
                return "UK";
            else
                return "USA";
        }
    }

}

VB

Imports Microsoft.VisualBasic
Imports MyCompany.Data

Public Class Class1
    Inherits BusinessRules

    <RowFilter("Customers", "grid1", "Country")> _
    Protected ReadOnly Property Country() As String
        Get
            RowFilter.Canceled = _
                String.IsNullOrEmpty(RowFilter.LookupContextController)
            If RowFilter.LookupContextController = "Orders" AndAlso _
                    RowFilter.LookupContextView = "editForm1" Then
                Return "UK"
            Else
                Return "USA"
            End If

        End Get
    End Property

End Class

This class is inherited from MyCompany.Data.BusinessRules base. 

Property Country is adorned with RowFilter attribute. This attribute will force the framework to evaluate the property whenever grid1 view of data controller Customers is expected to present data. The value of the property will be applied as a server-side filter.

The filtering property Country is notifying the framework that its value shall be ignored when property LookupContextController of RowFilter is null. This can be accomplished by assigning boolean value False to RowFilter.Canceled.

Row filter is constructed only once for each data page request received from the client. The framework will reset the cancellation flag of row filter prior to evaluating each business rules property matched to the requesting data controller view. If evaluation of the property has resulted in cancellation then property value is ignored. Otherwise the value is inserted as a parameterized SQL expression in the WHERE clause of SELECT statement constructed by the framework.

The third argument of RowFilter attribute  applied to Country property specifies the name of the field that must be filtered. This is useful if the property of the business rule is named differently than the actual field defined in the data controller view. It is redundant in our example.

Class BusinessRules features RowFilter property that gives you access to Controller, View, LookupContextController, LookupContextView, and LookupContextFieldName that are useful to determine if and how the filter shall be applied.  Lookup context properties are informing you if the data has been requested by the lookup field. You can examine lookup context field name to apply a server-side filter to the data that might be helpful if the same database lookup data is used to provide lookup values to more than one table in your database. If the data is requested by a standalone data view then you will find that all of the lookup context properties are equal to null.

Multiple RowFilter attributes can be applied to the same property.

Now you have to link the new business rules to Customers data controller defined in ~/Controllers/Customers.xml. This is done by adding attribute handler as shown here.

<dataController name="Customers" 
    conflictDetection="overwriteChanges" 
    label="Customers" xmlns="urn:schemas-codeontime-com:data-aquarium" 
    handler="Class1">
    ......

Run your application or navigate to the online demo at http://dev.codeontime.com/demo/filteringrules/?controller=Orders. 

Start editing any order in the grid view of orders.

Click on the link with the customer name.

Customer lookup window will display 13 records of customers from USA.

Press Escape key and click on any other link in Customer Company Name column. Click Edit button to start editing record in the form view editForm1.

Click on the lookup link in Customer Company Name field. Notice that only UK customers are presented.

Let’s see if our business rules have affected the global list of customers. Navigate to http://dev.codeontime.com/demo/filteringrules?controller=Customers. About ninety customer records shall be displayed. We have used RowFilter.Canceled property to prevent filtering when the data is no requested in the context of the lookup field.

 

Task 2

You want to limit the list of employees to those born between 1/1/1950 and 11/1/1960.

Solution

Continue modifying our class and add BirthDate and BirthDate2 properties.

C#

[RowFilter("Employees", "grid1", "BirthDate", 
    RowFilterOperation.GreaterThanOrEqual)]
public DateTime BirthDate
{
    get
    {
        return new DateTime(1950, 1, 1);
    }
}

[RowFilter("Employees", "grid1", "BirthDate", 
    RowFilterOperation.LessThanOrEqual)]
public DateTime BirthDate2
{
    get
    {
        return new DateTime(1960, 1, 1);
    }
}

VB

<RowFilter("Employees", "grid1", "BirthDate", _
            RowFilterOperation.GreaterThanOrEqual)> _
            Protected ReadOnly Property BirthDate() As DateTime
     Get
         Return New DateTime(1950, 1, 1)
     End Get
End Property

<RowFilter("Employees", "grid1", "BirthDate", _
            RowFilterOperation.LessThanOrEqual)> _
           Protected ReadOnly Property BirthDate2() As DateTime
    Get
        Return New DateTime(1960, 1, 1)
    End Get
End Property

Link Class1 to ~/Controllers/Employees.xml data controller in the same fashion as we did for Customers data controller. Properties BirthDate and BirthDate2 are creating a range filter for employee field BirthDate.

You can see filtering by BirthDate in action at http://dev.codeontime.com/demo/filteringrules/?controller=Employees.

This filter is consistently applied whenever employee information is presented in data views.

Task 3

You want to filter data based on ASP.NET session variable.

Solution

Business rules have property Context that provide access to standard Request, Response, Session, Cache, and Application objects available in ASP.NET web forms. If you have a value stored in the session variable then you can easily apply its value as a filter.

<RowFilter("Customers", "grid1", "Country")> _
Protected ReadOnly Property CountryFilter() As String
    Get
        Return Context.Session("Country")
    End Get
End Property

Task 4

You want to filter data for a certain user roles.

Solution

The following code will inspect user role if a current user is not a member of Admin role then only customers from Finland are presented. Administrator’s view is not limited by a filter, which is accomplishing by cancelling filtering caused by CountryFilter property.

<RowFilter("Customers", "grid1", "Country")> _
Protected ReadOnly Property CountryFilter() As String
    Get
        If Context.User.IsInRole("Admin") Then
            RowFilter.Canceled = True
            Return String.Empty
        Else
            Return "Finland"
        End If
    End Get
End Property

Remember that if multiple filter properties are applicable to a give data page request then each filtering property must cancel row filter on its own.

Conclusion

Business rules in Data Aquarium Framework web applications allow efficient data filtering logic that is reused throughout your application. Subscribe to premium projects and start being productive today.