Export (0) Print
Expand All

Calling Service Operations (WCF Data Services)

The Open Data Protocol (OData) defines service operations for a data service. WCF Data Services enables you to define such operations as methods on the data service. Like other data service resources, these service operations are addressed by using URIs. A service operation can return collections of entity types, single entity type instances, and primitive types, such as integer and string. A service operation can also return null (Nothing in Visual Basic). The WCF Data Services client library can be used to access service operations that support HTTP GET requests. These kinds of service operations are defined as methods that have the WebGetAttribute applied. For more information, see Service Operations (WCF Data Services).

Service operations are exposed in the metadata returned by a data service that implements the OData. In the metadata, service operations are represented as FunctionImport elements. When generating the strongly-typed DataServiceContext, the Add Service Reference and DataSvcUtil.exe tools ignore this element. Because of this, you will not find a method on the context that can be used to call a service operation directly. However, you can still use the WCF Data Services client to call service operations in one of these two ways:

The following considerations apply when using the WCF Data Services client to call service operations.

  • When accessing the data service asynchronously, you must use the equivalent asynchronous BeginExecute/EndExecute<TElement> methods on DataServiceContext or the BeginExecute/EndExecute methods on DataServiceQuery<TElement>.

  • The WCF Data Services client library cannot materialize the results from a service operation that returns a collection of primitive types.

  • The WCF Data Services client library does not support calling POST service operations. Service operations that are called by an HTTP POST are defined by using the WebInvokeAttribute with the Method="POST" parameter. To call a service operation by using an HTTP POST request, you must instead use an HttpWebRequest.

  • You cannot use CreateQuery<T> to call a GET service operation that returns a single result, of either entity or primitive type, or that requires more than one input parameter. You must instead call the Execute method.

  • Consider creating an extension method on the strongly-typed DataServiceContext partial class, which is generated by the tools, that uses either the CreateQuery<T> or the Execute method to call a service operation. This enables you to call service operations directly from the context. For more information, see the blog post Service Operations and the WCF Data Services Client.

  • When you use CreateQuery<T> to call a service operation, the client library automatically escapes characters supplied to the AddQueryOption by performing percent-encoding of reserved characters, such as ampersand (&), and escaping of single-quotes in strings. However, when you call one of the Execute methods to call a service operation, you must remember to perform this escaping of any user-supplied string values. Single-quotes in URIs are escaped as pairs of single-quotes.

This section contains the following examples of how to call service operations by using the WCF Data Services client library:

The following example calls a service operation named GetOrdersByCity, which takes a string parameter of city and returns an IQueryable<T>:

// Define the service operation query parameter. 
string city = "London";

// Define the query URI to access the service operation with specific  
// query options relative to the service URI. 
string queryString = string.Format("GetOrdersByCity?city='{0}'", city)
    + "&$orderby=ShippedDate desc"
    + "&$expand=Order_Details";

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

try
{
    // Execute the service operation that returns all orders for the specified city. 
    var results = context.Execute<Order>(new Uri(queryString, UriKind.Relative));

    // Write out order information. 
    foreach (Order o in results)
    {
        Console.WriteLine(string.Format("Order ID: {0}", o.OrderID));

        foreach (Order_Detail item in o.Order_Details)
        {
            Console.WriteLine(String.Format("\tItem: {0}, quantity: {1}",
                item.ProductID, item.Quantity));
        }
    }
}
catch (DataServiceQueryException ex)
{
    QueryOperationResponse response = ex.Response;

    Console.WriteLine(response.Error.Message);
}

In this example, the service operation returns a collection of Order objects with related Order_Detail objects.

The following example uses the CreateQuery<T> to return a DataServiceQuery<TElement> that is used to call the same GetOrdersByCity service operation:

// Define the service operation query parameter. 
string city = "London";

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

// Use the CreateQuery method to create a query that accessess 
// the service operation passing a single parameter.        
var query = context.CreateQuery<Order>("GetOrdersByCity")
    .AddQueryOption("city", string.Format("'{0}'", city))
    .Expand("Order_Details");

try
{
    // The query is executed during enumeration. 
    foreach (Order o in query)
    {
        Console.WriteLine(string.Format("Order ID: {0}", o.OrderID));

        foreach (Order_Detail item in o.Order_Details)
        {
            Console.WriteLine(String.Format("\tItem: {0}, quantity: {1}",
                item.ProductID, item.Quantity));
        }
    }
}
catch (DataServiceQueryException ex)
{
    QueryOperationResponse response = ex.Response;

    Console.WriteLine(response.Error.Message);
}

In this example, the AddQueryOption method is used to add the parameter to the query, and the Expand method is used to include related Order_Details objects in the results.

The following example calls a service operation named GetNewestOrder that returns only a single Order entity:

// Define the query URI to access the service operation,  
// relative to the service URI. 
string queryString = "GetNewestOrder";

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

try
{
    // Execute a service operation that returns only the newest single order.
    Order order
        = (context.Execute<Order>(new Uri(queryString, UriKind.Relative)))
        .FirstOrDefault();

    // Write out order information.
    Console.WriteLine(string.Format("Order ID: {0}", order.OrderID));
    Console.WriteLine(string.Format("Order date: {0}", order.OrderDate));
}
catch (DataServiceQueryException ex)
{
    QueryOperationResponse response = ex.Response;

    Console.WriteLine(response.Error.Message);
}

In this example, the FirstOrDefault method is used to request only a single Order entity on execution.

The following example calls a service operation that returns a collection of string values:

// Define the query URI to access the service operation,  
// relative to the service URI. 
string queryString = "GetCustomerNames";

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

try
{
    // Execute a service operation that returns only the newest single order.
    IEnumerable<string> customerNames
        = context.Execute<string>(new Uri(queryString, UriKind.Relative));

    foreach (string name in customerNames)
    {
        // Write out order information.
        Console.WriteLine(name);
    }
}
catch (DataServiceQueryException ex)
{
    QueryOperationResponse response = ex.Response;

    Console.WriteLine(response.Error.Message);
}

The following example calls a service operation that returns a single string value:

// Define the query URI to access the service operation,  
// relative to the service URI. 
string queryString = "CountOpenOrders";

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

try
{
    // Execute a service operation that returns the integer  
    // count of open orders. 
    int numOrders
        = (context.Execute<int>(new Uri(queryString, UriKind.Relative)))
        .FirstOrDefault();

    // Write out the number of open orders.
    Console.WriteLine(string.Format("Open orders as of {0}: {1}",
        DateTime.Today.Date, numOrders));
}
catch (DataServiceQueryException ex)
{
    QueryOperationResponse response = ex.Response;

    Console.WriteLine(response.Error.Message);
}

Again in this example, the FirstOrDefault method is used to request only a single integer value on execution.

The following example calls a service operation that returns no data:

// Define the query URI to access the service operation,  
// relative to the service URI. 
string queryString = "ReturnsNoData";

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

try
{
    // Execute a service operation that returns void.
    context.Execute<string>(new Uri(queryString, UriKind.Relative));
}
catch (DataServiceQueryException ex)
{
    QueryOperationResponse response = ex.Response;

    Console.WriteLine(response.Error.Message);
}

Because not data is returned, the value of the execution is not assigned. The only indication that the request has succeeded is that no DataServiceQueryException is raised.

The following example calls a service operation asynchronously by calling BeginExecute and EndExecute<TElement>:

// Define the service operation query parameter. 
string city = "London";

// Define the query URI to access the service operation with specific  
// query options relative to the service URI. 
string queryString = string.Format("GetOrdersByCity?city='{0}'", city)
    + "&$orderby=ShippedDate desc"
    + "&$expand=Order_Details";

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

// Execute the service operation that returns  
// all orders for the specified city. 
var results = context.BeginExecute<Order>(
    new Uri(queryString, UriKind.Relative),
    OnAsyncExecutionComplete, context);
private static void OnAsyncExecutionComplete(IAsyncResult result)
{
    // Get the context back from the stored state. 
    var context = result.AsyncState as NorthwindEntities;

    try
    {
        // Complete the exection and write out the results. 
        foreach (Order o in context.EndExecute<Order>(result))
        {
            Console.WriteLine(string.Format("Order ID: {0}", o.OrderID));

            foreach (Order_Detail item in o.Order_Details)
            {
                Console.WriteLine(String.Format("\tItem: {0}, quantity: {1}",
                    item.ProductID, item.Quantity));
            }
        }
    }
    catch (DataServiceQueryException ex)
    {
        QueryOperationResponse response = ex.Response;

        Console.WriteLine(response.Error.Message);
    }
}

Because no data is returned, the value returned by the execution is not assigned. The only indication that the request has succeeded is that no DataServiceQueryException is raised.

The following example calls the same service operation asynchronously by using CreateQuery<T>:

// Define the service operation query parameter. 
string city = "London";

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

// Use the CreateQuery method to create a query that accessess 
// the service operation passing a single parameter.        
var query = context.CreateQuery<Order>("GetOrdersByCity")
    .AddQueryOption("city", string.Format("'{0}'", city))
    .Expand("Order_Details");

// Execute the service operation that returns  
// all orders for the specified city. 
var results = 
    query.BeginExecute(OnAsyncQueryExecutionComplete, query);
private static void OnAsyncQueryExecutionComplete(IAsyncResult result)
{
    // Get the query back from the stored state. 
    var query = result.AsyncState as DataServiceQuery<Order>;

    try
    {
        // Complete the exection and write out the results. 
        foreach (Order o in query.EndExecute(result))
        {
            Console.WriteLine(string.Format("Order ID: {0}", o.OrderID));

            foreach (Order_Detail item in o.Order_Details)
            {
                Console.WriteLine(String.Format("\tItem: {0}, quantity: {1}",
                    item.ProductID, item.Quantity));
            }
        }
    }
    catch (DataServiceQueryException ex)
    {
        QueryOperationResponse response = ex.Response;

        Console.WriteLine(response.Error.Message);
    }
}
Show:
© 2014 Microsoft