Getting the Most Out of the Save Pipeline in Visual Studio LightSwitch
Visual Studio LightSwitch applications consist of three tiers: presentation, logic and data. This article discusses the logic tier and its save pipeline. The save pipeline is where developers write business logic that runs as changes are processed on the logic tier and saved to the data storage tier. The save pipeline is automatically generated with every LightSwitch application. Understanding the processing done in the save pipeline is not required to successfully build and deploy applications with LightSwitch, but adding save pipeline business logic provides additional flexibility and control when data is saved. What Is the Save Pipeline? When a LightSwitch application is built and deployed, one data service is generated on the logic tier for each data source specified in the application. For example, in Figure 1 there are two data sources specified. One is the built-in data source which contains Vendors and one is an attached data source which contains Customers. When Vendors are saved, changes will be sent to the data service that was generated for ApplicationData. When Customers are saved, changes will be sent to the data service that was generated for NorthwindData. Two data sources result in two generated data services. 
Figure 1: An application with two Data Sources.Each generated service has a SaveChanges operation, among others. The save pipeline is responsible for handling calls to SaveChanges. It processes the changes in sequence and inserts, updates or deletes data stored on the data tier. Calling the Save Pipeline The caller to SaveChanges can be a LightSwitch client or another save pipeline. Screens generated with LightSwitch automatically call SaveChanges when the Save button is clicked. The following code snippet shows a call to SaveChanges from LightSwitch code, which saves all changes that have been made on the ApplicationData data source. (Changes to other data sources remain uncommitted and must be saved explicitly by calling SaveChanges on them.) // Save changes on the ApplicationData data source
this.DataWorkspace.ApplicationData.SaveChanges();
Understanding Change Sets As changes are made to entities within a data source, those changes are tracked in a change set. When SaveChanges is called, this change set is serialized, sent to the data service’s SaveChanges operation and de-serialized into a server-side data workspace. The save pipeline operates on those changes and any additional changes made on the logic tier. Client and server code can inspect the change set for a data source and determine which entities have been changed. The GetChanges method on the data source’s Details member is the accessor for the change set. The change set has members for accessing inserted, deleted and modified entities separately. The following code shows how to access the modified entities in a change set and generate a string that contains the names of the entities. string changeString = "";
// Get the change set
EntityChangeSet changes =
this.DataWorkspace.MyData.Details.GetChanges();
// Loop over only modified entities
foreach (IEntityObject item in
changes.ModifiedEntities)
{
changeString +=
string.Format("Entity {0} has changes.\n",
item.ToString());
}
Coding within the Save Pipeline So far, everything we’ve discussed has been generated as part of the LightSwitch application with no coding required. But what if you want to control what happens within the logic tier? What if you want to reserve inventory every time an order is placed and then allocate that inventory once the order is fulfilled? What if you want to provide a simple workflow that tracks the state of a document and creates related entities as the document moves through a process? How can this be accomplished with the save pipeline? This section discusses where code can be added to a LightSwitch application to be executed within the save pipeline. Two types of code are executed within the save pipeline. The first is common entity code, which belongs to the entity and is executed on both the client and logic tiers. Common entity code is used to keep the entity in a valid state or calculate other values on the entity. It includes entity created code, property changed code, property read-only code, calculated properties and validation logic. This code is called “as-needed” on the logic tier. So, if a calculated property is never accessed from the logic tier that calculated property will never be called. The second type of code executed within the save pipeline is the pipeline interception methods, which are executed at specific points along the save pipeline. The available methods are unique to the different phases of the save pipeline. They are as follows (organized by phase): Pre-processing - SaveChanges_CanExecute: Called to determine whether or not SaveChanges can be executed.
- SaveChanges_Executing: Called before the operation is processed.
Validation - EntitySet_CanRead, CanInsert, CanUpdate, CanDelete: For each entity in the change set, permissions are checked to see if the requested changes can be performed.
- Entity Validation: Common property validation is called for each modified or inserted entity (the same validation code that runs on the client). This includes any built-in LightSwitch validation based on model properties such as MaxLength on a string or MaxValue on an integer.
- EntitySet_Validate: Called for each modified or inserted entity.
Pre-process Entities - EntitySet_Inserting: Called for each inserted entity.
- EntitySet_Updating: Called for each updated entity.
- EntitySet_Deleting: Called for each deleted entity.
Execution LightSwitch passes all of the changes to the underlying provider for processing. There are no interception methods in this phase. Post-process Entities - EntitySet_Inserted: Called for each inserted entity.
- EntitySet_Updated: Called for each updated entity.
- EntitySet_Deleted: Called for each deleted entity.
Post-processing - SaveChanges_Executed: Called after a successful processing of SaveChanges.
- SaveChanges_ExecuteFailed: Called after a failure in processing.
The save pipeline looks rather simple. Each changed entity in the change set gets processed once through the pipeline. However, if code in the data service makes additional changes, LightSwitch ensures that newly inserted, modified or deleted entities also pass through the pipeline. This ensures that business logic is applied uniformly to all entities and entity sets. Changes made to an entity from within its own pre-process pipeline interception methods do not cause the entity to be re-processed by the save pipeline. They are only re-validated. If the change causes the entity state to change, however (for example, from updated to deleted), the appropriate pre-process entity method will be called. Changes to the data source on which the pipeline is executing will be automatically processed by the save pipeline and do not need to be explicitly saved by calling SaveChanges. Changes made to a different data source must be saved by calling SaveChanges to initiate the save pipeline for that data source; otherwise those changes will be lost. Imagine the following code being called inside the save pipeline for ApplicationData. This code will make changes to the NorthwindData data source from within the ApplicationData save pipeline. // Make changes to NorthwindData entities
...
// Save changes to the NorthwindData data source
this.DataWorkspace.NorthwindData.SaveChanges();
Figure 2 shows how the save pipeline processes a change set and how changes impact the pipeline. 
Figure 2: The Save Pipeline.When the processing within the save pipeline succeeds, any changes made to entities in the original change set are serialized back to the client. In this way, the client can get updated IDs, or observe any other changes made by the data service code. Any entities added to the change set on the service tier are not serialized back to the client. The pipeline interception methods listed above are available in the Write Code dropdown in the LightSwitch entity designer. The General Methods section contains entity-specific methods as well as the entity pipeline methods. Entity-specific methods are prefixed with the entity name while entity pipeline methods are prefixed with the entity set name. The Access Control Methods section contains the methods that are called to check if calling SaveChanges is permitted and to check if the changes that are being attempted in the change set are permitted. The SaveChanges pre- and post-processing methods are listed under the Data Source Methods section. Returning to the question posed at the beginning of this section, let’s see how to reserve inventory every time an order is placed and then allocate that inventory once the order is fulfilled. Our application has an Order entity with related OrderLine entities and each OrderLine refers to an inventory Item. The following code reserves inventory on a new Order. public partial class ApplicationDataService
{
partial void Orders_Inserting(Order entity)
{
foreach (OrderLine line in entity.Lines)
{
line.Item.Quantity -= line.Quantity;
line.Item.ReservedQuantity += line.Quantity;
}
}
}
The code is on the ApplicationDataService class. All save pipeline code that is specific to that data service resides on this class. The second part of the above question is how to allocate inventory once the order is fulfilled. For this, we need to run code when an Order is updated and check to see if the State has changed to “Fulfilled.” partial void Orders_Updating(Order entity)
{
if (entity.Details.Properties.State.IsChanged &&
entity.State == "Fulfilled")
{
foreach (OrderLine line in entity.Lines)
{
line.Item.ReservedQuantity -= line.Quantity;
}
}
}
|