Walkthrough: Adding Query Methods

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

This walkthrough describes how to add and customize methods in WCF RIA Services that query a data source. Such methods, which are referred to as query methods, must be defined with a signature that the framework recognizes as specifying a query method. The query methods satisfy this requirement by applying the QueryAttribute. The set of expected query signatures are divided into two broad categories: those queries that always return a single type of Entity and those queries that can, potentially, return more than one Entity of type T in an IEnumerable or an IQueryable. For more information about the permitted query method signatures, see Domain Services.

When you create a new domain service class and specify their entities in the Add New Domain Service Class dialog box, the RIA Services framework automatically creates a simple query method in this class for each entity exposed by the service. This query method simply retrieves all of the records for the entity. This walkthrough describes how to add new query methods that perform more complex scenarios such as filtering by a parameter value. This walkthrough shows how to add queries that return a single entity and also how to add queries that return a collection of entities.

This and the other walkthroughs presented in the 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.

This walkthrough assumes you have completed the procedures described in Walkthrough: Creating a RIA Services Solution and have the solution created there ready to modify in the procedures described here.

  1. Open the solution constructed in the Walkthrough: Creating a RIA Services Solution topic that exposes data from the Customer table.

  2. In the server project, open the CustomerDomainService domain service class that exposes data from the Customer table.

  3. Add a query method that accepts an integer parameter and returns the Customer entity with the matching customer ID.

    If a method that returns a single entity includes the QueryAttribute attribute, you must set the IsComposable property to false. Users cannot specify additional query operations from the client. If the query method matches the expected signature for a query, you do not have to apply the QueryAttribute attribute. The return value must be a single instance of an entity object.

  1. Open the domain service class that exposes data from the Customer table.

  2. In the CustomerDomainService domain service class, add a query method that accepts a string parameter and returns any customers whose last name starts with that letter.

    The method can return an IQueryable object because the user may want to provide additional query operation from the client.

  1. In the client project, open MainPage.xaml.

  2. Add two TextBox controls and two Button controls so that the user can filter customer records either by the ID or by the first letter of the last name.

    The following XAML shows a complete layout along with the existing DataGrid.

  3. Open the code-behind page for MainPage.xaml (MainPage.xaml.cs or MainPage.xaml.vb).

  4. Add code to retrieve query results based on the user input.

  5. Run (F5) the application.

    The following illustration shows a list of customers filtered by the last name that appears when the application is run.