Visual Basic 2010 : Consuming WCF Data Services

Creating a Client Application

The goal of the next example is to show how you can perform read/insert/update/delete operations against a Data Service from a client. Follow these steps:

1.	Add to the current solution a new Console project and name it NorthwindClient.
2.	Right-click the project name and select Add Service Reference. This adds a reference to the Data Service similar to what happens for WCF services. Because in our example the service is available in the current solution, just click Discover. In real applications you will instead type the Uri of your service. Figure 1 shows how the Add Service Reference dialog appears now. Figure 1. Adding a reference to the ADO.NET Data Service.
3.	Replace the default identifier in the Namespace textbox with a more appropriate one, such as NorthwindServiceReference; then click OK.

At this point Visual Studio 2010 generates what in WCF is defined as a proxy class, which is client code. Basically it generates a number of classes: one class that inherits from System.Data.Services.Client.DataServiceContext and that can be considered as the Astoria counterpart for the Entity Framework’s ObjectContext and a series of counterpart classes for entities in the EDM. This means that, for our example, you have Customer, Order, and Order_Detail classes implemented on the client side. All these classes implement the INotifyPropertyChanged interface so that they can notify the UI of changes on the original data source. Instead the DataServiceContext class also exposes properties of type System.Data.Services.Client.DataServiceQuery(Of T) that are collections of the previously mentioned classes and that represent strongly typed queries against entity sets exposed by a Data Service. For example, the DataServiceContext class in our example (automatically named NorthwindEntities for consistency with the related context in the service) exposes the Customers, Orders, and Order_Details properties, respectively, of type DataServiceQuery(Of Customer), DataServiceQuery(Of Order), and DataServiceQuery(Of Order_Detail). Although you should never manually edit auto-generated code, if you are curious, you can inspect previously mentioned classes by expanding the NorthwindServiceReference item in Solution Explorer and clicking the Reference.vb file. This is the place where all the client code is implemented. You notice lots of similarities with an entity data model implementation, but do not become confused because WCF Data Services are a different thing. By the way, such similarities can help you understand how to perform data operations. For example, there are methods for adding objects (AddToCustomers, AddToOrders) and for removing objects (DeleteObject). For now, add the following Imports directives that allow shortening lines of code:

Imports NorthwindClient.NorthwindServiceReference
Imports System.Data.Services.Client

The next step is instantiating the proxy client class. At module level, add the following declaration:

Private northwind As New  _
        NorthwindEntities(New _
        Uri("http://localhost:1443/NorthwindService.svc"))

Notice how the instance requires you to specify the service Uri. This is the same that is specified when adding the service reference. The northwind variable represents the instance of the DataServiceContext class that exposes members for working against entities exposed by the Data Service and that allows performing CRUD operations. The first operation I am going to explain is insertion. Consider the following function:

Private Function AddNewOrder(ByVal relatedCustomer As Customer) As Order


    Dim newOrder As New Order
    With newOrder
        .Customer = relatedCustomer
        .OrderDate = Date.Today
        .ShipCountry = "Italy"
        .ShipCity = "Milan"
        .ShipName = "First"
    End With

    northwind.AddToOrders(newOrder)
    northwind.SetLink(newOrder, "Customer", relatedCustomer)
    northwind.SaveChanges()
    Return newOrder
End Function

The code first creates an instance of a new order and populates the desired properties. Notice how a relationship to the specified customer is also set. This relationship is just set in-memory, but it needs to be explicitly set when sending changes to the actual database.

The new order is added to the model via the AddToOrders method, whereas SetLink explicitly sets the relationship. The method requires the new object as the first argument, the navigation property in the model as the second argument, and the master object in the master-details relationship. Finally the code saves the new data to the database invoking SaveChanges. Later you see how to send to the data source changes in a batch. Performing an update operation is an easy task. You simply get the instance of the desired object and edit properties. The following snippet demonstrates how to update an existing order:

Private Sub UpdateOrder(ByVal OrderID As Integer)
    'Retrieving the one instance of the specified Order with
    'a lambda.
    Dim ord = northwind.Orders.Where(Function(o) o.OrderID = _
              OrderID).First

    ord.ShipName = "Second"
    ord.ShipCity = "Cremona"
    ord.ShipCountry = "Italy"
End Sub

The code shows how you simply get the instance of your object and replace properties. If you want to save changes at this point, invoke SaveChanges. We are not doing this now because we will save changes in the batch later.

The next step is implementing a deletion method. This is also a simple task, as demonstrated by the following code:

Private Sub DeleteOrder(ByVal OrderID As Integer)


    Dim ord = northwind.Orders.Where(Function(o) o.OrderID = _
              OrderID).First
    northwind.DeleteObject(ord)
End Sub

Also in this case you simply get the instance of the object you want to remove and then invoke the DeleteObject method. The last step is showing how you can save multiple changes to entities in one shot. The following code demonstrates this:

Private Sub SaveAllChanges()
    northwind.SaveChanges(Services.Client.SaveChangesOptions.Batch)
End Sub

SaveChanges receives an argument of type System.Data.Services.Client.aveChangesOptions, which is an enumeration whose most important value is Batch, which enables saving all pending changes with a single http request; thus it is efficient with regard to performances. Now we just need to invoke the various methods from within the Sub Main. The following code first creates a new order, updates it, and finally deletes it:

Sub Main()

    Dim cust = northwind.Customers.Where(Function(c) c.CustomerID = _
               "ALFKI").First

    Try
        Dim anOrder = AddNewOrder(cust)

        Console.WriteLine("Added new order: {0}", anOrder.OrderID)

        UpdateOrder(anOrder.OrderID)
        Console.WriteLine("Updated order {0}. ShipCity now is {1},
                          ShipName now is {2}",
                          anOrder.OrderID, anOrder.ShipCity,
                          anOrder.ShipName)

        'Replace the order ID with a valid one
        DeleteOrder(anOrder.OrderID)
        Console.WriteLine("Order deleted")

        SaveAllChanges()

        Console.ReadLine()
        northwind = Nothing

    Catch ex As DataServiceQueryException
        Console.WriteLine("The server returned the following error:")
        Console.WriteLine(ex.Response.Error.Message)
        Console.ReadLine()
    Catch ex As Exception

    End Try
End Sub

					  

The code also is ready for intercepting a DataServiceQueryException, a particular object that provides client information from DataServiceException objects thrown on the server side. If you now run the application, you get messages informing you about the data operations progress, as shown in Figure 2.

Figure 2. The sample application performs all operations.

Querying Data

One of the most common requirements of any data framework is the ability to perform queries. WCF Data Services allow two modes on the client side. The first one is utilizing query strings similarly to what it is possible to do with Uris. To accomplish this you invoke the Execute(Of T) method from the DataServiceContext class, where T is the type you want to retrieve a collection of. For example, the following code returns a collection of orders for the specified customer, sorted by order date:

Dim myOrders = Northwind.Execute(Of Order)(New _
               Uri("/Customers('ANATR')/Orders?orderby=OrderDate", _
               UriKind.Relative))

This way is efficient but avoids the strongly typed approach provided by LINQ. Fortunately the .NET Framework also enables using a special LINQ provider known as LINQ to Data Services. The following code snippet demonstrates how you can obtain the same result as previously by writing a LINQ query:

Dim myOrders = From ord In northwind.Orders
               Where ord.Customer.CustomerID = "ANATR"
               Select ord

Of course this is powerful but not necessarily the best choice. For example, you might want to prevent indiscriminate data access from clients, or you might simply want better performances implementing queries on the server side and exposing methods returning query results. This is where service operations take place.