Performing Data-Related Tasks by Using Code

You can accomplish many data-related design tasks by using the designers and tool windows in Visual Studio LightSwitch. However, you must add code to an application to accomplish certain tasks. For example, you must write code to validate a field by applying custom conditions. 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.

partial void RetrieveCustomer_Execute()
{
    Customer cust = this.Customers.SelectedItem;
    if (cust.ContactName == "Bob")
    {
        //Perform some task on the customer entity.
    }
}

The following example iterates over a collection of customers.

partial void RetrieveCustomers_Execute()
{
    foreach (Customer cust in this.DataWorkspace.NorthwindData.Customers)
    {
        if (cust.ContactName == "Bob")
        {
            //Perform some task on the customer entity.
        }
    }
}

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.

partial void RetrieveSalesOrders_Execute()
{
    Customer cust = this.Customers.SelectedItem;

    foreach (Order order in cust.Orders)
    {
        if (order.OrderDate == DateTime.Today)
        {
            //perform some task on the order entity.
        }
    }
}

The following example gets the customer who placed a specific order.

partial void RetrieveCustomer_Execute()
{
    Order order = this.DataWorkspace.NorthwindData.Orders_Single
        (Orders.SelectedItem.OrderID);

    Customer cust = order.Customer;
    //Perform some task on the customer entity.

}

You can retrieve queries from the model and then execute them in your code. To view an example, see How to: Retrieve Data from a Query by Using Code.

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.

partial void Orders_Inserting(Order entity)
{
    foreach (Order_Detail detail in entity.Order_Details)
    {
        detail.Product.UnitsInStock = 
            (short?)(detail.Product.UnitsInStock - detail.Quantity);
    }
}
NoteNote

If your code modifies data from other data sources, you must commit those changes by calling the SaveChanges method of that data source. For more information, see How to: Save Data.

You can delete data by calling the Delete method of any entity. The following example deletes a customer from the NorthwindData data source.

partial void DeleteCustomer_Execute()
{
    Customer cust =
        this.Customers.SelectedItem;

    if (Customers.CanDelete)
    {
        cust.Delete();
    }
}

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.

partial void ImportCustomers_Execute()
{
    foreach (SharePointCustomer spCust in 
this.DataWorkspace.SharePointData.NewCustomersInSharePoint())
    {
        Customer newCust = new Customer();

        newCust.ContactName = spCust.FirstName + " " + spCust.LastName;
        newCust.Address = spCust.Address;
        newCust.City = spCust.City;
        newCust.PostalCode = spCust.PostalCode;
        newCust.Region = spCust.Region;

        //Set the CopiedToDatabase field of the item in SharePoint.
        spCust.CopiedToDatabase = "Yes";
    }
    this.DataWorkspace.SharePointData.SaveChanges();


}

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.

If your application includes screens that combine data from multiple data sources, you must also add code to specify the order in which you want to update those sources.

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.

partial void Orders_Inserting(Order1 entity)
{
    foreach (Order_Detail1 detail in entity.Order_Details)
    {
        detail.Product.UnitsInStock = (short?)
            (detail.Product.UnitsInStock - detail.Quantity);
    }
    this.DataWorkspace.ProductDataSource.SaveChanges();

}

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.

partial void CustomersListDetail_Saving(ref bool handled)
{
    try
    {
        this.DataWorkspace.SharePointData.SaveChanges();
    }
    catch (DataServiceOperationException ex)
    {
        if (ex.ErrorInfo == "DTSException")
        {
            this.ShowMessageBox(ex.Message);
        }
        else
        {
            throw ex;
        }
    }
    handled = true;


}

If your application includes a screen that combines data from multiple sources, you must override the saveChangesTo method and explicitly call SaveChanges in the Saving method.

Public Class MyScreen
    Private Sub MyScreen_InitializeDataWorkspace(
            saveChangesTo As System.Collections.Generic.List(Of Microsoft.LightSwitch.IDataService))

        saveChangesTo.Add(Me.DataWorkspace.AppData1)
        saveChangesTo.Add(Me.DataWorkspace.AppData2)
    End Sub

    Private Sub MyScreen_Saving(ByRef handled As Boolean)
        Me.DataWorkspace.AppData1.SaveChanges()
        Me.DataWorkspace.AppData2.SaveChanges()
        handled = True
    End Sub
End Class
public class MyScreen
{

private void MyScreen_InitializeDataWorkspace(System.Collections.Generic.List<Microsoft.LightSwitch.IDataService> saveChangesTo)
{
saveChangesTo.Add(this.DataWorkspace.AppData1);
saveChangesTo.Add(this.DataWorkspace.AppData2);
}

private void MyScreen_Saving(ref bool handled)
{
this.DataWorkspace.AppData1.SaveChanges();
this.DataWorkspace.AppData2.SaveChanges();
handled = true;
}
}

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:

  • CanRead

  • CanInsert

  • CanDelete

  • CanUpdate

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.

partial void Customers_CanUpdate(ref bool result)
{
    result = this.Application.User.HasPermission(Permissions.RoleUpdate);
}

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.

partial void UndoAllCustomerUpdates_Execute()
{
    foreach (Customer cust in  
        this.DataWorkspace.NorthwindData.Details.
        GetChanges().OfType<Customer>())
    {
        cust.Details.DiscardChanges();
    }
}

partial void UndoAllUpdates_Execute()
{
    this.DataWorkspace.NorthwindData.Details.DiscardChanges();
}

partial void UndoCustomerEdit_Execute()
{
    Customers.SelectedItem.Details.DiscardChanges();
}

If you want to modify a query beyond the capabilities of the Query Designer, you can extend the query by adding code to the PreProcessQuery method of the query. For more information, see How to: Extend a Query by Using Code.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft