How to Use CslaGen to Generate CSLA Data Access Layer Code

• Download demo project (C# and SQL scripts) - 106.18 KB

Introduction

CSLA is a free 3-tier framework for .NET Framework 2.0 and 3.0. The Apress book "Expert C# 2005 Business Objects, Second Edition" by Rockford Lhotka documents CSLA for C# and there is also a VB 2005 edition. This is not a closed project, but rather a living and evolving one. It is supported by a dynamic and helpful community that you can find here. You can get CSLA C# and VB source files here (I use the 2.1.4 version).

CslaGen is a code generator that takes care of generating the data access layer files needed for the CSLA framework. There are templates for generating SQL Server stored procedures, as well as C# or VB. It also supports ActiveObjects extension to CSLA that implements the Observer pattern. At the time of writing, the main contributor is Andrés Villanueva (AKA "xal"). The Google group is here. You can get the latest version here and the latest version of the C# templates can be found here.

While CSLA is very well documented, CslaGen contributors lack the time to document it. This project is just an example to illustrate some very basic ways to use CslaGen.

Background

Rocky Lhotka doesn't subscribe to the datacentric concept of objects, but uses the behavioral concept. Objects are defined by their responsibilities. Thus, you should use different objects on selection listings and when editing the object itself.

The Database

The database Family is composed of the Mother and Daughter tables. The latter references the former, as shown in Fig. 1 below:

Under SQL Server, create a database Family. The project file CslaGen.zip includes queries to create the database tables and populate them with some data.

The Project Structure

We will assume that both Mother and Daughter objects are big objects, with lots of properties. Loading a collection of these objects is very expensive and we will load an abcList collection of lighter abcInfo objects (just names and enough information to load the selected object). Note that abcList and abcInfo are read-only objects. As you can see in Fig. 2, the MotherList is a root collection of MotherInfo children that allows us to select one of the Mothers and load the full object. The Mother object is a root object that is editable. It loads DaughterList, a child collection of DaughterInfo grandchildren. After selecting a DaughterInfo grand-child, our would-be application would load the full Daughter object in order to edit it.

Create Root-level Selection Objects

Responsibility: list and select root objects.

In this step, we will create list objects in order to list and select the root object to edit. You can skip it if your application doesn't need to list root objects. Loading a collection of complete root objects (with all their properties and children) may be a lengthy process. That's why we prefer to use just a subset of the properties of the root object, and to ignore the child objects. If you prefer to list complete root objects:

• In step 2.2, just right click and Select All.
• In step 2.3, create an Editable Root Collection instead of a Read Only Collection.
• 3.1. On the Schema Objects pane, select the database table Mother.
• 3.2. On the Columns pane, select the database columns ID, Forename, Surname and LastChanged.
• 3.3. Right click and select Create -> Read Only Collection. Note that you can't add or delete items on a read-only collection.
• 3.4. In the New Object Defaults window, set CollectionName = "MotherList" and ItemName = "MotherInfo".
• 3.5. On the MotherList, create a criterion to get all the items of the collection.
  • 3.5.1. On the Csla Objects pane, select the MotherList object.
  • 3.5.2. On the Csla Object Info pane, under 03. Criteria, edit the Criteria Objects collection by clicking on the ellipsis.
  • 3.5.3. On the Criteria Collection Editor window, add a member named AllCollection (or anything else you prefer).
  • 3.5.4. Under Misc, unfold GetOptions and set DataPortal, Factory and Procedure to True (note the ProcedureName field changes automatically to GetMotherList ) and then click OK.
• 3.6. Now create another criterion to get a list of Mother by forename and/or surname.
  • 3.6.1. Repeat steps 3.5.1 to 3.5.4. but use instead the member name Name
  • 3.6.2. Change the ProcedureName field to GetMotherListByName.
  • 3.6.3. Don't click OK right now, but instead edit the Properties collection under Properties by clicking on the ellipsis.
  • 3.6.4. Add a member. Drag the CriteriaProperty Collection Editor window to the upper part of the screen and click on the DbBindColumn field.
  • 3.6.5. On the Schema Objects window, select the column Forename of the table Mother. Now click on the member panel and the member name will change automatically.
  • 3.6.6. Repeat the latter operation for the column Surname. The Stored Procedure that CslaGen generates will combine both names. Say you specify Mar as the forename and an empty string as the forename. You will retrieve Mary Poppins, Mariah Carey, and other Mar%.

Create the Root Object "Mother"

Responsibility: edit Mother details.

• 4.1. On the Schema Objects pane, select the database table Mother, right click it and chose Create Editable Root. A new object named Mother is created that includes all the columns of this table.
• 4.2. Under 09. System.Object Overrides, change the ToString Property by clicking on the down arrow. Select Forename and Surname and press ENTER.

Create Child-level Selection Objects

Responsibility: list and select children.

We assume that loading a collection of complete child objects can be a lengthy process. Thus, we prefer to use a collection of subsets of Daughter. After selecting what Daughter to use, we will load the complete object. Of course, there are other possible strategies to handle large child objects. After understanding this example, you can easily adapt it to load a collection of complete child objects.

• 5.1. On the Schema Objects pane, select the database table Daughter.
• 5.2. On the Columns pane, select the database columns DaughterID, Forename, Surname, MotherID and LastChanged.
• 5.3. Right click and select Create -> Read Only Collection. Note that you can't add or delete items in a read-only collection.
• 5.4. On the New Object Defaults window, set CollectionName = "DaughterList" and ItemName = "DaughterInfo".
• 5.5. On the Csla Object Info pane of DaughterList, under 04. Child Object Options, change the Parent Type by clicking on the down arrow. Select the Mother object and press ENTER.
• 5.6. Now we must link the Mother object to this read-only collection so that it knows it has to load the collection.
  • 5.6.1. On the Csla Object Info pane of Mother, under 02. Business Properties, edit the Child Collection Properties collection by clicking on the ellipsis.
  • 5.6.2. On the ChildProperty Collection Editor window, add a member. Under Definition, set the Name, ParameterName and TypeName to DaughterList. Now click OK.

Create the Root Object "Daughter"

Responsibility: edit Daughter details.

Child objects are never loaded directly; their parent takes care of it. The parent of Daughter is Mother, but instead of loading a collection of complete Daughter objects, we assumed this could be a lengthy process and loaded a collection of subsets of Daughter.

• 6.1. On the Schema Objects pane, select the database table Mother, right click it and chose Create Editable Root. A new object named Mother is created that includes all the columns of this table
• 6.2. Under 09. System.Object Overrides, change the ToString Property by clicking on the down arrow. Select Forename and Surname and press ENTER.

The Example Program

The example program is a very simple one. It fills a tree view with mothers and daughters (although some mothers don't have any daughters at all). The date and place of birth only show up on the tooltip. There are no provisions for editing data.

• 7.1. Download the demo/source file and unzip it. The file FamilyGen.xml is the resulting file of the CslaGen project.
• 7.2. In SQL 2000 or SQL 2005, create a database Family and run the scripts in the SQL scripts directory. If something goes wrong, delete the Mother and Daughter tables and rerun the scripts following the appropriate order.
• 7.3. In VS 2005, open the Family solution under the CS source directory. First of all, you must:
  • Correct the CSLA reference.
  • Edit App.config and correct the connection string.

Now you can compile and run the solution.

Appendix: C# Code to Load the Family TreeView

private void formFamily_Load(object sender, EventArgs e)
{
    // Load the collection of all light MotherInfo objects
    MotherList motherList = MotherList.GetMotherList();
    foreach (MotherInfo motherInfo in motherList)
    {
        // Create the root node
        TreeNode node =
            treeViewRelations.Nodes.Add(motherInfo.Forename.Trim() +
            " " + motherInfo.Surname.Trim());

        // Get the complete Mother object
        // (along with the DaugtherInfo collection)
        Mother mother = Mother.GetMother
            (motherInfo.ID, motherInfo.LastChanged);

        // Display mother birth date and place on the tooltip
        node.ToolTipText = mother.BirthDate + " " + mother.BirthPlace;

        foreach (DaughterInfo daughterInfo in mother.DaughterList)
        {
            // Create a daughter node
            TreeNode subNode =
                node.Nodes.Add(daughterInfo.Forename.Trim() +
                " " + daughterInfo.Surname.Trim());

            // Get the complete Daughter object
            // NB - From CSLA point of view, the Daughter object
            // is a root object (as it loads itself)
            Daughter daughter = Daughter.GetDaughter
            (daughterInfo.DaughterID, daughterInfo.LastChanged);

            // display daughter birth date and place on the tooltip
            subNode.ToolTipText = daughter.BirthDate +
                " " + daughter.BirthPlace;
        }
    }
}

History

• First release: 08 August 2007
• Last revision: 18 March 2010