[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Collapse]WPF Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Common Concepts
 [Expand]MVVM Framework
 [Expand]Controls and Libraries
 [Collapse]Scaffolding Wizard
   Getting Started
  [Collapse]Overview
    System Requirements
    Common Application Architecture
    Functionality Overview
    View Types
    Structure of Classes in a Scaffolded Application
    Unit of Work Policy
    Localization
  [Expand]Data Access Layer
   UI Generation
  [Expand]Examples
  [Expand]Tutorials
 [Expand]Localization
  Redistribution and Deployment
  Get More Help
 [Expand]API Reference
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Unit of Work Policy

Expanded Overview

The Unit of Work Policy allows you to manage whether view models use their own individual instances of UnitOfWork or share the one provided by its parent.

The following policies are supported.

  • Individual - use an individual UnitOfWork and pass UnitOfWorkPolicy.Individual to children.
  • Shared - use a shared UnitOfWork and pass UnitOfWorkPolicy.Shared to children.
  • PassSharedToChildren - use an individual UnitOfWork, but pass UnitOfWorkPolicy.Shared to children.

By default, all view models use UnitOfWorkPolicy.Individual. Entities that are queried in one view model cannot be used in another view model. So a collection view model does not pass the selected Entity to its child SingleObjectViewModel. Instead, the collection view model passes the primary key of an Entity and the SingleObjectViewModel then fetches the Entity from its own UnitOfWork.

Sharing UnitOfWork instances allows a parent view model to commit or discard changes made by its children. A change made by a child view model does not need to be committed to the database immediately. Sharing makes it possible to create/modify several child Entities and commit changes in a single transaction.

The CollectionViewModel takes a unitOfWorkPolicy parameter in its constructor. This policy cannot be changed during the view model life time.

The SingleObjectViewModel also functions according to the specified UnitOfWorkPolicy, but it cannot be set explicitly and is always inherited from a parent CollectionViewModel.

Expanded Setting the Unit of Work Policy

To change the default Unit of Work Policy, set the additional unitOfWorkPolicy argument within either the CollectionViewModel constructor

or within the GetDetailsCollectionViewModel method.

Important

Changing the default Unit of Work Policy requires resetting the saved layout stored in the %LOCALAPPDATA%/[YourApplicationName] folder if it exists.

Expanded Scenarios

To illustrate the scenarios enabled by Unit of Work Policies, let's use an application based on the following data model.

It has the following hierarchical structure:

  1. Root CollectionViewModel: the Departments collection
  2. SingleObjectViewModel: individual Department instances
  3. Detail CollectionViewModel: the Courses and Employees collections specific to each department
  4. Detail SingleObjectViewModel: individual Course and Employee instances

Expanded Default Scenario

The following gallery illustrates the default scenario: all view models use UnitOfWorkPolicy.Individual. As the end-user navigates down the hierarchy, views are opened in separate tabs.

Expanded Shared Collection View Model Root

The UnitOfWorkPolicy.Shared policy is specified in the collection view model constructor.

This mode allows you to add several entities in the root collection and save them at once in a single transaction.

The following gallery illustrates this scenario: the DepartmentCollectionViewModel uses UnitOfWorkPolicy.Shared. The Departments view is shown in a tab. As the end-user navigates down the hierarchy, views are opened in modal windows.

Expanded Shared Single Object View Model

The UnitOfWorkPolicy.PassSharedToChildren policy is specified in the collection view model constructor.

In this mode, each single object view model gets an individual UnitOfWork. Each detail collection view model shares the UnitOfWork of its parent single object view model.

This mode allows you to edit several entities independently. A new entity can be created, several detail entities appended to it and then all of them saved in one step.

The following gallery illustrates this scenario: the DepartmentCollectionViewModel uses UnitOfWorkPolicy.PassSharedToChildren. The Employee view is opened in a modal window.

Expanded Shared Detail Collection View Model

The UnitOfWorkPolicy.Shared policy is specified in a GetDetailsCollectionViewModel invocation.

Every SingleObjectViewModel is independent of its detail collections and other single object view models. It is possible to add/modify several detail entities in a single transaction, but only if the parent entity is already saved to the database.

The following gallery illustrates this scenario: the view model for the DepartmentEmployees detail collection uses UnitOfWorkPolicy.PassSharedToChildren. The Employees view model in the Department-Journalism tab displays Save and Reset Changes buttons that allow the end-user to apply or revert changes made to several detail entities.

Expanded Limitations

The following features are only available in view models that use UnitOfWorkPolicy.Individual.

  • Projections
  • Instant Feedback server mode
  • Many-to-many associations with an implicit junction table, or a junction table that does not contain additional payload properties

Is this topic helpful?​​​​​​​