Walkthrough: Adding Query Methods

Article
08/19/2013

[WCF RIA Services Version 1 Service Pack 2 is compatible with either .NET framework 4 or .NET Framework 4.5, and with either Silverlight 4 or Silverlight 5.]

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<T> or an IQueryable<T>. 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.

Prerequisites

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.

To add a query method that accepts a parameter and returns a single entity

Open the solution constructed in the Walkthrough: Creating a RIA Services Solution topic that exposes data from the Customer table.
In the server project, open the CustomerDomainService domain service class that exposes data from the Customer table.
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.
```
<Query(IsComposable:=False)>
Public Function GetCustomersByID(ByVal customerID As Integer) As Customer
    Return Me.ObjectContext.Customers.Single(Function(c) c.CustomerID = customerID)
End Function
```
```
[Query(IsComposable=false)]
public Customer GetCustomersByID(int customerID)
{
    return this.ObjectContext.Customers.Single(c => c.CustomerID == customerID);
}
```

To add a query method that accepts a parameter and returns a collection of entities

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

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<T> object because the user may want to provide additional query operation from the client.

Public Function GetCustomersByLastNameLetter(ByVal startingLastNameLetter As String) As IQueryable(Of Customer)
    Return Me.ObjectContext.Customers.Where(Function(c) c.LastName.StartsWith(startingLastNameLetter) = True)
End Function

public IQueryable<Customer> GetCustomersByLastNameLetter(string startingLastNameLetter)
{
    return this.ObjectContext.Customers.Where(c => c.LastName.StartsWith(startingLastNameLetter) == true);
}

To display the results of those query methods in the client project.

In the client project, open MainPage.xaml.

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.

<UserControl xmlns:my="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls.Data"  x:Class="RIAServicesExample.MainPage"
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="https://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="https://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    d:DesignHeight="300" d:DesignWidth="400">

    <Grid x:Name="LayoutRoot" Background="White">
        <Grid.ColumnDefinitions>
            <ColumnDefinition></ColumnDefinition>
            <ColumnDefinition></ColumnDefinition>
        </Grid.ColumnDefinitions>
        <Grid.RowDefinitions>
            <RowDefinition Height="25"></RowDefinition>
            <RowDefinition></RowDefinition>
        </Grid.RowDefinitions>
        <StackPanel Orientation="Horizontal" Grid.Row="0" Grid.Column="0">
            <TextBlock Text="search by id: " ></TextBlock>
            <TextBox Name="IDValue" Width="50" ></TextBox>
            <Button Name="IDButton" Click="IDButton_Click" Content="Submit"></Button>
        </StackPanel>
        <StackPanel Orientation="Horizontal" Grid.Row="0" Grid.Column="1">
            <TextBlock Text="search by name: "></TextBlock>
            <TextBox Name="LetterValue" Width="30"></TextBox>
            <Button Name="LetterButton" Click="LetterButton_Click" Content="Submit"></Button>
        </StackPanel>

      <my:DataGrid Grid.Row="1" Grid.Column="0" Grid.ColumnSpan="2" Name="CustomerGrid"></my:DataGrid>
    </Grid>
</UserControl>

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

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

Partial Public Class MainPage
    Inherits UserControl
    Dim _customerContext As CustomerDomainContext

    Public Sub New()
        InitializeComponent()
    End Sub

    Private Sub LetterButton_Click(ByVal sender As System.Object, ByVal e As System.Windows.RoutedEventArgs)
        IDButton.IsEnabled = False
        LetterButton.IsEnabled = False
        Dim loadOp = Me._customerContext.Load(Me._customerContext.GetCustomersByLastNameLetterQuery(LetterValue.Text), AddressOf CustomerLoadedCallback, Nothing)
        CustomerGrid.ItemsSource = loadOp.Entities
    End Sub

    Private Sub IDButton_Click(ByVal sender As System.Object, ByVal e As System.Windows.RoutedEventArgs)
        IDButton.IsEnabled = False
        LetterButton.IsEnabled = False
        Dim loadOp = Me._customerContext.Load(Me._customerContext.GetCustomersByIDQuery(IDValue.Text), AddressOf CustomerLoadedCallback, Nothing)
        CustomerGrid.ItemsSource = loadOp.Entities
    End Sub

    Public Sub CustomerLoadedCallback(ByVal loadOperation As LoadOperation(Of Customer))
        IDButton.IsEnabled = True
        LetterButton.IsEnabled = True
    End Sub
End Class

public partial class MainPage : UserControl
{
    private CustomerDomainContext _customerContext = new CustomerDomainContext();

    public MainPage()
    {
        InitializeComponent();
    }

    private void LetterButton_Click(object sender, RoutedEventArgs e)
    {
        IDButton.IsEnabled = false;
        LetterButton.IsEnabled = false;
        LoadOperation<Customer> loadOp = this._customerContext.Load(this._customerContext.GetCustomersByLastNameLetterQuery(LetterValue.Text), CustomerLoadedCallback, null);
        CustomerGrid.ItemsSource = loadOp.Entities;
    }

    private void IDButton_Click(object sender, RoutedEventArgs e)
    {
        IDButton.IsEnabled = false;
        LetterButton.IsEnabled = false;
        LoadOperation<Customer> loadOp = this._customerContext.Load(this._customerContext.GetCustomersByIDQuery(int.Parse(IDValue.Text)), CustomerLoadedCallback, null);
        CustomerGrid.ItemsSource = loadOp.Entities;
    }

    void CustomerLoadedCallback(LoadOperation<Customer> loadOperation)
    {
        IDButton.IsEnabled = true;
        LetterButton.IsEnabled = true;
    }

}

Run (F5) the application.

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

Walkthrough: Adding Query Methods

Prerequisites

To add a query method that accepts a parameter and returns a single entity

To add a query method that accepts a parameter and returns a collection of entities

To display the results of those query methods in the client project.

Additional resources