Beth Massi - Sharing the goodness that is VB : ADO.NET Data Services

Interop Between VBA and Visual Studio Office Solutions (VSTO)

Beth Massi — Fri, 06 Nov 2009 05:03:46 GMT

Couple weeks ago when I was in Holland speaking at SDC an attendee asked me how he could call methods in an Office solution (VSTO) from VBA functions defined in a document and vice versa. I thought I’d follow up with a post on how to do this, but first a little background on why this architecture would make sense.

There are many reasons why you would build an Office solution using Visual Studio (VSTO) as opposed to a pure VBA solution. Andri Yadi, VSTO MVP, wrote a great piece on his blog a while back explaining the benefits of VSTO compared to VBA. He broke it down into 10 areas, of which the main benefits are the tools and designers you have available in Visual Studio as well as the entire .NET framework and modern languages at your disposal.

However, there are probably many VBA assets that people in your company have already written, like complex algorithms or other business logic that you really don’t want to rewrite. Or maybe you still want to allow users to customize these functions in the VBA editor but it’s necessary for you to call them from your .NET code.

Likewise, you may want to develop a customization that takes advantage of WCF services or a WPF UI, modern language features, or any other feature of the .NET framework that would be difficult or impossible to do in VBA, and you want the user to be able to access these methods from their VBA functions. The attendee at SDC didn’t go into much detail on what his Office customization was doing exactly but he wanted to make some of his public methods available to his VBA users and this makes sense in a lot of situations. Luckily Visual Studio makes this very easy to do.

Creating an Excel Document Customization

For this example I’ll create an Excel document customization that accesses data through a WCF service and does some calculations on that data. The calculations, however, will be in VBA. To access the remote data over the internet I’ll create an ADO.NET Data Service. I want to pull up data in a Northwind view called Sales Totals By Amount. I’ve shown how to create an ADO.NET Data Service many times before so I won’t go into too much detail here. Please refer to the steps shown in the Using ADO.NET Data Services article. The only difference in this case is I selected the View Sales Totals By Amount into my Entity Framework model when I performed that step.

I have an Excel macro-enabled workbook that already has a simple VBA function that Sums all the columns below the first row. The function is sitting in a module called MyFunctions.

To create the new Excel workbook customization I’m going to add a new project to my solution and select Office 2007 Excel Workbook. Next it will ask if you want to create a new document or use an existing one, here’s where I’ll specify the macro-enabled workbook I already have above.

Next Add a Service Reference to the ADO.NET Data Service (which I called NorthwindReportService) just like I showed here and copy the URI into your clipboard. Then create a setting to store the URI, just double-click on My Project (Properties in C#) and select the Settings tab and enter an application scope property called ServiceURI.

When you add the service reference this generates client-side proxy types that you can use. I’m going to bind the data returned from Sales_Totals_by_Amount to an Excel ListObject. Open the Data Source window (Data –> Show Data Sources) and then add a new data source (Data –> Add New Data Source…). In the Data Source Connection Wizard select Object, then Next, then expand the types in your project’s NorthwindReportService namespace. Select Sales_Totals_by_Amount and then click Finish and you will see the type’s properties appear in the Data Sources Window:

Double-click on Sheet1 in the project and drag the Sales_Totals_by_Amount from the Data Sources window onto the second row of the sheet (our macro is going to sum into the first row so we want to place the data starting on the second row). This will automatically set up a BindingSource in the system tray that we will use to set our list of data coming from the service. If you are familiar with Winforms development this should seem very familiar. The ListObject is the main data object you work with in Excel solutions. For this example I’m going to select the OrderId column, right-click and then Delete. I’ll do the same to the ShippedDate column because I only want to display the CompanyName and SaleAmount for this example. Finally I’ll set the formatting (Home Tab on the Excel Designer) to Currency for the first cell.

Now we’re ready to write some code to load our data. Right-click on ThisWorkbook and select View Code. Here I’m going to create a Friend ReadOnly Property so we can easily access the service reference from anywhere in the project. I’m making this Friend so that it won’t be visible outside of the .NET assembly. I’m also creating a Public method that gets the data from our service and optionally accepts a Company Name. The results are then set to the DataSource of the ListObject’s BindingSource on Sheet1:

Imports VBATest.NorthwindReportService

Public Class ThisWorkbook

    Private _ReportService As New NorthwindEntities(New Uri(My.Settings.ServiceURI))
    Friend ReadOnly Property ReportService() As NorthwindEntities
        Get
            Return _ReportService
        End Get
    End Property

    Public Sub GetData(Optional ByVal companyName = "")
        Try
            If Globals.Sheet1 IsNot Nothing Then

                Dim results As IEnumerable(Of Sales_Totals_by_Amount)

                If companyName = "" Then
                    results = Me.ReportService.Sales_Totals_by_Amount
                Else
                    results = From s In Me.ReportService.Sales_Totals_by_Amount _
                              Where s.CompanyName.StartsWith(companyName)
                End If

                Globals.Sheet1.Sales_Totals_by_AmountBindingSource.DataSource = results.ToList()
            End If
        Catch ex As Exception
            'TODO: Error Handling
            MsgBox(ex.ToString())
        End Try
    End Sub

    Private Sub ThisWorkbook_Startup() Handles Me.Startup

    End Sub

    Private Sub ThisWorkbook_Shutdown() Handles Me.Shutdown

    End Sub

End Class

Calling VBA from VSTO

Next I want to create a button on the ribbon that will first call the GetData method, then select the first cell in Sheet1, and finally call the VBA function SumBelow. In order to call a VBA method from VSTO you call Globals.ThisWorkbook.Application.Run passing it the full name to the VBA method. For this example that would be VBATest.xlsm!MyFunctions.SumBelow.

Add a New Item to the project and select Office, Ribbon (Visual Designer) and then drag a Button from the Office Ribbon Controls to the Group and Label it “Get Data”. I also specified an OfficeImageId to make it look pretty. (BTW, a nice way to browse the Office Images is to install the VSTO Power Tools and install the RibbonID Add-in like Ty shows in this video.)

Double-click on the Get Data button to add a click event handler and we’ll write the following code to load all the data and then call the VBA function. You need to make sure you set up proper error handling here because if the VBA function is removed or renamed the code here will fail. This code will also fail if the appropriate access is not granted to VBA macros in Excel. By default, VBA macros are not enabled but you can enable them on a per workbook basis (there’s a button at the top of the first sheet when you run it). This scenario assumes you have existing VBA code that has permission to run and you’re now calling those existing functions from VSTO.

Imports VBATest.NorthwindReportService
Imports Microsoft.Office.Tools.Ribbon

Public Class Ribbon1

    Private Sub Button1_Click() Handles Button1.Click
        'load the data from the service
        Globals.ThisWorkbook.GetData()
        Try
            'Make sure the first cell is selected
            Globals.Sheet1.Range("A1").Select()
            'Run the VBA function. This will result in a runtime error if the function 
            ' is removed or renamed or not allowed to run so make sure to provide 
            ' adequate error handling.             
            Globals.ThisWorkbook.Application.Run("VBATest.xlsm!MyFunctions.SumBelow")
        Catch ex As Exception
            'Todo: Error handling
            MsgBox(ex.ToString())
        End Try
    End Sub
End Class

Hit F5 to run. If you see a Security Warning (the default) that Macros are disabled, then just click Options and select “Enable this content”. Select the Add-Ins tab on the Ribbon and click the GetData button to see the data get loaded from the service and then the SumBelow VBA function will be called which will auto-sum the SaleAmount field and show the total in the first row.

Calling VSTO methods from VBA

As you can see it’s really easy to call VBA code from your Office solution in Visual Studio (VSTO) but it’s also fragile because of the late-bound architecture and the requirement that macros be enabled for the Workbook. Like all late-bound code, you need to have adequate error handling to prevent crashes. Much less fragile is calling VSTO methods from VBA functions because these methods are compiled into your .NET assembly and exposed via COM-interop which makes them available to VBA.

If we go back to our project and double-click on ThisWorkbook and look in the Properties window, you should see a property called EnableVbaCallers. Setting that Property to True will expose all Public methods in the ThisWorkbook class via COM to VBA.

If you now go back into the code-behind for ThisWorkbook you will see some COM attributes added to the class:

<Microsoft.VisualBasic.ComClassAttribute()> _
<System.Runtime.InteropServices.ComVisibleAttribute(True)> _
Public Class ThisWorkbook
...

Now we can call the GetData method from VBA code. Hit F5 to run and enable the macros (if asked) on the Workbook again. Select the Developer tab and launch the Visual Basic editor. (If you don’t see a developer tab click the Office icon – the globe in the left-hand corner – select Excel Options, and then on the Popular tab check the “Show Developer tab in the Ribbon”.)

Double-click on the ThisWorkbook and you will see that Visual Studio added a property to our VBA code for us called CallVSTOAssembly. This allows us to call any public method we defined in the ThisWorkbook class back in Visual Studio. Let’s add another function to the MyFunctions module that collects input from the user on the company name to look up and then fetches the data by calling the GetData method in .NET.

Save your code here and close the VBA Editor. Now back on the Developer tab on the Ribbon select Macros and then you should see the one we just wrote called GetDataAndSumBelow, select it and click Run. It will prompt for a company name (just type ‘S’ for instance) and it will run the ADO.NET Data Service query via the call to the .NET GetData method and then will return and call the SumBelow VBA function. Cool!

BUT WAIT… DON’T CLOSE EXCEL YET!

Tips Editing VBA Code when Debugging

Because we wrote the second VBA function above while we were in debug mode in Visual Studio once we close Excel we will lose all the VBA code we wrote when we debug again. Because of the way Visual Studio works with Office solutions, we aren’t actually editing the xlsm file in the project, we’re editing the running xlsm file in the \bin directory that has the VSTO solution attached. You cannot just copy this one in the \bin folder back into the project otherwise Visual Studio will report an error that a customization is already attached to the document when you compile again. So what do we do?

There’s probably other ways to do this but what I found the easiest was to open the Visual Basic editor again, select the MyFunctions module where all my code is stored and then right-click and select “Export File”. This will allow you to save the code outside the Workbook. Then when you debug again you can just import it by right-clicking again (delete the current one first).

When you’re finally satisfied with your VBA – VSTO code interop, close Visual Studio and open the .xlsm file in the project directory (not the \bin) and re-import your code again into that version. Then restart Visual Studio and it will be in there when you start debugging again. I find this easier than copying my code into the clipboard, closing VS, modifying the document, reopening VS every time. Just be aware of what version of the document you’re modifying when you tweak your VBA code and you should be OK.

I’ve uploaded the code for this example onto Code Gallery so have a look: http://code.msdn.microsoft.com/VBAVSTOInterop

More Resources

For more information on VBA – VSTO interop with Visual Studio please check out the following resources:

Enjoy!

Using the ReportViewer with ADO.NET Data Services and Entity Framework

Beth Massi — Thu, 20 Aug 2009 07:57:20 GMT

The Winforms ReportViewer in Visual Studio Pro will allow you define client reports with a variety of data sources. If you’re not familiar with creating client-side reports using the ReportViewer, take a look at these videos:

(The ReportViewer can also display server-based reports a la SQL Reporting Services and has a whole boatload of features that I’m not going to talk about here. For more information on this freely redistributable control, please read ReportViewer Controls (Visual Studio) in the MSDN library.)

ADO.NET Data Services was released with Visual Studio 2008 SP1 and is basically a framework for exposing your data models via RESTful web services. So if you are building a remote CRUD data access layer then this is a technology that will make that super-simple, especially if you just want to expose a few data entities as read-only report sources. (I’ve written a lot about how to use ADO.NET Data Services in a variety of ways so check out these posts if you’re interested.) Entity Framework was released at the same time and you can use EF as the data model behind your ADO.NET Data Service and expose it easily. If you’ve never created one before, check out this quick start here.

What’s the Problem?

If you’ve ever tried to use the ReportViewer to design a client-side report with an ADO.NET Data Service data source (or use an Entity Data Model directly) you may be disappointed. If you try to design a new report, the wizard may crash Visual Studio when selecting an entity. Yikes!

Let me show you what I mean, but don’t try this at home. I have an ADO.NET Data Service based on the Northwind database like the one I created here and in the quick start. I then added a Windows Forms client project to the same solution (File –> Add –> New Project, then select Windows Forms App). Now open Form1 in the client and from the toolbox under the Reporting tab, drop the Microsoft ReportViewer control onto the form and from the smart tag select “Design a New Report”.

This will open the Report Wizard. The first thing I need to do is tell it what data source to use, so I’ll select Service and click Next. This will open the Add Service Reference dialog box where I can add the reference to my data service and Visual Studio will generate the proxy objects for me. In this example my service is in the same solution as the client so I can just click the Discover button and Visual Studio will see it. I named it NorthwindService. Click OK then click Finish.

At this point I’m brought back to the Report Wizard:

Hmmmm…. I’m a little lost at this point because -- didn’t I just select the data source? Why don’t I see it?

Maybe I should have added the service reference first from the Solution Explorer instead of through the Report Wizard? You can do that and you’ll get to the same screen at this point.

So okay, I’ll click the Add Data Source button that’s calling to me. Granted, I like clicking buttons that have the ellipsis (…) on them because I’m always curious to see what’s under them, but this seems redundant.

This opens the same dialog as before but this time I’ll choose Object instead of Service. I’m choosing object this time because I’m going to try and bind to the client proxy types that were generated for me when I added the service reference. After selecting Object, click Next and expand the service namespace.

For this report I want to just display a list of Customers in the system so I’ll select Customers and then click Next.

Then… then…… are you ready?… you better sit down for this…. click Finish……. wait for it…. wait for it….. not responding…. uh ohhhh…..

Visual Studio has encountered a problem and needs to close. Darn!

Now that was fun.

How Do I Fix this?

Unfortunately the Report Wizard in Visual Studio 2008 doesn’t know how to work with many-to-many relationships and that’s exactly what we have defined in our EF Entity Data Model which is what is backing our ADO.NET Data Service. Customers have many CustomerDemographics and vice versa in Northwind. You can actually define a couple classes yourself manually and create a many-to-many association between them:

Public Class Class1

    Private _class2 As List(Of Class2)
    Public ReadOnly Property Class2() As List(Of Class2)
        Get
            Return _class2
        End Get
    End Property

End Class

Public Class Class2

    Private _class1 As List(Of Class1)
    Public ReadOnly Property Class1() As List(Of Class1)
        Get
            Return _class1
        End Get
    End Property

End Class

Try to use either class above as the data source of the report and it will crash too. Woah! So when the report designer tries to read these associations I’m guessing it gets into an infinite loop walking the association references back and forth and then it crashes. So it’s not an error with the generated proxy objects per se, the root cause is our object model. If I would have chosen Categories instead, it would have worked.

So what do we do? We could create another layer of classes without the associations on both sides if we wanted and then use those types instead but then we’d have to write code that IMO is pretty useless, just to shape the data again how we want on the client.

My recommendation is to create a separate data model for your reports that doesn’t have many-to-many associations at all. You’re going to end up with a lot of different looking entities anyways for your reports because they will most likely pull from multiple database Views and/or stored procedures. You’ll always be displaying one side of the many-to-many relationship on paper anyways.

Creating a Reporting Data Model

So let’s go back to the data service project and add a new Entity Data Model to the web project called NorthwindReport. This time I’ll just select the Customers, Orders and Order Details and all the Views defined in the database.

Next I’ll add the ADO.NET Data Service and call it NorthwindReport and configure it so that we’re only allowing read-only access to our data by setting the entity access rule like so:

Imports System.Data.Services
Imports System.Linq
Imports System.ServiceModel.Web

Public Class NorthwindReport
    Inherits DataService(Of NorthwindReportEntities)

    Public Shared Sub InitializeService(ByVal config As IDataServiceConfiguration)
        config.SetEntitySetAccessRule("*", EntitySetRights.AllRead)
    End Sub
End Class

Now back on the client we can add the service reference to this service instead. After we add the service reference we can run the Report Wizard again by selecting “Design a New Report” smart tag on the ReportViewer control like I showed in the beginning. Select Object as the data source (or Service if you didn’t add the service reference first, then you’ll have to click “Add Data Sources…” again and then select Object) and you should see the list of entities exposed in the NorthwindReport data model. Now when we select Customer, we don’t have a problem.

Design the report how you like (see the documentation for more details) by clicking through the wizard and then go back to the smart tag on the ReportViewer and you should see the report you just created in the dropdown. Next go to the code-behind for the form and in the Load handler we just set the BindingSource.DataSource property to the results of the ADO.NET Data Service LINQ query:

Imports NorthwindClient.NorthwindReportService

Public Class Form1

    Private Sub Form1_Load() Handles MyBase.Load
        'TODO: put in My.Settings
        Dim uri As New Uri("http://localhost:1933/NorthwindReport.svc/")
        'Create the service reference
        Dim db As New NorthwindReportEntities(uri)

        'Set the report's DataSource to the results of the query
        Me.BindingSource.DataSource = From c In db.Customers _
                                      Where c.Country = "USA" _
                                      Order By c.CompanyName

        Me.ReportViewer1.RefreshReport()
    End Sub
End Class

Now hit F5 to run this baby and you’ll see the report pull the data from the service and display in the form:

Recap & Resources

ADO.NET Data Services are a great way to quickly and easily expose data on the web, especially if it’s just read-only data used for remote reporting clients. The key to using the ReportViewer with ADO.NET Data Services (or an Entity Data Model directly, or even your own object model) is to make sure there are no many-to-many associations on the entities. Here are the resources you need to get started with ReportViewer and ADO.NET Data Services:

Enjoy!

Using Windows Presentation Foundation in Office Clients

Beth Massi — Tue, 11 Aug 2009 03:31:51 GMT

I was cleaning up my desk today and in the piles of mail and gobs of paper I found the SDN Magazine “Women in Technology” issue 101 that featured an article I wrote that was released in print back in May. Well, I just noticed today that near the end of June they made most of the articles available online, including mine. :-)

Using Windows Presentation Foundation and Line-of-Business Data in Microsoft Office Clients

In this article I talk about how to expose Line-of-Business data via ADO.NET Data Services to an Excel client using WPF. Office solutions you build with Visual Studio are designed to work with Windows Forms controls but you can also use WPF controls in your solutions as well. Any UI element that can host Windows Forms controls in an Office solution (VSTO) can also host WPF controls using the Winforms ElementHost as a container.

Using WPF controls in Office allows you to think out of the box and provide world-class data visualizations that are not possible with Windows Forms controls. And you can do it easily in an instantly familiar end-user application like those in the Office family. But what if you don’t have any fancy data visualizations? Even the simplest controls that display data are often better off as WPF controls in Office applications because they better match the UI styles used in the latest versions of Office. Using WPF can make your add-ins look built into the Office applications themselves, providing a better user experience.

This article describes one piece of the Northwind Office Business Application (OBA) we created in the beginning of the year so if you’re interested in OBA development with Outlook, Word, Excel and Sharepoint I’d suggest reading these as well:

OBA Part 1 - Exposing Line-of-Business Data

OBA Part 2 - Building and Outlook Client against LOB Data

OBA Part 3 - Storing and Reading Data in Word Documents

OBA Part 4 - Building an Excel Client against LOB Data

OBA Part 5 - Building the SharePoint 2007 Workflow

The full sample application, built with Visual Studio 2008, is here: http://code.msdn.microsoft.com/OBANorthwind

Of course, the rest of the magazine is pack full of awesome articles from very well known women in technology (scroll to the bottom of this page for the whole list). I’m honored to be featured with them in this issue. Thanks again to Marianne van Wanrooij and the folks at SDN for putting this together and I’ll see you in October at the SDN Conference!

Enjoy!

OBA Part 5 - Building the SharePoint 2007 Workflow

Beth Massi — Wed, 22 Apr 2009 08:06:20 GMT

In my last few app building posts we've been building a simple Office Business Application (OBA) for the new Northwind Traders. If you missed them:

Today we're going to build out the SharePoint workflow using Visual Studio 2008 SharePoint 2007 workflow templates. There's a plethora of information on building these in the MSDN library. In order to develop against SharePoint you will need to set up your development environment properly so I would read this first if you're just getting started. My SharePoint development environment is a 32bit Windows 2008 Server running MOSS 2007 and Visual Studio Professional 2008 Service Pack 1.

If you recall our architecture diagram of our Northwind Traders OBA involved our Sales Reps submitting purchase orders as Word 2007 documents up to SharePoint which kicked off a workflow to parse the document and update the database with the order data through our data service. This allows us to store the unstructured document on SharePoint and the structured order data in our database.

In Part 3 we built the code that does the parsing of the document, now we just need to get that code into our workflow. We’ll also build in a delay so that the workflow can check the database later to see if the order has been shipped and update the status appropriately. We’ll also take advantage of SharePoint’s workflow history and task list to report outcomes or any issues that may arise.

Creating a Document Library for the Purchase Order Documents

For this example we need to add a document library called Orders for the purchase order documents that are submitted. To create the document library, navigate to your SharePoint site and then in the right-had upper corner drop down the Site Actions, select Create (or just navigate to /_layouts/create.aspx) and then under Libraries select Document Library.

The only other property that I changed here is the document template, change that to Microsoft Office Word Document and then hit the Create button. This will bring you to the doc library and you’ll see the default fields in the column headers. We’re going to need to modify these to show the Order Status, an Order Number, the Shipped Date and the email address of the Sales Rep that submitted the order.

Click on Settings then select Create column to create new columns for the orders in the document library.

For this example I added the following columns:

Order Status
Choice (New, Processed, Shipped, On Hold, Canceled)
Required = No
Default = New
Add to Default View
Order Number
Single line of text
Required = No
Add to Default View
Shipped Date
Date Only (no Time)
Required = No
Add to Default View
Sales Rep Email
Single line of text
Required = Yes
Add to Default View

After I added these columns I added a new default view to display them in the order I want. Click on the Settings again and select Create view.

The only thing the user is required to fill out when they upload a new purchase order document is the sales rep’s email address. (Recall that we added this field to the database when we built the data service). The Order Status and Shipped Date will actually be filled out automatically by the workflow depending on whether the order is new or has been updated by the Excel client (which we built in the last OBA post) that the shipping department uses to mark orders as shipped. Order Number will also be assigned by the workflow. We’ll use this to correlate the data with the purchase order document here in the list so we’ll need to add this field to the database.

Adding the Order Number to Northwind

So now we have the document library set up, we’re almost ready to write the workflow. First we’ll need to add the OrderNumber field to the Orders table in the Northwind database and then refresh our data service service so that this starts to show up as an available field on the Order.

USE Northwind
GO

ALTER TABLE dbo.Orders ADD
    OrderNumber nvarchar(25) NULL
GO

In order to pick up this new field we need to refresh the Entity Data Model behind our data service. In the NorthwindDataService project open the NorthwindModel.edmx and then right-click on the design surface and select Refresh from database. This will pick up the OrderNumber field on the Order entity. Rebuild the data service.

Options on Hosting the Data Service for Workflow Development

If you’ve been following along and playing with the sample, you’ll notice that the NorthwindDataService project is currently set to be hosted in the ASP.NET development server right now so that testing the Excel and Outlook clients is easy. However at this point you may opt to deploy this to IIS instead so that you don’t have to remember to start it up manually every time you want to test the SharePoint Workflow. And of course for deployment to production you’ll need to host it in IIS anyway.

It gets slightly tricky if you want to host the data service in IIS on the same server as SharePoint because SharePoint takes over Port 80. So the easiest thing to do is to open IIS Manager and just create a new web site on Port 82 called NorthwindHost and then create a new application virtual directory called Northwind under that. By default, when you create a new web site it should also create a new Application Pool for you running under the identity NETWORK SERVICE. The identity you use here will need to have read and execute file permissions on the physical locations of any virtual directories you create as well as proper database permissions.

It’s XCOPY deployment at that point. Just copy the Web.Config, Northwind.svc and the \bin directory over to the physical location of the Northwind virtual directory and you should be good to go. You can do this in Visual Studio (if running as an administrator) just right-click on the NorthwindDataService project in the solution explorer and then select publish. Then enter http://localhost:82/Northwind/ (or whatever you named it) and it will build and publish the files there automatically.

Note however, that before the WCF service will activate you have to install the WCF service handlers into IIS. These may not be installed automatically so in Windows 2008 check the Server Manager, scroll down to the Features Summary and select “Add Features”. Then expand the first node “.NET 3.0 Features” and check WCF Activation.

Remember if you change the location of the data service then you need to update the settings in the Excel and Outlook client (app.config file).

Creating the SharePoint Workflow

If you’re not doing this already, restart Visual Studio and Run as Administrator. This is necessary so that you can deploy and debug your workflow. Next add a new project to the solution, File –> Add –> New Project. For this example we’re just going to create a simple SharePoint 2007 Sequential Workflow. (Note: You will need Visual Studio 2008 Professional and higher to get these templates.)

As I mentioned before the workflow will kick off when a new purchase order is added to the document library in order to parse the data in the document. So when the order is first added to the list it will have a status of New. After it is parsed we will set the status to Processed, which happens right away. Later, after the shipping department enters the shipped date in the Excel client and updates the Orders.ShippedDate field in the database, we need the workflow to wake back up and set the order status to Shipped. For this example I’m going to build a delay into the workflow to check the database (via our data service) every so often. For testing it can be a couple minutes but once we deploy we can set it to every couple hours. Note that if you’re building more statuses or states into your own workflows you may want to take a look at the State Machine Workflow template instead.

So the next step is to specify where your SharePoint site and document library resides, for development this is going to be http://YourServerName. Once you specify the site you can then select the Orders document library in the Library dropdown. Leave “Automatically associate workflow?” checked so that Visual Studio can deploy the workflow to the site automatically for us.

On the next page check off how you want to start the workflow. For this example we’ll select “When an item is created”. You can also check “Manually by users” which can be helpful when testing but it’s not necessary for our example. Note that you can change these settings later on the Workflow project -- from the Project menu select “SharePoint debug settings..”. You need to be running Visual Studio as an administrator to open these settings. You’ll need to do this if you’re going to run the Workflow in the sample code against your own SharePoint site.

When the project is created it will automatically add a workflow called Workflow1 and open the designer which will display an event activity for onWorkflowActivated. An OnWorkflowActivated activity must be the first activity in a Windows SharePoint Services workflow so Visual Studio automatically sets one up for us. I renamed Workflow1 to ProcessOrder in the Solution Explorer (I like descriptive names ;-)) which means I’ll also need to update the values for the CorrelationToken.OwnerActivityName as well as the WorkflowProperties.Name to set them to ProcessOrder:

Now you can start laying out the design of the workflow. If you have used the WF designer before then this part should be familiar. Take a look at your toolbox and you’ll see the SharePoint specific activities listed under the Workflow 3.0 and 3.5 tabs. The design of the workflow for this example will be simple.

There are three main blocks to the workflow that we’re going to build:

First is the parsing of the order data in the document which is a standard code activity that you find in the Windows Workflow v3.0 tab on the toolbox.
The second block is a standard While loop that contains a delay activity. This piece will periodically query the database until the Order.ShipDate is updated in the database by the Excel client.
The third block will be an IfElse activity which will check the Order status and either write an informational message to the History list in the case the order shipped successfully, otherwise we create a Task and assign it to the administrator for further investigation. The LogToHistoryListActivity and the CreateTask items can be found in the SharePoint Workflow tab on the toolbox.

Before we start writing the workflow code, let’s create some constants that we can use to refer to the data service URI, our order statuses, and list column names (I just added a new Module called Constants.vb):

Friend Module Constants
    Public Const OrderStatusColumn As String = "Order Status"
    Public Const OrderNumberColumn As String = "Order Number"
    Public Const ShippedDateColumn As String = "Shipped Date"
    Public Const SalesRepEmailColumn As String = "Sales Rep Email"

    Public Const NewStatus As String = "New"
    Public Const ShippedStatus As String = "Shipped"
    Public Const ProcessedStatus As String = "Processed"
    Public Const OnHoldStatus As String = "On Hold"
    Public Const CanceledStatus As String = "Canceled"

    Public Const ServiceURL As String = "http://localhost:82/NorthwindService/Northwind.svc"
End Module

Parsing the Order Document (CodeActivity parseOrder)

The Workflow kicks off immediately after a purchase order document is checked into the document library. The first code activity out of the gate is parsing the order document’s customXML for the order data we need. I already demonstrated a simple console application for extracting the order data from a Word document in Part 3. This code uses the Open XML SDK so you’ll need to download that and install it on your SharePoint server so that the assemblies are in the GAC. Then add an assembly reference to DocumentFormat.OpenXML.

From that console application project I copied the DocumentOderData.vb, Extensions.vb code files and the OrderEntry.xsd into the workflow project. Module1.vb had a method called ParseOrderDocument which parsed the docx file and populated a DocumentOrderData class with the information. I took that code and created a new class called Shredder and modified the interface a bit so that we could pass it a Microsoft.Sharepoint.SPFile class instead:

Imports DocumentFormat.OpenXml.Packaging
Imports <xmlns="urn:microsoft:examples:oba">

Public Class Shredder

    Public Function ParseOrderDocument(ByVal docFile As SPFile) As DocumentOrderData
        Using docStream = docFile.OpenBinaryStream
            Return ParseOrderDocument(WordprocessingDocument.Open(docStream, False))
        End Using
    End Function

    Public Function ParseOrderDocument(ByVal wordDoc As WordprocessingDocument) As DocumentOrderData
...

We also had a means for adding this data to the database via a method called AddNewOrder. The only change we need here is to create a unique OrderNumber string, add it to the Order entity, and return it to the workflow so we can also set it on the list item in SharePoint. You can decide how you want to generate unique order numbers, whether you want them to be GIUDs or timestamps or some other random number. I like using a combination of the CustomerID and the current date&time so that it’s human readable.

Dim orderNum = Replace(Replace(Replace(cust.CustomerID & Now.ToString(), "/", ""), ":", ""), " ", "")

This will work as long as there aren’t two orders for the same customer submitted within the same second so depending on your actual scenario you may opt for a different strategy :-). So this AddNewOrder code I placed into a class called OrderManager which also encapsulates all calls to the data service. Speaking of our data service, we’ll need to add a Service Reference to the workflow project called NorthwindService (right-click on the workflow project and select Add Service Reference) which will add the database entity types to our project.

Now drop a CodeActivity onto the Workflow designer and in the properties window name it parseOrder. Then right-click on it in the designer and select Generate Handlers to automatically generate the parseOrder_ExecuteCode handler. If the order data is extracted and added to the database successfully then an order number is assigned and the status is set to Processed. If the document does not contain the <OrderEntry> CustomXML then the status will be set to Canceled. If there is a problem adding the data to the database then the status is set to On Hold. (Notice that this code also uses the Application.Log to write messages to the Event Log which you can see how to set up here.)

Public Class ProcessOrder
    Inherits SequentialWorkflowActivity

    Public workflowProperties As New SPWorkflowActivationProperties
    Public Sub New()
        MyBase.New()
        InitializeComponent()
    End Sub

    Private Sub parseOrder_ExecuteCode(ByVal sender As System.Object, _
                                       ByVal e As System.EventArgs)
        'This method is executed once the purchase order is uploaded 
        ' and checked into the document library 
        Try
            Dim orderNumber As String = ""
            Dim shredder As New Shredder

            'Valid OrderStatus: New, Processed, Shipped, Cancelled, On Hold
            ' (See Constants.vb for column and status strings)
            Dim status = workflowProperties.Item(OrderStatusColumn).ToString()

            If status = NewStatus Then
                'Get order data out of the document
                Dim docData = shredder.ParseOrderDocument(Me.workflowProperties.Item.File)

                If docData IsNot Nothing Then
                    Dim manager As New OrderManager
                    Dim employeeEmail = workflowProperties.Item(SalesRepEmailColumn).ToString()

                    'Add order data to the DB (through the service) and return the order number.
                    orderNumber = manager.AddNewOrder(docData, employeeEmail)

                    If orderNumber <> "" Then
                        status = ProcessedStatus
                        My.Application.Log.WriteEntry( _
                            String.Format("Order {0} added to database successfully.", _
                                          orderNumber), TraceEventType.Information)
                    Else
                        status = OnHoldStatus
                        My.Application.Log.WriteEntry( _
                            String.Format("Order could not be added to database for {0}.", _
                                          Me.workflowProperties.Item.Name), TraceEventType.Error)
                    End If
                Else
                    status = CanceledStatus
                    My.Application.Log.WriteEntry( _
                        String.Format("Invalid purchase order submitted for {0}", _
                                      Me.workflowProperties.Item.Name), TraceEventType.Error)
                End If
            End If

            If status <> "" Then
                Me.workflowProperties.Item(OrderStatusColumn) = status
                If orderNumber.Length() > 0 Then
                    Me.workflowProperties.Item(OrderNumberColumn) = orderNumber
                End If
                Me.workflowProperties.Item.Update()
            End If

        Catch ex As Exception
            My.Application.Log.WriteException(ex)
        End Try

    End Sub

Now that the order is in the database, you can open the Excel client we wrote in part 4 and enter a ShippedDate and click save to update the order.

Querying the Database Periodically (WhileActivity waitForProcessed)

Next we need a WhileActivity so that we can check the database to see if the ShippedDate has been updated. Drag a standard While activity from the toolbox under the parseOrder and name it waitForProcessed in the properties window. Right-click on the designer and select View Code and write the following method:

    Private Sub orderProcessed(ByVal sender As System.Object, ByVal e As ConditionalEventArgs)
      Try
            Dim status = Me.workflowProperties.Item(OrderStatusColumn).ToString()
            Dim orderNumber = Me.workflowProperties.Item(Constants.OrderNumberColumn).ToString()

            If status <> ProcessedStatus Then
                'End while branch and go to next step in sequence if status is:
                '  Canceled = invalid purchase order (no <OrderEntry> CustomXML found)
                '  On Hold = Could not add data to database (see error log for details)
                e.Result = False
            Else
                'Get order from DB
                Dim manager As New OrderManager
                Dim processedOrder = manager.GetOrder(orderNumber)

                'If order was shipped (ShippedDate not NULL) then set Order Status to Shipped.
                If processedOrder IsNot Nothing Then
                    If processedOrder.ShippedDate IsNot Nothing AndAlso _
                       processedOrder.ShippedDate.HasValue Then
                        My.Application.Log.WriteEntry( _
                            String.Format("Order {0} has shipped as of {1}", _
                                          orderNumber, Now()), TraceEventType.Information)

                        Me.workflowProperties.Item(OrderStatusColumn) = ShippedStatus
                        Me.workflowProperties.Item(ShippedDateColumn) = processedOrder.ShippedDate
                        Me.workflowProperties.Item.Update()
                        'end while branch and go to next step in sequence
                        e.Result = False
                    Else
                        My.Application.Log.WriteEntry( _
                            String.Format("Order {0} has not shipped as of {1}", _
                                          orderNumber, Now()), TraceEventType.Warning)
                        'keep workflow running until shipped or canceled
                        e.Result = True
                    End If
                Else
                    My.Application.Log.WriteEntry( _
                        String.Format("Order {0} has been deleted from the database", _
                                      orderNumber, Now()), TraceEventType.Error)

                    Me.workflowProperties.Item(OrderStatusColumn) = CanceledStatus
                    Me.workflowProperties.Item.Update()
                    'end while branch and go to next step in sequence
                    e.Result = False
                End If
            End If

        Catch ex As Exception
            My.Application.Log.WriteException(ex)
        End Try

    End Sub

Notice in this code we’re referring to a method on the OrderManager called GetOrder which simply queries the Order entity from the database via the data service using LINQ:

Imports OBADemoWorkflow.NorthwindServiceReference

Public Class OrderManager
    Private ctx As New NorthwindEntities(New Uri(Constants.ServiceURL))

    Public Function AddNewOrder(ByVal docData As DocumentOrderData, _
                                ByVal employeeEmail As String) As String...

    Public Function GetOrder(ByVal orderNumber As String) As Order
        Try
            Dim theOrder = (From o In ctx.Orders _
                            Where o.OrderNumber = orderNumber).FirstOrDefault()

            Return theOrder

        Catch ex As Exception
            My.Application.Log.WriteException(ex)
            Return Nothing
        End Try
    End Function
End Class

Now you can go back to the designer and set the Condition on the waitForProcessed WhileActivity to the orderProcessed method. Set the Condition to a Code Condition and the dropdown will contain only those methods that have the right signature, i.e. have a ConditionalEventArgs parameter. The orderProcessed method will set the e.Result = True only if the order is in the Processed state, is still in the database, and its ShippedDate is still NULL. This means that the While activity will continue to run.

Because the shipping department most likely will not ship the order out the door the second the order is entered into the database (<g>), we need a way for our workflow to delay and check periodically. Depending on your business you may want to check hourly or even daily. For testing you probably want to check every minute or two. This is where the DelayActivity comes in. Drag a standard Delay activity onto the designer inside the While Activity and set the Timeout Duration in the properties window to 3 minutes or so.

Before we go on I want to mention that there were known issues with the Delay activities not firing correctly in SharePoint that are addressed by this KB Article: http://support.microsoft.com/kb/953630/. The SharePoint timer service (OWSTIMER.exe) is set to only wake up every 5 minutes, so you probably want to set that to a shorter interval in your testing environment otherwise you’ll have to wait at least 5 minutes no matter how short you set your Delay activity. Another other issue I noticed was sometimes on rebuild & redeployment I needed to restart the timer service manually from an admin command prompt:

>Net Stop SPTimerV3
>iisreset
>Net Start SPTimerV3

Also there is an issue with debugging delays. I couldn’t just press F5 to debug the workflow after the delay. Up until that point I debugged just fine (which is where almost all our code is in this example) but if I wanted to see the rest of the code execute after the delay then I needed to attach to the OWSTIMER.exe process (while you’re debugging, on the main menu select Tools –> Attach to Process). This is also one of the reasons why I enabled the Application.Log to send messages to the Event Log.

Wrapping Up the Workflow (History Logging and Creating Tasks)

The last piece of the workflow is simple, if the order is shipped we’ll just log a message to the workflow history list otherwise we’ll create a task for the administrator to investigate. Drop an IfElse activity under the While activity set and name it checkIfShipped. Then name the first branch ifShipped and the second branch elseNotShipped. In the ifShipped branch drop a LogToHistoryListActivity which is found in the SharePoint Workflow tab on the Toolbox. In the elseNotShipped drop a CreateTask activity. On the properties window for the CreateTask create a new field binding for both the TaskID and TaskProperties and enter a correlationToken with the parent activity set to ProcessOrder (the workflow).

Then right-click on both the CreateTask and LogToHistoryActivity and select Generate Handlers in order to generate the method stubs for each of them. We’ll also need a method called isOrderShipped with the same signature as the orderProcessed method above to be able to set it as the Code Condition of the ifShipped branch. We need to check the workflowProperties.Item for the order status and set the e.Result = True if the status is Shipped.

Private Sub isOrderShipped(ByVal sender As Object, ByVal e As ConditionalEventArgs)
    'Returns True if Order Status equals Shipped
    Dim status = Me.workflowProperties.Item(OrderStatusColumn).ToString()
    e.Result = (status = ShippedStatus)
End Sub

Private Sub createTask1_MethodInvoking(ByVal sender As System.Object, ByVal e As System.EventArgs)
    Try
        'This will execute if the workflow is ending but the Order Status 
        ' is not Shipped (i.e. Canceled or On Hold). 
        ' This code creates a workflow task item so the AssignedTo can investigate.
        Dim status = Me.workflowProperties.Item(OrderStatusColumn).ToString()
        Dim name = Me.workflowProperties.Item.Name

        createTask1_TaskId1 = Guid.NewGuid()
        createTask1_TaskProperties1.AssignedTo = "obavm09\wssdeveloper"
        createTask1_TaskProperties1.Title = String.Format("Problem with order {0}", name)
        createTask1_TaskProperties1.Description = String.Format("Order {0} as of {1}", status, Now)
    Catch ex As Exception
        My.Application.Log.WriteException(ex)
    End Try
End Sub

Private Sub logToHistoryListActivity1_MethodInvoking(ByVal sender As System.Object, _
                                                     ByVal e As System.EventArgs)
    logToHistoryListActivity1.HistoryOutcome = "Order has been shipped."
End Sub

Testing the Workflow

In Visual Studio (still running as Administrator) Rebuild the solution. Then right-click on the OBADemoWorkflow project and select Deploy from the context menu. Now we can head over to the document library and upload some purchase orders. I used the one we created previously in Part 3 with ALFKI as the CustomerID. Go to the Orders document library, click Upload, Browse for the purchase order and click OK. Then fill out the required field Sales Rep Email (this is the Employee.EmailAddress field we added to the database in Part 1). Once you click “Check In” the workflow will kick off.

The Order status is first set to “New”….

But if you quickly refresh the list you will see that the Order Status and Order Number change as the order is processed and entered into the database.

Now the workflow is in its delay activity waiting for us to update the Order.ShippedDate. Open up the Excel client and enter something in the ShippedDate field and save the sheet (or manually modify the database). The next time the SharePoint timer runs it will waken our delay which will check the database again and set the status appropriately.

If you select the OBADemoWorkflow status (the last column in the view which is added automatically for us when we deploy) then you can see the status message in the Workflow History list. To see a task get created you can perform the same process but instead of updating the ShippedDate, delete the Order from the database (or delete the OrderNumber) and the workflow will set the status to Canceled and you will see a task in the list instead. And remember in testing we set the delay to a few minutes but in production Northwind Traders will be good with a 12 hour delay (gourmet foods don’t ship that quickly ;-)).

I’ve added this workflow to the sample code we’ve been building up on Code Gallery so have a look. I hope this real(er)-world, componentized sample has given you a good introduction into OBA and some of the awesome VSTO features of Visual Studio 2008.

Enjoy!

OBA Part 4 - Building an Excel Client against LOB Data

Beth Massi — Mon, 09 Mar 2009 01:45:21 GMT

In my last few app building posts we've been building a simple Office Business Application (OBA) for the new Northwind Traders. If you missed them:

(In the last post on OBA I mentioned we would build out the SharePoint Workflow next but I realized that it's important to see how the Excel client works before we write the workflow, so that will be the next post.)

In this post I want to focus on how we can build an Excel client for our shipping department. This will be a customized Excel spreadsheet that lists the orders that need to be shipped and allows users to enter the ship dates and save them back to the database.

We'll also generate a pivot table and chart so that we can visualize the percentages of cities that we're shipping our products. This is one of the key advantages of building an Excel client. Not only does it lend itself well for editing tabular data, it also makes it very easy to provide additional analysis of that data.

The Excel Document Customization

I've been building upon the the Visual Studio Solution that we started in the first post on OBA when we built the data service. So just add a new project to the solution (File -> Add -> New Project) and select Office 2007 Excel Workbook which is available in Visual Studio 2008 Professional and higher:

Since we're building a document customization and not an Add-In this means that our code will only run on the specific document as opposed to running in the Excel application over any document that is opened. After we add the project we're asked if we want to import an existing Excel workbook or create a new one. For this example we'll want to create a new one named the same name as our project, NorthwindClientExcel.xlsx. After we specify this, our project is created and the Excel designer opens.

Next step is to add the data service reference just like we did for the Outlook Add-In. Right-click on the project, select Add Service Reference. Click the Discover button and it should find our ADO.NET data service in the solution called NorthwindDataService. Name the service reference NorthwindService.

Data Binding in Excel

Now that we have our service reference we can retrieve the list of Order objects that have not been shipped yet and display them in the first sheet of our workbook. But we'll also want to show the Order Details to the shipping department and display the Quantity and Product that should be shipped. We'll do this using an Excel Action Pane by setting up a master-detail view of the data. So as the user scrolls through the Order rows, the Action Pane will display the Order Details. The user only needs to make changes to the Order rows itself so this design will work well.

The magic control we use in Excel to bind data to rows is called the ListObject. This object can easily bind to a Winforms BindingSource just like any other Winforms control. So to set up our data source so we can bind to a BindingSource we'll want a BindingList(Of Order) so that list change notifications are communicated to the UI. We'll also need to augment the Order partial class on the client so that property change notifications are also sent.

So first create a new class named Order and place it in the same Namespace as the NorthwindService service reference we just added. This is where the client proxy objects are generated for us so in order to extend these classes with our own code we just need to get it into the same Namespace. (Here's a Visual Basic tip, you know you've got it right if you see the Order properties and methods in the Declarations drop down above the editor for the Order class.) We need to fire a change notification on all of the properties of our Order so I've placed code to do this in all the xxxChanged() partial methods like so :

Imports NorthwindExcelClient.NorthwindService
Imports System.ComponentModel

Namespace NorthwindService

    Partial Public Class Order
        Implements INotifyPropertyChanged

        Public Event PropertyChanged(ByVal sender As Object, _
                                     ByVal e As PropertyChangedEventArgs) _
                                     Implements INotifyPropertyChanged.PropertyChanged

        Private Sub FirePropertyChanged(ByVal propertyName As String)
            If propertyName <> "" Then
                RaiseEvent PropertyChanged(Me, New PropertyChangedEventArgs(propertyName))
            End If
        End Sub

        Private Sub OnShippedDateChanged()
            FirePropertyChanged("ShippedDate")
        End Sub

        Private Sub OnOrderDateChanged()
            FirePropertyChanged("OrderDate")
        End Sub

        'FirePropertyChanged is called from all xxxChanged() partial methods.
        ' I excluded the rest of the code here for clarity....
.
.
.
    End Class
End Namespace

Next we need to create a BindingList(Of Order). I'm going to create a class called MyOrdersList that inherits from this which will also encapsulate the calls to the ADO.NET Data Service. MyOrdersList will use the data service context on the client (NorthwindService in our case) to retrieve and update the Orders. We don't want to allow adds or deletes in this application because orders are going through a workflow and our shipping department is only updating the information on an order, specifically the ShippedDate. So we'll need to override AddNewCore and RemoveItem to prevent this. We'll also override the OnListChanged so that we can tell the data service context to mark the Order entity as updated.

We also need a couple housekeeping fields for saving and for exposing a HasChanges property. The interesting code to notice here is that we're specifying a MergeOption on the data service client to OverwriteChanges after we save as opposed to the default AppendOnly. This means that after we save our changes it will refresh the existing Order entity instances with changes from the database.

Imports NorthwindExcelClient.NorthwindService
Imports System.ComponentModel

Public Class MyOrderList
    Inherits BindingList(Of Order)

    Private DataServiceContext As New NorthwindEntities(New Uri(My.Settings.ServiceURI))
    Private _hasChanges As Boolean
    Private _isSaving As Boolean

    Public ReadOnly Property HasChanges() As Boolean
        Get
            Return _hasChanges
        End Get
    End Property

    Sub New()
        MyBase.New()
        Me.DataServiceContext.MergeOption = Services.Client.MergeOption.OverwriteChanges
    End Sub

    ''' <summary>
    ''' Do not allow adds.
    ''' </summary>
    ''' <returns></returns>
    ''' <remarks></remarks>
    Protected Overrides Function AddNewCore() As Object
        Throw New NotSupportedException("You cannot add items to the list.")
        Return Nothing
    End Function
    ''' <summary>
    ''' Do not allow deletes.
    ''' </summary>
    ''' <param name="index"></param>
    ''' <remarks></remarks>
    Protected Overrides Sub RemoveItem(ByVal index As Integer)
        Throw New NotSupportedException("You cannot remove items from the list.")
    End Sub
    ''' <summary>
    ''' When a property is updated on an order, then we need to
    ''' tell the data services client to mark it as updated.
    ''' </summary>
    ''' <param name="e"></param>
    ''' <remarks></remarks>
    Protected Overrides Sub OnListChanged(ByVal e As System.ComponentModel.ListChangedEventArgs)
        If Not _isSaving Then
            'The Order partial class is implementing INotifyPropertyChanged so this will work
            If e.ListChangedType = ListChangedType.ItemChanged Then
                Me.DataServiceContext.UpdateObject(Me(e.NewIndex))
                _hasChanges = True
            End If
            MyBase.OnListChanged(e)
        End If
    End Sub

Before we get into the code that will retrieve and save the orders, let's bind this to a ListObject and get it onto our Excel worksheet. Since we're going to have to interact with the list of orders from our Sheet1 as well as the Action Pane displaying the details, I'm going to create a property on the Workbook itself that exposes the MyOrdersList. Double-click on the ThisWorkbook in the project and switch to the Code view:

Public Class ThisWorkbook

    'This is the data source we'll be working with on the Sheet and Action Pane.
    ' This class communicates with the ADO.NET Data Service
    Private _orderList As MyOrderList
    Public ReadOnly Property OrderList() As MyOrderList
        Get
            If _orderList Is Nothing Then
                _orderList = New MyOrderList()
            End If
            Return _orderList
        End Get
    End Property

Now build the project and open the Data Sources window. Add a new Object Data Source and select MyOrderList then Finish. Drag the MyOrderList onto the designer for Sheet1, just drop it into the first cell, and it will generate all the columns for every property on the Order. You can also change the name of it on the Design tab -- I'll change ours to OrderListObject.

Unfortunately it drops all the columns regardless if we select a drop target of none or not. Right click on the column and select Delete from the drop-down menu to delete a column (don't press the delete key). I'm going to remove the first three and the last three columns that it dropped. You'll also want to set any date fields you're displaying in the sheet to Text format. This is to work around a bug in the ListObject where it won't let you change date values if the formatting isn't set to text. You do this by selecting the column then right-click, select Format Cells, and then select Text from the list.

We can be explicit about setting our data source and binding to columns in the startup event handler:

Public Class Sheet1

    Private Sub Sheet1_Startup() Handles Me.Startup
        Dim myApp = NorthwindExcelClient.Globals.ThisWorkbook
        Me.OrderBindingSource.DataSource = myApp.OrderList

        Me.OrderListObject.SetDataBinding(Me.OrderBindingSource, "", _
                                          "ShippedDate", _
                                          "Freight", _
                                          "ShipName", _
                                          "ShipAddress", _
                                          "ShipCity", _
                                          "ShipRegion", _
                                          "ShipPostalCode", _
                                          "ShipCountry")

        Me.OrderListObject.AutoSelectRows = True

        myApp.LoadOrders()
    End Sub

Also notice the last line calls a method on ThisWorkbook to load the orders. Let's see how we can do this by writing a query against our ADO.NET data service.

Querying and Saving Orders via our Data Service

Now we can return back to our MyOrdersList and write a method for returning the list of orders that have not yet been shipped. Here I call the service to return a list of unshipped orders, add them all to MyOrderList and then raise the list changed event once to notify the Excel ListObject to refresh it's UI:

 ''' <summary>
''' Queries the open orders from the data service 
''' and returns the number of orders returned in the results
''' </summary>
''' <returns>number of orders returned from the service</returns>
''' <remarks></remarks>
Public Function LoadOrders() As Integer
    Dim isLoaded = True
    Me.Clear()

    Me.RaiseListChangedEvents = False

    Dim orders = From o In DataServiceContext.Orders _
                 Where o.ShippedDate Is Nothing _
                 Order By o.OrderDate

    For Each o In orders
        Me.Add(o)
    Next

    Me.RaiseListChangedEvents = True
    Me.OnListChanged(New ListChangedEventArgs(ListChangedType.Reset, 0))
    Return Me.Count
End Function

We're also going to need a way to load the order details, shipper and product entities when requested. This will happen as the user selects rows of data -- we need to display these details in our Action Pane. By default these entity references and collections are not loaded, we need to do this explicitly. This is a good thing in our case because it avoids transferring unnecessary data if the user doesn't select the Order row in the sheet.

''' <summary>
''' Loads the Order Details and Product information from the data 
'''  service and returns the OrderDetails for the specified order.
''' </summary>
''' <param name="o"></param>
''' <remarks></remarks>
Public Sub LoadOrderDetails(ByVal o As Order)
    If (o IsNot Nothing) Then
        If o.Shipper Is Nothing Then
            Me.DataServiceContext.LoadProperty(o, "Shipper")
        End If
        If o.Order_Details Is Nothing OrElse o.Order_Details.Count = 0 Then
            Me.DataServiceContext.LoadProperty(o, "Order_Details")
            For Each detail In o.Order_Details
                detail.Order = o
                If detail.Product Is Nothing Then
                    Me.DataServiceContext.LoadProperty(detail, "Product")
                End If
            Next
        End If
    End If
End Sub

Finally we need a method that submits changes back to the data service. This is easily done by calling SaveChanges on the service context which sends all the changes we made in the client through the service. Note here that we are not sending them in a single batch, therefore if one order fails to update the ones before the failure will still be saved. You may need to put more robust error handling here depending on what kind of failures you anticipate in your applications. Simple error handling is done for this example in the Action Pane (we'll get there next).

    ''' <summary>
    ''' Saves the customer changes back to the service.
    ''' </summary>
    ''' <returns>true if save was successful, otherwise an exception is thrown</returns>
    ''' <remarks></remarks>
    Public Function SaveChanges() As Boolean
        Dim saved As Boolean
        Try
            _isSaving = True
            Me.DataServiceContext.SaveChanges()
            _hasChanges = False
            saved = True
        Finally
            _isSaving = False
        End Try

        Return saved
    End Function

End Class

Creating the Excel Action Pane Using WPF

Now we're ready to design our Action Pane that will display the order details as well as provide a status message area and a Save and Refresh button. Refresh will re-load the orders from the service and Save will send the changes back. (Later we'll also hook up Excel's save button to do the same thing.)

I've showed how to use WPF in Office applications before when we built the Outlook Add-In in Part 2. It's the same technique here -- use the Winforms ElementHost as a container for your WPF control. So let's create our WPF user control -- add a new item to the project and select WPF category on the left and then choose WPF User Control. I named it WPFActionPane and click OK.

The reason for using WPF in this case is so that we could really get a nice look-and-feel that matches Excel's colors. Additionally we can easily provide a couple simple animations so that users notice the control on the right-hand side of the spreadsheet -- this is the default location of an Action Pane. So here's the layout of the control and the styles used to make the read-only GridView have a nice Excel-friendly look:

<UserControl x:Class="WPFActionPane"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"  
             MinHeight="200" MinWidth="200" 
             VerticalContentAlignment="Stretch" 
             HorizontalContentAlignment="Stretch" Height="400" >
<UserControl.Resources>
<Storyboard x:Key="LoadingStoryBoard">
    <DoubleAnimation
                    Storyboard.TargetName="ListGrid"
                    Storyboard.TargetProperty="Opacity"
                    From="0.0" To="1.0" Duration="0:0:0.5" 
                    AutoReverse="False"  />
</Storyboard>
<Storyboard x:Key="UpdateStoryBoard">
    <ColorAnimation From="White" To="Yellow" 
                    Storyboard.TargetName="txtStatus" 
                    Storyboard.TargetProperty="Background.Color" 
                    AutoReverse="True" />
    <ColorAnimation From="Black" To="White" 
                    Storyboard.TargetName="txtStatus" 
                    Storyboard.TargetProperty="Foreground.Color" 
                    AutoReverse="True" />
</Storyboard>
<Style x:Key="GridViewStyle" TargetType="TextBox">
    <Setter Property="Margin" Value="-3,0,-9,-3" />
    <Setter Property="Cursor" Value="Arrow" />
    <Setter Property="IsReadOnly" Value="True" />
    <Setter Property="BorderBrush" Value="#B8CCE4" />
</Style>
<Style x:Key="ListViewStyle" TargetType="ListView">
    <Setter Property="Background">
        <Setter.Value>
            <LinearGradientBrush EndPoint="0.5,1" StartPoint="0.5,0">
                <GradientStop Color="#4F81BD" Offset="0"/>
                <GradientStop Color="White" Offset="1.0"/>
            </LinearGradientBrush>
        </Setter.Value>
    </Setter>
</Style>
<Style x:Key="ListViewItemStyle" TargetType="ListViewItem">
    <Setter Property="Background" Value="Transparent"/>
    <Setter Property="BorderBrush" Value="Transparent"/>
    <Setter Property="BorderThickness" Value="1"/>
    <Setter Property="HorizontalContentAlignment" Value="Stretch" />
    <Setter Property="VerticalContentAlignment" Value="Stretch" />
    <Setter Property="Height" Value="22" />
    <!--Removes the row higlight-->
    <Setter Property="Template">
        <Setter.Value>
            <ControlTemplate TargetType="{x:Type ListViewItem}">
                <GridViewRowPresenter 
                    SnapsToDevicePixels="{TemplateBinding SnapsToDevicePixels}" 
                    VerticalAlignment="{TemplateBinding VerticalContentAlignment}" 
                    Grid.RowSpan="2"/>
            </ControlTemplate>
        </Setter.Value>
    </Setter>
</Style>
<Style x:Key="GridViewColumnHeaderStyle" TargetType="GridViewColumnHeader">
    <Setter Property="Background" Value="#4F81BD"></Setter>
    <Setter Property="Foreground" Value="#DBE5F1"></Setter>
    <Setter Property="FontWeight" Value="Bold"></Setter>
    <Setter Property="HorizontalContentAlignment" Value="Left"></Setter>
    <Setter Property="BorderThickness" Value="2"></Setter>
    <Setter Property="Focusable" Value="False"></Setter>
    <Setter Property="BorderBrush">
        <Setter.Value>
            <LinearGradientBrush EndPoint="0.5,1" StartPoint="0.5,0">
                <GradientStop Color="White" Offset="0"/>
                <GradientStop Color="#B8CCE4"  Offset="1.0"/>
            </LinearGradientBrush>
        </Setter.Value>
    </Setter>
    <Setter Property="Template">
        <Setter.Value>
            <ControlTemplate TargetType="{x:Type GridViewColumnHeader}">
                <Grid SnapsToDevicePixels="True">
                    <Border BorderThickness="0,0,0,1" 
                            BorderBrush="{TemplateBinding Border.BorderBrush}" 
                            Background="{TemplateBinding Panel.Background}" Name="HeaderBorder">
                        <Border Padding="{TemplateBinding Control.Padding}" Grid.RowSpan="2">
                        <ContentPresenter 
                            RecognizesAccessKey="True" 
                            Content="{TemplateBinding ContentControl.Content}" 
                            ContentTemplate="{TemplateBinding ContentControl.ContentTemplate}" 
                            ContentStringFormat="{TemplateBinding ContentControl.ContentStringFormat}" 
                            Name="HeaderContent" Margin="0,0,0,1" 
                            HorizontalAlignment="{TemplateBinding Control.HorizontalContentAlignment}" 
                            VerticalAlignment="{TemplateBinding Control.VerticalContentAlignment}" 
                            SnapsToDevicePixels="{TemplateBinding UIElement.SnapsToDevicePixels}" />
                        </Border>
                    </Border>
                </Grid>
            </ControlTemplate>
        </Setter.Value>
    </Setter>
</Style>
</UserControl.Resources>
 <Grid Height="Auto" Width="Auto" Name="MainGrid">
    <Grid.RowDefinitions>
        <RowDefinition Height="50" />
        <RowDefinition Height="50" />
        <RowDefinition Height="140*" />
        <RowDefinition Height="60" />
    </Grid.RowDefinitions>
    <StackPanel Orientation="Horizontal" HorizontalAlignment="Right" VerticalAlignment="Top"  
                Visibility="Hidden" Name="ButtonStack">
       <Button Height="40" Name="cmdSave" Width="40" Margin="3" ToolTip="Save">
            <Image Source="FloppyDisk.png" />
        </Button>
        <Button Height="40" Name="cmdRefresh" Width="40" Margin="3" ToolTip="Refresh">
            <Image Source="Refresh.png" Name="Image1" />
        </Button>
    </StackPanel>
    <StackPanel Grid.Row="1">
        <TextBlock Name="txtShipper" Width="Auto" Height="25"
                 Text="{Binding Path=Shipper.CompanyName, StringFormat=Ship via \{0\}}"  
                 Foreground="DarkBlue" />
        <TextBlock Name="txtOrderDate" Width="Auto" Height="25"
                  Text="{Binding Path=OrderDate, StringFormat=Ordered \{0:D\}}" 
                  Foreground="DarkBlue"/>
       
    </StackPanel>
    <Image Grid.Row="2" Source="northwindlogo.gif" Width="140" Height="140" />
    <Grid Grid.Row="2" Background="White" Name="ListGrid">
        <ListView 
            ItemsSource="{Binding Path=Order_Details}"
            Style="{StaticResource ListViewStyle}"
            ItemContainerStyle="{StaticResource ListViewItemStyle}"
            Name="ListView1" Margin="4" IsEnabled="True" 
            BorderThickness="0" >
            <ListView.View>
                 <GridView 
                     ColumnHeaderContainerStyle="{StaticResource GridViewColumnHeaderStyle}">
                        <GridViewColumn Header="Product" Width="150">
                        <GridViewColumn.CellTemplate>
                            <DataTemplate>
                                <TextBox 
                                    Text="{Binding Path=Product.ProductName}" 
                                    Style="{StaticResource GridViewStyle}"/>
                            </DataTemplate>
                        </GridViewColumn.CellTemplate>
                    </GridViewColumn>
                    <GridViewColumn Header="Quantity" Width="61">
                        <GridViewColumn.CellTemplate>
                            <DataTemplate>
                                <TextBox 
                                    Text="{Binding Path=Quantity, StringFormat='n0'}" 
                                    Style="{StaticResource GridViewStyle}" />
                            </DataTemplate>
                        </GridViewColumn.CellTemplate>
                    </GridViewColumn>
                    </GridView>
            </ListView.View> 
            </ListView>
    </Grid>
   <Grid Grid.Row="3">
       <TextBox Name="txtStatus" TextWrapping="Wrap" Background="Transparent"
              IsReadOnly="True" BorderThickness="0" HorizontalContentAlignment="Stretch" 
              VerticalScrollBarVisibility="Auto" Cursor="Arrow"></TextBox>
     
    </Grid>
</Grid>
</UserControl>

The code that calls the load and save on the orders will be here since this control will interact directly with the list of Orders. In the code-behind of the WPFActionPane we'll also animate the control by running the StoryBoards defined in the XAML when we display the order details and when we display status messages at the bottom of the pane. (Note that I've also included the images referred by the XAML above into the project and set their Build Action to Resource in the properties for the files in the Solution Explorer).

We will pass the reference to the list of Orders into the control which we can then set as the DataContext. This will trigger all the data bindings to hook up to the currently selected Order's details as noted by the dot syntax in the bindings above. For instance, if we want to display the shipper's company name then we specify the Shipper.CompanyName path on the Order object contained in the list.

Imports NorthwindExcelClient.NorthwindService
Imports System.Windows.Data
Imports System.Windows.Media

Partial Public Class WPFActionPane

    Private _orderList As MyOrderList
    Public Property OrderList() As MyOrderList
        Get
            Return _orderList
        End Get
        Set(ByVal value As MyOrderList)
            _orderList = value
            Me.DataContext = _orderList
        End Set
    End Property

    Private Sub cmdRefresh_Click() Handles cmdRefresh.Click
        Me.LoadOrders()
    End Sub

    Private Sub cmdSave_Click() Handles cmdSave.Click
        Me.SaveOrders()
    End Sub
    ''' <summary>
    ''' Saves changes made to the orders in the sheet
    ''' </summary>
    ''' <returns></returns>
    ''' <remarks></remarks>
    Public Function SaveOrders() As Boolean
        Dim msg = "Orders could not be saved." & vbCrLf
        Try
            'Save changes back to the data service
            If Me.OrderList.SaveChanges() Then
                msg = "Orders saved."
            End If

            Me.SetMessage(msg)

        Catch ex As Exception
            Me.SetMessage(ex.ToString())
        End Try
    End Function
    ''' <summary>
    ''' Re-loads the orders that are not shipped yet. 
    ''' </summary>
    ''' <remarks></remarks>
    Public Sub LoadOrders()
        Dim msg = ""
        Try
            Dim count = Me.OrderList.LoadOrders()
            msg = String.Format("{0} orders returned.", count)

            Me.SetMessage(msg)
            Me.ButtonStack.Visibility = Windows.Visibility.Visible
        Catch ex As Exception
            Me.SetMessage(ex.ToString())
        End Try
    End Sub
    ''' <summary>
    ''' Show the Order Details in the ListView by moving the position
    ''' </summary>
    ''' <param name="o"></param>
    ''' <remarks></remarks>
    Public Sub DisplayOrderDetails(ByVal o As Order)
        If o IsNot Nothing Then
            Me.OrderList.LoadOrderDetails(o)
            Dim view = CollectionViewSource.GetDefaultView(Me.DataContext)
            view.MoveCurrentTo(o)

            Me.ListGrid.Visibility = Windows.Visibility.Visible
            Me.ListView1.SelectedIndex = -1
            Dim story = CType(Me.Resources("LoadingStoryBoard"), Animation.Storyboard)
            story.Begin()
        End If
    End Sub
    ''' <summary>
    ''' Sets the status message on the control
    ''' </summary>
    ''' <param name="msg"></param>
    ''' <remarks></remarks>
    Public Sub SetMessage(ByVal msg As String)
        Me.txtStatus.Text = msg
        Dim story = CType(Me.Resources("UpdateStoryBoard"), Animation.Storyboard)
        story.Begin()
    End Sub

End Class

Now we can create the Action Pane. Add a new item to the project and select Actions Pane Control from the Office group. I named it OrdersActionPane:

Now from the toolbox in the WPF Interoperability category you should see the ElementHost, drag that onto the Actions Pane user control, click the smart tag and select the WPFActionPane control as the hosted content and dock it in the parent container. I'm also going to set the font of the OrdersActionPane to Calibri 11 point.

In the code behind for the OrdersActionPane we need to set the OrderList for the WPF control as well as listen to position changed event on the OrderListBindingSource that is hooked up as the DataSource of the ListObject on Sheet1. When the position changes we need to tell the WPF control to display that Order's details. There are many ways to integrate WPF and Windows Forms to manage currency but we're trying to keep this example straightforward so we'll do it the easy way:

Imports System.Data.Services.Client
Imports NorthwindExcelClient.NorthwindService

Public Class OrdersActionsPane

    Private Sub OrdersActionsPane_Load() Handles Me.Load
        'Pass in our data source to the WPF control
        Me.WpfActionPane1.OrderList = NorthwindExcelClient.Globals.ThisWorkbook.OrderList
        'When the position changes in the spreadsheet, display the order details in the WPF control
        AddHandler NorthwindExcelClient.Globals.Sheet1.MyOrderListBindingSource.PositionChanged, _
                  AddressOf Me.DisplayOrderDetails
    End Sub

    Private Sub DisplayOrderDetails(ByVal sender As Object, ByVal e As EventArgs)
        Dim source = TryCast(sender, BindingSource)
        If source IsNot Nothing Then
            If source.Position > -1 Then
                Me.WpfActionPane1.DisplayOrderDetails(TryCast(source.Current, Order))
            End If
        End If
    End Sub
End Class

Finally we're almost ready to test this out. The last thing we need to do is load the Actions Pane when the application starts as well as expose a LoadOrders to our Sheet. This is because if we're adding charts, pivot tables or other types of controls for data analysis we can't rely on the Action Pane loading the data, we need the sheet to be able to call upon it explicitly. We also will hook up the Excel BeforeSave event so that we can call save on the orders. So back in the ThisWorkbook class:

   Private _orderActions As New OrdersActionsPane

    Private Sub ThisWorkbook_Startup(ByVal sender As Object, _
                                     ByVal e As System.EventArgs) Handles Me.Startup
        'Load the action pane
        Me.ActionsPane.Controls.Add(_orderActions)
    End Sub

    Public Sub LoadOrders()
        _orderActions.WpfActionPane1.LoadOrders()
    End Sub

    Private Sub ThisWorkbook_BeforeSave(ByVal SaveAsUI As Boolean, _
                                        ByRef Cancel As Boolean) Handles Me.BeforeSave
        _orderActions.WpfActionPane1.SaveOrders()
    End Sub
End Class

Hit F5 and try it out. You will see all the Orders that have not shipped. As you select a row, the details are displayed in the Action Pane and an animation that shows the Northwind logo fades into and out of view so that it catches the user's attention without annoying them ;-). Modify any of the fields in the Sheet and click save to save your changes back to the service.

Adding a Pivot Table and Chart

The final thing we want to do is add a pivot table and a pie chart to our Sheet that will display a breakdown of cities we're shipping to. In the designer for Sheet1 select the first cell and then go to the Insert tab. On the left select the arrow under the PivotTable and select PivotChart. A dialog will open which allows you to select the location of the PivotChart. Here I'm just adding it under the ListObject, it will automatically move down as orders come back from the data service.

Now you move into specifying the PivotTable fields and values through Excel like you normally would. Here I'm adding the ShipCity as both a label and a value, which automatically assumes a count. I also right-click on the chart and am allowed to change the chart type to a Pie Chart:

We're not quite done though. In order to get our PivotTable to update when the data is retrieved from the service we need to add some code to handle this. First name the PivotTable by right-clicking on it and selecting PivotTable Options -- I named it PivotTableShipCity. Now in the code behind we can handle the ListChanged event on the BindingSource which bubbles up what we're doing in our MyOrdersList class -- when we load the orders in the LoadOrders method, we raise the ListChangedEvent and pass a "Reset" parameter. Now we can check that here:

Private Sub MyOrderListBindingSource_ListChanged(ByVal sender As Object, _
            ByVal e As System.ComponentModel.ListChangedEventArgs) _
            Handles MyOrderListBindingSource.ListChanged

    If e.ListChangedType = System.ComponentModel.ListChangedType.Reset Then

        Dim table = TryCast(Me.PivotTables("PivotTableShipCity"), Excel.PivotTable)
        If table IsNot Nothing Then
            table.RefreshTable()
        End If
        Me.MyOrderListBindingSource.MoveFirst()

    End If
End Sub

Now when we hit F5 we will see the open orders come down into the spreadsheet and the pie chart will update to display our Excel data visualization. Nice!

I've updated our sample on Code Gallery with a new release that includes this Excel client so have a look.

Now that we understand what our shipping department is doing we can build out our SharePoint workflow. It will need to parse the purchase order using the code from part 3 and it will also need to update the order status based on the change made here to the ShippedDate field. We don't want our Excel client to be tightly coupled to SharePoint so we'll need to think about how we can achieve this all from our SharePoint Workflow. Until next time...

Enjoy!

OBA Part 3 - Storing and Reading Data in Word Documents

Beth Massi — Fri, 13 Feb 2009 04:55:33 GMT

In my last few posts we've been building a simple Office Business Application (OBA) for the new Northwind Traders. If you missed them:

In this post I'm going to talk about how we can create a purchase order in Word 2007 that contains data about the items being purchased and how we can query that data and place it into our database. We'll use this code as a basis for our SharePoint Workflow which we will build out in the next post.

This allows us to store the unstructured document on SharePoint and the structured order data in our database.

However before we build out the SharePoint Workflow we need a clean way to store and then retrieve the structured order data inside the Word 2007 document. Since Word 2007 documents are Open XML we can use the Open XML SDK and LINQ to XML to easily parse the document. (I've talked about how to manipulate documents with Open XML SDK before here.)

Content Controls

One way to store data in an Word 2007 document is by using content controls. These allow you to define specific data areas/fields in the document which are then bound to XML that is placed inside the document. When users enter data into these areas of the document the data is stored as a CustomXML Part inside the document. You can use Visual Studio to create content controls and map them to XML or you can use Word itself. There's also a nifty tool called the Word 2007 Content Control Toolkit that makes the mapping more visual. I'd also highly recommend installing the VSTO Power Tools as well which includes a VS Add-In for manipulating Open XML documents. This allows you to look inside the document easily to inspect all the parts directly within Visual Studio.

So the first thing to do is to create a purchase order template and lay out the content controls on the document. We'll create something very simple using Microsoft Word 2007. On the Developer tab you will see the Controls section. There you can choose which types of controls to lay out on the document. Click the properties button to assign a friendly title and tag to the control. Here I've laid out the minimum information we'll need to submit an order to the system:

Users can write anything else around the content controls but the system only cares about capturing the data we've specified. This gives us the ability to store structured and unstructured data completely inside the .docx file.

Creating and Mapping the XML

Now we are ready to map the values of the content controls to some custom XML. The XML document for our order looks like this. (Note that there are 10 <OrderDetail> elements I just snipped them for brevity):

<OrderEntry xmlns="urn:microsoft:examples:oba">
  <CustomerID />
  <OrderDate />
  <Shipper />
  <OrderDetails>
    <OrderDetail>
      <ProductName />
      <Quantity />
    </OrderDetail>
    <OrderDetail>...
  </OrderDetails>
</OrderEntry>

Now open up the Word 2007 Content Control Toolkit an open the OrderEntryTemplate.docx. Under Actions select "Create a new Custom XML Part", switch to edit view, and then paste in the XML:

Next switch to Bind View and then drag the elements onto the content controls on the left. Make sure you select the element first and then drag it.

Once you're done, save the document and then you can open it in Visual Studio if you've loaded the VSTO Power Tools. This will show the Open XML parts of the document and you can expand the customXml folder and see that our XML has been added to the document.

If you back into Word and fill out the content controls and then view the document in Visual Studio again, you will see that the item1.xml custom XML part will contain the data we entered.

Now that we have a purchase order template we can give this to our sales reps who can collaborate with our high volume customers via email to fill it out. They can then submit the purchase orders to a SharePoint list that can run a workflow to extract the order data and update the database through the data service.

Using the Open XML SDK to Retrieve the Order Data

The easiest way to programmatically manipulate Office 2007 Open XML documents is by using the Open XML SDK. Once you install it you can then Add Reference to the DocumentFormat.OpenXML assembly. In order to use LINQ to XML you'll also need a reference to System.Core and System.Xml.Linq. These are imported automatically when you create a new project in Visual Studio 2008. You'll also need to add a Service Reference to the ADO.NET Data Service like I've shown before. So let's start simple and just create a console application for now called NorthwindOrderDocParser. Later we'll talk about moving this to a SharePoint workflow.

Before we start parsing the document let's create a couple simple classes that store the data we're extracting from our document.

''' <summary>
''' These classes represents the order data that is inside the Word Document. 
''' </summary>
''' <remarks></remarks>
Public Class DocumentOrderData

    Sub New(ByVal customerID As String, ByVal orderDate As Date, ByVal shipperName As String)
        _CustomerID = customerID
        _OrderDate = orderDate
        _Shipper = shipperName
    End Sub

    Private _CustomerID As String
    Public Property CustomerID() As String
        Get
            Return _CustomerID
        End Get
        Set(ByVal value As String)
            _CustomerID = value
        End Set
    End Property

    Private _OrderDate As Date
    Public Property OrderDate() As Date
        Get
            Return _OrderDate
        End Get
        Set(ByVal value As Date)
            _OrderDate = value
        End Set
    End Property

    Private _Shipper As String
    Public Property Shipper() As String
        Get
            Return _Shipper
        End Get
        Set(ByVal value As String)
            If value Is Nothing OrElse value.Trim = "" Then
                value = "Speedy Express"
            End If
            _Shipper = value
        End Set
    End Property

    Private _details As New List(Of Detail)
    Public ReadOnly Property Details() As List(Of Detail)
        Get
            Return _details
        End Get
    End Property

    Public Class Detail
        Sub New(ByVal productName As String, ByVal quantity As Short)
            _ProductName = productName
            _Quantity = quantity
        End Sub

        Private _ProductName As String
        Public Property ProductName() As String
            Get
                Return _ProductName
            End Get
            Set(ByVal value As String)
                _ProductName = value
            End Set
        End Property

        Private _Quantity As Short
        Public Property Quantity() As Short
            Get
                Return _Quantity
            End Get
            Set(ByVal value As Short)
                _Quantity = value
            End Set
        End Property
    End Class
End Class

Next, let's add a schema for the OrderEntry XML data that is contained in the document. This will give us IntelliSense on our XML when we're using LINQ to XML. We can just open the document in Visual Studio like before and copy the OrderEntry XML data into the clipboard. Then we can Add a new XML to Schema Item and paste into the Wizard's dialog box. This will infer the schema and place the XSD file into the project automatically for us. Notice that I specified a namespace on our OrderEntry XML data. We now can import this namespace into our main program along with a few other .NET namespaces we'll need:

'Reference to our data service and data entities:
Imports NorthwindOrderDocParser.NorthwindService
'Open XML SDK:
Imports DocumentFormat.OpenXml.Packaging
Imports System.IO
'Default XML Namespace:
Imports <xmlns="urn:microsoft:examples:oba">

We are almost ready to start writing our main program to parse the purchase order. First we need a test document. For this test I filled out the following information in a document called MyTestOrder.docx.

Now we can write our main program:

Module Module1

    Sub Main()
        Try
            Dim docFile = My.Computer.FileSystem.GetFileInfo("MyTestOrder.docx")

            Dim docData As DocumentOrderData
            Using sr = docFile.OpenRead()
                'Attempt to parse the document for order data
                docData = ParseOrderDocument(sr)
                sr.Close()
            End Using

            If docData IsNot Nothing Then
                Dim employeeEmail = "sales@nwtraders.com"

                'Attempt to add the order data through the service
                AddNewOrder(docData, employeeEmail)
                Console.WriteLine("Order saved successfully.")
            Else
                Console.WriteLine("No order data was found in the document.")
            End If

        Catch ex As Exception
            Console.WriteLine("Order could not be processed." & vbCrLf & ex.ToString())
        End Try

        Console.ReadLine()
    End Sub

The ParseOrderDocument method is going to need to grab the XML data from our Custom XML parts as we iterate over the part collection. It's a collection because there can actually be many Custom XML definitions in our document. In order to make grabbing the XML data from the parts easier let's create an Extension method that extends the OpenXMLPart type. I like to place Extension methods in a separate file called Extensions.vb:

Imports DocumentFormat.OpenXml.Packaging
Imports System.IO
Imports System.Xml

Module Extensions

    ' Create an extension method so we can easily access the part XML
    <System.Runtime.CompilerServices.Extension()> _
    Function GetXDocument(ByVal part As OpenXmlPart) As XDocument
        Dim xdoc As XDocument

        Using sr As New StreamReader(part.GetStream())
            xdoc = XDocument.Load(XmlReader.Create(sr))
            sr.Close()
        End Using

        Return xdoc
    End Function
End Module

Now we can go back to our main Module1 and add a the ParseOrderDocument method. Notice that I'm using the Extension method we created in the For Each part... loop to return the custom XML as an XDocument. Then I use the child axis property <OrderEntry> (displayed in IntelliSense as I type the query) to see if the element exists. Also notice that since I imported our XML namespace at the top of the file it will only return an <OrderEntry> element in that namespace. So we're safe not to clash with other custom XML that may be added to the document by other processes.

''' <summary>
''' Attempts to parse the word document for order data and returns an order
'''  object with all the required. The document must have a customXML part 
'''  that adheres to the OrderEntry.xsd
''' </summary>
''' <param name="docStream">The document to parse</param>
''' <returns>The order data contained in the document</returns>
''' <remarks></remarks>
Function ParseOrderDocument(ByVal docStream As Stream) As DocumentOrderData
    Dim orderData As DocumentOrderData = Nothing

    Try
        'Use the Open XML SDK to open the document and access parts easily
        Dim wordDoc = WordprocessingDocument.Open(docStream, False)

        Using wordDoc
            'Get the main document part (document.xml)
            Dim mainPart = wordDoc.MainDocumentPart
            Dim docXML As XElement = Nothing

            'Find the order data custom XML part
            For Each part In mainPart.CustomXmlParts
                docXML = part.GetXDocument.<OrderEntry>.FirstOrDefault()
                If docXML IsNot Nothing Then
                    Exit For
                End If
            Next

            If docXML Is Nothing Then
                Throw New InvalidOperationException("This document does not contain order entry data.")
            End If

            'Grab the order data fields from the XML 
            Dim customerID = docXML.<CustomerID>.Value.Trim()
            Dim orderDate = docXML.<OrderDate>.Value.Trim()
            Dim shipper = docXML.<Shipper>.Value.Trim()

            If customerID <> "" AndAlso IsDate(orderDate) Then
                'Create and fill the DocumentOrderData  
                orderData = New DocumentOrderData(customerID, CDate(orderDate), shipper)

                For Each item In docXML.<OrderDetails>.<OrderDetail>
                    'Grab order details data fields
                    Dim product = item.<ProductName>.Value.Trim()
                    Dim quantity = item.<Quantity>.Value.Trim()

                    If product <> "" AndAlso IsNumeric(quantity) Then
                        'Add a new DocumentOrderData.Detail for each product found
                        orderData.Details.Add(New DocumentOrderData.Detail(product, CShort(quantity)))
                    End If

                Next
            End If
            wordDoc.Close()
        End Using

    Catch ex As Exception
        Throw New InvalidOperationException("Could not process this document.", ex)
    End Try

    Return orderData
End Function

Updating the Database through the Data Service

Now that we have our document parsed we're just left with adding the data through our data service. What we need to do is query the reference data (entities) that we'll need to properly associate on our Order. For instance Order will need a reference to the Customer, the Employee and the Shipper. Then each Order_Detail will need a reference to the Product entity. Notice that we're passing the employee email address into this method so that we can associate the sales rep with the order. If you recall we had to add this field to the Customer and Employee tables in Northwind. (For this test program I'm hard-coding the value but later we'll get this information from the Outlook client when it submits the order to SharePoint.)

Once we have these entities queried and returned from the service we can link them up properly and add our new Order and Order_Details to the data service. For more information on updating data and setting proper linkage to entities returned from an ADO.NET data service read this post and this one.

    ''' <summary>
    ''' Adds a new order through the ADO.NET Data service and sets up all the required
    ''' associations to related entities.
    ''' </summary>
    ''' <param name="docData">The order data</param>
    ''' <param name="employeeEmail">EmailAddress of sales representitve</param>
    ''' <remarks></remarks>
    Private Sub AddNewOrder(ByVal docData As DocumentOrderData, ByVal employeeEmail As String)

        Dim ctx As New NorthwindEntities(New Uri("http://localhost:1234/Northwind.svc/"))
        Dim cust As Customer
        Try
            'Try to retrieve the customer
            cust = (From c In ctx.Customers _
                     Where c.CustomerID = docData.CustomerID).FirstOrDefault()

        Catch ex As Exception
            Throw New InvalidOperationException("Invalid customer ID.")
        End Try

        If cust IsNot Nothing Then

            Dim ship = (From s In ctx.Shippers _
                        Where s.CompanyName = docData.Shipper).FirstOrDefault()

            'Email Address will come from our Outlook client/sales person 
            Dim emp = (From e In ctx.Employees _
                       Where e.EmailAddress = employeeEmail).FirstOrDefault()

            Dim o As New Order()

            o.OrderDate = docData.OrderDate
            o.RequiredDate = Now.AddDays(2)
            o.ShipAddress = cust.Address
            o.ShipCity = cust.City
            o.ShipCountry = cust.Country
            o.ShipName = cust.ContactName
            o.ShipPostalCode = cust.PostalCode
            o.ShipRegion = cust.Region
            o.Freight = 25

            ctx.AddToOrders(o)

            o.Customer = cust
            ctx.SetLink(o, "Customer", cust)

            If ship IsNot Nothing Then
                o.Shipper = ship
                ctx.SetLink(o, "Shipper", ship)
            End If

            If emp IsNot Nothing Then
                o.Employee = emp
                ctx.SetLink(o, "Employee", emp)
            End If

            o.Order_Details = New System.Collections.ObjectModel.Collection(Of Order_Detail)

            For Each item In docData.Details
                Dim productName = item.ProductName.ToLower()
                Dim product = (From p In ctx.Products _
                               Where p.ProductName.ToLower() = productName).FirstOrDefault()

                If product IsNot Nothing Then
                    'Create a detail for each product being ordered
                    Dim detail As New Order_Detail()
                    o.Order_Details.Add(detail)

                    detail.Quantity = item.Quantity
                    detail.UnitPrice = If(product.UnitPrice.HasValue, _
                                          product.UnitPrice.Value, 1D)

                    ctx.AddToOrder_Details(detail)

                    detail.Product = product
                    ctx.SetLink(detail, "Product", product)

                    detail.Order = o
                    ctx.SetLink(detail, "Order", o)

                    ctx.AddLink(o, "Order_Details", detail)
                End If
            Next
            'Saving in Batch mode will update the data inside a database transaction
            'This will throw an exception if the service can't save the Order
            ctx.SaveChanges(Services.Client.SaveChangesOptions.Batch)
        End If
    End Sub
End Module

When we run this program we will see that Customer ALFKI now has a new Order and 4 Order Details entered into the database. Since we're sending the updates in Batch mode this will cause our order data to be properly wrapped in a database transaction.

Next post we'll talk about how we can create a SharePoint workflow to run this code when order documents are added to a SharePoint list. However, if SharePoint is not a requirement of your system (maybe you have no need to collaborate on documents or store this unstructured data) you could easily add this code directly to the Outlook client we built in the previous post.

I updated the sample on Code Gallery with this project so have a look.

Enjoy!

OBA Part 2 - Building an Outlook Client against LOB Data

Beth Massi — Sun, 08 Feb 2009 01:36:00 GMT

In the last couple posts we've been talking about an Office Business Application (OBA) architecture for the new Northwind Traders and how to expose line-of-business (LOB) data, in our case the Northwind SQL database, using ADO.NET Data Services.

Today we're going to talk about how to build an Outlook Add-In that pulls the order history from the database through our data service when a customer email arrives in the inbox of our sales reps. This allows the sales reps to easily communicate current order status and product inventory with the customer without having to open up another program. That's the idea -- we're choosing to build a solution that is instantly familiar to our users since they already live in Outlook.

We're going to display the order history and inventory information in a WPF control in an adjoining form region so that it displays on the email item itself. It will display when the email opens or is displayed in the preview pane. We could have used a Windows Forms control but WPF is going to look a lot better. We want to match the blue color gradients that Outlook uses so that the control looks built in. Using WPF in Office solutions built with Visual Studio is really easy so let's get started.

The Outlook Add-in Project

I'm going to build upon the Visual Studio Solution that we started in the previous post when we built the data service. This solution also contains a database project that I'm using to keep the change scripts organized. If you recall we needed to add an EmailAddress field to Customers and Employees tables in Northwind. We also added some Customer and Employee data that specify the email addresses we are going to use to test the sample.

So just add a new project to the solution and select Office 2007 Outlook Add-In which is available in Visual Studio 2008 Professional and higher:

Next we need to add a service reference to the data service like I showed here when building a simple console app client. Right-click on the project, select Add Service Reference, click the "Discover" button and name the reference NorthwindService. This will generate the proxy code and entity types used by the data service. It will also add a reference to the System.Data.Services.Client assembly.

Building the Outlook Form Region

Now we'll add the Outlook Form region. Add new item to the project and select Outlook Form Region and name it EmailForm. When you click "Add", a dialog will appear that will ask you if you want to design a new region yourself or if you want to import one. Select "Design a new form region" and click Next. Then it asks you how you want the region to appear, whether it should be on it's own tab or adjoining or a complete replacement. We want to display the order and product information below the customer emails so select adjoining.

When we click next we are asked what the Name of the adjoining region should be -- this is displayed in the separator between the email and our control -- so I have specified "Order History". And since we only want to display order history on emails in read mode, uncheck the compose mode checkbox. Finally we are asked which message classes will display the form region. Keep the default selection which specifies all messages. Click finish and the designer will display an empty Windows Forms user control.

Let's test this out real quick, even though we haven't written any code. Set the Outlook client as the Startup Project and hit F5 and you will see Outlook open. Select any message in your inbox and notice that below the email you will see a blank form region labeled "Order History". However we don't want the form region to display for every email we get, only the Northwind customers. So what we'll do is write some code that checks the Northwind database for any email addresses coming into the inbox to see if they match our customers and only display the region in that case. Back on the EmailForm user control right-click and view code, you will see the following template already set up for you:

Imports Microsoft.Office.Tools.Outlook

Public Class EmailForm
#Region "Form Region Factory"
    <Microsoft.Office.Tools.Outlook.FormRegionMessageClass(FormRegionMessageClassAttribute.Note)> _
    <Microsoft.Office.Tools.Outlook.FormRegionName("NorthwindOutlookClient.EmailForm")> _
    Partial Public Class EmailFormFactory

        ' Occurs before the form region is initialized.
        ' To prevent the form region from appearing, set e.Cancel to true.
        ' Use e.OutlookItem to get a reference to the current Outlook item.
        Private Sub EmailFormFactory_FormRegionInitializing(ByVal sender As Object, _
                                                     ByVal e As FormRegionInitializingEventArgs) _
                                                     Handles Me.FormRegionInitializing
        End Sub
    End Class
#End Region
    'Occurs before the form region is displayed. 
    'Use Me.OutlookItem to get a reference to the current Outlook item.
    'Use Me.OutlookFormRegion to get a reference to the form region.
    Private Sub EmailForm_FormRegionShowing(ByVal sender As Object, _
                                      ByVal e As System.EventArgs) Handles MyBase.FormRegionShowing
    End Sub

    'Occurs when the form region is closed.   
    'Use Me.OutlookItem to get a reference to the current Outlook item.
    'Use Me.OutlookFormRegion to get a reference to the form region.
    Private Sub EmailForm_FormRegionClosed(ByVal sender As Object, _
                                     ByVal e As System.EventArgs) Handles MyBase.FormRegionClosed
    End Sub
End Class

The EmailFormFactory nested class is what creates the EmailForm and it gives us a chance to cancel showing the region. Here's where we need to write some code that gets the email address from the mail item and checks the database through the data service. In the FormRegionShowing event handler of the EmailForm we will pull down the Order History based on the customer address along with the Order_Details and related Products. Since we're going to need to get the EmailAddress as well as connect to the same data service in both event handlers, a good place to write global code is in the ThisAddIn class which is automatically created for you when you create the Add-in project.

Double-click on ThisAddIn in the Solution Explorer to open the code. You will see StartUp and ShutDown event handlers for the Add-In automatically generated for you. We don't need to add any code into these handlers. All we need to do is add a public property to the service reference for our data service as well as a function to extract the SMTP email address from the mail item. Note that I added an application setting to specify the location of the data service. During development this is going to be http://localhost:1234:/Northwind.svc but when we deploy the application we'll change it to the location of our production service:

Imports NorthwindOutlookClient.NorthwindService

Public Class ThisAddIn

    Private _ctx As NorthwindEntities
    Public ReadOnly Property DataServiceContext() As NorthwindEntities
        Get
            If _ctx Is Nothing Then
                'Specify the Service URI in the app.config via project settings.
                _ctx = New NorthwindEntities(New Uri(My.Settings.ServiceURI))
            End If
            Return _ctx
        End Get
    End Property

    ''' <summary>
    ''' Extracts the SMTP email address from the mail item.
    ''' </summary>
    ''' <param name="mailItem">the Outlook mail item</param>
    ''' <returns>The SMTP email address, otherwise empty string</returns>
    ''' <remarks></remarks>
    Public Function GetEmailAddress(ByVal mailItem As Outlook.MailItem) As String
        Dim recip As Outlook.Recipient
        Dim exUser As Outlook.ExchangeUser
        Dim emailAddress As String = ""

        Try
            If mailItem IsNot Nothing AndAlso mailItem.SenderEmailType IsNot Nothing Then
                ''get SMTP Address for the sender of this email
                If mailItem.SenderEmailType.ToLower = "ex" Then
                    recip = Globals.ThisAddIn.Application.GetNamespace("MAPI") _
                            .CreateRecipient(mailItem.SenderEmailAddress)

                    exUser = recip.AddressEntry.GetExchangeUser()
                    emailAddress = exUser.PrimarySmtpAddress
                Else
                    emailAddress = mailItem.SenderEmailAddress
                End If
            End If

        Catch ex As Exception
            emailAddress = ""
        End Try
        Return emailAddress
    End Function

    Private Sub ThisAddIn_Startup(ByVal sender As Object, _
                                  ByVal e As System.EventArgs) Handles Me.Startup
    End Sub

    Private Sub ThisAddIn_Shutdown(ByVal sender As Object, _
                                   ByVal e As System.EventArgs) Handles Me.Shutdown
    End Sub
End Class

Now back in the EmailFormFactory we can add this code to check if we should even be displaying the form region at all. If we don't want to show it, just set e.Cancel =True:

' Occurs before the form region is initialized.
' To prevent the form region from appearing, set e.Cancel to true.
' Use e.OutlookItem to get a reference to the current Outlook item.
Private Sub EmailFormFactory_FormRegionInitializing(ByVal sender As Object, _
                                                    ByVal e As FormRegionInitializingEventArgs) _
                                                    Handles Me.FormRegionInitializing
    Dim emailAddress As String = ""
    Dim ctx = NorthwindOutlookClient.Globals.ThisAddIn.DataServiceContext
    Try
        Dim mailItem = TryCast(e.OutlookItem, Outlook.MailItem)
        emailAddress = NorthwindOutlookClient.Globals.ThisAddIn.GetEmailAddress(mailItem)

        If emailAddress <> "" Then
            'Make sure the email address is actually in the database
            Dim customer = (From c In ctx.Customers _
                            Where c.EmailAddress = emailAddress).FirstOrDefault()

            If customer Is Nothing Then
                emailAddress = ""
            End If
        End If
    Catch ex As Exception
        'TODO: Error logging
        emailAddress = ""
    End Try

    e.Cancel = (emailAddress = "")
End Sub

Note that a service call could experience unexpected delays depending on where the data service is located. We may want to consider just displaying the form region and writing the calls to the service asynchronously. This is possible using the ADO.NET Data Services client as described in this article. For now, we'll keep this OBA sample simple and assume that the data service is located somewhere on our intranet.

Now that we have this code in place we can write the code that will specify a LINQ query to retrieve the order history in the EmailForm's FormRegionShowing handler. Notice I'm using the ".Expand" syntax in the query to pull in the related entities on the Order. Then I'm pulling the Product entity down for each of the Order_Detail entities so I can display inventory information. (We may want to consider only pulling orders within a date range for better scalability but here I'm pulling all of them down for the specified customer for simplicity.)

'Occurs before the form region is displayed. 
'Use Me.OutlookItem to get a reference to the current Outlook item.
'Use Me.OutlookFormRegion to get a reference to the form region.
Private Sub EmailForm_FormRegionShowing(ByVal sender As Object, _
                ByVal e As System.EventArgs) Handles MyBase.FormRegionShowing

    Dim emailAddress As String = ""
    Dim ctx = NorthwindOutlookClient.Globals.ThisAddIn.DataServiceContext
    Try
        Dim mailItem = TryCast(Me.OutlookItem, Outlook.MailItem)
        emailAddress = NorthwindOutlookClient.Globals.ThisAddIn.GetEmailAddress(mailItem)

        If emailAddress <> "" Then
            'pull the order history from the database
            Dim customerOrders = From o In ctx.Orders.Expand("Order_Details").Expand("Customer") _
                              Where o.Customer.EmailAddress = emailAddress _
                              Order By o.OrderDate Descending

            For Each order In customerOrders
                For Each detail In order.Order_Details
                    ctx.LoadProperty(detail, "Product")
                Next
            Next

            Dim ordersList As New List(Of Order)(customerOrders)
            'TODO: Set this ordersList as the DataContext of our WPF user control

        End If
    Catch ex As Exception
        'Could not connect to the service
        'TODO: Error logging
    End Try
End Sub

You also should notice that we still need to pass this list of Order entities that were returned from the data service into our WPF control -- but first we need to create it!

Building the WPF User Control

So let's add a new WPF User control via Add New Item (listed under WPF) -- I named it OrderHistory. This will show the WPF designer. The WPF User Control simply specifies just the UI in XAML of what the control should look like and sets up the data binding to the properties on our entities.

Here we've set up two ListViews that display Order and Order_Details and below that the Product inventory information along with an Image Control showing off the new Northwind logo. This control is really easy to data bind because of how the entity associations are specified in our data model. Order has Order_Details collection and Order_Detail has a Product reference. When the WPF User Control's DataContext property is set to the list of Orders, the data binding will take care of displaying the related data properly. Here's how we set up the data bound controls (styles omitted for clarity):

<UserControl x:Class="OrderHistory"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Height="300" Width="541" Name="OrderList" Grid.IsSharedSizeScope="True">
    <UserControl.Resources>
        <Style ...

    </UserControl.Resources>
<Grid>
<Grid.RowDefinitions>
    <RowDefinition Height="120" />
    <RowDefinition Height="160*" />
</Grid.RowDefinitions>
       
<ListView IsSynchronizedWithCurrentItem="True" 
          ItemsSource="{Binding}" Name="ListViewOrder" Margin="0,0,0,6" 
          Style="{StaticResource ListViewStyle}">
    <ListView.View>
        
        <GridView ColumnHeaderContainerStyle="{StaticResource ColumnHeaderStyle}">
            <GridViewColumn DisplayMemberBinding="{Binding Path=ShipName}" 
                            Width="200">Ship to</GridViewColumn>
            <GridViewColumn DisplayMemberBinding="{Binding Path=OrderDate, StringFormat='d'}" 
                            Width="100">Order Date</GridViewColumn>
            <GridViewColumn DisplayMemberBinding="{Binding Path=ShippedDate, StringFormat='d'}" 
                            Width="100">Ship Date</GridViewColumn>
            <GridViewColumn DisplayMemberBinding="{Binding Path=OrderTotal, StringFormat='c2'}" 
                            Width="100">Order Total</GridViewColumn>
        </GridView>
    </ListView.View>
</ListView>
    <Grid Grid.Row="1" Margin="0" Name="DetailsGrid" 
          DataContext="{Binding Path=Order_Details}">
        <ListView ItemsSource="{Binding}" Style="{StaticResource ListViewStyle}"
                  IsSynchronizedWithCurrentItem="True" Name="ListViewDetails" Margin="0,0,0,81">
            <ListView.View>
                <GridView ColumnHeaderContainerStyle="{StaticResource ColumnHeaderStyle}">
                    <GridViewColumn Header="Product" Width="300" 
                                    DisplayMemberBinding="{Binding Path=Product.ProductName}" />
                    <GridViewColumn Header="Quantity" Width="100" 
                                    DisplayMemberBinding="{Binding Path=Quantity, StringFormat='n0'}" />
                    <GridViewColumn Header="Unit Price" Width="100" 
                                    DisplayMemberBinding="{Binding Path=UnitPrice, StringFormat='c2'}" />
                </GridView>
            </ListView.View>
        </ListView>
        <Image Height="75" HorizontalAlignment="Right" Name="Image1" 
               Stretch="None" VerticalAlignment="Bottom" Width="75" 
               Source="northwindlogo75.gif" SnapsToDevicePixels="True" 
               StretchDirection="DownOnly" MinHeight="75" MinWidth="75" 
               MaxHeight="75" MaxWidth="75" ClipToBounds="True" />
        <StackPanel Height="75" Name="StackPanel1" VerticalAlignment="Bottom" Margin="0,0,81,0">
            <TextBlock Height="25" Name="txtProductName" Width="Auto"
                       Text="{Binding Path=Product.ProductName, 
                                      StringFormat=Inventory information for \{0\}}" />
            <TextBlock Height="25" Name="txtUnitsInStock" Width="Auto" 
                       Text="{Binding Path=Product.UnitsInStock, 
                                      StringFormat=Units in stock: \{0:n0\}}" />
            <TextBlock Height="25" Name="txtUnitsOnOrder" Width="Auto" 
                       Text="{Binding Path=Product.UnitsOnOrder, 
                                      StringFormat=Units on order: \{0:n0\}}"/>
        </StackPanel>
    </Grid>
</Grid>
</UserControl>

Notice that there is a field I'm binding to called OrderTotal on the Order entity however if you go back to the data model (Northwind.edmx in the NorthwindService project) you won't see this field coming from the database. That's because it's a calculated property on the Order entity on the client. You can extend the entities on the client using Partial Classes. All you have to do is right click on the project and select Add-->Class, call it Order, and then make sure you specify the proper namespace of the service reference:

Imports NorthwindOutlookClient.NorthwindService

Namespace NorthwindService

    Partial Public Class Order

        Private _total As Decimal = 0
        Public ReadOnly Property OrderTotal() As Decimal
            Get
                If _total = 0 Then
                    _total = Aggregate detail In Me.Order_Details _
                                Into Sum(detail.Quantity * detail.UnitPrice)                    
                End If
                Return _total
            End Get
        End Property
    End Class

End Namespace

Now that we have our WPF control all designed we are ready to add it to our form region. EmailForm is a Windows Forms user control so in order to add the WPF user control we need to first add an ElementHost control. This is found in the WPF Interoperability Tab on your toolbox. When you drop this control onto the designer you can immediately select the WPF user control to display, in our case it shows the OrderHistory control we just designed (if you don't see it, build the project first).

I also set it to dock in the parent container so it takes up the entire region and set the font of the EmailForm region to Calibri 11. Lastly we can add the line of code back in our EmailForm_FormRegionShowing handler to set the list of Orders we returned from our data service to the DataContext of the WPF user control:

Dim ordersList As New List(Of Order)(customerOrders)
'Set this ordersList as the DataContext of our WPF user control
Me.OrderHistory1.DataContext = ordersList

That should do it! To test this you need to make sure the email address you'll be using is in the database so you'll have to add some test data. When we run it we should see the adjoining form region at the bottom of our customer emails (click to enlarge):

One tip to remove the Outlook Add-in when you're done debugging is to select Build --> Clean Solution menu item in Visual Studio to unregister the Add-In.

I've uploaded the code that we've talked about so far in this series to Code Gallery so have a look. I'll continue adding releases to this as we build the other pieces of the OBA. Next post I'll show how we can create a purchase order in Word 2007 and use that to automatically feed Order data into the Northwind database.

Enjoy!

OBA Part 1 - Exposing Line-of-Business Data

Beth Massi — Wed, 04 Feb 2009 01:23:24 GMT

Last post I talked about the high-level architecture of our Office Business Application for the new Northwind Traders. There are a lot of different architecture options to consider when building an OBA. OBA is all about using Microsoft Office with your Line of Business (LOB) data. Whether that involves using SharePoint as well depends on the application. Since we wanted to store the unstructured data (the Northwind customer P.O.) SharePoint is a good fit here.

There are a lot of options when thinking about how to expose your LOB data. For instance, you may already have a service oriented architecture at the enterprise that exposes data contracts and processes that you can consume from Office clients. Or maybe you have a small business and have decided to expose a simple service that returns and consumes n-tier DataSets directly. Or you already have a custom LOB data entry system using custom business objects and you want to reuse the business layer in the Office client. OBA doesn't dictate how you expose this data. Because you can consume data in Office clients the same way you do in Windows apps the same types of decisions need to be made.

When we sat down to write the new Northwind Traders application we thought about how our data would need to behave and what would be the best way for all the pieces to easily update and query the Northwind database. Because there was only going to be simple validations needed on the data and mostly CRUD operations we opted to expose an Entity Data Model via ADO.NET Data Services like I showed before. This allowed us to get a secure service up and running in minutes.

We did make some minor changes to our old friend, the Northwind database. First, since we wanted to be able to look up order history for a customer when they emailed the sales reps, we needed to add an EmailAddress field to the Customers table (amazing that we didn't have that field before!). We also added it to the Employees table.

ALTER TABLE dbo.Customers ADD
    EmailAddress varchar(50) NULL
GO
ALTER TABLE dbo.Employees ADD
    EmailAddress varchar(50) NULL
GO

Then we populated the data with some customers and employees that were actually folks on our team because we need real email addresses to work with :-)

Next I created a new ASP.NET Web Application and added an ADO.NET Data Service and an Entity Data Model just like how I showed in this post. (You will need Visual Studio 2008 Service Pack 1 in order to get these new item templates.) For testing we set the service to allow full access to all the entities in the model -- we'll lock it down later. I also am passing detailed errors which we won't want to do once we're in production:

Public Class Northwind
    Inherits DataService(Of NorthwindEntities)

    ' This method is called only once to initialize service-wide policies.
    Public Shared Sub InitializeService(ByVal config As IDataServiceConfiguration)
        config.SetEntitySetAccessRule("*", EntitySetRights.All)
        config.UseVerboseErrors = True
    End Sub
End Class

One thing we did want to do is set up our data model so that it enforced constraints (i.e. there cannot be an Order without a Customer) but since some of our legacy data didn't specify all of these constraints we made the changes to the model instead, so that the integrity on all new data would be enforced through the service. This is often the case in projects, you cannot change the legacy databases but you still need to work with proper data models. So we changed the EDM so that all the entities were singular and not plural (Customer instead of Customers, Order instead of Orders, etc). We also changed the associations so that they were enforced and so that one to many collections were plural and the one-to-one were singular (i.e. Order has Order_Details collection and Order_Detail has Product reference). You can modify these from the Properties window of the Entity Data Model Designer.

Once I have the model and the data service code set up we can hit F5 and navigate our browser to the Northwind.svc and test the call to pull up all the customers (i.e. http://localhost:1234/Northwind.svc/Customers) just like how I showed in this post.

Now that we have our data exposed as a data service we can build the Office clients to interact with it just like I showed before here when we built a simple Excel client. Next post I'll show how we can use WPF controls in an Outlook Add-In in order to display the customer order history by querying the data through the data service.

Until next time...

Building an Office Business Application for TechReady 8

Beth Massi — Tue, 03 Feb 2009 03:09:00 GMT

The last week I've been working with a couple teammates on an Office Business Application (OBA) demonstration we wanted to put together for TechReady 8. TechReady is an internal conference we deliver to the field employees. It's my first one and so far it's been pretty fun. This morning Scott Hanselman hosted an "UnKeynote" that showcased a lot of the new stuff coming in Visual Studio 2010 that I can't talk about yet but believe me it was cool. ;-)

The application I helped build with Rachel and Mike on my team was a total blast. We wanted to demonstrate using Office as a client to Line-of-Business data as well as show some of the nifty features of SharePoint workflows. So we decided it was time to bring poor Northwind Traders into the 21st century. Here's what we came up with:

We needed a way to easily and securely expose our LOB data -- the Northwind database -- to the enterprise. So we created an entity data model against our SQL Server Northwind database and then exposed it using ADO.NET Data Services . The Northwind sales reps do all of their work in Outlook, communicating with our high-volume customers. So we built an Outlook Add-in that they can use to look up the customer order history from the database and easily work with purchase orders. The Add-in displays a form region with the customer order history in an adjoining area below when they open the email.

The orders are then submitted to a SharePoint document library as Word 2007 documents with XML data specified via content controls. A SharePoint Workflow then shreds this document data (using VB XML literals support and the Open XML SDK) and passes it to the ADO.NET data Service which persists the data in the database. This was written as a SharePoint sequential workflow.

We also built an Excel client for our shipping department to use that displays the orders that are ready to ship which allows them to update the ship date and save it back to through the data service. It also shows the products and quantities ordered in an Action Pane and does some data analysis using a pivot table and pie chart to show the breakdown of shipping cities and freight cost. We also used WPF user controls in the Outlook and Excel clients so that we could match the look-and-feel of Office.

Finally we created a web part for the SharePoint site that displays key performance indicators like oversold products and our top customer sales.

I have to say it was a very fun project to work on and I personally learned a lot about Excel and WPF as well as the OBA architecture. We spend about 3 days building this and I was pleasantly surprised how well the tools worked together. The pieces we built were predominantly in Visual Studio 2008 by Rachel and I and Mike handled the bleeding edge SharePoint parts.

In the next few blog posts I'll go into the details of building WPF user controls in the Excel and Outlook clients and how we exposed a simple, clean data model against the not-so-clean Northwind database. I'll also show the technique of how we easily stripped the order data out of the Word 2007 documents.

For now, some good links on OBA and VSTO development:

Until next time....

UPDATE - Here is the full set of articles and code: http://code.msdn.microsoft.com/OBANorthwind

ADO.NET Data Services - Building an Excel Client

Beth Massi — Fri, 23 Jan 2009 09:46:21 GMT

Last few posts I've been building a WPF client against ADO.NET Data Services, if you missed them:

Today I want to show a simple Excel client that queries our service and allows us to edit the customers in Northwind. I'm going to use Visual Studio 2008 (VSTO) to build a document-level customization against an Excel 2007 Workbook. We'll also build an Actions Pane that allows us to query and save customers to our ADO.NET data service. Excel's tabular data format lends itself well to CRUD database operations when we Add, Delete and Update rows in a Sheet. (NOTE: You cannot create Office solutions in Visual Studio Express editions.)

Setting Permissions on Customers

The first thing we need to do on our data service is allow access to the Customers entity set on our data model. In the first article I showed how to set up our service and permissions. For this example we'll be building upon the same data service we used for the WPF client which works with Product and Categories so I'll just need to add access to Customers:

Public Class Northwind
    Inherits DataService(Of NorthwindEntities)

    ' This method is called only once to initialize service-wide policies.
    Public Shared Sub InitializeService(ByVal config As IDataServiceConfiguration)
        config.SetEntitySetAccessRule("Products", EntitySetRights.All)
        config.SetEntitySetAccessRule("Categories", EntitySetRights.AllRead)
        config.SetEntitySetAccessRule("Customers", EntitySetRights.All)
    End Sub
...

Creating an Excel Client

Next we'll add the Excel 2007 project to the same solution we've been working on to make things simple for debugging. However, it's important to note that when we want to deploy the Excel (or WPF) client we should place the project into it's own solution. (For more information on deploying Office solutions, read this article.) You would also need to deploy the ADO.NET Data Service just like any other WCF Service to an IIS server first before deploying any clients.

Right-click on the solution and Add --> New Project then select the Office --> 2007 category on the left and choose the Excel 2007 Workbook project.

Next add the service reference to the data service by right-clicking on the Excel project and selecting Add Service Reference. This is exactly how we added the service reference to our WPF client which generates the client proxy and entity types for us.

Now add a New Item and select Actions Pane Control. This will open up the designer and we can add Windows Forms or WPF controls onto the pane. If we want to add WPF controls then first create a WPF user control and then add an ElementHost onto the pane and then you can specify which WPF user control to display. In this example all I'm going to need is a label, a couple textboxes and a couple buttons so I'm going to just use Windows Forms controls, nothing fancy here. The pane will allow the user to specify a filter on country and find customers that match as well as save changes back. I also added a multi-line, readonly textbox for status messages below the buttons.

We'll come back to the code for this actions pane after we set up our data source. The data source will be the list of customer entities returned from the service.

Tracking Changes on Customer Entities

Our actions pane is going to control how we query and save the customers. But instead of interacting with the service client proxy directly I'm going to create a class that inherits from a BindingList(Of Customer) so that we can also encapsulate the tracking of adds, updates and deletes of the customers that we bring down from the service. This class will also have a method to execute a customer query filtered by a specified country as well as a method to save changes. Finally we'll need to override some BindingList methods that will allow us to tell the data service client whether to add, update or delete as the customer entities are added to, updated or removed from the list.

Imports ExcelClient.NorthwindService
Imports System.ComponentModel

Public Class MyCustomerList
    Inherits BindingList(Of Customer)

    Private DataServiceContext As New NorthwindEntities(New Uri("http://localhost:1234/Northwind.svc"))
    Private _isAdding As Boolean
    Private _isSaving As Boolean
    Private _hasChanges As Boolean

    Public ReadOnly Property HasChanges() As Boolean
        Get
            Return _hasChanges
        End Get
    End Property

    ''' <summary>
    ''' Queries the customers from the ADO.NET Data Service 
    ''' and returns the number of customers returned in the results
    ''' </summary>
    ''' <param name="country">The country to use in the query filter</param>
    ''' <returns>number of customers returned from the service</returns>
    ''' <remarks></remarks>
    Public Function FillCustomersByCountry(ByVal country As String) As Integer
        Dim i = 0
        Dim customers = From c In DataServiceContext.Customers _
                        Where c.Country = country _
                        Order By c.CustomerID

        For Each c In customers
            Me.Add(c)
            i += 1
        Next
        Return i
    End Function

    ''' <summary>
    ''' Saves the customer changes back to the service.
    ''' </summary>
    ''' <returns>true if save was successful, otherwise an exception is thrown</returns>
    ''' <remarks></remarks>
    Public Function SaveChanges() As Boolean
        Dim saved As Boolean
        Try
            _isSaving = True
            Me.DataServiceContext.SaveChanges()
            _hasChanges = False
            saved = True
        Finally
            _isSaving = False
        End Try

        Return saved
    End Function

    Protected Overrides Function AddNewCore() As Object
        _isAdding = True
        Return MyBase.AddNewCore()
    End Function

    Protected Overrides Sub RemoveItem(ByVal index As Integer)
        Dim c = Me(index)
        Me.DataServiceContext.DeleteObject(c)
        _hasChanges = True
        MyBase.RemoveItem(index)
    End Sub

    Protected Overrides Sub OnListChanged(ByVal e As System.ComponentModel.ListChangedEventArgs)
        If Not _isSaving Then
            'The Customer partial class will need to implement 
            ' INotifyPropertyChanged for this will work
            If e.ListChangedType = ListChangedType.ItemChanged Then
                If _isAdding Then
                    Me.DataServiceContext.AddToCustomers(Me(e.NewIndex))
                    _isAdding = False
                Else
                    Me.DataServiceContext.UpdateObject(Me(e.NewIndex))
                End If
                _hasChanges = True
            End If
            MyBase.OnListChanged(e)
        End If
    End Sub

End Class

In order for the OnListChanged event to fire when a property on a customer entity is changed we will need to extend the partial class generated on the client. We'll need to Implement INotifyPropertyChanged and overwrite some partial methods just like we did to our product entity in the last post when we added validation. It's important to make sure the partial class is in the same namespace as the client service reference.

Imports ExcelClient.NorthwindService
Imports System.ComponentModel

Namespace NorthwindService

    Partial Public Class Customer
        Implements INotifyPropertyChanged

        Public Event PropertyChanged(ByVal sender As Object, ByVal e As PropertyChangedEventArgs) _
                     Implements INotifyPropertyChanged.PropertyChanged

        Private Sub FirePropertyChanged(ByVal propertyName As String)
            If propertyName <> "" Then
                RaiseEvent PropertyChanged(Me, New PropertyChangedEventArgs(propertyName))
            End If
        End Sub

        Private Sub OnAddressChanged()
            FirePropertyChanged("Address")
        End Sub

        Private Sub OnCityChanged()
            FirePropertyChanged("City")
        End Sub

        Private Sub OnCompanyNameChanged()
            FirePropertyChanged("CompanyName")
        End Sub

        Private Sub OnContactNameChanged()
            FirePropertyChanged("ContactName")
        End Sub

        Private Sub OnContactTitleChanged()
            FirePropertyChanged("ContactTitle")
        End Sub

        Private Sub OnCountryChanged()
            FirePropertyChanged("Country")
        End Sub

        Private Sub OnCustomerIDChanged()
            FirePropertyChanged("CustomerID")
        End Sub

        Private Sub OnFaxChanged()
            FirePropertyChanged("Fax")
        End Sub

        Private Sub OnPhoneChanged()
            FirePropertyChanged("Phone")
        End Sub

        Private Sub OnPostalCodeChanged()
            FirePropertyChanged("PostalCode")
        End Sub

        Private Sub OnRegionChanged()
            FirePropertyChanged("Region")
        End Sub
       
    End Class
End Namespace

Binding an Excel Sheet to the Customer List

Now that we have a way to track our customer entities we can work with them on an Excel Sheet by binding them to a ListObject control. First open up the data sources window (on the main menu select Data --> Show Data Sources) and then add a new data source and select the Object data source type. Then expand the ExcelClient.NorthwindService namespace and select the Customer object. Now open up Sheet1 in the project to open the Excel designer and drag the Customer onto the Sheet, this will create a ListObject control that is bound to a CustomerBindingSource.

Right-click on the sheet and View Code. All we need to do is set the CustomerBindingSource.DataSource property to an instance of our MyCustomerList. I'm going to make the list a public field of the Sheet so the Actions Pane can interact with it easily.

Public Class Sheet1

    Public CustomerList As New MyCustomerList()

    Private Sub Sheet1_Startup() Handles Me.Startup
        Me.CustomerBindingSource.DataSource = Me.CustomerList
    End Sub

End Class

Hooking Up the Actions Pane

In order to add an Actions Pane to an Excel Workbook we need to open up the Workbook code-behind so double-click on ThisWorkbook in the project and add the pane to the ActionPane.Controls collection like so:

Public Class ThisWorkbook

    Public CustomerActions As New CustomerActionsPane()

    Private Sub ThisWorkbook_Startup() Handles Me.Startup
        Me.ActionsPane.Controls.Add(Me.CustomerActions)
    End Sub

End Class

Now back in the CustomerActionsPane we can write code to interact with the CustomerList on Sheet1. We'll just add some code to the click event handlers of our buttons. First the Find button click handler will attempt to grab a reference to the CustomerList on Sheet1 and then it will call the FillCustomersByCountry method we created:

Public Class CustomerActionsPane

    Private Sub cmdFind_Click() Handles cmdFind.Click
        Dim msg = ""
        Try
            Dim searchTerm = Me.txtSearchTerm.Text.Trim()
            If searchTerm <> "" Then

                Dim list = ExcelClient.Globals.Sheet1.CustomerList
                Dim count = list.FillCustomersByCountry(searchTerm)

                msg = String.Format("{0} customers returned from server.", count)
            Else
                msg = "Please enter a country filter."
            End If

        Catch ex As Exception
            msg = ex.ToString
        End Try
        Me.txtStatus.Text = msg
    End Sub
...

Handling Exceptions from the Data Service

Next we need to write the code for our Save button click handler. Here we need to anticipate exceptions coming back from our database. By default we don't expose verbose exception details from our data service because this could give malicious hackers clues into the architecture of our service or worse our database structure. So what we get back from the ADO.NET data service is a DataServiceRequestException with a generic message. You can add additional information to this exception by overriding the HandleException method on the data service itself. For instance we could do something like this to return database exceptions:

Public Class Northwind
    Inherits DataService(Of NorthwindEntities)

    ' This method is called only once to initialize service-wide policies.
    Public Shared Sub InitializeService(...

    Protected Overrides Sub HandleException(ByVal args As HandleExceptionArgs)

        If args.Exception.InnerException IsNot Nothing Then
            If TypeOf args.Exception.InnerException Is SqlClient.SqlException Then
                'If we have config.UseVerboseErrors = True in the InitializeService
                ' then the InnerException (last parameter) will be serialized in detail
                ' including SQL message and full stack trace otherwise just the generic 
                ' message below will be returned. 
                args.Exception = New DataServiceException(args.ResponseStatusCode, _
                        TypeName(args.Exception.InnerException), _
                        "The database could not save the data. Check constraints.", _
                        "en-US", _
                         args.Exception.InnerException)

            End If
        End If
        'TODO: Log the exception
    End Sub
...

The message that is returned, however, is an XML document which contains different information depending on if we have config.UseVerboseErrors set to True in the InitializeService method or not. If we're not (the default) then the XML document returned from this handler would look like:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<error xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
    <code>SqlException</code>
    <message xml:lang="en-US">
         The database could not save the data. Check constraints.
    </message>
</error>

If we did have config.UseVerboseErrors = True in the InitializeService then the XML document would be:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<error xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
    <code>SqlException</code>
    <message xml:lang="en-US">
        The database could not save the data. Check constraints.
    </message>
    <innererror xmlns="xmlns">
        <message>
            The DELETE statement conflicted with the REFERENCE constraint "FK_Orders_Customers"...
        </message>
        <type>System.Data.SqlClient.SqlException</type>
        <stacktrace>
            at System.Data.SqlClient.SqlConnection.OnError(SqlException...full stack trace...
        </stacktrace>
    </innererror>
</error>

It's definitely not a good idea to return database details in error messages so make sure your production code does not have UseVerboseErrors set to True.

So back on our actions pane we can hook up the Save button click handler and write a few lines of code to extract any message from the XML. First we need to add an XML namespace Import because the error document declares a default namespace as seen above.

Imports System.Data.Services.Client
Imports <xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">

Public Class CustomerActionsPane

    Private Sub cmdFind_Click(...

    Private Sub cmdSave_Click() Handles cmdSave.Click
        Dim msg = "Customers could not be saved." & vbCrLf
        Try
            Dim list = ExcelClient.Globals.Sheet1.CustomerList

            If list.SaveChanges() Then
                msg = "Customers saved."
            End If

        Catch ex As DataServiceRequestException When ex.InnerException IsNot Nothing
            Try
                Dim xmlError = XElement.Parse(ex.InnerException.Message)
                msg &= xmlError.<message>.Value

            Catch ex1 As Exception 'message isn't xml, so display string
                msg &= ex.InnerException.ToString()
            End Try

        Catch ex As Exception
            msg &= ex.ToString
        End Try

        Me.txtStatus.Text = msg
    End Sub
End Class

Running the Excel Client

Now that we've got all our code written let's open up Fiddler and SQL Profiler and run this baby. After the Actions Pane opens we can click the Find button and the Customer list is populated and we can see it on our Sheet. From here we can add a new row or modify rows and the changes will be tracked in our list. We can also delete rows as well by right-clicking on the row and selecting Delete. (click image to enlarge)

Slick! Note that we will trigger a constraint violation if we attempt to delete a Customer that has Orders and this will cause our ExceptionHandler to return a generic message that is displayed in the status message area. We're not doing it in this example but you can opt to continue processing the rest of the changes by indicating that option in the SaveChanges method. In that case you'll get a DataServiceRespons object back that you can inspect for errors on the offending submissions. I'll expand on that in a follow-up post.

I've added a new Code Gallery sample so you can download it and play with the Excel client. It also includes the WPF client we built in the previous posts.

Enjoy!

ADO.NET Data Services - Intercepting Queries and Adding Validation

Beth Massi — Thu, 22 Jan 2009 07:53:00 GMT

Last few posts I've been building a WPF client against ADO.NET Data Services, if you missed them:

Today I want to show you how we can add validation or any other extra processing when data is queried from the data service as well as when we attempt to make changes to the data.

Ways of Querying a ADO.NET Data Service

First let's recap how we can query a data service. In our WPF client we've been taking advantage of LINQ but that's not the only way to send queries to the service. Because we're using the data service client framework we can write LINQ queries against the service and the client handles translating the queries into HTTP GETs. But we could also easily specify the raw URI's to send to the service. For instance, when we want to fill a combobox of categories ordered by CategoryName we could do this instead:

Imports System.Data.Services.Client
.
.
'Use the untyped DataServiceContext and pass URIs.
Dim ctx As New DataServiceContext(New Uri("http://localhost:1234/Northwind.svc"))
'Explicitly execute the the HTTP GET
Dim cats = ctx.Execute(Of Category)(New Uri("Categories?$orderby=CategoryName", UriKind.Relative))
'Display results in a combobox
Me.cboCategoryLookup.ItemsSource = cats.ToList()

In the code above the query is explicitly executed on the second line. You can achieve the same response by typing http://localhost:1234/Northwind.svc/Categories?$orderby=CategoryName in the address bar of your browser.

However one of the benefits of adding a service reference to our client is that it generates a proxy that inherits from the DataServiceContext that allows typed access to the entity sets that we're exposing from our service. This makes our code cleaner so we can write a LINQ query to do the same job instead:

Imports WpfClient.NorthwindService
.
.
Dim ctx As New NorthwindEntities(New Uri("http://localhost:1234/Northwind.svc"))

'Use LINQ to query the service instead
Dim cats = From c In ctx.Categories _
           Order By c.CategoryName

'Display results in a combobox. 
'The query is executed when we access the results (calling ToList())
Me.cboCategoryLookup.ItemsSource = cats.ToList()

Notice however that there is a subtle difference in this code that you should be aware of. When you write a LINQ query it never executes unless you access the results. In this case we're accessing the results when we call ToList() on the query. This is called deferred execution and it's something to be aware of. But if we look in Fiddler then we can see that the exact same HTTP GET is sent to the service: http://localhost:1234/Northwind.svc/Categories?$orderby=CategoryName

This also means that not every LINQ query can be translated into an HTTP GET. For instance, what if we just wanted to display a couple properties of the category in the combobox. You would think we'd be able to do something like this:

Dim cats = From c In ctx.Categories _
           Order By c.CategoryName _
           Select c.CategoryName, c.Description

Unfortunately if you try to do this you'll get a NotSupportedException thrown at you by the client framework because it can't translate the query into an HTTP GET. In this case you need to pull down the category entities you want first and then you can project over those to create a list of anonymous types with only the properties you specify. But remember that you need to "execute" the query against the service first and then query over the list that is returned. Here's a way to do this:

Dim cats = From c In ctx.Categories _
           Order By c.CategoryName

'Now project only the properties we want. 
' Call ToList() on the first query to execute the service call
Dim results = From c In cats.ToList() _
              Select c.CategoryName, c.Description

For more details on what is and isn't supported refer to this article.

Intercepting Queries

Now that we understand how queries work we can start messing with how they execute. :-) Say we want to query only the Products in Northwind that are not Discontinued. We could write the query against our data service that specified the filter like so:

Dim products = From p In ctx.Products _
               Where p.Discontinued = False _
               Order By p.ProductName

Or we could write the raw URI:

Dim productURI As New Uri("Products()?$filter=Discontinued%20eq%20false&$orderby=ProductName", _
                          UriKind.Relative)

Dim products = ctx.Execute(Of Product)(productURI)

But what if it was a new requirement of the entire system that nowhere should we be displaying discontinued products? If this is the case we should be enforcing this on our data service instead. This can be done using query interceptors on the service. The way we create these is we annotate a method on our service with the QueryInterceptor attribute. The method you write must follow these rules:

The method must have public scope and be annotated with the QueryInterceptorAttribute, taking the name of a entity set as a parameter.
The method must accept no parameters.
The method must return an expression of type System.Linq.Expressions.Expression(Of Func(Of T, Boolean)) that is the filter to be composed for the entity set.

The first two requirements are easy the third may be confusing if you've never played with lambda expressions. Basically what happens is you specify additional filtering to apply onto the incoming query via this lambda. So in order to append our condition that we should only be returning products that are not discontinued we can add this method to our data service:

Imports System.Data.Services
Imports System.Linq
Imports System.ServiceModel.Web
Imports System.Linq.Expressions

Public Class Northwind
    Inherits DataService(Of NorthwindEntities)

    ' This method is called only once to initialize service-wide policies.
    Public Shared Sub InitializeService(ByVal config As IDataServiceConfiguration)
        config.SetEntitySetAccessRule("Products", EntitySetRights.All)
        config.SetEntitySetAccessRule("Categories", EntitySetRights.All)
    End Sub

    <QueryInterceptor("Products")> _
    Public Function FilterProducts() As Expression(Of Func(Of Product, Boolean))
        'Only return products that are not discontinued
        Return Function(p) p.Discontinued = False
    End Function

End Class

Now we can write our queries without specifying the additional filter on discontinued and this will not be sent to the service from our client in the HTTP GET but will be executed against our database. The query interceptor will execute regardless if we write a LINQ query or feed it the raw URI.

LINQ Query:

Dim products = From p In ctx.Products Order By p.ProductName
Me.ListView1.ItemsSource = products.ToList()

URI:

Dim productURI As New Uri("Products()?$orderby=ProductName", UriKind.Relative)
Dim products = ctx.Execute(Of Product)(productURI)
Me.ListView1.ItemsSource = products.ToList()

Pretty slick. You could of course do other processing here first. And you can also specify your own additional service operations as well by attributing them with a <WebGet> attribute. More on those in a later post.

Validation with Change Interceptors

You can also add methods to your service that will execute when changes are submitted. This allows us to add validation or other processing onto the data being submitted to the database. You do this by attributing a method in the data service with the ChangeInterceptor attribute. A change interceptor will pass the entity being saved and a parameter that indicates what update operation is being performed. For instance, say we want to put a validation on our ProductName so that users cannot submit empty product names to the database. We could write a method in our data service like so:

<ChangeInterceptor("Products")> _
Public Sub OnChangeProducts(ByVal p As Product, ByVal ops As UpdateOperations)
    If ops = UpdateOperations.Add OrElse ops = UpdateOperations.Change Then
        'Do not allow products with empty names
        If p.ProductName = "" Then
            Throw New DataServiceException(400, "Product name cannot be empty")
        End If
    End If
End Sub

When we throw a DataServiceException we can specify the HTTP status code and the message to return to the client. 400 indicates "Bad Request" and we pass the message on what the problem was. So if we try to submit a new or existing product with no product name we will get an HTTP error as seen in Fiddler:

This is what's happening on the wire when we call SaveChanges and the exception is caught on the client. This prevents our data from being invalid no matter what client it's coming from. However this isn't that user-friendly to say the least. If we're building a smart client it's much better to put this type of validations on the client as well.

We can do this in our WPF client by extending the Product partial class and implementing IDataErrorInfo and adding our validation. On the WPF client create a new class called Product and place it in the same exact namespace as the NorthwindEntities data service client proxy that is generated for us when we add the service reference. It's called NorthwindService in our case. Then we can overwrite the partial method OnProductNameChanging to do the client-side validation. This method is called from the ProductName property setter in the generated entity on the client. Here's an example of how we can collect validation messages on the Product.

Imports WpfClient.NorthwindService
Imports System.ComponentModel

Namespace NorthwindService

    Partial Public Class Product
        Implements IDataErrorInfo

        Private Sub OnProductNameChanging(ByVal value As String)
            If value Is Nothing OrElse value.Trim = "" Then
                Me.AddError("ProductName", "Product name cannot be empty")
            Else
                Me.RemoveError("ProductName")
            End If
        End Sub

#Region "IDataErrorInfo Members"
        Private m_validationErrors As New Dictionary(Of String, String)

        Private Sub AddError(ByVal columnName As String, ByVal msg As String)
            If Not m_validationErrors.ContainsKey(columnName) Then
                m_validationErrors.Add(columnName, msg)
            End If
        End Sub

        Private Sub RemoveError(ByVal columnName As String)
            If m_validationErrors.ContainsKey(columnName) Then
                m_validationErrors.Remove(columnName)
            End If
        End Sub

        Friend ReadOnly Property HasErrors() As Boolean
            Get
                Return (Me.Error IsNot Nothing)
            End Get
        End Property

        Friend ReadOnly Property [Error]() As String _
                                 Implements System.ComponentModel.IDataErrorInfo.Error
            Get
                If m_validationErrors.Count > 0 Then
                    Return "Product Data is invalid"
                Else
                    Return Nothing
                End If
            End Get
        End Property

        Default Friend ReadOnly Property Item(ByVal columnName As String) As String _
                                         Implements System.ComponentModel.IDataErrorInfo.Item
            Get
                If m_validationErrors.ContainsKey(columnName) Then
                    Return m_validationErrors(columnName).ToString
                Else
                    Return Nothing
                End If
            End Get
        End Property
#End Region

    End Class

End Namespace

Notice that the client-side IDataErrorInfo properties are declared as Friend (internal) so that they are not serialized back up to the server. Next we need to make sure the bindings in the XAML of our ProductDetail form is set up to display the error.

<TextBox 
 Text="{Binding Path=ProductName, ValidatesOnDataErrors=True}"
 Height="25" Name="TextBox1" Width="180" Margin="3" HorizontalAlignment="Left" />

You can also add a validation ErrorTemplate if you like. I've shown this validation technique with WPF here before. So when we don't enter the ProductName on a product we can display the problem to the user right away without bothering our data service:

Check out the updated sample on Code Galley, in there I also implement IEditableObject so that users can cancel out of editing of the products.

However, the fact that we have to put rules in two locations in our code is a total drag. If we could type share the entity partial classes on the server and the client then we could write this code in one place and run it in both the client and the server. This is why if you have complex business rules you're probably better off creating your own DataContracts and implementing your own WCF services. However, applications like this that have simple validation and heavy CRUD requirements make it a perfect candidate to use ADO.NET Data Services.

Next post I'll show how we can query and edit tabular data inside of an Excel client and post changes back to the data service.

Enjoy!

ADO.NET Data Services - Enforcing FK Associations and a Fix for Deleting Entities

Beth Massi — Wed, 21 Jan 2009 06:15:00 GMT

Last post I described one way to build a smart client in WPF against ADO.NET Data Services. In this example we are editing the products table and associating them to categories in the categories table from Northwind. In the Northwind database the CategoryID on the Products table allows nulls so that you can have products that do not necessarily belong to a category. More common, however, are associations that are required and enforced by not allowing nulls in the foreign keys in the database. If we make a change to our Northwind data model to enforce this we will encounter errors when we try to save the data back to the service.

Enforcing Foreign Key Constraints

Let me show you what I mean by changing the example to enforce that products belong to a category. Open up the Northwind data model in the designer and select the FK_Products_Categories association and change the multiplicity property on the category end to 1 (One) and then save the model and build the service. Then make sure to update the service reference on the client and rebuild again (under the client project expand Service References then right-click on the reference and choose Update Reference).

If we tried to use the original code sample against this new data model we would have problems. When we run the client and make a change to a product and associate a new category we would get the error: A relationship is being added or deleted from an AssociationSet 'FK_Products_Categories'. With cardinality constraints, a corresponding 'Products' must also be added or deleted. This is a problem because the Data Services client was trying to delete the link to the category on the product first and then update the product after that.

If we tried to add a new product it would have also failed: Entities in 'NorthwindEntities.Products' participate in the 'FK_Products_Categories' relationship. 0 related 'Categories' were found. 1 'Categories' is expected. This is a problem because the client data service is attempting to add a new product with no associated category (if you look in the request header you will not see the category reference). Now that we've changed the model these situations are not allowed so they fail.

In order to fix them I had to make a couple code changes. First we need to change how we were setting the category association. Instead of calling DeleteLink and AddLink on the Category entity we need to call SetLink on the Product entity instead. In fact, this will work regardless if we are enforcing the association exist or not so it's best to use this when setting 1..1 associations (and it makes a lot more sense to me as well). Because of this I updated the previous post and the code sample on code gallery with this new code. So when we edit our Product we need to change our code to this:

Dim p As Product = CType(Me.ProductView.CurrentItem(), Product)
If p IsNot Nothing Then

    Dim frm As New ProductDetail()
    frm.Product = p
    frm.CategoryList = Me.CategoryLookup
    Dim oldCategory = p.Category

    If frm.ShowDialog() Then 'changes were made 
        Dim newCategory = p.Category

        'If the category was changed, set the new link
        ' then set the product state to updated
        With Me.DataServiceClient
            If (newCategory IsNot oldCategory) Then

                .SetLink(p, "Category", newCategory)

                'This will not work if we are enforcing the FK to 
                ' Category from Product. Use SetLink instead
                '.DeleteLink(oldCategory, "Products", p)
                '.AddLink(newCategory, "Products", p)
            End If
            .UpdateObject(p)
        End With
.
.
.

When we add new Products we also need to call SetLink after we add the new Product:

'Add a new Product to the List
Dim p As Product = CType(Me.ProductView.AddNew(), Product)
p.ProductName = "New Product"

'Create our detail form and setup the data 
Dim frm As New ProductDetail()
frm.Product = p
frm.CategoryList = Me.CategoryLookup

If frm.ShowDialog() Then 'OK
    Me.ProductView.CommitNew()
    Dim newCategory = p.Category

    'Add a new product and set the association to the parent Category
    With Me.DataServiceClient
       .AddToProducts(p)
       .SetLink(p, "Category", newCategory)

       'This will not work if we are enforcing the FK to 
       ' Category from Product. Use SetLink instead
       '.AddLink(newCategory, "Products", p)
   End With
.
.
.

The rule of thumb is AddLink is used when we are modifying the 1...many or many...many relationships on an entity and SetLink is used to modify a 1..1 relationship as in the case of our example. Check out this blog post which should help clear up when to use SetLink versus AddLink.

Deleting Entities Involved in an Association

You may have issues deleting entities that are involved in an association (regardless of whether they are enforced or not). This was a bug in ADO.NET Data Services described in KB958484 and is fixed with this update. (This should be flowing along with your regularly scheduled Windows Updates but you may not have gotten it yet so if you're experiencing this issue make sure you install this fix.) In our example I was forced to detach the category object from the client context before submitting the deletes.

Dim p As Product = CType(Me.ProductView.CurrentItem(), Product)
If p IsNot Nothing Then

    With Me.DataServiceClient
        .Detach(p.Category)
        .DeleteObject(p)
    End With

    Me.ProductView.Remove(p)
End If

Unfortunately this has side effects when working in batch like we've set up on our form. If I then added or edited another product but chose the same category that was on a product that I deleted, then I would get an InvalidOperationException on the client: The context is not currently tracking the entity. This is because I detached the category when I shouldn't have. But if I don't detach the category before deleting the product then I get another error, this time an XMLException: Root element is missing. Note, that if we didn't bring down the associated category for each product then this would work fine. It only happens when we have an association.

Once you install the update this bug will be fixed and the correct code should be to just call .DeleteObject:

    With Me.DataServiceClient
       .DeleteObject(p)
    End With

This means that we can enable batching and add/update/delete products at will and submit them all at once in one call.

Try
    'Batching will wrap all changes submitted into a transaction
    Me.DataServiceClient.SaveChanges(System.Data.Services.Client.SaveChangesOptions.Batch)
    MsgBox("Your data was saved")
Catch ex As Exception
    MsgBox(ex.ToString())
End Try

Notice that when we batch save our changes we also get a database transaction. In your own applications you should determine if the set of data you are submitting to the server should be wrapped in a transaction or not (click image to enlarge).

Products aren't reliant on each other so in this example it's probably overkill. You should evaluate your sets of data carefully to ensure the right level of isolation is needed. I updated the sample on Code Gallery for you to play with.

You may be asking "Why doesn't the data services client do all this association linking for me automatically?" The reason I've gleaned from a few folks is that the team wanted the framework to be very simple and work with POCO (Plain Old CLR Objects) with no extra overhead. That said, there is a line of practicality here so they are looking into extending this in future versions. I'd like to also see the ability to extend the entities and add additional business functionality and properties not backed by database fields to them as well. That would make ADO.NET Data Services my data access layer of choice for general purpose n-tier smart client business applications.

Okay, so now that we have CRUD working properly in all our scenarios in the next post (soon) I'll show how we can intercept queries and change operations in order to do some additional processing -- I know I said that last post but this time I mean it ;-).

Enjoy!

ADO.NET Data Services - Building a WPF Client

Beth Massi — Fri, 16 Jan 2009 07:30:00 GMT

In my last post I introduced ADO.NET Data Services and how you can easily expose your data model via RESTful services that support the basic CRUD (Create,Retrieve,Update,Delete) operations. Basic CRUD database operations map well to the familiar HTTP verbs POST, GET, MERGE, DELETE and the framework takes care of the plumbing for us. In this post I'm going to build a simple WPF client that shows how to work with the client piece of the framework which resides in the System.Data.Service.Client namespace.

The ADO.NET Data Service

Based on the previous example, our data service exposes the Northwind data model that I created as an Entity Data Model generated from the database. The only thing I've done to the Entity Model is I've changed the Categories navigation property on the Product to singular (since a product can only have one category) as well as the names of the entities themselves and the entity sets to plural like so:

We're going to build a client that allows us to do CRUD operations on the Products data so I'm going to allow full access to that entity set. And since products must belong to a category in Northwind, we need to be able to associate them when we are editing the products. Therefore I'll need to retrieve a list of categories for our lookup list so I've enabled read access on the Categories entity set. So here's what our data service looks like in the Northwind.svc:

Imports System.Data.Services
Imports System.Linq
Imports System.ServiceModel.Web

Public Class Northwind
    Inherits DataService(Of NorthwindEntities)

    ' This method is called only once to initialize service-wide policies.
    Public Shared Sub InitializeService(ByVal config As IDataServiceConfiguration)
        config.SetEntitySetAccessRule("Products", EntitySetRights.All)
        config.SetEntitySetAccessRule("Categories", EntitySetRights.AllRead)
        ' Return verbose errors to help in debugging
        config.UseVerboseErrors = True
    End Sub

End Class

Simple stuff. Next I'm going to add a new project to the solution and select WPF application. Then we need to add a Service Reference to the data service exactly how I showed in the previous post when I created the client console application in that example. This step will add a reference to the client framework (System.Data.Services.Client) as well as generate the proxy code for our model.

This is something to be aware of. At this time ADO.NET Data Services cannot type share the entities so you end up having client types and server types. Because of this, ADO.NET Data Services are not meant to replace a real business object layer (yet). So if you have complex business rules you want to share on the client and server you are better off writing your own WCF services and data contracts. However, if you have simple CRUD and validation requirements or are looking for a remote data access layer for applications where business rules and validations are processed predominantly on the server (like web or reporting or query-heavy applications) then ADO.NET Data Services are a great fit. And no one is stopping you from using both your own WCF services in addition to ADO.NET data services in your client applications.

Building the WPF Client

Now it's time to build out some UI. We're going to have two forms, one for displaying the list of products by category which will allow you to modify them and another form that will open when editing or adding the product details. First let's build the ProductList form. I want to make the user pick a category before I pull down the products so I've got a combobox I'll need to populate with the list of categories available and a search button to execute the query to the data service. Under that I have a ListBox with it's View set to a GridView and I've defined the binding to a few of the product properties to show up in the columns. Under that is the buttons we'll use to make changes to the data; Edit, Add, Delete and Save. Here's the XAML

<Window x:Class="ProductList"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Title="Northwind Traders" Height="385" Width="533" Name="ProductList">
<Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="50*" />
        <RowDefinition Height="198*" />
        <RowDefinition Height="44*" />
    </Grid.RowDefinitions>
    <ListView 
        ItemsSource="{Binding}"
        IsSynchronizedWithCurrentItem="True" 
        Grid.Row="1" Name="ListView1" Margin="0,4,0,0">
        <ListView.View>
            <GridView>
                <GridViewColumn Header="Product Name" Width="200" 
                          DisplayMemberBinding="{Binding Path=ProductName}" />
                <GridViewColumn Header="Category" Width="150" 
                          DisplayMemberBinding="{Binding Path=Category.CategoryName}" />
                <GridViewColumn Header="Price" Width="70" 
                          DisplayMemberBinding="{Binding Path=UnitPrice, StringFormat='c2'}" />
                <GridViewColumn Header="Units" Width="70"  
                          DisplayMemberBinding="{Binding Path=UnitsInStock, StringFormat='n0'}" />
            </GridView>
      </ListView.View>
    </ListView>
    <GroupBox Header="Search Products" Margin="0,0,3,0" Name="GroupBox1" >
        <Grid>
            <ComboBox Margin="90,6,199,0" Height="26" VerticalAlignment="Top" 
                      Name="cboCategoryLookup"  DisplayMemberPath="CategoryName" 
                      IsSynchronizedWithCurrentItem="True" />
            <Label HorizontalAlignment="Left" HorizontalContentAlignment="Right" 
                   Margin="6,6,0,0" Name="Label1" Width="78" Height="26" 
                   VerticalAlignment="Top">Category:</Label>
            <Button HorizontalAlignment="Right" Margin="0,5.98,132,0" Width="64" Height="26" 
                    VerticalAlignment="Top"
                    Name="btnSearch" >Search</Button>
        </Grid>
    </GroupBox>
    <Button Name="btnAdd" 
            HorizontalAlignment="Right" Margin="0,0,143,12" 
            Width="64" Grid.Row="2" Height="26" 
            VerticalAlignment="Bottom" >Add</Button>
    <Button Name="btnDelete" 
            HorizontalAlignment="Right" Margin="0,0,73,12" 
            Width="64" Grid.Row="2" Height="26" 
            VerticalAlignment="Bottom" >Delete</Button>
    <Button Name="btnEdit" 
            HorizontalAlignment="Right" Margin="0,0,213,12" 
            Width="64" Grid.Row="2"  Height="26" 
            VerticalAlignment="Bottom" >Edit</Button>
    <Button Name="btnSave" 
            HorizontalAlignment="Right" Margin="0,0,3,12" 
            Width="64" Grid.Row="2" Height="26" 
            VerticalAlignment="Bottom" >Save</Button>
</Grid>
</Window>

Notice how we set up the binding to display the category for the product. Each product has a parent category that is accessed through the Category navigation property on the Product entity as defined in our Entity Data Model. This is how we traverse the association so that we can get at the CategoryName on the category entity that is associated with the product.

Before we can write our queries against our data service we will need to set up a few class-level variables to keep track of the data service client proxy, the list of products and categories and the products' CollectionView. Note that you need to supply the URI to the service when you create the instance of the client proxy. (I've hard-coded it here for clarity but in a real app this should be in your My.Settings so that you can change it after deployment.)

Imports WpfClient.MyDataServiceReference

Class ProductList

   Private DataServiceClient As New NorthwindEntities(New Uri("http://localhost:1234/Northwind.svc"))
   Private Products As List(Of Product)
   Private CategoryLookup As List(Of Category)
   Private ProductView As ListCollectionView

Querying the Data Service Using LINQ

Now we can write some code in our Loaded event handler to query the list of categories from our data service and populate the Category combobox. We can write a LINQ query over the DataServiceClient proxy and it will handle translating the call to the RESTful data service.

Private Sub Window1_Loaded() Handles MyBase.Loaded

    'Grab the list of categories and populate the combobox
    Me.CategoryLookup = (From c In Me.DataServiceClient.Categories _
                         Order By c.CategoryName).ToList()

    Me.cboCategoryLookup.ItemsSource = Me.CategoryLookup
    Me.cboCategoryLookup.SelectedIndex = 0
End Sub

Let's open up Fiddler and SQL Profiler and see what happens when we run it. (Note: to run localhost web calls through Fiddler I changed the URI to http://ipv4.fiddler:1234/Northwind.svc. See this page for details.)

What we're looking at is our form with the categories ordered by their name. Then we have Fiddler showing the HTTP Get request header and the RSS Atom feed response containing the categories. Notice how the LINQ query is automatically translated to the GET /Northwind.svc/Categories()?$orderby=CategoryName and passed as a query against our IQueryable Entity Data Model. The Entity Framework handles the communication to SQL Server. You can see the SQL query in SQL Profiler.

It's important to note that since LINQ queries on the client need to be translated to HTTP GETs by the framework not every extension method you see available in IntelliSense will work. It also may be impossible to write complex sub-queries. In those cases you may need to write a simpler queries, convert them to in-memory collections like a List and then write additional queries over the in-memory collections. Take a look at the middle of this article for a list of supported operations.

Now that we have the list of Categories to choose from we can handle the Search button's click event and write the query to bring down the related Products. Since we want to be able to edit their details, including associating a parent Category, we need to explicitly load the Category property on the Product entity which is a reference to the parent Category entity. We then populate a simple List with the results and set up the binding on the form by setting the Window's DataContext.

Private Sub btnSearch_Click() Handles btnSearch.Click
    'Get the selected category from the combobox
    Dim category = CType(Me.cboCategoryLookup.SelectedItem, Category)

    'Return all the products for that category ordered by ProductName
    Dim results = From p In Me.DataServiceClient.Products.Expand("Category") _
                  Order By p.ProductName _
                  Where p.Category.CategoryID = category.CategoryID

    'Populate the Products list 
    Me.Products = New List(Of Product)(results)
    'Set the DataContext of the Window so controls will bind to the data
    Me.DataContext = Me.Products
    'Grab the CollectionView so that we can use it to add and remove items from the list
    Me.ProductView = CType(CollectionViewSource.GetDefaultView(Me.DataContext), ListCollectionView)

End Sub

The .Expand("Category") syntax above is what loads the parent Category entity onto the Product. Now when we run the form and hit the Search button the list of Products is populated.

Creating the Product Detail Form

Now we need to create a form that will allow us to edit or add the details of a Product. We're going to call this form up from the Edit and Add buttons at the bottom of the ProductList form. I've created a simple one that has a couple stack panels, one with labels and one with the data bound controls, and an OK and Cancel button. Here's the XAML:

<Window x:Class="ProductDetail"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Title="Product Details" Height="318" Width="353">
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="243*" />
            <RowDefinition Height="42*" />
        </Grid.RowDefinitions>
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="114*" />
            <ColumnDefinition Width="218*" />
        </Grid.ColumnDefinitions>
        <StackPanel Name="StackPanel1">
            <Label Height="25" Name="Label1" Width="Auto" 
                   HorizontalContentAlignment="Right" Margin="3">Product Name:</Label>
            <Label Height="25" Name="Label2" Width="Auto" 
                   HorizontalContentAlignment="Right" Margin="3">Category:</Label>
            <Label Height="25" Name="Label3" Width="Auto" 
                   HorizontalContentAlignment="Right" Margin="3">Quantity per Unit:</Label>
            <Label Height="25" Name="Label4" Width="Auto" 
                   HorizontalContentAlignment="Right" Margin="3">Unit Price:</Label>
            <Label Height="25" Name="Label5" Width="Auto" 
                   HorizontalContentAlignment="Right" Margin="3">Units in Stock:</Label>
            <Label Height="25" Name="Label6" Width="Auto" 
                   HorizontalContentAlignment="Right" Margin="3">Units on Order:</Label>
            <Label Height="25" Name="Label7" Width="Auto" 
                   HorizontalContentAlignment="Right" Margin="3">Reorder Level:</Label>
        </StackPanel>
        <StackPanel Grid.Column="1" Name="StackPanel2">
            <TextBox 
                Text="{Binding Path=ProductName}"
                Height="25" Name="TextBox1" Width="180" Margin="3" HorizontalAlignment="Left" />
            <ComboBox 
                Name="cboCategoryLookup" 
                Height="25" Width="180" Margin="3" HorizontalAlignment="Left" IsEditable="False" 
                DisplayMemberPath="CategoryName" 
                SelectedValuePath="CategoryID"
                SelectedValue="{Binding Path=Category.CategoryID, Mode=OneWay}"/>
            <TextBox 
                Text="{Binding Path=QuantityPerUnit}"
                Height="25" Name="TextBox2" Width="180" Margin="3" 
                HorizontalAlignment="Left" />
            <TextBox 
                Text="{Binding Path=UnitPrice}"
                Height="25" Name="TextBox3" Width="84" Margin="3" 
                HorizontalAlignment="Left" HorizontalContentAlignment="Right" />
            <TextBox 
                Text="{Binding Path=UnitsInStock}"
                Height="25" Name="TextBox4" Width="84" Margin="3" 
                HorizontalAlignment="Left" HorizontalContentAlignment="Right" />
            <TextBox 
                Text="{Binding Path=UnitsOnOrder}"
                Height="25" Name="TextBox5" Width="84" Margin="3" 
                HorizontalAlignment="Left" HorizontalContentAlignment="Right" />
            <TextBox 
                Text="{Binding Path=ReorderLevel}"
                  Height="25" Name="TextBox6" Width="84" Margin="3" 
                HorizontalAlignment="Left" HorizontalContentAlignment="Right" />
            <CheckBox 
                IsChecked="{Binding Path=Discontinued}"
                Height="16" Name="CheckBox1" Width="120" 
                HorizontalAlignment="Left" Margin="3">
                Discontinued?
                </CheckBox>
        </StackPanel>
        <Button Name="btnOK" IsDefault="True"
                Grid.Column="1" Grid.Row="1"  
                Width="76" Height="26" Margin="0,0,81.627,4" 
                VerticalAlignment="Bottom" 
                HorizontalAlignment="Right" >OK</Button>
        <Button Name="btnCancel" IsCancel="True" 
                Grid.Column="1" Grid.Row="1" 
                Width="76" Height="26" Margin="0,0,0,4" 
                VerticalAlignment="Bottom" 
                HorizontalAlignment="Right">Cancel</Button>
    </Grid>
</Window>

Note the binding syntax on the category lookup in the XAML above. The DisplayMemberPath="CategoryName" SelectedValuePath="CategoryID" are fairly straight-forward. The DisplayMemberPath is set to the field on the items in the combobox that we want to display to the user. The SelectedValuePath is set to the field on the items in the combobox that is used to set the value on the Product. To set up the list of items to display in the combobox we will set the ItemsSource property to a List(Of Category) in code. It's on these Category objects where we are indicating the properties to use for display and selection. If we were using DataSets or LINQ to SQL classes the SelectedValuePath would match up with the CategoryID foreign key field in the Product. However since the Entity Data Model uses object associations instead of ID properties, normal data binding won't get us all the way there.

Therefore SelectedValue="{Binding Path=Category.CategoryID, Mode=OneWay}" is specified to indicate to traverse the Category navigation property over to the Category entity hanging off the Product and to match that CategoryID to the CategoryID on the list of categories in the combobox. This gets the right category to display when we open the form. Notice however the Mode is set to OneWay. If we don't specify this, then when we select a new Category in the combobox, only the CategoryID on the related entity would change and NOT the reference itself which is what we need. (I'm thinking this should be possible in WPF to set the Product.Category value to a Category object in XAML but it escapes me.) Therefore we need to set it in code when we close the form. The code is a lot shorter than my explanation of the code ;-):

Imports WpfClient.MyDataServiceReference

Partial Public Class ProductDetail

    'This is the Product we are editing and is 
    ' set from the calling form.
    Private _product As Product
    Public Property Product() As Product
        Get
            Return _product
        End Get
        Set(ByVal value As Product)
            _product = value
            'Binds the controls to this product
            Me.DataContext = _product
        End Set
    End Property

    'This is the same list of categories
    Private _categoryList As List(Of Category)
    Public Property CategoryList() As List(Of Category)
        Get
            Return _categoryList
        End Get
        Set(ByVal value As List(Of Category))
            _categoryList = value
            Me.cboCategoryLookup.ItemsSource = _categoryList
        End Set
    End Property

    Private Sub btnOK_Click() Handles btnOK.Click
        'Manually associate the selected Category with the Product.Category property
        Me.Product.Category = CType(Me.cboCategoryLookup.SelectedItem, Category)
        Me.DialogResult = True
        Me.Close()
    End Sub
End Class

Adding New Products

Now that we have our forms designed and our data binding set up let's get back to the good stuff. First we need to hook up the Add button back on our ProductList form. Since we are working with a single reference to the data service client proxy it's already attached to the objects that we've retrieved. Working with a single reference also allows us to send batch update requests to the service (more on that in a minute). Here's the code for our Add button's click event handler:

Private Sub btnAdd_Click() Handles btnAdd.Click

    'Add a new Product to the List
    Dim p As Product = CType(Me.ProductView.AddNew(), Product)
    p.ProductName = "New Product"
    Me.ListView1.ScrollIntoView(p)

    'Create our detail form and setup the data 
    Dim frm As New ProductDetail()
    frm.Product = p
    frm.CategoryList = Me.CategoryLookup

    If frm.ShowDialog() Then 'OK
        Me.ProductView.CommitNew()
        Dim newCategory = p.Category

        'Add a new product and set the association to the parent Category
        With Me.DataServiceClient
            .AddToProducts(p)
            .SetLink(p, "Category", newCategory)
        End With

        'Refresh the grid 
        Me.DataContext = Nothing
        Me.DataContext = Me.Products
    Else 'Cancel - remove the new product from the list
        Me.ProductView.CancelNew()
    End If

End Sub

Now we can Add new products to the list:

Notice that we're not actually saving anything yet in the code above -- we won't hit the data service again until the user clicks Save. So in order to see if this works and what the call to add a product looks like on the wire, let's hook up our Save button -- it's very simple:

    Private Sub btnSave_Click() Handles btnSave.Click
        Try
            Me.DataServiceClient.SaveChanges()
            MsgBox("Your data was saved")
        Catch ex As Exception
            MsgBox(ex.ToString())
        End Try

    End Sub

All we need to do here is call SaveChanges on the client proxy. If we haven't made any changes this will do nothing. But if we have then it will send all the changes to the data service in sequence. Depending on the data sets you are working with you may opt for a different strategy like sending the updates to the server immediately after each edit. This is chattier on the wire but reduces the possibility of someone else editing the data and running into database concurrency issues. As I mentioned you can also batch all the requests into a single chunky call to the data service by specifying this in the SaveChanges:

Me.DataServiceClient.SaveChanges(System.Data.Services.Client.SaveChangesOptions.Batch)

Deleting Products

To delete a product we can call DeleteObject on the proxy. Finally I remove the object itself from the Products List in which the form is bound through the CollectionView.

    Private Sub btnDelete_Click() Handles btnDelete.Click
        If MessageBox.Show("Are you sure you want to delete this item?", _
                           Me.Title, MessageBoxButton.YesNo) = MessageBoxResult.Yes Then

            Dim p As Product = CType(Me.ProductView.CurrentItem(), Product)
            If p IsNot Nothing Then
                With Me.DataServiceClient
                    
                    .DeleteObject(p)
                End With

                Me.ProductView.Remove(p)
            End If
        End If
    End Sub

Editing Products

Last but not least we need to write the code to edit products in the list. Here we need to check if the category was changed and if so we need to delete the old link to the Category and add the new one.

Private Sub btnEdit_Click() Handles btnEdit.Click

    Dim p As Product = CType(Me.ProductView.CurrentItem(), Product)
    If p IsNot Nothing Then
      
        Dim frm As New ProductDetail()
        frm.Product = p
        frm.CategoryList = Me.CategoryLookup
        Dim oldCategory = p.Category

        If frm.ShowDialog() Then
            Dim newCategory = p.Category
            'If the category was changed, set the new link
            ' then set the product state to updated
            With Me.DataServiceClient
                If (newCategory IsNot oldCategory) Then
                    .SetLink(p, "Category", newCategory)
                End If
                .UpdateObject(p)
            End With
            
            'Refresh the grid to pick up change to category 
            Me.DataContext = Nothing
            Me.DataContext = Me.Products
        End If
    End If
End Sub

When we run the form and make some changes, they all are submitted to the data service. If we didn't specify the Batch option in SaveChanges then the requests are sent in sequence to the data service. Here I've selected an update, HTTP MERGE, operation:

If we did set the Batch option in the save changes you would see only one large payload in Fiddler. I've uploaded the sample application onto Code Gallery so have a look.

In the next post I'll show how we can intercept queries and change operations in order to do some additional processing as well as showing how to add simple validations.

UPDATE Jan 20-2009: I actually updated the code snippets above and updated the code sample because I uncovered some issues with deletes and enforcing FK associations. Check that post out here.

Enjoy!

Using ADO.NET Data Services

Beth Massi — Sat, 10 Jan 2009 06:52:20 GMT

This week I worked through a good article on getting started with ADO.NET Data Services (a.k.a Astoria) called Using ADO.NET Data Services. If you're not familiar with the technology it's basically a framework for exposing your data models via RESTful web services. So if you are building a remote CRUD data access layer then this is a technology that you'll probably want to look into. It should save you some time especially if you're trying to expose your data over REST.

(Note: We're in the process of adding Visual Basic code snippets to the article but you can also download the VB sample projects here on Code Gallery.)

I'm building a few different Windows clients (WPF and Office) to see how we could use ADO.NET Data Services in our n-tier business applications and I'll blog about that soon. But for this post I'd like to highlight the getting started parts of the article that I found most helpful when trying to understand how to work with our database over the web.

File > New Project > ASP.NET Web Application....

Creating an ADO.NET Data Service is easy if you are using Visual Studio 2008 SP1. First create a new ASP.NET Web Application:

This will create a new ASP.NET project with a default.aspx page. If you're just building the service then you can delete this file right away. Next you need to add a new item to the project and select ADO.NET Data Service.

For this example I want to expose data in the Northwind sample database so I'm naming the service Northwind.svc. This will add the System.Data.Services and System.Data.Services.Client (the server and client pieces of the framework) to your project. Right-click on the Northwind.svc in the solution explorer and select Set as Start Page.

This process spits out a code template that sets up your data service by creating a class called Northwind that inherits from DataService.

Imports System.Data.Services
Imports System.Linq
Imports System.ServiceModel.Web

Public Class Northwind
    ' TODO: replace [[class name]] with your data class name
    Inherits DataService(Of [[class name]])

    ' This method is called only once to initialize service-wide policies.
    Public Shared Sub InitializeService(...

End Class

Notice however that you have some work to do. The DataService acts upon a data model, more specifically, a data model that exposes IQueryable properties. (Take a look at the CustomDataService example that is explained in the MSDN article if you're interested in creating a compatible data source yourself.) If you're lazy like me then you can use an Entity Framework data model which implements IQueryable by default.

Adding an Entity Data Model

So in order to fill out the [[class name]] of our IQueryable data source we need to create one first. Add a new item to the project and select ADO.NET Entity Data Model. I named the model NorthwindModel.

Now you can run through the wizard to create the model. I'll just generate it from the database, select all the tables and then hit Finish. This process creates an IQueryable data source called NorthwindEntities. Now we can go back into the data service and fill out the [[class name]].

Public Class Northwind
    Inherits DataService(Of NorthwindEntities)

Setting Access to Tables in the Data Model

We also want to control access to the tables in our data model. It's probably a really bad idea to allow read/write access to every table in our database but it's possible by configuring an EntitySetAccessRule on the DataServiceConfiguration that is passed into the InitializeService method. Note that this is a Shared method so it will only run once no matter how many instances of the Northwind DataService are created. You may need to keep that in mind when debugging via Visual Studio and force some rebuilds if you change the code in there.

Public Class Northwind
    Inherits DataService(Of NorthwindEntities)

    ' This method is called only once to initialize service-wide policies.
    Public Shared Sub InitializeService(ByVal config As IDataServiceConfiguration)
        ' Everyone can party on my data!
        config.SetEntitySetAccessRule("*", EntitySetRights.All)
    End Sub

End Class

This allows anyone access to update, insert, delete and query the tables in the model. Probably a bad idea. So you can allow just read-only:

config.SetEntitySetAccessRule("*", EntitySetRights.AllRead)

You can also write additional web methods for querying and updating the data with some additional processing. I'll get to that in a follow-up post or you can jump into that section of the article. First let's see how we query our data via an HTTP GET in IE.

Querying the Data via HTTP GET

Hitting F5 on the project will now automatically start the service and open the browser to the Northwind.svc which lists all the entities in which we're allowing access in our data model.

When we want to query our data, say all the customers, then we can do that via an HTTP GET by typing in the browser address bar: http://localhost:1234/Northwind.svc/Customers and a feed of all the customers in Northwind will be returned. If you're browsing using IE then it will attempt to put a style sheet on the feed, just right-click and view source to see the actual data returned (I'm just displaying the first two in the feed for clarity):

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<feed xml:base="http://localhost:1308/Northwind.svc/" 
      xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" 
      xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" 
      xmlns="http://www.w3.org/2005/Atom">
  <title type="text">Customers</title>
  <id>http://localhost:1308/Northwind.svc/Customers</id>
  <updated>2009-01-10T02:17:37Z</updated>
  <link rel="self" title="Customers" href="Customers" />
  <entry>
    <id>http://localhost:1308/Northwind.svc/Customers('ALFKI')</id>
    <title type="text"></title>
    <updated>2009-01-10T02:17:37Z</updated>
    <author>
      <name />
    </author>
    <link rel="edit" 
          title="Customers" 
          href="Customers('ALFKI')" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Orders" 
          type="application/atom+xml;type=feed" 
          title="Orders" 
          href="Customers('ALFKI')/Orders" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/CustomerDemographics" 
          type="application/atom+xml;type=feed" 
          title="CustomerDemographics" 
          href="Customers('ALFKI')/CustomerDemographics" />
    <category term="NorthwindModel.Customers" 
              scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <content type="application/xml">
      <m:properties>
        <d:CustomerID>ALFKI</d:CustomerID>
        <d:CompanyName>Alfreds Futterkiste</d:CompanyName>
        <d:ContactName>Maria Anders</d:ContactName>
        <d:ContactTitle>Sales Representative</d:ContactTitle>
        <d:Address>Obere Str. 57</d:Address>
        <d:City>Berlin</d:City>
        <d:Region m:null="true" />
        <d:PostalCode>12209</d:PostalCode>
        <d:Country>Germany</d:Country>
        <d:Phone>030-0074321</d:Phone>
        <d:Fax>030-0076545</d:Fax>
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>http://localhost:1308/Northwind.svc/Customers('ANATR')</id>
    <title type="text"></title>
    <updated>2009-01-10T02:17:37Z</updated>
    <author>
      <name />
    </author>
    <link rel="edit" 
          title="Customers" 
          href="Customers('ANATR')" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Orders" 
          type="application/atom+xml;type=feed" 
          title="Orders" 
          href="Customers('ANATR')/Orders" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/CustomerDemographics" 
          type="application/atom+xml;type=feed" 
          title="CustomerDemographics" 
          href="Customers('ANATR')/CustomerDemographics" />
    <category term="NorthwindModel.Customers" 
              scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <content type="application/xml">
      <m:properties>
        <d:CustomerID>ANATR</d:CustomerID>
        <d:CompanyName>Ana Trujillo Emparedados y helados</d:CompanyName>
        <d:ContactName>Ana Trujillo</d:ContactName>
        <d:ContactTitle>Owner</d:ContactTitle>
        <d:Address>Avda. de la Constitución 2222</d:Address>
        <d:City>México D.F.</d:City>
        <d:Region m:null="true" />
        <d:PostalCode>05021</d:PostalCode>
        <d:Country>Mexico</d:Country>
        <d:Phone>(5) 555-4729</d:Phone>
        <d:Fax>(5) 555-3745</d:Fax>
      </m:properties>
    </content>
  </entry>
.
.
.

Notice that this also returns the relationship information from the customer to the other tables in the model. So if we wanted to return all the orders for customer ALFKI then we would use the relative URL in this feed like so:

http://localhost:1234/Northwind.svc/Customers('ALFKI')/Orders

BTW, if you're going to get serious about developing RESTful web services I'd highly suggest you download Fiddler which will allow you to inspect your HTTP traffic and payloads. It's a lot easier to view this data in Fiddler than in IE.

Building a Simple Client

This stuff is all fun and games until we want to write a real client against our service. I don't think anyone would be too happy with IE as their client against this service, no matter how cool we wrote it. So let's take a look at a simple client that queries a product, makes a change, and submits it back to the service. This is an example that is illustrated in the article that helped me understand how to make changes to the data.

First thing we need to do is configure our service so we can query and update the product table. I'm also going to open up the Categories table for read access:

Public Class Northwind
    Inherits DataService(Of NorthwindEntities)

    ' This method is called only once to initialize service-wide policies.
    Public Shared Sub InitializeService(ByVal config As IDataServiceConfiguration)
        config.SetEntitySetAccessRule("Products", EntitySetRights.All)
        config.SetEntitySetAccessRule("Categories", EntitySetRights.AllRead)
    End Sub

End Class

Now let's add a simple console application (real clients soon, I promise!) to illustrate the client-side code it takes to query and update a product in our database. Once you add a new console application to the solution we need to add the service reference to our Northwind Data Service. Right click on the client console application and select "Add Service Reference". When the dialog opens click the Discover button and it should find the data service.

Once we add this service reference to our client this will automatically generate the client-side proxy that inherits from DataServiceContext and the necessary entities to work with our data service. It also adds a reference to the System.Data.Services.Client assembly which has the client-side framework where the DataServiceContext object lives. This is another added benefit than you creating a remote data access layer yourself. You tell the DataServiceContext how to track changes to the entities and it can can batch up requests and send them at once to the service.

One of cool things about having an IQueryable data source exposed through a data service is that you can use LINQ over the entities generated on the client-side and the framework will handle translating that to HTTP requests. You can dive deeper into the article on the exact query syntax it can support but it's pretty full featured. For instance back on the IE client, if we just want to return the top 2 customers we could type: http://localhost:1234/Northwind.svc/Customers?$top=2

But when we're working with a managed client we can write a LINQ query against the data service instead. Here I'm returning all the products in the Beverages category:

Imports MyDataServiceClient.ServiceReference1

Module Module1
    Private ServiceURI As Uri = New Uri("http://localhost:1308/Northwind.svc/")

    Sub Main()
        Dim ctx As New NorthwindEntities(ServiceURI)

        Dim results = From p In ctx.Products _
                      Where p.Categories.CategoryName = "Beverages" 

        For Each p In results
            Console.WriteLine(p.ProductName)
        Next
        Console.ReadLine()
    End Sub

End Module

Pretty slick. Notice that since I'm using the Categories in the query, I have to enable access to that on the service side otherwise I'll get an error when running the client.

Saving Changes through the ADO.NET Data Service

In order to update the database we tell the DataServiceContext that we updated the object and then tell it to pass the change to the server by calling SaveChanges.

Imports MyDataServiceClient.ServiceReference1

Module Module1
    Private ServiceURI As Uri = New Uri("http://localhost:1308/Northwind.svc/")

    Sub Main()
        Dim ctx As New NorthwindEntities(ServiceURI)

        Dim product = (From p In ctx.Products _
                      Where p.ProductName = "Chai").FirstOrDefault()

        If product IsNot Nothing Then

            product.ProductName = "Chai Tea"
            ctx.UpdateObject(product)

            Try
                'You can batch up changes on the DataServiceContext
                ' before calling SaveChanges. This will hit the service.
                ctx.SaveChanges()
                Console.WriteLine("Saved Product")
            Catch ex As Exception
                Console.WriteLine(ex.ToString())
            End Try
        End If
    End Sub

End Module

Nice. In the next post I'll dig a little deeper into how we can intercept queries so that we can do some server-side processing first as well as how we can add additional processing methods to our service in order to perform custom querying and validation. I'm also building a WPF client for doing batch editing that I'll introduce. For now, please read the article on MSDN for more information. Until next time....

Enjoy!

More PDC Tidbits, Data Everywhere, Visual Studio 2010 CTP

Beth Massi — Thu, 30 Oct 2008 02:07:57 GMT

Day 3 at PDC is off to a great start so far. I just attended a session on the architecture and development of the content delivery infrastructure and Silverlight client for the NBC Olympics online. It's pretty amazing how they pulled it off but one of the reasons for the success was scrumming and face-to-face meetings. With teams scattered all over the globe from Redmond to Beijing it takes great project management besides super technical skills to drive success. This is key to any software project, not just large ones like this.

DATA EVERYWHERE

Now I'm sitting in a session with Pablo Castro, a Software Architect over in SQL, on offline-enabled data services and desktop applications. This one is really good. I'm really interested in this one because on my former system that I developed we implemented our own data caching mechanisms and some of the challenges once you decide what data can be offline is how to efficiently synchronize it with the server as well as determining how stale you can tolerate the data. The plumbing for serializing and syncing the data is non-trivial so I'm happy to see these frameworks that handle that for you.

ADO.NET Data Services (Astoria) make it really really easy for you to put your data on the web. I've been getting into it since it was added to Visual Studio 2008 SP1. I think that combining this with Sync Services will make a great framework for you to build an easy data caching framework as well as enable you to "play back" calls to the service for you once you get back online. Pablo referred to this as "Astoria Offline" integrated into Visual Studio. I can't wait.

He built a simple ADO.NET Data Service (just like Saaid showed here) using the Entity Framework to model some data. The service then exposes this model to the web. The new thing he showed is that when creating the service there was an option on the dialog to create an offline enabled service. This adds code to enable sync services and scripts to modify the SQL Server database schema to enable change tracking on the tables (similar to how you do it now in VS 2008 using sync services, like Milind showed here). Then Pablo added a WPF client. and added a Service Reference to the data service. Because it was set up as an offline-enabled service it asks you if you want to take the service offline. If you say yes then it downloads the metadata from the service, creates a local SQL CE database and then adds an Entity Framework model to the local database. This allows you to code against the local data model which then syncs with the service behind the scenes using an orchestrator. VERY COOL. Its amazing what you can do with Visual Studio.

DOWNLOADS

Speaking of Visual Studio --- Visual Studio 2010 and .NET 4.0 CTP was released on Monday so have a look at an early build of the next version of VS. I'll be bugging the Visual Studio teams for Channel 9 videos in the coming months to show us what they got in there and how to use it. Now's the time for feedback so play with it and tell us about it on the Dev10 CTP Feedback page and the feedback forums.

Other things to look at and play with:

Windows Azure Tools for Microsoft Visual Studio CTP

Channel 9 PDC news and announcements

PDC Online

Enjoy!