Visual Basic 2010 : Implementing and Consuming WCF Data Services - Implementing Service Operations

Service operations are .NET methods that can perform data operations on the server side. With service operations developers can preventively establish access rules and customize the business logic, such as data validation or access restrictions. They are basically WCF extensions for Data Services and perform operations via Http requests, meaning that you can execute service operations within a web browser or from a client application. Service operations can return the following types:

• IQueryable(Of T) in data-centric scenarios with EDMs or LINQ-to-SQL models

• IEnumerable(Of T)

• .NET primitive types, because Data Services can also expose in-memory collections

• No type (Sub methods)

Service operations can be used for both reading and writing data to the service. In a reading situation, service operations are Function methods marked with the WebGet attribute, whereas in writing situations they are decorated with the WebInvoke attribute. The next example explains how to read order details for the specified order and return fetched data to the client. First, add the following method to the NorthwindService class:

<WebGet()> Public Function GetOrderDetails(ByVal OrderID As Integer) _
                  As IQueryable(Of Order_Detail)

    If OrderID > 0 Then
        Dim query = From det In Me.CurrentDataSource.Order_Details
                    Where det.OrderID = OrderID
                    Select det

        Return query
    Else
        Throw New DataServiceException(400,
                                       "OrderID is not valid")
    End If
End Function

The method explanation is quite simple. It performs a simple validation on the OrderID argument; if valid, it executes a LINQ to Data Services query for getting related order details returning an IQueryable(Of Order_Detail) type. Notice the CurrentDataSource object, which represents the instance of the NorthwindEntities class on the server side. If the OrderID is considered invalid, the method throws a DataServiceException, which is specific for throwing errors from the service. You can specify an Http error code and an error message. To make a service operation recognizable and executable, you need to set permissions for it. This is accomplished by invoking the DataServiceConfiguration.SetServiceOperationAccessRule method; therefore, uncomment the following line of code in the InitializeService method:

'config.SetServiceOperationAccessRule _
("MyServiceOperation", ServiceOperationRights.AllRead)

Then you need to replace the operation name as follows:

config.SetServiceOperationAccessRule("GetOrderDetails",
                                ServiceOperationRights.AllRead)

In our scenario we just need to read data from the service, so the AllRead permission is appropriate. If you now run the service, you can type the following line in the browser address bar to invoke the service operation, making sure to type the appropriate port number of the development server on your machine:

http://localhost:1443/NorthwindService.svc/GetOrderDetails?OrderID=10250

Basically you invoke the operation writing its name after the service address. Notice that operations’ names and parameters are case-sensitive. At this point you are ready for calling the service operation from the client application. Return to the NorthwindClient project, and add the following method that invokes the service operations for fetching order details:

Private Sub ViewDetails(ByVal OrderID As Integer)
    Console.WriteLine("Showing details for Order ID: " _
                      & OrderID.ToString)

    Dim details = northwind.Execute(Of Order_Detail) _
                  (New Uri("GetOrderDetails?OrderID=" & _
                   OrderID.ToString,
                   UriKind.Relative))

    For Each detail In details
        Console.WriteLine("ID: {0}, Unit price: {1}, Quantity: {2}",
                          detail.OrderID,
                          detail.UnitPrice,
                          detail.Quantity)
    Next
    Console.ReadLine()
End Sub

The code is still quite simple. It invokes the service operation building a query string concatenating the supplied order ID. Notice how the Execute(Of Order_Detail) method is invoked because the service operations return a collection of the same type. The method requires you to specify the Uri of the service operation, which in this case is its name followed by the order Id. Before you run the application, you need to update the service reference. This step can be performed later in this case, because you do not invoke a managed method, whereas you invoke a service operation via a query string. To update the service reference, in Solution Explorer, just right-click the NorthwindServiceReference item and select Update Service Reference. Updating the service reference is something that you must do each time you perform changes on the service after a reference has been already added in the client application. If you now run the application, you get details for the specified order, as shown in Figure 1.

Figure 1. Getting order details via a service operation.

If you want to perform insertions, updates, or deletions, you can implement web invokes on the server side. This is accomplished by decorating methods with the WebInvoke attribute. The MSDN documentation provides examples on WebInvoke at this address.