Performing Data-Related Tasks by Using Code
You can use the designers and tool windows in Visual Studio LightSwitch to accomplish many data-related design tasks. However, certain tasks can only be accomplished by adding code to an application. For example, to validate a field by applying custom conditions, you must write code. This document shows how to accomplish data-related tasks by using the data runtime object model. For more information about where you can write code in an application, see the following topics:
The following list shows common data-related tasks that you can accomplish by using the data runtime object model. The tasks are described later in this document.
You can read individual data items or collections of data items from any data source in your application.
The following example retrieves the customer that is currently selected in a screen.
The following example iterates over a collection of customers.
You can read data from related entities. For example, a Customer entity might have a one-to-many relationship with an Orders entity. You could iterate over all orders that have been placed by a customer by using the Orders property of the Customer entity.
The following example iterates over the collection of orders that are related to a customer.
The following example gets the customer who placed a specific order.
You can update data for any entity by using code. The following example shows code that runs when a user creates an order in the Order entity in a screen and then clicks the Save button. The code updates a field in the Products entity by using a field in the Order Details entity.
If your code modifies data from other data sources, you must commit those changes by calling the SaveChanges method of that data source.
The following example adds a new customer to the NorthwindData data source. This example populates the fields that describe the new customer by using information from a contact that was recently added to a SharePoint list. The example calls a query named NewCustomersInSharePoint to determine which contacts in the SharePoint list have not yet been imported to the NorthwindData data source.
Private Sub ImportCustomers_Execute() For Each spCust As SharePointCustomer In _ Me.DataWorkspace.SharePointData.NewCustomersInSharePoint Dim newCust As Customer = New Customer() With newCust .ContactName = spCust.FirstName & " " & spCust.LastName .Address = spCust.Address .City = spCust.City .PostalCode = spCust.PostalCode .Region = spCust.Region 'Set the CopiedToDatabase field of the item in SharePoint. spCust.CopiedToDatabase = "Yes" End With Next Me.DataWorkspace.SharePointData.SaveChanges() End Sub
Typically, pending changes are committed to a data source when the user clicks the Save button in a screen. However, you can also commit pending changes by adding code that calls the SaveChanges method of a data source. You must add this code if you want to accomplish either of these tasks:
Commit changes that you make to data that is located in other data sources.
Override the Save event of a screen.
The files in which you write custom code have a primary data source. If you add custom code that modifies data from another data source in your LightSwitch solution, you must commit those changes by calling the SaveChanges method of that data source.
The following example shows code that runs when a user creates an order in an Order entity in a screen and then clicks the Save button. The code updates a field in the Products entity by using a field in the Order Details entity. Because the Products entity is located in another data source, this code calls the SaveChanges method of that data source to commit the changes.
You can change the behavior of the Save button on a screen by overriding the Save event. Because you are replacing the behavior of the Save button, your code must call the SaveChanges method when you want to commit pending changes.
The following example overrides the Save event of a customer screen to catch and handle a specific exception that might be thrown if the save operation fails.
You can apply custom validation rules to the fields of an entity. You can add custom error messages that appear when users modify the value of properties in ways that do not conform to your validation rules. For more information, see How to: Validate Data in a LightSwitch Application
By default, all users can view, insert, delete, or update data that appears in a screen. However, you can restrict these permissions by adding code to one of the following methods:
If you restrict an operation by using these methods, LightSwitch makes the operation unavailable to users who do not have unrestricted permissions. For more information, see How to: Handle Data Events.
The following example enables a user to update customer information if the user has update permission. This code example requires a permissions group named RoleUpdate. For more information about how to add a permissions group to your application, see Enabling Authorization and Creating Permissions in LightSwitch.
By default, LightSwitch calls these methods when a user attempts to view, insert, delete, or update information. You can also call these methods in your custom code before data is read or modified.
You can identify and discard pending changes before they are committed to a data source. The following example shows three user methods that identify and discard pending changes. The UndoAllCustomerUpdates method discards all changes made to all customers. The UndoAllUpdates method discards all changes made to the data source. The UndoCustomerEdit method discards changes made to the currently selected row of data in a customer screen.
Private Sub UndoAllCustomerUpdates_Execute() For Each Cust As Customer In _ Me.DataWorkspace.NorthwindData.Details. _ GetChanges().OfType(Of Customer)() Cust.Details.DiscardChanges() Next End Sub Private Sub UndoAllUpdates_Execute() Me.DataWorkspace.NorthwindData.Details.DiscardChanges() End Sub Private Sub UnduCustomerEdit_Execute() Customers.SelectedItem.Details.DiscardChanges() End Sub