Blog: Posts from July, 2012

The application framework of each project is generated in C# or Visual Basic. The business rules engine of the framework takes care of executing SQL, Email, and JavaScript business rules in response to actions defined in the data controller. Naturally, developers can create business rules written in the programming language of the project to tap in the power of the business rules engine and vast Microsoft.NET library.

For example, the “Code” business rule defined in the project configuration will result in the code file generated in the project output folders.

The business rule file provides a method template linked to the data controller business rule with Rule attribute. The file will not be re-created during subsequent code generation sessions. Any modifications to the file will become a permanent extension of the application framework.

Let’s implement a validation business logic.  Note that the highlighted text indicates the conditional expression inserted in the automatically generated business rule method template.

C#:

using System;
using MyCompany.Data;

namespace MyCompany.Rules
{
    public partial class CustomersBusinessRules : MyCompany.Data.BusinessRules
    {
        /// <summary>
        /// This method will execute in any view before an action
        /// with a command name that matches "Insert|Update|Delete".
        /// </summary>
        [Rule("r100")]
        public void r100Implementation(string customerID, string companyName,
            string contactName, string contactTitle, string address, string city,
            string region, string postalCode, string country, string phone, string fax)
        {
            // This is the placeholder for method implementation.
            if (country == "USA")
            {
                // tell the application framework to skip the execution of update, insert, or delete
                PreventDefault();
                // set the focus to the field "Country" and display an error message
                Result.Focus("Country",
                    "You are not authorized to {0}, " +
                    "if the Country is equal to \"USA\".",
                    Arguments.CommandName.ToLower());
                // show an additional information in the message bar at the top of the page
                Result.ShowMessage("Error trying to execute {0} command",
                    Arguments.CommandName);
            }
        }
    }
}

Visual Basic:

Imports MyCompany.Data
Imports System

Namespace MyCompany.Rules
    Partial Public Class CustomersBusinessRules
        Inherits MyCompany.Data.BusinessRules
        ''' <summary>
        ''' This method will execute in any view before an action
        ''' with a command name that matches "Insert|Update|Delete".
        ''' </summary>
        <Rule("r100")> _
        Public Sub r100Implementation(ByVal customerID As String, ByVal companyName As String,
            ByVal contactName As String, ByVal contactTitle As String, ByVal address As String,
            ByVal city As String, ByVal region As String, ByVal postalCode As String,
            ByVal country As String, ByVal phone As String, ByVal fax As String)
            ' This is the placeholder for method implementation.
            If (country = "USA") Then
                ' tell the application framework to skip the execution of update, insert, or delete
                PreventDefault()
                ' set the focus to the field "Country" and display an error message
                Result.Focus("Country",
                    "You are not authorized to {0}, " &
                    "if the Country is equal to ""USA"".",
                    Arguments.CommandName.ToLower())
                ' show an additional information in the message bar at the top of the page
                Result.ShowMessage("Error trying to execute {0} command",
                    Arguments.CommandName)
            End If
        End Sub
    End Class
End Namespace

The pattern of implementation is following closely the pattern of SQL and JavaScript business rules. Both of these alternatives are actually built on top of the same infrastructure demonstrated in this example.

The screenshot shows the “code” business rule in action.

The Code Default property provides an expression written in C#/Visual Basic that evaluates to an initial field value of a new data row. Database tables frequently define default column expressions that will be evaluated by the database engine when a new record is persisted. From the user perspective, it is beneficial to see what exactly will be inserted in the column at the time when the user enters the field values instead of leaving the fields blank and relying on the database to fill in the blanks. The Code Default may provide a duplicate calculation that fulfills this need.

Default Values with C# / Visual Basic

The New Orders form has two date fields, Order Date and Required Date, that should have defaults when the form is first initialized.

Start the Project Designer. In the Project Explorer, switch to the Controllers tab, and double-click on Orders / Fields / OrderDate node.

Change the Code Default:

Press OK to save. Double-click on Orders / Fields / RequiredDate node.

Change the Code Default:

Press OK to save. On the Project Browser toolbar, press Browse button.

Navigate to the Orders page, and create a new record. The Order Date field will be populated with the current date. The Required Date field will be populated with the date seven days in the future.

This is how the code generator incorporates the code expression in the C#/Visual Basic business rules.

C#:

using System;
using MyCompany.Data;

namespace MyCompany.Rules
{
    public partial class OrdersBusinessRules : MyCompany.Data.BusinessRules
    {
        
        [RowBuilder("Orders", RowKind.New)]
        public void BuildNewOrders()
        {
            UpdateFieldValue("OrderDate", DateTime.Now);
            UpdateFieldValue("RequiredDate", DateTime.Now.AddDays(7));
        }
    }
}

Visual Basic:

Imports MyCompany.Data

Namespace MyCompany.Rules
    
    Partial Public Class OrdersBusinessRules
        Inherits MyCompany.Data.BusinessRules
        
        <RowBuilder("Orders", RowKind.New)>  _
        Public Sub BuildNewOrders()
            UpdateFieldValue("OrderDate", DateTime.Now)
            UpdateFieldValue("RequiredDate", DateTime.Now.AddDays(7))
        End Sub
    End Class
End Namespace

A custom utility class can be implemented for complex calculations. A static or shared property or method of the class can be used in Code Default expressions similar to how System.DateTime class is used in the example.

Default Values with SQL Business Rules

Code Default permits simple default values. For a majority of situations or when a more complex default value calculation involving interactions with the database is required, SQL Business Rules provide a great alternative.

Switch back to the Project Designer. Double-click on Orders / Fields / OrderDate field node.

Clear the Code Default:

Save the field. Double-click on Orders / Fields / RequiredDate field node.

Change the following properties:

Press OK to save the field. Right-click on Orders / Business Rules node, and select New Business Rule option.

Use the following configuration:

set @OrderDate = GETDATE()
set @RequiredDate = DATEADD("d", 7, getdate())

Press OK to save the business rule. On the toolbar, press Browse.

Navigate to the Orders page, and create a new order. The correct date values will be presented as default values.

The business rule matching New command is automatically executed on the server and the values of parameters OrderDate and RequiredDate are transferred to the fields with the same name in a new row.