サービス操作およびサービスアクションの呼び出し (WCF Data Services)

Open Data Protocol (OData) は、データサービスのサービス操作とサービスアクションの両方を定義します。他のデータサービスリソースと同様に、サービス操作とサービスアクションは URI によってアドレス指定できます。サービス操作とサービスアクションの両方は、エンティティ型のコレクション、1 つのエンティティ型のインスタンス、プリミティブ型 (整数、文字列など)、および null (Visual Basic では Nothing) を返すことができます。サービス操作とは異なり、サービスアクションはデータモデルのリソースにバインドすることができ、システムに対する副作用があるので、HTTP POST 要求で呼び出す必要があります。詳細については、「サービス操作 (WCF Data Services)」および「OData アクションを使用してサーバー側の動作を実装する」を参照してください。

サービス操作とサービスアクションの両方は、OData を実装するデータサービスによって返されるメタデータに公開されます。メタデータ内では、どちらも FunctionImport 要素として表されます。厳密に型指定された DataServiceContext を生成するとき、この要素は "サービス参照の追加" と DataSvcUtil.exe ツールで無視されます。このため、サービス操作を直接呼び出すために使用できるコンテキストにはメソッドはありません。ただし、次のいずれかの方法を使用して、WCF Data Services クライアントでサービス操作を呼び出すことができます。

DataServiceContext の Execute<TElement>(Uri) メソッドを呼び出すことによって、サービス操作の URI を提供します。すべてのサービス操作およびサービスアクションを呼び出すために、この方法をお勧めします。 HTTP POST 要求を使用することによって呼び出されるサービスアクションまたはサービス操作については、httpMethod を受け取る Execute<TElement>(Uri, String, Boolean, array<OperationParameter[]) メソッドオーバーロードを呼び出し、POST の値を指定します。このメソッドを呼び出すときに、パラメーター値の OperationParameter コレクションを operationParameters に渡すことによって、実行時に 1 つ以上のパラメーターを指定することもできます。サービスアクションを呼び出す場合、この方法で指定できるのはバインドされないパラメーターのみです。
DataServiceContext の CreateQuery<T>(String) メソッドを使用して、DataServiceQuery<TElement> オブジェクトを作成します。 CreateQuery<T>(String) を呼び出すとき、サービス操作の名前が entitySetName パラメーターに渡されます。このメソッドは、列挙されたときまたは Execute() メソッドが呼び出されたときにサービス操作を呼び出す DataServiceQuery<TElement> オブジェクトを返します。このメソッドは、コレクションを返す GET サービス操作の呼び出しに使用されます。 1 つのパラメーターは、AddQueryOption(String, Object) メソッドを使用して指定することができます。このメソッドによって返される DataServiceQuery<TElement> オブジェクトは、クエリオブジェクトのようにさらに構成できます。詳細については、「データサービスのクエリ (WCF Data Services)」を参照してください。このメソッドは、サービスアクションの呼び出しには使用できません。

サービス操作およびサービスアクションの呼び出しに関する注意点

WCF Data Services クライアントを使用してサービス操作を呼び出す際は、次の点に注意してください。

データサービスに非同期にアクセスするときは、DataServiceContext の同等の非同期 BeginExecute<TElement>(Uri, AsyncCallback, Object)/EndExecute<TElement>(IAsyncResult) メソッドまたは DataServiceQuery<TElement> の BeginExecute(AsyncCallback, Object)/EndExecute(IAsyncResult) メソッドを使用する必要があります。
ツールによって生成される厳密に型指定された DataServiceContext 部分クラスで CreateQuery<T>(String) メソッドまたは Execute<TElement>(Uri) メソッドを使用してサービス操作を呼び出す拡張メソッドを作成することを検討してください。これにより、コンテキストから直接サービス操作を呼び出すことができます。詳細については、ブログの投稿「サービス操作および WCF Data Services クライアント」を参照してください。
CreateQuery<T>(String) を使用してサービス操作を呼び出す場合、クライアントライブラリは、アンパサンド (&) などの予約文字のパーセントエンコードを実行し、文字列内の単一引用符をエスケープして、AddQueryOption(String, Object) に入力された文字を自動的にエスケープします。ただし、いずれかの Execute メソッドを呼び出してサービス操作を呼び出す場合は、このユーザーが指定した任意の文字列値のエスケープを実行する必要があります。 URI 内の単一引用符は、単一引用符のペアとしてエスケープされます。
サービス操作とは異なり、サービスアクションをそれ以上構成することはできません。これは、サービスアクションを呼び出した後は、サービス側のクエリ操作を追加で実行できないことを意味します。詳細については、「OData アクションを使用してサーバー側の動作を実装する」を参照してください。

サービス操作の呼び出しの例

このセクションには、WCF Data Services クライアントライブラリを使用してサービス操作を呼び出す方法を示す次の例が含まれています。

Execute<T> を呼び出してエンティティのコレクションを返す

次の例では、文字列パラメーター city を受け取り、IQueryable<T> を返す、GetOrdersByCity という名前のサービス操作を呼び出します。

' 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> を呼び出して単一のエンティティを返す

次の例では、単一の Order エンティティのみを返す、GetNewestOrder という名前のサービス操作を呼び出します。

' 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)

サービス操作およびサービス アクションの呼び出しに関する注意点