Export (0) Print
Expand All

Walkthrough: Taking a Tour of RIA Services

[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

This walkthrough provides you with an overview of many of the features in WCF RIA Services. In this walkthrough, you create a RIA Services application that retrieves data from tables in the AdventureWorks OLTP sample database. First, you retrieve the data by specifying the LoadOperation. You then retrieve that data with the DomainDataSource control. You specify sorting, filtering, and paging for the data presentation control, and add a DataForm control to present a detailed view of the data. You apply validation rules to the fields and enable the user to edit data values. You restrict access to a domain operation to authenticated users. Finally, you define the association between two related tables and display the related data.

Ff713719.Tip(en-us,VS.110).gifTip:
For shorter walkthroughs for getting started by creating a more basic RIA Services solution, see Walkthrough: Creating a RIA Services Solution or Walkthrough: Using the Silverlight Business Application Template.

This and the other walkthroughs presented in the WCF RIA Services documentation require several prerequisite programs, such as Visual Studio 2010 and the Silverlight Developer Runtime and SDK, be installed and configured properly, in addition to WCF RIA Services and the WCF RIA Services Toolkit. They also require installing and configuring SQL Server 2008 R2 Express with Advanced Services and installing the AdventureWorks OLTP and LT database.

Detailed instructions for the satisfaction of each of these prerequisites are provided by the topics within the Prerequisites for WCF RIA Services node. Follow the instructions provided there before proceeding with this walkthrough to ensure that you encounter as few problems as possible when working through this RIA Services walkthroughs.

In this section, you create and set up the solution.

To create a new WCF RIA Services application

  1. In Visual Studio 2010, create a new RIA Services project by selecting File, New, and then Project.

    The New Project dialog box appears.

  2. In the Installed Templates pane, expand the Visual Basic or Visual C# node, and select the Silverlight category.

  3. Select the Silverlight Business Application template and name the application HRApp.

    RIA_HRAppStart
  4. Click OK.

    Notice the structure of the solution that is created:

    • The solution consists of two projects: a Silverlight client project named HRApp and an ASP.NET Web Application server project named HRApp.Web.

    • The default solution contains many automatically implemented features including navigation, user login and logout, and new user registration.

    RIA_HRAppStructure
  5. Build and Run (F5) the application and explore the default implementation.

  6. Close your Web browser.

To set up the application

  1. In Solution Explorer, in the client project, open MainPage.xaml.

  2. In XAML view, find the TextBlock named ApplicationNameTextBlock.

    As shown in the following markup, notice that the application name is retrieved from a resource.

  3. In Solution Explorer, expand the Assets folder, and then expand the Resources folder.

  4. Open the ApplicationStrings.resx file.

  5. Change the ApplicationName resource to HR Application.

  6. Save and close the ApplicationStrings.resx file.

  7. In Solution Explorer, right-click the Views folder, click Add, and then click New Item.

    The Add New Item dialog box is displayed.

  8. Select the Silverlight Page template from the Silverlight category of Installed Templates and name it EmployeeList.xaml.

    RIA_HRAppAddPage
  9. Click Add.

  10. Open EmployeeList.xaml if it does not open automatically.

  11. Add the following XAML between the <Grid> tags.

  12. Save the EmployeeList.xaml file.

  13. Open MainPage.xaml.

  14. Add a new hyperlink button to the top of the page by adding the following XAML between the two existing hyperlink buttons.

  15. Run the application and notice the new Employee List link on the upper right corner of the page, between the Home and About links. Click on it to display “Employee List” in the body of the page.

    RIA_HRAppPageView

In this section, you create an ADO.NET Entity Data Model for tables in the AdventureWorks sample database. Then, you create a domain service that exposes the entities and displays that data in the client project.

To add a data source

  1. In Solution Explorer, right-click the HRApp.Web project, click Add, and then click New Item.

    The Add New Item dialog box is displayed.

  2. In the Data category, select the ADO.NET Entity Data Model template.

    RIA_HRAppAddEntity
  3. Change the name to AdventureWorks.edmx, and then click Add.

    The Entity Data Model Wizard opens.

  4. On the Choose Model Contents page, click Generate from database, and then click Next.

  5. On the Choose Your Data Connection page, create a connection to the AdventureWorks database.

  6. Name the entity connection settings AdventureWorks_DataEntities and then click Next.

  7. On the Choose Your Database Objects page, expand the Tables node.

  8. Add check marks next to the Employee, PurchaseOrderDetail, and PurchaseOrderHeader tables.

  9. Name the model namespace AdventureWorks_DataModel and then click Finish.

    The entity data model appears in the designer.

  10. Build the solution.

To add a domain service object and query for data

  1. In Solution Explorer, right-click the HRApp.Web project, click Add, and then click New Item.

    The Add New Item dialog box is displayed.

  2. In the Web category, select the Domain Service Class template.

    RIA_HRAppAddService
  3. Name the new item OrganizationService.

  4. Click Add.

  5. In the Add New Domain Service Class dialog box, select Employee, PurchaseOrderDetail, and PurchaseOrderHeader from the Entities list, and then select Enable editing for each entity.

  6. Ensure that the Enable client access and Generate associated classes for metadata check boxes are selected.

  7. Click OK.

    OrganizationService.cs/vb and OrganizationService.metadata.cs/vb files are added to the project.

  8. Open the OrganizationService.cs/vb file.

    Notice that query, insert, update, and delete methods have been created for each entity. A query method is always created for an entity. The insert, update, and delete methods were added because Enable editing was selected.

  9. Customize the GetEmployees() query method to return employees sorted by EmployeeID by replacing the generated code with the following code.

  10. Build the solution.

    Building the solution generates the Domain Context and entities in the client project.

  11. Open EmployeeList.xaml.

  12. From the Toolbox, drag a DataGrid control to Design view just after the TextBlock control.

    Dragging a DataGrid to Design view adds a reference to the System.Windows.Controls.Data assembly and adds the sdk prefix to the Page element.

  13. Change the default values for the DataGrid control by removing the Height and Width properties, making it read-only, setting it to automatically generate columns, and setting its minimum height.

  14. Save EmployeeList.xaml.

  15. Open EmployeeList.xaml.cs/vb.

  16. Add the following using or Imports statements.

  17. Instantiate the OrganizationContext class and load employee data by adding the following code to EmployeeList.xaml.cs/vb.

    The OrganizationContext class is automatically generated in the client project based on the OrganizationService class in the server project.

  18. Run the application.

  19. Click the Employee List link to see the DataGrid.

    RIA_HRAppDataGrid

To add a custom query

  1. In the HRApp.Web project, open OrganizationService.cs/vb.

  2. Add a new method named GetSalariedEmployees by adding the following code to the body of the class.

  3. Build the solution.

  4. In the client project, open EmployeeList.xaml.cs/vb.

  5. In the constructor, replace the call to GetEmployeesQuery() with a call to GetSalariedEmployeesQuery().

  6. Run the application and click the Employee List link.

    Notice that all of the displayed employees have the SalariedFlag value checked. Employees with EmployeeID 1, 2, and 4 no longer appear in the list because they are not salaried.

    RIA_HRAppFilteredDataGrid

To add a domain data source

  1. Open EmployeeList.xaml.

  2. From the Toolbox, drag the DomainDataSource control to Design view, just before the DataGrid. The DomainDataSource might appear at the bottom of the list of controls.

    Ff713719.Tip(en-us,VS.110).gifTip:
    If the DomainDataSource control is not in the Toolbox, right click in the Toolbox, and click Choose Items. Under the Silverlight Components tab check DomainDataSource, and click OK.

    When you drag the DomainDataSource control to Design view, a reference with the prefix riaControls is created for the System.Windows.Controls namespace in the Page element. Also, a data source icon appears in the lower-left corner of Design view.

  3. For C# solutions, add the following namespace declaration to the XAML file.

    xmlns:ds="clr-namespace:HRApp.Web"
    
  4. For Visual Basic solutions, add the following namespace declaration to the XAML file.

    xmlns:ds="clr-namespace:HRApp"
    
  5. Name the DomainDataSource control employeeDataSource and set the LoadSize, AutoLoad, and query method by replacing the existing XAML with the following XAML.

  6. Set the DomainContext for the DomainDataSource by adding the following XAML.

  7. Replace the DataGrid with the following XAML.

  8. Open EmployeeList.xaml.cs/vb.

  9. In the constructor, remove or comment out the code to instantiate the OrganizationContext instance, the call to GetSalariedEmployeesQuery(), and the code to set the DataGrid control’s ItemsSource property.

    You no longer need to explicitly load data, since the DomainDataSource will do this automatically.

  10. Run the application and click the Employee List link.

    The application works the same as before.

To add sorting, filtering, and paging to the data source

  1. Open EmployeeList.xaml.

  2. In the DomainDataSource, add the following SortDescriptors to specify how data is sorted in the DataGrid.

    This XAML shows how to sort the VacationHours column in ascending order.

  3. Run the application and click the Employee List link.

    The data is sorted by VacationHours and you can change the sort direction by clicking the column header.

  4. Open EmployeeList.xaml.

  5. To enable the user to filter which records are returned by providing a value, add the following XAML before the DataGrid.

    The XAML adds a TextBox control so that the user can input a value.

  6. In the DomainDataSource, add a filter descriptor that is bound to the TextBox control you added in the previous step.

  7. Run the application and click the Employee List link.

  8. In the Min Vacation Hours Filter text box, type 70.

    Notice that the listed employees have VacationHours greater than or equal to 70.

    RIA_HRAppVacationFilter
  9. Open EmployeeList.xaml.

  10. From the Toolbox, drag a DataPager control to just below the DataGrid.

  11. Set the page size to 5 and set the source as shown in the following XAML.

  12. Run the application and click the Employee List link.

    You see only 5 rows of filtered data per page and pager controls below the DataGrid.

    RIA_HRAppPagedData

In this section, you use the DataForm control from the Silverlight Toolkit to provide a detailed view of the data. By default, the Silverlight Business Application project template contains the System.Windows.Controls.Data.DataForm.Toolkit.dll binary in the Libs folder.

To add a DataForm

  1. Open EmployeeList.xaml.

  2. Add the following namespace declaration.

    xmlns:dataForm="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls.Data.DataForm.Toolkit"
    
  3. After the DataPager control, add the following XAML to add a DataForm control.

    This XAML sets the DataForm attributes and specifies the columns to be displayed.

  4. Run the application and click the Employee List link.

    The DataForm displays details of the item selected in the DataGrid.

    RIA_HRAppDataForm

When you select the Enable editing check box in the New Domain Service Class dialog box, methods are generated in the domain service layer to update, insert, and delete the entity. In this section, you add edit buttons to the user interface of the employee list to enable users to execute these operations.

To update a record

  1. Open the EmployeeList.xaml file.

  2. After the DataForm control, add the following XAML to add a Submit button.

  3. In the DomainDataSource control, specify an event handler for the SubmittedChanges event.

  4. Open EmployeeList.xaml.cs/vb.

  5. Add the following event handler for the button click event.

    The submitButton is disabled to prevent the user from submitting the change again as the operation is being processed.

  6. Add an event handler for the SubmittedChanges event that checks whether the submit operation completed successfully and enables submitButton.

  7. Run the application and click the Employee List link.

  8. Select an employee and click the pencil icon in the upper-right hand corner of the data form to enable editing.

    You can now modify any editable field.

  9. Make changes to the employee data and click OK.

  10. Click the Submit button to save the data.

    Changes are saved to the database on the server only when you click the Submit button.

To add custom methods to a domain service

  1. In the HRApp.Web server project, open OrganizationService.cs/vb. File

  2. Add the following custom method named ApproveSabbatical.

  3. Build the solution.

  4. Open EmployeeList.xaml.

  5. After the Submit button, add the following XAML to add an Approve Sabbatical button.

  6. Open EmployeeList.xaml.cs/vb.

  7. Add the following event handler for the button click event that calls the ApproveSabbatical domain operation.

  8. Run the application and click the Employee List link.

  9. Click the Approve Sabbatical button and note that the CurrentFlag check box for the selected employee is cleared.

The DataForm control can show validation errors from the data access layer (DAL). For example, if you enter a non-integer value in the VacationHours field, a validation error is displayed. The following illustration shows an example of the validation behavior.

RIA_HRAppValidation

When you select the Generate associated classes for metadata check box in the New Domain Service Class dialog box, a file that contains metadata is created. In this walkthrough, the metadata file is named OrganizationService.metadata.cs/vb. In this section, you add validation attributes to this file. The validation rules will be enforced in the client and server projects.

You also create a user interface to allow the addition of new employee records to the database. The validation rules that you added in the previous sections will automatically be applied in the new user interface.

To add basic validation

  1. In the HRApp.web project, open OrganizationService.metadata.cs/vb.

  2. Add the following attributes to the Gender and VacationHours properties.

  3. Build the solution.

  4. Run the application and click the Employee List link.

  5. Select an employee and click the pencil icon in the upper-right hand corner of the data form to enable editing.

  6. Enter a value in the Vacation Hours field that is not within the valid range (0-70) and move the focus to another control.

    You see a validation error for vacation hours.

    RIA_HRAppRangeValidation
  7. Delete the value in the Gender field and move the focus to another control.

    You see a validation error for gender.

To add custom validation

  1. In Solution Explorer, right-click the HRApp.Web project, click Add, and then click New Item.

    The Add New Item dialog box is displayed.

  2. In the Code category, select the Code File template.

  3. Name the new item OrganizationService.shared.cs or OrganizationService.shared.vb.

    Files that end with .shared.cs or .shared.vb are available in both the client and server projects. Shared files enable you to run the same validation rule in both projects. After you build the solution in a later step, look in the hidden Generated_Code folder on the client, and you will see the OrganizationService.shared.cs/vb file.

  4. Click Add.

  5. To create a customized validation class that verifies the values assigned to the Gender property, add the following code to the shared file.

  6. Open OrganizationService.metadata.cs/vb.

  7. Add the following custom validation attribute to the Gender property.

  8. Build the solution.

  9. Run the application and click the Employee List link.

  10. Select an employee and click the pencil icon in the upper-right hand corner of the data form to enable editing.

  11. Enter a value in the Gender field that is not M or F and move the focus to another control.

    The result of the custom validation appears.

    RIA_HRAppCustomValidation

In this section, you add a form that enables the user to create a new record in the Employee table.

To add a new record

  1. In the HRApp project, add a new item.

  2. In the Silverlight category, select the Silverlight Child Window template.

  3. Name the new item EmployeeRegistrationWindow.xaml.

    RIA_HRAppAddChildWindow
  4. Click Add.

  5. Open EmployeeRegistrationWindow.xaml.cs/vb.

  6. If you are using C#, add the following using statement.

  7. Add a property for the new Employee entity that is created with the user values.

  8. Open EmployeeRegistrationWindow.xaml.

  9. Add the following namespace declaration to EmployeeRegistrationWindow.xaml to use the DataForm control in this window.

    xmlns:dataForm="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls.Data.DataForm.Toolkit"
    
  10. Add the following DataForm control to EmployeeRegistrationWindow.xaml just before the Cancel button.

  11. Open EmployeeRegistrationWindow.xaml.cs/vb.

  12. Add the following code to create a new Employee instance and handle either committing the new instance or canceling the insertion.

  13. Open EmployeeList.xaml.

  14. Between the DataPager and the DataForm, add the following XAML to create a button named addNewEmployee.

  15. Open EmployeeList.xaml.cs/vb.

  16. Add the following code to handle the button click event and display the EmployeeRegistrationWindow.

  17. Add the following method to handle the closed event for EmployeeRegistrationWindow.

  18. Open OrganizationService.cs/vb.

  19. Modify the InsertEmployee method by adding the following code.

  20. Run the application and click the Employee List link.

  21. Click the Add Employee button.

    The EmployeeRegistrationWindow opens.

    RIA_Employee_Registration
  22. Add data in the window and select the Salaried check box.

  23. Click OK.

  24. Refresh the page and ensure that the new employee appears in the DataGrid.

In this section, you restrict access to the ApproveSabbatical method to only authenticated users.

To add authentication

  1. Open OrganizationService.cs/vb.

  2. Add the RequiresAuthentication attribute to the ApproveSabbatical method.

    When you apply the RequiresAuthentication attribute to a domain operation, you ensure that only authenticated users can call the operation. If an anonymous user clicks the Approve Sabbatical button, the operation is not executed.

  3. Open EmployeeList.xaml.cs/vb.

  4. Add the following using or Imports statements.

  5. Modify the approveSabbatical_Click method and add a LoggedIn handler to check whether the user is authenticated.

  6. Run the application and click the Employee List link.

  7. Select an employee record and click the Approve Sabbatical button.

    You are redirected to the login window.

  8. Click the Register now link.

  9. Complete the required fields to create a new account.

  10. Click OK.

    You are logged in with that account and your name appears in a bar below the navigation links.

With RIA Services you can easily work with data from related tables. In this section, you add a new Silverlight Page and display data from the PurchaseOrderHeader and PurchaseOrderDetail tables. You can also customize the data modification operations so the related data is modified together. For an example of modifying the data in related tables through a domain operation, see Compositional Hierarchies.

To display data from related tables

  1. In the HRApp project, right-click the Views folder, click Add, and then click New Item.

  2. Add a new Silverlight Page named PurchaseOrders.xaml.

  3. Open PurchaseOrders.xaml.

  4. Add the following XAML between the <Grid> tags.

  5. Open MainPage.xaml.

  6. After the EmployeeList link, add the following XAML to include a link to the PurchaseOrders page.

  7. Open OrganizationService.metadata.cs/vb.

  8. Add the Include and Composition attributes to the PurchaseOrderDetails property in the PurchaseOrderHeaderMetadata class.

  9. Open OrganizationService.cs/vb.

  10. Change the GetPurchaseOrderHeaders method so that the related records in PurchaseOrderDetails are also retrieved with the query.

  11. Open PurchaseOrders.xaml.

  12. On the Data menu, click Show Data Sources to open the Data Sources window.

  13. Drag the PurchaseOrderHeader node to the design surface for PurchaseOrders.xaml.

    RIA_Order_Header

    A DataGrid with columns from the PurchaseOrderHeader table appears.

  14. In the Data Sources window, expand the PurchaseOrderHeader node.

  15. Drag the PurchaseOrderDetails node that is located inside the PurchaseOrderHeader node to the design surface just under the DataGrid for PurchaseOrderHeader.

    RIA_Order_Details

    A DataGrid with columns from the PurchaseOrderDetails table appears.

  16. In XAML view, find the DataGrid controls for both PurchaseOrderHeader and PurchaseOrderDetails.

  17. Remove the Width=”400” property from each DataGrid so that it will fill the available width.

  18. Before the PurchaseOrderHeader DataGrid, add the following TextBlock control to label the data.

  19. Before the PurchaseOrderDetails DataGrid, add the following TextBlock control to label the data.

  20. To limit the number of records that are retrieved, add the following filter descriptor to the DomainDataSource control.

    The following shows the complete XAML for PurchaseOrders.xaml.

  21. Run the application and click the Purchase Orders link.

  22. Select different records in the PurchaseOrderHeader DataGrid.

    Notice that the related PurchaseOrderDetail records are automatically displayed.

    RIA_Details_and_Header

This walkthrough has given you a tour of many of the features in RIA Services. To learn the details of specific areas, see the other walkthroughs in this documentation.

Show:
© 2014 Microsoft