调用服务操作和动作 (WCF Data Services)

2013-10-24

开放式数据协议 (OData) 定义数据服务的服务操作与服务动作。与其他数据服务资源一样，服务操作和服务动作也通过使用 URI 进行寻址。服务操作和动作可返回实体类型集合、单个实体类型实例、基元类型（如整数和字符串）以及 null（Visual Basic 中为 Nothing）。与服务操作不同的是，服务动作可与数据模型资源绑定，并且必须通过 HTTP POST 请求来调用，因为它们对系统有副作用。有关更多信息，请参见服务操作（WCF 数据服务）和使用 OData 动作实现服务器端行为。

服务操作和服务动作都在由实现 OData 的数据服务所返回的元数据中进行公开。在该元数据中，服务操作和动作都表示为 FunctionImport 元素。在生成强类型 DataServiceContext 时，“添加服务引用”和 DataSvcUtil.exe 工具将忽略此元素。因此，无法在上下文中找到一种方法用来直接调用服务操作。不过，您仍可使用 WCF 数据服务客户端并通过以下两种方式之一来调用服务操作：

通过对 DataServiceContext 调用 Execute<TElement>(Uri) 方法，提供服务操作的 URI。建议使用此方法来调用所有服务操作和服务动作。对于通过 HTTP POST 请求调用的服务动作或服务操作，请调用取用 httpMethod 的 Execute<TElement>(Uri, String, Boolean, array<OperationParameter[]) 方法重载并提供 POST 值。还可通过在调用此方法时将参数值的 OperationParameter 集合传递给 operationParameters，在执行期间提供一个或多个参数。在调用服务动作时，只能通过这种方式提供非绑定参数。
通过对 DataServiceContext 使用 CreateQuery<T>(String) 方法来创建 DataServiceQuery<TElement> 对象。在调用 CreateQuery<T>(String) 时，该服务操作的名称将提供给 entitySetName 参数。此方法返回一个 DataServiceQuery<TElement> 对象，该对象在枚举时或在调用 Execute() 方法时调用该服务操作。此方法用于调用返回集合的 GET 服务操作。可通过使用 AddQueryOption(String, Object) 方法来提供单个参数。可以进一步编辑此方法返回的 DataServiceQuery<TElement> 对象，就像对待任何查询对象一样。有关更多信息，请参见查询数据服务（WCF 数据服务）。此方法不能用于调用服务动作。

调用服务操作和动作的注意事项

使用 WCF 数据服务客户端调用服务操作时的注意事项如下。

在异步访问数据服务时，必须使用同等异步 BeginExecute<TElement>(Uri, AsyncCallback, Object)/EndExecute<TElement>(IAsyncResult) 方法（针对 DataServiceContext）或 BeginExecute(AsyncCallback, Object)/EndExecute(IAsyncResult) 方法（针对 DataServiceQuery<TElement>）。
请考虑对强类型 DataServiceContext 分部类创建扩展方法，该分部类通过工具生成，使用 CreateQuery<T>(String) 或 Execute<TElement>(Uri) 方法来调用服务操作。这样您就可以直接从上下文调用服务操作。有关更多信息，请参阅博客文章 Service Operations and the WCF Data Services Client（服务操作和 WCF Data Services 客户端）。
使用 CreateQuery<T>(String) 调用服务操作时，客户端库会自动对提供给 AddQueryOption(String, Object) 的字符进行转义，方法是执行保留字符百分比编码（如“and”符 (&)），并转义字符串中的单引号。但是，在通过调用某个 Execute 方法来调用服务操作时，您必须记得对所有用户提供字符串值执行这种转义。 URI 中的单引号转义为单引号对。
与服务操作不同的是，服务动作不可进一步编辑。这意味着，在调用服务动作之后，不能再执行任何其他服务端查询操作。有关更多信息，请参见使用 OData 动作实现服务器端行为。

调用服务操作示例

本节通过以下示例演示如何使用 WCF 数据服务客户端库来调用服务操作：

调用 Execute<T> 以返回实体集合

下面的示例调用名为 GetOrdersByCity 的服务操作，该操作采用字符串参数 city，并返回 IQueryable<T>：

' Define the service operation query parameter.
Dim city As String = "London"

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

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

Try

    ' Execute the service operation that returns all orders for the specified city.
    Dim results = context.Execute(Of Order)(New Uri(queryString, UriKind.Relative))

    ' Write out order information.
    For Each o As Order In results
        Console.WriteLine(String.Format("Order ID: {0}", o.OrderID))
        For Each item As Order_Detail In o.Order_Details
            Console.WriteLine(String.Format(vbTab & "Item: {0}, quantity: {1}", _
                item.ProductID, item.Quantity))
        Next
    Next
Catch ex As DataServiceQueryException
    Dim response As QueryOperationResponse = ex.Response

    Console.WriteLine(response.Error.Message)
End Try

// 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);
}

在此示例中，该服务操作返回 Order 对象的集合，其中含有相关的 Order_Detail 对象。

使用 CreateQuery<T> 返回实体集合

下面的示例使用 CreateQuery<T>(String) 来返回用于调用同一 GetOrdersByCity 服务操作的 DataServiceQuery<TElement>：

' Define the service operation query parameter.
Dim city As String = "London"

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

' Use the CreateQuery method to create a query that accessess
' the service operation passing a single parameter.       
Dim query = context.CreateQuery(Of Order)("GetOrdersByCity") _
        .AddQueryOption("city", String.Format("'{0}'", city)).Expand("Order_Details")

Try
    ' The query is executed during enumeration.
    For Each o As Order In query
        Console.WriteLine(String.Format("Order ID: {0}", o.OrderID))
        For Each item As Order_Detail In o.Order_Details
            Console.WriteLine(String.Format(vbTab & "Item: {0}, quantity: {1}", _
                item.ProductID, item.Quantity))
        Next
    Next
Catch ex As DataServiceQueryException
    Dim response As QueryOperationResponse = ex.Response
    Console.WriteLine(response.Error.Message)
End Try

// 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);
}

在此示例中，AddQueryOption(String, Object) 方法用于向查询中添加参数，而 Expand(String) 方法用于在结果中包括相关 Order_Details 对象。

调用 Execute<T> 以返回单个实体

下面的示例调用名为 GetNewestOrder 的服务操作，该操作仅返回单个 Order 实体：

' Define the query URI to access the service operation, 
' relative to the service URI.
Dim queryString As String = "GetNewestOrder"

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

Try
    ' Execute a service operation that returns only the newest single order.
    Dim o As Order = _
        context.Execute(Of Order)( _
            New Uri(queryString, UriKind.Relative)).FirstOrDefault()

    ' Write out order information.
    Console.WriteLine(String.Format("Order ID: {0}", o.OrderID))
    Console.WriteLine(String.Format("Order date: {0}", o.OrderDate))
Catch ex As DataServiceQueryException
    Dim response As QueryOperationResponse = ex.Response

    Console.WriteLine(response.Error.Message)
End Try

// 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);
}

在此示例中，FirstOrDefault<TSource>(IEnumerable<TSource>) 方法用于在执行时仅请求单个 Order 实体。

调用 Execute<T> 以返回基元值集合

下面的示例调用返回字符串值集合的服务操作：

' Define the query URI to access the service operation, 
' relative to the service URI.
Dim queryString As String = "GetCustomerNames"

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

Try

    ' Execute a service operation that returns a collection of customer names.
    Dim customerNames As IEnumerable(Of String) _
        = context.Execute(Of String)(New Uri(queryString, UriKind.Relative))

    For Each name As String In customerNames
        ' Write out customer information.
        Console.WriteLine(name)
    Next

Catch ex As DataServiceQueryException
    Dim response As QueryOperationResponse = ex.Response

    Console.WriteLine(response.Error.Message)
End Try

// 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 a collection of customer names
    IEnumerable<string> customerNames
        = context.Execute<string>(new Uri(queryString, UriKind.Relative));

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

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

调用 Execute<T> 以返回单个基元值

下面的示例调用返回单个字符串值的服务操作：

' Define the query URI to access the service operation, 
' relative to the service URI.
Dim queryString As String = "CountOpenOrders"

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

Try
    ' Execute a service operation that returns the integer 
    ' count of open orders.
    Dim numOrders As Integer = context.Execute(Of Integer)( _
        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 ex As DataServiceQueryException
    Dim response As QueryOperationResponse = ex.Response

    Console.WriteLine(response.Error.Message)
End Try

// 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);
}

同样，在此示例中，FirstOrDefault<TSource>(IEnumerable<TSource>) 方法用于在执行时仅请求单个整数值。

调用不返回数据的服务操作

下面的示例调用不返回任何数据的服务操作：

' Define the query URI to access the service operation, 
' relative to the service URI.
Dim queryString As String = "ReturnsNoData"

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

Try
    ' Execute a service operation that returns void.
    context.Execute(Of String)( _
        New Uri(queryString, UriKind.Relative))
Catch ex As DataServiceQueryException
    Dim response As QueryOperationResponse = ex.Response

    Console.WriteLine(response.Error.Message)
End Try

// 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);
}

由于不返回数据，因此不分配执行的值。请求已成功的唯一指示是未引发 DataServiceQueryException。

异步调用服务操作

下面的示例通过调用 BeginExecute<TElement>(Uri, AsyncCallback, Object) 和 EndExecute<TElement>(IAsyncResult) 来异步调用服务操作：

' Define the service operation query parameter.
Dim city As String = "London"

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

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

' Define the delegate to callback into the process
Dim callback As AsyncCallback = AddressOf OnAsyncExecutionComplete

' Execute the service operation that returns 
' all orders for the specified city.
Dim results = context.BeginExecute(Of Order)( _
    New Uri(queryString, UriKind.Relative), _
    callback, context)

// 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 Shared Sub OnAsyncExecutionComplete(ByVal result As IAsyncResult)

    ' Get the context back from the stored state.
    Dim context = TryCast(result.AsyncState, NorthwindEntities)

    Try
        ' Complete the exection and write out the results.
        For Each o As Order In context.EndExecute(Of Order)(result)
            Console.WriteLine(String.Format("Order ID: {0}", o.OrderID))

            For Each item As Order_Detail In o.Order_Details
                Console.WriteLine(String.Format(vbTab & "Item: {0}, quantity: {1}", _
                    item.ProductID, item.Quantity))
            Next
        Next
    Catch ex As DataServiceQueryException
        Dim response As QueryOperationResponse = ex.Response
        Console.WriteLine(response.Error.Message)
    End Try
End Sub

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);
    }
}

由于不返回数据，因此不分配由该执行返回的值。请求已成功的唯一指示是未引发 DataServiceQueryException。

下面的示例通过使用 CreateQuery<T>(String) 来异步调用同一服务操作：

' Define the service operation query parameter.
Dim city As String = "London"

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

' Use the CreateQuery method to create a query that accessess
' the service operation passing a single parameter.       
Dim query = context.CreateQuery(Of Order)("GetOrdersByCity") _
            .AddQueryOption("city", String.Format("'{0}'", city)) _
            .Expand("Order_Details")

' Define the delegate to callback into the process
Dim callback As AsyncCallback = AddressOf OnAsyncQueryExecutionComplete

' Execute the service operation that returns 
' all orders for the specified city.
Dim results = _
    query.BeginExecute(callback, query)

// 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 Shared Sub OnAsyncQueryExecutionComplete(ByVal result As IAsyncResult)
    ' Get the query back from the stored state.
    Dim query = TryCast(result.AsyncState, DataServiceQuery(Of Order))

    Try
        ' Complete the exection and write out the results.
        For Each o As Order In query.EndExecute(result)

            Console.WriteLine(String.Format("Order ID: {0}", o.OrderID))

            For Each item As Order_Detail In o.Order_Details
                Console.WriteLine(String.Format(vbTab & "Item: {0}, quantity: {1}", _
                    item.ProductID, item.Quantity))
            Next
        Next
    Catch ex As DataServiceQueryException
        Dim response As QueryOperationResponse = ex.Response

        Console.WriteLine(response.Error.Message)
    End Try
End Sub

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);
    }
}

请参阅

其他资源

数据客户端 (WCF Data Services)