Beth Massi - Sharing the goodness that is VB : OBA

Build WPF Data Controls for Outlook Addins Easily with VS2010

Beth Massi — Mon, 21 Dec 2009 22:14:29 GMT

Last post I showed how to migrate our Northwind Outlook client to .NET 4 and Office 2010. This Outlook Add-in displays order history information in an adjoining form region so sales associates can see that data immediately when communicating with customers. When we originally built this with Visual Studio 2008, we used a WPF user control to display the data so that we could better match the look and feel of Outlook 2007. However we had to manually figure out the colors we needed and bind the data to the controls by writing XAML by hand.

Today I want to show how we can use drag & drop data binding and the new WPF designer in Visual Studio 2010 to quickly create this control without writing one line of XAML ourselves.

Displaying WPF Controls in Form Regions with ElementHost

Office clients by default work with Windows Forms controls. If you create a new Form Region you can add any Windows form control from the toolbox onto it. If you want to add WPF controls you simply add what’s called an ElementHost control which you find in the WPF Interoperability tab on your toolbox. This allows you to select from and host WPF User Controls in your project.

This is the same technique in VS2008 and VS2010. However, VS2010 makes it much easier to create the WPF User Control in the first place because you can now use the data sources window to design and data bind WPF controls. The WPF designer is also much easier to use. Let’s see how we can build a WPF control that displays Order information and have Visual Studio generate all the XAML we need automatically for us, and have it look good too.

Using the Data Sources Window with WPF

Let’s create a new WPF control called OrderHistoryDD where we’ll use drag & drop data binding from the data sources window. Project –> Add New Item, then select User Control (WPF). To view the data sources window select menu Data –> Show Data Sources. Because we already have added a service reference to our data service (which we built in part 1), you will see the client types that were generated for us appear in the data sources window.

We want to display three levels of related information to the user. Orders, the related Order Details and the related Product inventory information. If you are familiar with Windows Forms development using the data sources window here is the same. You can select which controls should be dropped onto the design surface by selecting the desired control in the dropdown.

The controls that are available to you depend on which target framework you are using. Since we are targeting .NET Framework 4 then we have some new controls at our disposal namely the WPF DataGrid and the DatePicker.

However, we are only displaying data to the user here (new orders are handled as POs in Word and the editing is done by our shipping department in the Excel client) so we’ll select TextBox controls instead of the DatePicker control. I also only want to display the ShipName, OrderDate, RequiredDate and ShippedDate in the Order grid so for the rest of the fields you can select [None].

Now drag the Orders onto the WPF design surface and you will see those fields in the grid. By default it is anchored to the top and left of the control. Click on the arrow to the right of the grid to also anchor it to the right side so it will stretch.

Since we are not allowing edits, in the Property window for the DataGrid, set the IsReadOnly property to True. Also set the ColumnWidth property to Auto. To modify the order in which the columns appear, click on the ellipsis (…) next to the Columns property to open up the columns editor. Here we can also set the data binding and formatting on our columns by selecting the Binding property and dropping down the editor. You’ll notice that the columns are already bound to the data based on what we specified in the data sources window. Expand Options and you’ll see some additional settings you can make on the Binding. For this example, set the String Format to a simple date for all three date columns.

You can also set additional properties here like styles and widths, etc. Since we set the DataGrid Width to Auto, I’ll select each of the column’s widths here, right-click on the Width property and select “Reset value” so that they pick up the same setting. This means the cells will auto size to display all the data.

Now we need to display the related Order Details. To do this, back in the data sources window expand the Order Details under the Orders. It’s very important you select the related Order Details under the Orders otherwise the user won’t see the Order Details change as they select the Order above. This sets up a master-detail binding when we do it this way. This time, just select drop controls as TextBoxes for Quantity and UnitPrice and drop the related Order Details DataDrid under the Orders DataGrid. We also want to display the ProductName here, but because that field is on the Product entity we will have to add a column and set up the binding to it in the Column editor instead.

So click the Columns ellipsis button for the Order Details DataGrid in the Property window and then click the Add button to add a new column. Set the Header property to “Product”. Open up the Binding editor again and expand the Path section. Select Product then ProductName to set up the binding to that field.

Select the Bindings for Quantity and UnitPrice and expand the Options node to set the String Format for those columns to display as number and currency respectively.

Now we want to display the inventory information for each Product selected on the Order Details. Same as before, in the data sources window expand the related Product under the Order – Order Details. Select the dropdown on Product and select Details. Then select to drop Labels for just ProductName, UnitsInStock and UnitsOnOrder. Drag the Product onto the form under the Order Details DataGrid and it will create three labels bound to the corresponding fields on Product. It creates a Grid control (not to be confused with DataGrid) with two columns with the field labels on the left and the controls on the right. Dock the entire grid control to the bottom left by selecting the grid and then clicking on the dock arrow at the top. This will dock it to the bottom left. Next add an image control to the bottom right, select the Source property, and select the Northwind traders logo.

Notice that we haven’t typed any XAML at all to set any of this up so far. If you look in the generated XAML you will see all the control and data binding definitions. Visual Studio 2010 takes care of all of this for us. But we also want to set up some nice styles on the data grids. Let’s set the alternating row colors and set up a style in the control resources so that we can share it on both DataGrids. We don’t have to know XAML to do this either.

Styling the DataGrids and Sharing Style Resources

To quickly set up a nice gradient style shared on both data grids for alternating rows, select a DataGrid and then AlternatingRowBackground in the property window. This opens up the new Brush Editor. Select the third glyph at the top left for gradient. You can select the start and stop gradient colors with the color selector on the left but it’s much easier if you already have an application in mind that has the colors you want, just click the eyedropper in order to pick up any color on your desktop.

After you set up the style how you like it, you can extract it from the DataGrid control into the user control resources so that you can share it on both grids. Click on the diamond next to the AlternatingRowBackground property and select Extract Value to Resource. Name the resource and then click OK to add it to the resources section of the user control.

Now you can go to the other DataGrid, click that AlternatingRowBackground and select “Apply Resource”. Then you can select from SystemColors and Local resources that match. Expand Local and you will see the resource you just created. We could spend all day styling our DataGrids but the nice thing is we can do a lot without having to know XAML.

Hooking Up the Data to CollectionViewSource

Now we need to hook up our WPF user control onto the form region and load it with data from our data service. If you haven’t already done so, build the project and then on the EmailForm select the ElementHost and chose the OrderHistoryDD user control we just built.

We already have written the the code to load the data into a List(Of Orders). The same code we wrote for our VS2008 version here applies in VS2010. The only difference now is that we need to set the List(Of Orders) to the CollectionViewSource.Source property for the master view source, in this case it’s called OrdersViewSource. I’ve talked about CollectionViewSources for master-details before. You can see this in the XAML that was generated for us, as well as the related OrdersOrder_DetailsViewSource:

<UserControl.Resources>
    <CollectionViewSource x:Key="OrdersViewSource" 
                          d:DesignSource="{d:DesignInstance my:Order, CreateList=True}" />
    <CollectionViewSource x:Key="OrdersOrder_DetailsViewSource" 
                          Source="{Binding Path=Order_Details, 
                                           Source={StaticResource OrdersViewSource}}" />

Because the CollectionViewSources are chained together (similar to how Winforms BindingSources are set up), all we need to do is set the master’s Source property and all the controls will pick up their bindings properly. To make this easier, create a property on the OrderHistoryDD user control that exposes the OrdersViewSource. In the code-behind for the WPF user control:

Imports System.Windows.Data
Public Class OrderHistoryDD

    Public ReadOnly Property OrdersViewSource As CollectionViewSource
        Get
            Return CType(Me.Resources("OrdersViewSource"), CollectionViewSource)
        End Get
    End Property
End Class

Now in the code-behind for the form region (the FormRegionShowing event handler for EmailForm) change the line of code that sets the DataContext of the old user control and set the OrdersViewSource.Source property instead:

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

'In VS2010 CollectionViewSources are used instead:
Me.OrderHistoryDD1.OrdersViewSource.Source = ordersList

Now rebuild and run it to see your lovely new user control appear in Outlook:

But something is missing. We want to display the line item and order totals in the grids. We could add a property onto the Order partial class, but we also want to sub-total each of the line items. Instead of adding read-only properties to the partial classes we can write one WPF value converter that handles both of these cases and then use that in our DataGrids.

Writing a Converter to Aggregate Totals

I’ve talked about how to write a converter to format data in controls exactly how you like. In this case we want to write one that will take either a single Order_Detail to calculate the line item total or a collection of Order_Details to calculate the Order total. Here’s one way to do that.

Imports System.Windows.Data
Imports NorthwindOutlookClient.NorthwindService.NorthwindModel

'Used by the OrderHistory WPF control to display line totals and Order total in the UI
Public Class OrderTotalConverter
    Implements IValueConverter

    Public Function Convert(ByVal value As Object, ByVal targetType As System.Type,
                            ByVal parameter As Object,
                            ByVal culture As System.Globalization.CultureInfo) As Object _
                        Implements System.Windows.Data.IValueConverter.Convert

        Dim total As Double = 0.0
        If TypeOf value Is Order_Detail Then
            'return the line item total
            Dim o = CType(value, Order_Detail)
            total += o.Quantity * o.UnitPrice

        ElseIf TypeOf value Is IEnumerable(Of Order_Detail) Then
            'return the order total
            For Each o As Order_Detail In value
                total += o.Quantity * o.UnitPrice
            Next
        End If
        Return total
    End Function

    Public Function ConvertBack(ByVal value As Object,
                                ByVal targetType As System.Type,
                                ByVal parameter As Object,
                                ByVal culture As System.Globalization.CultureInfo) As Object _
                            Implements System.Windows.Data.IValueConverter.ConvertBack
        Return Nothing
    End Function
End Class

Once you add this class rebuild the project. Now go back to the Order DataGrid and select Columns in the Property window to open the Column editor. Add a new TextBoxColumn, set the Header property to “Total” and then open up the Binding property. Set the Path to Order_Details and then expand Converter and select the NorthwindOutlookClient then OrderTotalConverter. Under Resources select “Create New…” and name and save the OrderTotalConverter in the resources section so you can select it on the Order_Details DataGrid. Expand Options and select the currency String Format.

Next Select the Order_Details DataGrid, add a new column, set the Header property to say “Total”. Select the Bindings property but this time don’t select anything for the Path. Expand Converter and select select the NorthwindOutlookClient then OrderTotalConverter and now in the Resources you will see OrderTotalConverter1, select that. Expand Options and select the currency String Format for this column as well.

Now rebuild and run the project again. You can set a breakpoint on the Convert method and you will see that different value types are getting passed in depending on what DataGrid column is requesting the conversion. And best of all, now the user can see line item and order totals in the form region.

As you can see Visual Studio 2010 has much improved RAD designers for data binding and styling business applications like this one. I’ve uploaded the source code which works with Visual Studio 2010 Beta 2 and Outlook 2010 Beta onto Code Gallery so have a look.

Enjoy!

Migrating an Outlook Client to .NET Framework 4 in Visual Studio 2010

Beth Massi — Wed, 16 Dec 2009 07:12:00 GMT

Early this year we built a business application for order management for Northwind Traders on the Office and SharePoint platform using Visual Studio 2008 and Office & SharePoint 2007. If you missed them:

The solution consists of an Outlook client that pulls up order history when a customer email arrives in the sales associate’s inbox. This way they don’t have to leave Outlook (the application that they live in all day) to see corresponding line-of-business (LOB) data, in this case order history, right in the email message. LOB data is exposed via a simple REST-based WCF data service (built in part 1) and is displayed in the reading pane in Outlook for each customer.

Today I want to take a look at how we can migrate the Outlook client we built in part 2 to Office 2010 and .NET Framework 4.0 Client Profile using Visual Studio 2010. The VSTO 4 Runtime has changed so there are some manual steps you may have to take when you migrate your solutions depending on what features you are using.

I set up a Windows 7 VHD with Visual Studio, SharePoint & Office Betas that I’ll be using for development, just like I explained in this post - Setting up Windows 7 for Office & SharePoint 2010 Beta Development. If you’d like to follow along you can download the Visual Studio 2008 version of the code here.

Required Changes for the New VSTO 4 Runtime

First I want to point out some excellent information on MSDN that you should familiarize yourself with if you are migrating Office solutions built with Visual Studio (VSTO). All the samples, walkthroughs and videos on the Visual Studio 2010 resources page on the VSTO Dev Center are valuable but if you are migrating you should pay close attention to this item -

Migrating Office Solutions to the .NET Framework 4

I also recommend familiarizing yourself with the new VSTO4 Runtime here -

Visual Studio Tools for Office Runtime Overview

In particular, if your Outlook project uses Form Regions or the Ribbon designer then you will have some work to do if you target .NET Framework 4 because the VSTO 4 runtime has been updated to use Office object model interfaces and not directly inherit from classes like was done in the previous versions of the VSTO runtime. Moving forward this is a very good thing because it removes the dependency on specific versions of Office and enables Office solutions to use the new embedded interop types feature (sometimes referred to as “no-PIAs”) in the .NET Framework 4. This means solutions can run on end user computers without installing these primary interop assemblies (PIAs).

So you may have to reach into the designer generated files and tweak some code. Note that depending on how you structure your application it may be easier after you retarget to .NET 4 to just create a new Form Region and a new Ribbon and copy your user code into them. This is especially true if you are migrating solutions using Visual Studio Beta 2 to .NET 4 because of a bug which I’ll show you how to work around. Let’s take a look at what we need to do for our Northwind Outlook client.

Migrating the Outlook Solution to Visual Studio 2010

Before I jump into migrating this solution I should point out that building Office client solutions in Visual Studio became a lot easier starting in Visual Studio 2008 with all the designer support that was added directly into the Visual Studio box. You can create form regions, ribbons, and host WPF controls easily using these tools in VS2008 without having to install additional extensions. These tools have been updated in Visual Studio 2010 to allow you to build upon Office 2010 but they are just as easy to use.

So let’s start with opening the NorthwindOutlookClient solution in Visual Studio 2010. The migration wizard will open and you’ll be guided through conversion of the project to VS2010. Note that depending on what you have installed on your development machine will determine what Visual Studio does with the solution. If you have the .NET 3.5 framework installed then the target framework will not change, however if you only have .NET 4 then it will update to that automatically. (For more information see How to Upgrade Office Solutions and Configuring a Computer to Develop Office Solutions).

Since my development environment is a Windows 7 machine set up with Office 2010, Visual Studio 2010 and SharePoint Foundation 2010 I get some warnings immediately about the version of Office being wrong. “This project requires Microsoft Office Outlook 2007, but this application is not installed.” However it will build and run just fine in Outlook 2010.

Updating the Target Framework to .NET 4

Now let’s change the target framework to .NET Framework 4 Client Profile. In Visual Basic you do this by selecting the project properties Compile tab, scroll down to “Advanced Compile Options…” and then select the new framework in the dropdown.

I should mention that the Client Profile is a subset of the full .NET 4 Framework meant for client applications like WPF, Windows Forms and Office solutions. This means it’s a smaller install if your users don’t have the .NET Framework installed at all. It doesn’t include any server pieces like ASP.NET. This is also now the default framework target for new Windows, WPF and Office projects.

So once we change the framework, this will close and then reopen the project. Now we’ve got a bunch of stuff in our errors list. Ouch. There are 48 errors but only 25 of them are related to the VSTO 4 runtime changes. The minor problem is that the WPF control is referencing System.Xaml and when we switched the target this gets dropped (at least it does in Beta 2) so we need to just reference this 4.0 assembly. If you open up the OrderHistory.g.vb file, hover over the error, and drop down the error correction it will take care of this for you.

Much more important is the 25 errors around our Form Region. We have two options, we can either add a brand new Form Region to the project, add our controls, paste our custom code into it, and delete the old one, or we can modify the designer generated code. In this case, because there is only one user control on the Form Region, it’s much easier to just create a new one. But if you have very complicated layouts you may need to take the route of updating the designer code to use the new interfaces. For the sake of learning what we need to do in these trickier situations, I’ll opt to go that route too.

Update Outlook Projects that Contain Form Regions

Since we’ll be modifying the designer generated code you’ll need to make sure you click the Show All Files toolbar button on the Solution Explorer. Now we can open up the EmailForm.Designer.vb file in the editor.

This documentation contains the step-by-step code conversions that you need to perform to upgrade your form regions. First we need to modify the declaration of the form region class so that it derives from FormRegionBase instead of FormRegionControl:

<System.ComponentModel.ToolboxItemAttribute(False)> _
<Global.Microsoft.VisualBasic.CompilerServices.DesignerGenerated()> _
Partial Class EmailForm
    Inherits Microsoft.Office.Tools.Outlook.FormRegionBase

The documentation also shows what the code looks like against a 3.5 target and what it should look like against a 4.0 target. For instance we have a problem with the constructor. In 3.5 we have:

    Public Sub New(ByVal formRegion As Microsoft.Office.Interop.Outlook.FormRegion)
        MyBase.New(formRegion)
        Me.InitializeComponent()
    End Sub

However in .NET 4 we need to change this to:

    Public Sub New(ByVal formRegion As Microsoft.Office.Interop.Outlook.FormRegion)
        MyBase.New(Globals.Factory, formRegion)
        Me.InitializeComponent()
    End Sub

Next we need update the signature of the InitializeManifest method (note that underscores are not necessary here in Visual Basic when targeting .NET Famework 4)

Private Shared Sub InitializeManifest(
     ByVal manifest As Microsoft.Office.Tools.Outlook.FormRegionManifest,
     ByVal factory As Microsoft.Office.Tools.Outlook.Factory)

A Better Way to Upgrade (for now) – Working Around a Bug in Visual Studio 2010 Beta 2

Steps 5-8 of the documentation tell us to create a new Form Region to get the new factory code that we need -- this is why it may just be easier for you to start this way. Unfortunately there’s a bug in Visual Studio 2010 Beta 2 when you attempt to add a new item to the project it will select the wrong language. If you have a C# project it will select VB templates and if you have a VB project it will select C# templates. Doh! (Now that’s taking language parity thing a bit too far ;-)) So the way you have to work around this is to create a new Outlook Add-in project based on .NET 4 already and then add a new form region there. This is a bug only with migrated projects and it will be fixed in the final release.

However, if you also want to keep building upon this solution in Beta 2, you should recreate the project, selecting a .NET 4 target, and add your existing files into it. This will ensure that things work smoothly going forward. You can actually name the project the same thing, you just need to put it into a different folder. Here’s how you do it.

First clean the solution to remove the registered Add-In. From the menu select Build –> Clean NorthwindOutlookClient.

Now since we have multiple projects in this solution you can right-click on the NorthwindOutlookClient in the Solution Explorer and then select Remove. Then close Visual Studio and open the folder where the NorthwindOutlookClient resides and rename that folder to NorthwindOutlookClient_OLD. Reopen the solution in Visual Studio.

Next go to the main menu and select File –> Add –> New Project then make sure you select .NET Framework 4 and then choose Outlook 2010 Add-in and name it NorthwindOutlookClient.

Next right-click on the project and select Set as StartUp Project. Then Add –> Existing Item and select all the code, app.config, .xaml and .gif files in the NorthwindOutlookClient_OLD directory:

When prompted, say YES to overwrite ThisAddIn but say NO to overwrite ThisAddIn.Designer file. (Even though we didn’t select the designer file, it is automatically brought in when we select ThisAddin.)

Next we need to re-add our Service Reference to our data service by right clicking and select Add –> Service Reference, click Discover button and then name the service the same thing, NorthwindService.

Next make sure the .gif file is set to a Resource in the file properties. Select the file in the Solution Explorer and in the properties window set the Build Action to Resource.

Finally, because we are using WPF controls in this solution, right-click and select Add Reference to add the .NET assembly references for System.Xaml, PresentationCore, PresentationFramework, WindowsBase and WindowsFormsIntegration.

Back to Migrating the Form Region

Now you can get back to upgrading your Form Region as explained in steps 5-8 . Add a new Form Region by selecting Project –> Add New Item and then selecting Form Region (now you’ll see the right templates). Walk through the wizard and then Show All Files again to open the designer generated file and grab the code for the two partial classes (note that the factory is an embedded class):

It’s not too painful to change your original code once you get the right template for it. You just need to make sure that after you paste in these two partial classes, you update all instances of the class name with yours. In our case the name of the Form Region is EmailForm so the updated code back in the NorthwindOutlookClient project will look like this (I know it’s ugly that’s why it’s designer generated ;-). As an aside, look at where underscores are still necessary to resolve ambiguity if there is a line break):

Partial Public Class EmailFormFactory
    Implements Microsoft.Office.Tools.Outlook.IFormRegionFactory

    Public Event FormRegionInitializing As  _
        Microsoft.Office.Tools.Outlook.FormRegionInitializingEventHandler

    Private _Manifest As Microsoft.Office.Tools.Outlook.FormRegionManifest

    <System.Diagnostics.DebuggerNonUserCodeAttribute()> _
    Public Sub New()
        Me._Manifest = Globals.Factory.CreateFormRegionManifest()
        EmailForm.InitializeManifest(Me._Manifest, Globals.Factory)
    End Sub

    <System.Diagnostics.DebuggerNonUserCodeAttribute()> _
    ReadOnly Property Manifest() As Microsoft.Office.Tools.Outlook.FormRegionManifest _
             Implements Microsoft.Office.Tools.Outlook.IFormRegionFactory.Manifest
        Get
            Return Me._Manifest
        End Get
    End Property

    <System.Diagnostics.DebuggerNonUserCodeAttribute()> _
   Function CreateFormRegion(ByVal formRegion As Microsoft.Office.Interop.Outlook.FormRegion) As _
             Microsoft.Office.Tools.Outlook.IFormRegion _
             Implements Microsoft.Office.Tools.Outlook.IFormRegionFactory.CreateFormRegion

        Dim form As EmailForm = New EmailForm(formRegion)
        form.Factory = Me
        Return form
    End Function

    <System.Diagnostics.DebuggerNonUserCodeAttribute()> _
    Function GetFormRegionStorage(ByVal outlookItem As Object,
                  ByVal formRegionMode As Microsoft.Office.Interop.Outlook.OlFormRegionMode,
                  ByVal formRegionSize As Microsoft.Office.Interop.Outlook.OlFormRegionSize) _
             As Byte() _
             Implements Microsoft.Office.Tools.Outlook.IFormRegionFactory.GetFormRegionStorage

        Throw New System.NotSupportedException()
    End Function

    <System.Diagnostics.DebuggerNonUserCodeAttribute()> _
    Function IsDisplayedForItem(ByVal outlookItem As Object,
                ByVal formRegionMode As Microsoft.Office.Interop.Outlook.OlFormRegionMode,
                ByVal formRegionSize As Microsoft.Office.Interop.Outlook.OlFormRegionSize) _
            As Boolean _
            Implements Microsoft.Office.Tools.Outlook.IFormRegionFactory.IsDisplayedForItem

        Dim cancelArgs As Microsoft.Office.Tools.Outlook.FormRegionInitializingEventArgs =
            Globals.Factory.CreateFormRegionInitializingEventArgs(outlookItem,
                                                                  formRegionMode,
                                                                  formRegionSize,
                                                                  False)
        cancelArgs.Cancel = False
        RaiseEvent FormRegionInitializing(Me, cancelArgs)
        Return Not cancelArgs.Cancel
    End Function

    <System.Diagnostics.DebuggerNonUserCodeAttribute()> _
    ReadOnly Property Kind() As Microsoft.Office.Tools.Outlook.FormRegionKindConstants _
             Implements Microsoft.Office.Tools.Outlook.IFormRegionFactory.Kind
        Get
            Return Microsoft.Office.Tools.Outlook.FormRegionKindConstants.WindowsForms
        End Get
    End Property
End Class
End Class

Partial Class WindowFormRegionCollection

    Friend ReadOnly Property EmailForm() As EmailForm
        Get
            For Each Item As Object In Me
                If (TypeOf (Item) Is EmailForm) Then
                    Return CType(Item, NorthwindOutlookClient.EmailForm)
                End If
            Next
            Return Nothing
        End Get
    End Property
End Class

Now it looks like all our project errors have disappeared (thanks to Visual Basic’s background compiler). However if you didn’t create a brand new project like I explained above in order to work around that migration bug, then when you rebuild the solution you’ll see the build still fails. In this case we have one more thing to do.

Removing the SecurityTransparent Attribute

The next section of the documentation on upgrading Office solutions has information on how to Remove the SecurityTransparent attribute from Office Projects that you upgrade from Visual Studio 2008. Under My Project node in the Solution Explorer, open up the AssemblyInfo file and you’ll see at the bottom the SecurityTransparent attribute. Remove that line of code. If you created a new project based on .NET 4 from the get-go this file will already be correct.

Run it!

Now you should be able to rebuild the project and it will succeed. Hit F5 and now we have the Outlook client working and looking as before, but now we are targeting the .NET framework 4 and we have all the new features at our disposal.

As you can see there are some manual steps to migrating Office solutions to the .NET Framework 4, but once you are familiar with the changes, it’s pretty straightforward. Keep in mind that if you are migrating your own solutions and you have code that loads form regions and/or ribbons dynamically at runtime you will also have to update that code as well to use the factory methods and interfaces instead of classes, take a look at the documentation for details. Hopefully dealing with a little migration pain now will pay off in the long run to you and your users.

Resources

For more information on building Office solutions with Visual Studio please check out:

Office Development with Visual Studio Developer Center on MSDN = http://msdn.com/vsto
Visual Studio Tools for Office Team Blog = http://blogs.msdn.com/vsto
Visual Studio 2010 Resources

For more information on underscores in Visual Basic 10 in Visual Studio 2010 see:

Enjoy!

Office Development with Visual Studio Tutorial Series – Part 2

Beth Massi — Tue, 08 Dec 2009 18:51:00 GMT

Last month Robert Green, VSTO MVP, started a series of tutorials on building on Office 2007. Today we published part 2 of his step-by-step tutorials. Thanks Robert!

In this second part of the series of tutorials on Office Business Applications, learn how to create a Word 2007 price quote generation solution using Visual Studio 2008. This tutorial shows you how to create a custom task pane to display data from a database and binding that data to content controls. This step-by-step tutorial also includes full source code in Visual Basic. Check out the tutorial on the VSTO Developer Center:

Building an Office Business Application Part 2 – Generating Automobile Quotes

And if you missed part 1:

Building an Office Business Application Part 1 - Scheduling Customer Appointments

If you’re just getting started with Office development in Visual Studio, this is a great place to start.

Enjoy!

SDC 2009 Recap & Surprise

Beth Massi — Tue, 20 Oct 2009 13:39:26 GMT

SDC09 has been a blast. I just finished my last session on Building Office Business Applications with Visual Studio 2010 and I think it went well. We created an OBA for good old Northwind Traders. I migrated the 2008 code which is here on code gallery into VS 2010 and showed the new features of VS2010 that makes Office development easier focusing on RAD data binding (including WPF) and designers, new multi-project deployment, and SharePoint 2010 tools.

My main goal was to provide a real-world scenario and architecture but keep the demo code manageable and simple while also introducing folks to all the RAD designers available. This way you can take apart the sample easily and reuse just the pieces you need. Check out the code and 5-part article series on how to build the Northwind OBA in Visual Studio 2008:

I migrated the solutions to use Office 2010 and SharePoint 2010 for my presentation so once those Betas are available I’ll update the links with that code. Beta 2 for Visual Studio released yesterday so I got to show everyone the latest and greatest tools including SharePoint 2010 tooling. Some of the features that make Office development and deployment easier are covered in these walkthroughs:

Office Programming (C# and Visual Basic)

Embedding Type Information from Microsoft Office Assemblies (C# and Visual Basic)

Deploying Multiple Office Solutions in a Single ClickOnce Installer

Copying a Document to the End User Computer after a ClickOnce Installation

SharePoint Development in Visual Studio 2010

Yesterday my talks went really well too but I’ve done them many times before, last time being code camp. I did one on VB10 / C#4 language features which are covered in these walkthroughs on MSDN:

Creating and Using Dynamic Objects (C# and Visual Basic)

Embedding Types from Managed Assemblies (C# and Visual Basic)

Use Named and Optional Arguments in Office Programming (C# Programming Guide)

Create a Collection Used by a Collection Initializer

Create an Add Extension Method Used by a Collection Initializer

I also did a talk on using Open XML and LINQ to XML to manipulate Office 2007 document formats.

Happy Birthday!

Yes it’s my birthday today. Not really an important one in my opinion, I’m just getting old I guess ;-). But when I showed up in my session this morning the room had been decorated with rainbow streamers. It was very cute and I thought that was the end of it. But afterwards during lunch I was lead onto the stage in the main hall and properly embarrassed by the event organizers. They brought out a cake with a gigantic fire-cracker on it! Then all the attendees sang happy birthday to me in Dutch. It was totally embarrassing but also incredible to feel loved by the Dutch developer community :-).

THANKS TO ALL OF YOU!

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