When handling an event in business logic code, you can perform an action that triggers another business logic event, that in turn is handled and triggers yet another event, and so on. For example, handling a field change event, you can set another field, or perform any other possible action. In most data frameworks, such actions are either blocked or can only be handled in a straightforward way creating uncontrolled recursion. Uncontrolled event triggering leads to complicated situations often creating unintended effects and side effects. Every database developer can recall situations where a harmless code intended to, say, commit a record once certain fields are entered by the end user, either does not work or produces unexpected and often disastrous results.

DataObjects for .NET solves this problem by allowing the developer to exercise full control over the order of actions performed by business logic code. Various actions, including method calls and field value assignments, can be specified to take place either immediately or after DataObjects for .NET has completed performing previous actions that are already in the queue, and completed handling the events that are being handled.

When the end user initiates an action leading to a business logic event (for example, sets a field value, or deletes a row), DataObjects for .NET starts executing it by creating an action context stack. The initial state of this stack is one level with the requested action contained in it. If no actions have been requested by the business logic code while this action was handled, the stack is destroyed. If, however, an action (that itself can trigger a business logic event), is requested while handling this action, the requested action can be processed by DataObjects for .NET in two different ways:

• Immediate (default): DataObjects for .NET adds a new level to the action context stack and starts handling this new action. The original action handling is waiting until the new action is handled. This is the "straightforward", recursive event handling mentioned above.
• Deferred: Alternatively, DataObjects for .NET can add the requested action to the action queue, to be processed after all actions already in the queue are finished. In this case, DataObjects for .NET does not do anything with the requested action, it just adds it to the queue and immediately returns, continues to handle the event. The requested action will be processed before DataObjects for .NET relinquishes control, "in due course", when the event code has finished executing and all the actions that got to the queue earlier have been processed.

To control the action order, use the ExecutionMode property. Its two possible values, Immediate (default) and Deferred, specify the two modes described above.

ExecutionMode is a read-only property. You never need to set execution mode permanently. You only need to set it for the duration of a certain fragment of code, after which it must be restored to its previous value. Since changing execution mode can inadvertently break your code, we strongly recommend using try-finally blocks to ensure that previous execution mode is always restored.

To set execution mode, call the PushExecutionMode method, passing it the new mode as a parameter. To restore the previous execution mode, call PopExecutionMode.

For example, the following code (taken from Adding Rows and Primary Keys) sets the primary key field in a newly added row immediately after the row has been created.

To write code in Visual Basic

Private Sub table_Customers_AfterAddNew(ByVal sender As Object, ByVal e As C1.Data.RowChangeEventArgs) Handles TableLogic1.AfterAddNew
    e.DataTable.DataSet.PushExecutionMode _
         (C1.Data.ExecutionModeEnum.Deferred)
    'The following field value assignment and a method call
    'will actually execute only after all other actions handling
    'the row addition will be finished
    e.Row("CustomerID") = TextBox1.Text
    e.Row.EndEdit()
    e.DataTable.DataSet.PopExecutionMode()
End Sub

To write code in C#

private void table_Customers_AfterAddNew(object sender, C1.Data.RowChangeEventArgs e)
{
    e.DataTable.DataSet.PushExecutionMode(ExecutionModeEnum.Deferred);
    // The following field value assignment and a method call
    // will actually execute only after all other actions handling
    // the row addition will be finished
    e.Row["CustomerID"] = textBox1.Text;
    e.Row.EndEdit();
    e.DataTable.DataSet.PopExecutionMode();
}

Although this code would probably work without changing execution mode, doing so would be unsafe, since it would trigger EndEdit before AddNew is completely finished (for example, a grid or another bound control could be not yet notified at that time that a row has been added).

What we really want in cases like this ("after this, do that") is to emulate end user actions, as if the end user typed the key value after adding a new row, which is essentially what DataObjects for .NET is doing in the Deferred execution mode.