NestedUnitOfWork Class

A nested unit of work.

Assembly: DevExpress.Xpo.v24.1.dll

NuGet Packages: DevExpress.Win.PivotGrid, DevExpress.Win.TreeMap, DevExpress.Xpo

Declaration

C#
VB.NET

public class NestedUnitOfWork :
    UnitOfWork

Public Class NestedUnitOfWork
    Inherits UnitOfWork

Remarks

A Nested Unit of Work is a new Unit of Work initiated inside a Session or another Unit of Work. Changes made within a Nested Unit of Work are merged with the parent session rather than passed to the data store if the Nested Unit of Work is committed. Changes made to nested objects do not immediately affect the corresponding objects in the parent session because a Nested Unit of Work operates on cloned objects.

Nested Units of Work provide the following features:

Isolate possible errors and changes that can be canceled without affecting other uncommitted changes;
Build a hierarchy of changes by combining multiple related changes in an atomic operation;
The nesting depth is limited only by the available memory.

Nested Units of Work are represented by the NestedUnitOfWork class. The Nested Unit of Work’s parent is a Session or Unit of Work from which the Nested Unit of Work is initiated.

To create a new Nested Unit of Work, call the parent Session’s or Unit of Work’s Session.BeginNestedUnitOfWork method.

To commit changes made within the Nested Unit of Work since it was started, use the UnitOfWork.CommitChanges method. The Nested Unit of Work commits changes to the parent Session or Unit of Work. To commit these changes further (to the data store or to the grandparent, if the parent is a Nested Unit of Work too), call the parent Unit of Work’s UnitOfWork.CommitChanges method.

Since every Session uses separate copies of persistent objects, the Nested Unit of Work’s objects cannot be used in combination with the parent Unit of Work’s objects. To obtain a copy of the parent Unit of Work’s object in the Nested Unit of Work, use the NestedUnitOfWork.GetNestedObject or NestedUnitOfWork.GetNestedObject<T> method. To obtain a copy of the Nested Unit of Work’s object in the parent Unit of Work, use the NestedUnitOfWork.GetParentObject or NestedUnitOfWork.GetParentObject<T> method.

The Session.Reload method called in the Nested Unit of Work may not always reload the object. If you need to cancel changes made in the Nested Unit of Work, dispose of the Nested Unit of Work and start a new one from the parent.

C#
VB.NET

using(UnitOfWork parentUOW = new UnitOfWork()) {
    Order order = new Order(parentUOW);
    //...
    Payment lastPayment;
    using(NestedUnitOfWork nestedUOW = parentUOW.BeginNestedUnitOfWork()) {
        Payment payment = new Payment(nestedUOW);
        payment.Order = nestedUOW.GetNestedObject<Order>(order);
        //...
        if(isPaymentConfirmed) {
            nestedUOW.CommitChanges();
            lastPayment = nestedUOW.GetParentObject<Payment>(payment);
        }
    }
    //...
    parentUOW.CommitChanges();
}

Using parentUOW As New UnitOfWork()
    Dim order As New Order(parentUOW)
    '...
    Dim lastPayment As Payment
    Using nestedUOW As NestedUnitOfWork = parentUOW.BeginNestedUnitOfWork()
        Dim payment As New Payment(nestedUOW)
        payment.Order = nestedUOW.GetNestedObject(Of Order)(order)
        '...
        If isPaymentConfirmed Then
            nestedUOW.CommitChanges()
            lastPayment = nestedUOW.GetParentObject(Of Payment)(payment)
        End If
    End Using
    '...
    parentUOW.CommitChanges()
End Using

Important

The Nested Unit of Work does not automatically synchronize with the parent Session or Unit of Work after the latter is modified, and further manipulations in the Nested Unit of Work may lead to issues. We recommend disposing of the Nested Unit of Work before accessing the parent session. Usually, the Nested Unit of Work should be disposed of after its changes are committed to the parent and before the parent’s CommitChanges method is called. Nested Units of Work started from the same parent cannot operate concurrently.

Note

You can try this functionality in the XPO Tutorials demo’s Data Exchange and Manipulation | NestedUnitsOfWork section (C:\Users\Public\Documents\DevExpress Demos 24.1\Components\WinForms\Bin\XpoTutorials.exe).