Запросы к службе данных (службы WCF Data Services)

  • Статья

Клиентская библиотека служб Службы WCF Data Services позволяет выполнять запросы службы данных, используя знакомые шаблоны программирования .NET Framework, включая использование языка LINQ. Клиентская библиотека преобразует запрос, определенный на клиенте как экземпляр класса DataServiceQuery, в сообщение запроса HTTP GET. Библиотека получает ответное сообщение и преобразует его в экземпляры классов клиентской службы данных. Эти классы отслеживаются экземпляром DataServiceContext, которому принадлежит объект DataServiceQuery.

Запросы к службе данных

Универсальный класс DataServiceQuery представляет запрос, который возвращает коллекцию, включающую ноль или больше экземпляров типа сущности. Запрос к службе данных всегда относится к контексту существующей службы данных. Этот контекст поддерживает URI службы и сведения о метаданных, необходимые для создания и выполнения запроса.

Если используется диалоговое окно Добавление ссылки на службу, чтобы добавить службу данных в клиентское приложение на основе .NET Framework, создается класс контейнера сущностей, который наследует от DataServiceContext. Этот класс включает свойства, возвращаемые типизированными экземплярами DataServiceQuery. Для каждого набора сущностей, предоставляемого службой данных, имеется одно свойство. Эти свойства облегчают создание экземпляра типизированного объекта DataServiceQuery.

Запрос выполняется в следующих сценариях.

  • Если результаты перечислены неявно, например:

    • Если свойство DataServiceContext, которое представляет набор сущностей, перечисляется, например во время цикла foreach (C#) или For Each (Visual Basic).

    • Если запрос назначен коллекции List.

  • Если метод Execute или BeginExecute вызывается явно.

  • При вызове оператора выполнения запроса LINQ, такого как First или Single.

Следующий запрос, если он выполняется, возвращает все сущности Customers в службе данных Northwind:

' Define a new query for Customers.
Dim query As DataServiceQuery(Of Customer) = context.Customers

// Define a new query for Customers.
DataServiceQuery<Customer> query = context.Customers;

Дополнительные сведения см. в разделе Как выполнять запросы к службе данных (службы WCF Data Services).

Запросы LINQ

Поскольку класс DataServiceQuery реализует интерфейс IQueryable, определяемый языком LINQ, клиентская библиотека Службы WCF Data Services может преобразовывать запросы LINQ к данным набора сущностей в URI, который представляет выражение запроса, вычисляемое для ресурса службы данных. В следующем примере показан запрос LINQ, эквивалентный предыдущему объекту DataServiceQuery, который возвращает объект Orders со стоимостью транспортировки более 30 долларов и упорядочивает результаты по стоимости транспортировки.

Dim selectedOrders = From o In context.Orders _
        Where (o.Freight > 30) _
        Order By o.ShippedDate Descending _
        Select o

var selectedOrders = from o in context.Orders
                     where o.Freight > 30
                     orderby o.ShippedDate descending 
                     select o;

Этот запрос LINQ преобразуется в следующий URI запроса, который выполняется для основанной на Northwind службы данных quickstart:

https://localhost:12345/Northwind.svc/Orders?Orderby=ShippedDate&?filter=Freight gt 30
Dd673933.note(ru-ru,VS.100).gifПримечание
Набор запросов, которые можно выразить в синтаксисе LINQ, шире, чем набор запросов, поддерживаемых в URI-синтаксисе на основе технологии REST, который используется в службах данных.Исключение NotSupportedException возникает, если запрос не может быть сопоставлен с URI в целевой службе данных.

Добавление параметров запроса

Запросы службы данных поддерживают все параметры запроса, которые предоставляют службы Службы WCF Data Services . Метод AddQueryOption вызывается для присоединения параметров запроса к экземпляру DataServiceQuery. AddQueryOption возвращает новый экземпляр DataServiceQuery, эквивалентный исходному запросу, но с новым набором параметров запроса. Следующий запрос, если он выполняется, возвращает объект Orders, отфильтрованный по значению Freight и упорядоченный по OrderID по убыванию.

' Define a query for orders with a Freight value greater than 30
' and that is ordered by the ship date, descending.
Dim selectedOrders As DataServiceQuery(Of Order) = context.Orders _
.AddQueryOption("$filter", "Freight gt 30") _
.AddQueryOption("$orderby", "OrderID desc")

// Define a query for orders with a Freight value greater than 30
// and that is ordered by the ship date, descending.
DataServiceQuery<Order> selectedOrders = context.Orders
    .AddQueryOption("$filter", "Freight gt 30")
    .AddQueryOption("$orderby", "OrderID desc");

Параметр запроса $orderby можно использовать как для упорядочения, так и для фильтрации запроса, основанного на одном свойстве, как в следующем примере, в котором фильтруются и упорядочиваются возвращаемые объекты Orders, основанные на значении свойства Freight:

' Create the DataServiceContext using the service URI.
Dim context = New NorthwindEntities(svcUri)

' Define a query for orders with a Freight value greater than 30
' that also orders the result by the Freight value, descending.
Dim selectedOrders As DataServiceQuery(Of Order) = _
context.Orders.AddQueryOption("$orderby", "Freight gt 30 desc")

Try
    ' Enumerate over the results of the query.
    For Each order As Order In selectedOrders
        Console.WriteLine("Order ID: {0} - Freight: {1}", _
                order.OrderID, order.Freight)
    Next
Catch ex As DataServiceQueryException
    Throw New ApplicationException( _
            "An error occurred during query execution.", ex)
End Try

// Create the DataServiceContext using the service URI.
NorthwindEntities context = new NorthwindEntities(svcUri);

// Define a query for orders with a Freight value greater than 30
// that also orders the result by the Freight value, descending.
DataServiceQuery<Order> selectedOrders = context.Orders
    .AddQueryOption("$orderby", "Freight gt 30 desc");

try
{
    // Enumerate over the results of the query.
    foreach (Order order in selectedOrders)
    {
        Console.WriteLine("Order ID: {0} - Freight: {1}",
            order.OrderID, order.Freight);
    }
}
catch (DataServiceQueryException ex)
{
    throw new ApplicationException(
        "An error occurred during query execution.", ex);
}

Можно последовательно вызывать метод AddQueryOption, чтобы сконструировать сложные выражения запроса. Дополнительные сведения см. в разделе Как добавить параметры запроса к запросу службы данных (службы WCF Data Services).

Параметры запроса предоставляют другой способ выражения синтаксических компонентов запроса LINQ. Дополнительные сведения см. в разделе LINQ Query Syntax versus Method Syntax (C#).

Ответы на запросы

При выполнении запроса DataServiceQuery он возвращает объект IEnumerable запрошенного типа сущности. Этот результат запроса может быть приведен к объекту QueryOperationResponse, как в следующем примере:

' Execute the query for all customers and get the response object.
Dim response As QueryOperationResponse(Of Customer) = _
    CType(query.Execute(), QueryOperationResponse(Of Customer))

// Execute the query for all customers and get the response object.
QueryOperationResponse<Customer> response = 
    query.Execute() as QueryOperationResponse<Customer>;

Экземпляры типа сущности, которые представляют сущности в службе данных, создаются на клиенте процессом, называемым материализацией объектов. Дополнительные сведения см. в разделе Материализация объектов (службы WCF Data Services). Объект QueryOperationResponse реализует объект IEnumerable для предоставления доступа к результатам запроса. Объект QueryOperationResponse имеет также следующие члены, позволяющие производить доступ к дополнительным сведениям о результате запроса.

  • Error — возвращает ошибку, инициируемую операцией, если ошибка возникает.

  • Headers — содержит коллекцию заголовков ответов HTTP, связанных с ответом на запрос.

  • Query — возвращает исходный объект DataServiceQuery, создавший ответ QueryOperationResponse.

  • StatusCode — возвращает код ответа HTTP для ответа на запрос.

  • TotalCount — возвращает общее число сущностей в наборе сущностей, если метод IncludeTotalCount вызван на клиенте DataServiceQuery.

  • GetContinuation — возвращает объект DataServiceQueryContinuation, который содержит URI следующей страницы результатов.

По умолчанию службы Службы WCF Data Services возвращают только данные, явно выбранные URI запроса. Это дает возможность явно загрузить дополнительные данные из службы данных, если это необходимо. Запрос отправляется в службу данных при каждой явной загрузке данных из службы данных. Данные, которые можно явно загрузить, включают связанные сущности, разбитые на страницы данные ответа и потоки двоичных данных.

Dd673933.note(ru-ru,VS.100).gifПримечание
Поскольку служба данных может возвратить разбитый на страницы ответ, рекомендуется, чтобы приложение использовало шаблон программирования для обработки разбитого на страницы ответа службы данных.Дополнительные сведения см. в разделе Загрузка отложенного содержимого (службы WCF Data Services).

Объем возвращаемых запросом данных может быть также уменьшен указанием, что в ответе возвращаются только определенные свойства сущности. Дополнительные сведения см. в разделе Проекции запросов (службы WCF Data Services).

Получение подсчета общего числа сущностей в наборе

В некоторых сценариях полезно знать общее число сущностей в наборе сущностей, а не только число, возвращаемое запросом. Вызовите метод IncludeTotalCount на объекте DataServiceQuery для запроса, чтобы этот общий подсчет сущностей в наборе возвращался с результатом запроса. В этом случае свойство TotalCount возвращаемого объекта QueryOperationResponse возвращает общее число сущностей в наборе.

Можно также получить только общее число сущностей в наборе либо как значение типа Int32, либо как значение типа Int64, вызвав метод Count или LongCount соответственно. Если вызываются эти методы, объект QueryOperationResponse не возвращается, при этом возвращается только значение подсчета. Дополнительные сведения см. в разделе Как определить количество сущностей, возвращенных запросом (службы WCF Data Services).

В этом разделе

Проекции запросов (службы WCF Data Services)

Материализация объектов (службы WCF Data Services)

Как выполнять запросы к службе данных (службы WCF Data Services)

Как добавить параметры запроса к запросу службы данных (службы WCF Data Services)

Как определить количество сущностей, возвращенных запросом (службы WCF Data Services)

Как проецировать результаты запроса (службы WCF Data Services)

См. также

Другие ресурсы

Клиентская библиотека служб WCF Data Services