Beth Massi - Sharing the goodness that is VB : Office

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!

Setting up Windows 7 for Office & SharePoint 2010 Beta Development

Beth Massi — Thu, 03 Dec 2009 03:16:00 GMT

So I decided to get my Windows 7 laptop installed with all the latest public Betas this week which includes Visual Studio Beta 2, SharePoint 2010 Beta and Office 2010 Beta. I had been using internal builds and thought it would be better to get in sync with everyone else in the community. I have to say there were a couple bumps that I experienced along the way that had me scratching my head and searching the web so I thought I’d consolidate all the resources I found and document the steps I did which resulted in a successful install. There is a lot of information out there depending on how you want to configure your system and I’m definitely not going to cover all the possibilities, I’m just going to focus on setting up a Windows 7 development environment and what worked for me in hopes of saving some time for other folks out there. As always, your mileage may vary.

NOTE: If you don’t plan on doing any SharePoint development then the install of Visual Studio and Office 2010 should be very smooth. I only experienced issues installing SharePoint 2010 Beta on my Windows 7 development machine. Also be aware that SharePoint 2010 Beta is supported on Windows 7 (and Vista) only for development purposes. So you will still need to have a testing environment built on Windows 2008 Server (or R2). For more information please see, Setting Up the Development Environment for SharePoint Server , SharePoint Deployment, Determine hardware and software requirements and SharePoint 2010 Beta Release Known Issues.

OS Requirements & Boot From VHD

Before you attempt to set up a Windows 7 development environment, I highly recommend booting from VHD. Do yourself a favor and create a Windows 7 bootable VHD so that if you mess up any part of an install you can simply delete it/roll back and start over. There’s a lot of information out there on how to do this but I used these instructions to create a Win7 64-bit VHD via Hyper-V, sysprep-ed it, copied it to my local hard drive, and then used BCDEdit to add the VHD to my boot menu.

Make sure you create a 64-bit Windows 7 Professional or higher edition with at least 4GB RAM if you’re going to do SharePoint development. You'll need Windows 7 Enterprise or Ultimate to boot from VHD.

What to Install - SharePoint Foundation or SharePoint Server?

There are two versions of SharePoint that you can choose to install. It’s recommend that you install SharePoint Foundation (formerly known as WSS) if you only have 4 GB of RAM on your machine because there’s a lot less services running than the Server version (formerly known as MOSS). But if you need all the functionality of SharePoint Server then make sure you have enough of RAM. Just for fun I installed the Server version on my machine with only 4GB and it’s maxed out at 95% so I went with Foundation in the end. :-)

Download Microsoft SharePoint Foundation 2010 Beta here.

Download Microsoft SharePoint Server 2010 Beta here.

Note that you do not need to register or obtain a product key for installing SharePoint Foundation but you do for Server. The Product Key for Server is located at the bottom of the download page after you register (I missed it the first time so make sure you grab that before installing).

Installing SharePoint 2010 Beta on Windows 7

Read these instructions carefully: Setting Up the Development Environment for SharePoint Server. These are the instructions you’ll need to follow with a few additions I’ve added below as you go. Now that you’ve got your 64-bit Windows 7 VHD (are logged in as an administrator account) and downloaded SharePoint 2010 Beta you’re ready to proceed to Step 2 in the instructions.

Step 2: Install the Prerequisites for SharePoint 2010

There are a lot of prerequisites that you’ll need to install before you get to actually installing the SharePoint Beta. Follow all the instructions in Step 2 exactly as it says for Windows 7 to install all the prereqs and Windows features. But note that figure 3 in bullet #9 is incorrect. WCF Non-HTTP Activation should appear as checked. The script in bullet #8 is correct, it’s just a problem with the screenshot so don’t get confused.

Next reboot.

BEFORE going to Step 3, you will need to install a WCF hotfix as described in this post which fixes an "Unrecognized attribute 'allowInsecureTransport'" error. The WCF hotfix for Windows 7 is available here. After installing this hotfix, reboot.

Now you’re at Step 3 and ready to install SharePoint.

Step 3: Install SharePoint 2010

Follow the instructions listed in this step to install SharePoint until you get to bullet #5. When you get here, you need to download and install the SQL Server 2008 KB 970315 x64 hotfix SQL_Server_2008_SP1_Cumulative_Update_2 build
10.00.2714.00 which you get to by clicking the View and request hotfix downloads link at the top of the KB article.

When installing this though I got the error "Invoke or BeginInvoke cannot be called on a control until the window handle has been created." To resolve it, I closed the all open windows including the SharePoint Configuration wizard (which is sitting open after SharePoint is installed) and then I reran the hotfix. Not sure what is going on here but it looks like it’s a known issue on Win 7 64 according to this post.

After that successfully installed I rebooted again.

Now you need to run the SharePoint Configuration wizard, Start –> Programs –> Microsoft SharePoint 2010 Products –> SharePoint 2010 Products Configuration.

Note to domain users: If you are installing as an administrator but your account is part of a domain, you will need to make sure you have online access to the domain controller! Otherwise configuration will fail on Step 2 with “Exception: Microsoft.SharePoint.SPException: User cannot be found.” This happens even though you select to install the standalone version. This bit me because I was installing on a laptop at home and was not on the corporate domain. I had to start my VPN and then I was good to go, until step 5 that is. ;-)

On Step 5 I ran into another error “Failed to register SharePoint services. An exception of type System.ServiceProcess.TimeoutException was thrown.” This happened when I was installing the Server version and not Foundation. However I found a thread that told me this is related to low memory so I closed some other programs I had running and tried it again and it ran fine. This is why you should make sure you have enough memory before starting. ;-)

You made it! SharePoint 2010 Beta should now be installed. To verify, open your browser to http://<MachineName> and you should be able to start playing with your new SharePoint site.

Installing Visual Studio 2010 Beta 2

Everything should be super easy to install now but just in case you may want to save your VHD after you get SharePoint successfully installed ;-).

You’ll need Visual Studio 2010 Beta Professional edition or higher to work with Office & SharePoint. I just picked the whole she-bang, Visual Studio 2010 Ultimate. I used the web installer but you can also choose the ISO package if you want to bring it all down once.

Download Visual Studio 2010 Ultimate (web bootstrapper) (See this page for more download options).

There was no hitch to install all the components of Visual Studio 2010 and .NET Framework 4. It took me about 35 minutes to wait for it to complete with one reboot in the middle. For more information, see the Visual Studio 2010 Beta 2 Readme, Visual Studio 2010 Product Information and Featured Overviews and Walkthroughs.

Installing Microsoft Office 2010 Beta

This one is probably the easiest to install.

Download Office 2010 Beta here.

Scroll to the bottom of the page to get started. You’ll need to register and then you’ll get a product key page with a download button at the bottom. Save your product key and then select the language to download. Note that it says “Download the 32-bit (x86) version:” but the download will include both 32-bit and 64-bit so don’t worry.

Once you click the download button you’ll actually have to install a little download manager to get the setup package. Once you download the package, click on the ProfessionalPlus.exe to start the install. You’ll see a big button “Install Now”. Click that and in about 15 minutes you’ll have Office installed. It doesn’t get much easier than that.

Let ‘er Rip!

Okay so you want to be able to test these things are all installed and playing happily. In order to develop against SharePoint you’ll need to open Visual Studio as run as Administrator. Next, open the Server Explorer and you should see a SharePoint Connections node. Expand that node and you should be able to browse your SharePoint site.

You should also explore some of the awesome new project templates under the Office > 2010 and SharePoint > 2010 nodes in the File > New Project dialog.

What’s Next?

Now it’s time for us to learn how to use these Office and SharePoint tools in Visual Studio! Check out some of my favorite resources:

Office 2010 Development Resources

SharePoint 2010 Development Resources

SharePoint Development in Visual Studio 2010 Walkthroughs

SharePoint Development in Visual Studio 2010 Videos

SharePoint Development Forums

SharePoint 2010 Development Resources

SharePoint Team Blog

Enjoy!

New Learning Resources on the VSTO Developer Center

Beth Massi — Wed, 02 Dec 2009 01:43:20 GMT

Last week we revamped the Learn pages on the VSTO Developer Center with more content that allows you to pivot on more fine-grained topics and tasks under each type of Office solution. We’ve changed the layout of these pages so that you can browse for a type of solution (right now we have Excel, Word, Outlook and Deployment) and then you can drill down into the specific topics to reveal articles and videos underneath. As you select a topic on the left, the content changes on the right so check it out.

We’ve gone through and picked key content in the Visual Studio and Office MSDN libraries, other Developer Centers and blogs to bring you a better integrated learning experience -- especially if you’re just getting started programming Office solutions with Visual Studio. Let me know what topics I’ve missed by making a comment to the end of this post or by contacting me directly and I’ll get them added. Also let me know how you like this layout, I’m planning on taking this approach to the Visual Basic Developer Center as well.

Enjoy!

SF Bay.NET UG Tonight: Create a Custom Outlook Add-In using VSTO

Beth Massi — Wed, 18 Nov 2009 22:23:22 GMT

If you’re in the Bay Area, come on out to downtown SF where Robin will be talking about Outlook Add-ins tonight.

Create a custom Outlook Add-In using VSTO

When: Wednesday, 11/18/2009 at 6:30 PM
Where: Microsoft San Francisco Office, 835 Market Street, Suite 700, San Francisco

Visual Studio 2008 and Office 2007 made it easier than ever to create add-ins for Office. In this session, Robin Shahan will show how to program an add-in for Outlook that modifies the Quick Access Toolbar, adds your own section to the Office Ribbon, and adds a command bar to the main Outlook window. Then she will show you how to deploy the application via ClickOnce deployment.

Presenter's Bio

Robin Shahan has over 20 years of experience developing complex, business-critical applications. She is currently the Director of Engineering for GoldMail, a small company based in San Francisco whose product provides voice-over-visual messages. Robin is a moderator in the MSDN Forum for ClickOnce and Setup & Deployment projects, and vows to learn Windows Installer some day. She is also a Microsoft MVP in Client App Dev; you can follow her blog at http://robindotnet.wordpress.com/, or on Twitter, @RobinDotNet.

Register for this talk tonight on the Bay.NET website.

See you there!

Interop Between VBA and Visual Studio Office Solutions (VSTO)

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

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

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

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

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

Creating an Excel Document Customization

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

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

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

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

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

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

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

Imports VBATest.NorthwindReportService

Public Class ThisWorkbook

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

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

                Dim results As IEnumerable(Of Sales_Totals_by_Amount)

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

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

    Private Sub ThisWorkbook_Startup() Handles Me.Startup

    End Sub

    Private Sub ThisWorkbook_Shutdown() Handles Me.Shutdown

    End Sub

End Class

Calling VBA from VSTO

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

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

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

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

Public Class Ribbon1

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

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

Calling VSTO methods from VBA

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

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

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

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

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

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

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

BUT WAIT… DON’T CLOSE EXCEL YET!

Tips Editing VBA Code when Debugging

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

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

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

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

More Resources

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

Enjoy!

Merging Text & Photos into a Word Document using Open XML SDK

Beth Massi — Fri, 25 Sep 2009 00:55:10 GMT

Yesterday I posted about how we could create a letter generator (mail merge) that took data from a database to create a Word 2007 document using the System.IO.Packaging class. I showed how to take data from Northwind using a single LINQ query to create XDocument objects representing letters to customers and then create a single document of all the data using XML Literals.

Today I want to show how we can embed images into the documents as well as text. Since we’re using Northwind for this example, we’ll use the Employee.Photo field from that database.

The Letter Template with Photo

The first thing to do is create a letter template with our field placeholders as well as an image placeholder. We’ll also need to insert a page break at the end because we’re going to merge all the letters into a single document for easy printing:

The next step is to grab the document.xml from this docx file. Because it’s an Open XML package, as I showed in yesterday’s post, we can just rename this file with a .zip extension temporarily and drill into the word\document.xml. However, there’s an easier way to work with these packages by installing the Open XML package editor Visual Studio add-in from the VSTO Power Tools download.

Once you install the VSTO Power tools, save this template in your project. Then you can just double-click on the .docx file in the Solution Explorer and it will open the package editor (it also works with .pptx and .xslx files). Now you can drill into the document.xml directly in Visual Studio and inspect all the parts of the package easily.

The difference between this template and the template we used yesterday is there is an image imbedded into the document. So you will see an image embedded into the package in the media folder. This is referred to as an “image part”. This part is linked to the “main document part” which is the word\document.xml file. The Open XML package editor shows the links (relationships) to all the parts. When you look at the relationship properties you’ll see that it has a unique ID. This is the same ID that you will see in the main document part at the point where we embedded the image, in our case it’s set to rId4. (I’ve omitted all the WordProccessingML for clarity):

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<w:document ...
  <w:body> ...

        <w:drawing> ...

              <a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
              <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
                <pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
                  <pic:nvPicPr>
                    <pic:cNvPr id="0" name="image1.png"/>
                    <pic:cNvPicPr/>
                  </pic:nvPicPr>
                  <pic:blipFill>
                    <a:blip r:embed="rId4" cstate="print"/>
                    <a:stretch>
                      <a:fillRect/>
                    </a:stretch>
                  </pic:blipFill>
                  <pic:spPr>
                    <a:xfrm>
                      <a:off x="0" y="0"/>
                      <a:ext cx="1829055" cy="2124372"/>
                    </a:xfrm>
                    <a:prstGeom prst="rect">
                      <a:avLst/>
                    </a:prstGeom>
                  </pic:spPr>
                </pic:pic>
              </a:graphicData>
            </a:graphic> ...
          
        </w:drawing> ...

        <w:p w:rsidR="00622A50" w:rsidRDefault="00622A50">
            <w:r>
                <w:br w:type="page"/>
            </w:r>
        </w:p> ...

  </w:body>
</w:document>

Installing the Open XML SDK

As I mentioned yesterday, manipulating the package directly with the System.IO.Packaging classes gets a little bit tricky when you have to start adding embedded images and objects and linking them together. Instead, it’s easier to use the Open XML SDK to do this because it will handle linking new image parts we add to the package automatically for us. The SDK provides a strongly-typed way of accessing the parts in a package so it cuts down on the amount of code you have to write yourself. Version 1.0 requires only .NET 2.0, Version 2 requires .NET 3.5 and uses LINQ to provide more functionality when querying the parts. This version is currently a CTP. For what we’re doing you can use either version but I have Version 2 installed.

The assembly that is installed in the GAC when you install the SDK is called DocumentFormat.OpenXml.dll and you’ll need to add a project reference to this. When you distribute your application you can simply xcopy the assembly with your application for easy deployment. (After you add the reference, select it in the Server Explorer and then in the Properties window set Copy Local to True in order to have it outputted to the \bin folder when you build your application.)

Now we can add the namespace imports we’ll be working with at the top of our program, including the DocumentFormat.OpenXml.Packaging namespace:

Imports <xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
Imports System.Xml
Imports System.IO
Imports DocumentFormat.OpenXml.Packaging

Modifying the Letter Class and LINQ Query to Get the Photo

In order to create letters for our customers in the database, we want to end up with a collection of XDocuments with our data merged into them. I created a Letter class that has two properties, CustomerID As String and Document As XDocument. We’re also going to add a new property for the photo byte array called EmployeePhoto As Byte() and OrderID as Integer. Next we need to modify the query so that it selects the photo as well as add the above WordProcessingML into our XML Literal to specify where the image should appear in the document. Because the relationship IDs must be unique, I’m going to use the OrderID as the suffix for the relationship ID for each of the images we want to embed. Like before, we can use embedded expressions to merge the data into the right places in the XDocument.

(I’ve omitted all the XML with the embedded expressions for clarity, take a loot at the code sample for the whole listing.) The bolded areas show the modified sections of the query:

Dim letters = _
  From Order In db.Orders _
  Join Employee In db.Employees _
    On Order.EmployeeID Equals Employee.EmployeeID _
  Where Order.OrderDate IsNot Nothing AndAlso _
    Order.ShippedDate IsNot Nothing AndAlso _
    Order.ShippedDate.Value.Date >= #1/1/1998# _
  Let DateOrder = Order.OrderDate.Value.ToShortDateString _
  Let DateShip = Order.ShippedDate.Value.ToShortDateString _
  Select New Letter With { _
    .CustomerID = Order.CustomerID, _
    .OrderID = Order.OrderID, _



    .EmployeePhoto = If(Employee.Photo IsNot Nothing, Employee.Photo.ToArray, Nothing), _
    .Document = <?xml version="1.0" encoding="utf-8" standalone="yes"?>
        <w:document ... 
            <w:body> ...
                <w:p w:rsidR="00A9498E" w:rsidRDefault="00A9498E" w:rsidP="00AA2EC6">
                    <w:r>
                        <w:t xml:space="preserve">If you have any issues please contact </w:t>
                    </w:r>
                    <w:proofErr w:type="spellStart"/>
                    <w:r>
                        <w:t><%= Employee.FirstName & " " & Employee.LastName %></w:t>
                    </w:r>
                    <w:proofErr w:type="spellEnd"/>
                        <w:r>
                            <w:t xml:space="preserve"> at</w:t>
                        </w:r>
                        <w:r w:rsidR="005F35D6">
                            <w:t xml:space="preserve"> ext.</w:t>
                        </w:r>
                        <w:r>
                            <w:t xml:space="preserve"></w:t>
                        </w:r>
                        <w:r w:rsidR="005F35D6">
                            <w:t><%= Employee.Extension %></w:t>
                        </w:r>
                        </w:p> ...
                        <w:drawing> ...
                            <pic:blipFill> ...
                                <a:blip r:embed=<%= "rId" & Order.OrderID %>/> ...
                        </w:drawing> ...
                        <w:p w:rsidR="00622A50" w:rsidRDefault="00622A50">
                            <w:r>
                                <w:br w:type="page"/>
                            </w:r>
                        </w:p> ...
                    </w:body>
                </w:document>}

The query returns an IEnumerable(Of Letter) objects with the Document property set to the document.xml data for that customer and the EmployeePhoto set to the photo byte array. If we wanted to create separate documents (which is exactly what I demonstrated in my DevProConnections article) it’s actually pretty simple because all we need to do is copy the template and then replace the document.xml and the image data, we don’t have to mess with the relationship ID at all. However if we want to create a single document with all our letters we need to delete the placeholder image part and add new unique image parts for the Letter.EmployeePhoto.

Adding and Linking the Images into a Single Word Document

Because relationship IDs must be unique in a document I used the OrderID as the embedded expression for the r:embed attribute in the XML Literal above. You can choose to use any unique ID you want but it must start with an alpha character, that’s why I prefixed it with “rId”. When you use the Open XML SDK to add the new image parts we have to specify the relationship ID to use. To update the code we wrote yesterday to work with the Open XML SDK and also work with images we first need to add a call to open the Word document template, grab the main document part and then delete the image part by calling DeletePart:

'Place the letters in a separate directory
Dim sourceFile = CurDir() & "\LetterTemplate.docx"
Dim letterDir = CurDir() & "\Letters\"
My.Computer.FileSystem.CreateDirectory(letterDir)

Dim mergeFile = letterDir & "AllLetters.docx"
My.Computer.FileSystem.CopyFile(sourceFile, mergeFile, True)

'Open the Document template using the Open XML SDK
Using wordDoc = WordprocessingDocument.Open(mergeFile, True)

    'get the main document part (document.xml)
    Dim mainPart = wordDoc.MainDocumentPart()

    'Delete the placeholder image from the template so we can replace it with the real photos
    mainPart.DeletePart("rId4")

This opens the Word document as read/write and then deletes the placeholder image. You should also notice at this point that the code is a bit simpler to open the package than yesterday because we don’t have to declare the relative URI’s or content types. The Open XML SDK helps us here. Next we need to load the document.xml into an XElement object and grab the body:

    Dim mainDocumentXML As XElement
    Using sr As New StreamReader(mainPart.GetStream)
        mainDocumentXML = XElement.Load(sr)
    End Using

    Dim mainBody = mainDocumentXML...<w:body>.First()
    Dim i = 0

Now we can loop through all the letters, grab the body of those XDocuments and then add an image part. We need to specify the content type and the relationship ID that must match what we embedded in the XML Literal in our query. Then we can either replace the main document body with the first letter (overwrite our placeholder data) otherwise we append the rest of the letter contents into the document:

    For Each letter In letters
        Dim nextBody = letter.Document...<w:body>.First()
        'Add the new imagePart. The SDK takes care of linking this properly.
        Dim imagePart = mainPart.AddImagePart("image/png", "rId" & letter.OrderID)

        If i = 0 Then
           'Replace the first body contents in the template
           mainBody.ReplaceNodes(nextBody.Elements())
        Else
           'Otherwise append the next letter contents
           mainBody.Add(nextBody.Elements())
        End If

Next we need to feed the byte array data into the ImagePart. Note that since I’m using Northwind for this example there is an OLE header on those images that we must strip off that is 78 bytes. If you are using your own images stored in SQL Server you won’t have to do that:

        'Now feed the byte array into the ImagePart
        If letter.EmployeePhoto IsNot Nothing Then
            'Using ms As New System.IO.MemoryStream(letter.EmployeePhoto.ToArray)
            'NOTE: Northwind Photos have an OLE header on them that we must strip off.
            ' You don't have to do this if you are using your own SQL-server stored images
            Using ms As New System.IO.MemoryStream(letter.EmployeePhoto, 78, _
                                                   letter.EmployeePhoto.Length - 78)
                imagePart.FeedData(ms)
            End Using
        End If

        i += 1
    Next

Now that we’ve built up the document XML, added our image parts and linked them properly, the final step is to replace the document part with our XML just like before:

    'Replace the document part with our XML
    Using sw As New StreamWriter(mainPart.GetStream(FileMode.Create))
        mainDocumentXML.Save(sw)
    End Using

End Using

Now when we run the application you will see a single document with all the letters, including photos, that’s much easier to print than multiple files.

There’s Always Room for Improvement

LINQ & Northwind savvy folks may notice that I’m actually creating duplicates of the employee photos. Since I’m flattening out the data in my query to have 1 photo per order there could be an unnecessary amount of duplicate images. This can cause the document to get bloated. To be more efficient we should reuse the relationship ID’s to the images if they are the same on multiple orders. One approach would be to modify the LINQ query and Letter object to select the EmployeePhoto and then have a collection of order & document data under that. I’ll leave that experiment up to you :-)

Take a look at the full code listing for this example as well as the complete project with other Open XML examples here on Code Gallery.

Enjoy!

Mail Merging Into a Single Word Document Using XML Literals

Beth Massi — Thu, 24 Sep 2009 02:18:00 GMT

With the release of Microsoft Office 2007 we can work with a much simpler, standard, XML format called Open XML which opens the door for many types of applications that cannot work via COM. What if you needed to build a scalable web service that processes many documents in high volume? What if you wanted to quickly read or write to these formats from a client application but wanted to have minimal dependencies on other applications? These types of programs do not want to require Microsoft Office be installed to run. The cool thing is you have the tools already with Visual Basic 2008. XML Literals are an easy way to manipulate any kind of XML, including Open XML.

I’ve written before on how to use XML Literals to manipulate Word documents, if you missed them:

If you aren’t familiar with XML Literals or Open XML then I’d suggest reading the article in the first bullet above first. It’s a great intro into XML Literals, Open XML and it also demonstrates a couple practical ways of reading and writing to Word document formats directly.

Recently I got a great question on how to change the program outlined in the last bullet above to merge letters we were creating on the fly from a database into a single document instead of multiple documents like we’re doing. This would make it much easier for an end user to print them. That’s such an obvious thing I can’t believe I didn’t think of that! For those of you that aren’t familiar with what we did I’ll give a quick recap of that application.

Creating Word Documents with XML Literals

What I wanted to do is take all the Customers in the Northwind database who had some orders shipping today and send them thank you letters. To get started I created a new Word 2007 document with the letter text and some placeholder field names to indicate where I want the data:

Save the document (I named it Doc1.docx) and then rename the .docx extension to .zip and you can drill into the package and see a bunch of XML documents inside it. If we drill down through the zip file we'll see that the text we just typed is located in the \word\document.xml file. Copy this xml and paste it into the Visual Basic editor, it will infer it as an XDocument object, and then you can use embedded expressions to replace the placeholders. (If I’ve lost you, read this article which explains it step-by-step.)

In order to create letters for our customers in the database, we want to end up with a collection of XDocuments with our data merged into them. I created a simple class called Letter that has two properties, CustomerID As String and Document As XDocument. Then I wrote a LINQ query to select the data and embed it into the document (I’ve omitted all the WordProcessingML for clarity, take a loot at the code sample for the whole listing.)

Dim letters = _
    From Order In db.Orders _
    Join Employee In db.Employees _
        On Order.EmployeeID Equals Employee.EmployeeID _
    Where Order.OrderDate IsNot Nothing AndAlso _
        Order.ShippedDate IsNot Nothing AndAlso _
        Order.ShippedDate.Value.Date >= #1/1/2007# _
    Let DateOrder = Order.OrderDate.Value.ToShortDateString _
    Let DateShip = Order.ShippedDate.Value.ToShortDateString _
    Select New Letter With { _
        .CustomerID = Order.Customer.CustomerID, _
        .Document = <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <w:document ...
    <w:p w:rsidR="00705CFF" w:rsidRDefault="00112228" w:rsidP="00AA2EC6">
        <w:r>
            <w:br/>
        </w:r>
        <w:r w:rsidR="007A5236">
            <w:t xml:space="preserve">Dear </w:t>
        </w:r>
            <w:proofErr w:type="spellStart"/>
        <w:r>
            <w:t><%= Order.Customer.ContactName %></w:t>
        </w:r>
        <w:proofErr w:type="spellEnd"/>
            <w:r w:rsidR="00AA2EC6">
                <w:t>,</w:t>
            </w:r>
     </w:p>
     <w:p w:rsidR="00E04FB0" w:rsidRDefault="00AA2EC6" w:rsidP="00AA2EC6">
        <w:r>
            <w:t xml:space="preserve">We’d like to inform you that the order you placed on </w:t>
        </w:r>
        <w:proofErr w:type="spellStart"/>
            <w:r w:rsidR="00112228">
                <w:t><%= DateOrder %></w:t>
            </w:r>
        <w:proofErr w:type="spellEnd"/>
            <w:r w:rsidR="00806521">
                <w:t xml:space="preserve"> has shipped on </w:t>
            </w:r>
        <w:proofErr w:type="spellStart"/>
            <w:r w:rsidR="00112228">
                <w:t><%= DateShip %></w:t>
            </w:r>
... </w:document>}

The query returns an IEnumerable(Of Letter) objects with the Document property set to the document.xml data for that customer. The next step involved taking the template Doc1.docx file, making a copy of it and then simply replacing the document.xml part inside the package with the one here in the Letter class for each letter. However, what I did was create separate letters for each customer. Instead we want to create one .docx file with ALL the letter data merged inside.

Merging into a Single Word Document

The first thing we need to do is insert a page break between all our letters. The easiest thing to do is to open back up your template Doc1.docx file in Word and insert a page break, save it, and then look at the document.xml again in the package. You should see this WordProccessingML element inserted near the end:

<w:p w:rsidR="00622A50" w:rsidRDefault="00622A50">
    <w:r>
        <w:br w:type="page"/>
    </w:r>
</w:p>

Paste this into the query above in the document exactly where you pulled it out of the document.xml.

Next we have a couple options on how to manipulate the package (docx file). I’ve shown how to use the Open XML SDK before to manipulate documents but in this simple case we can use the System.IO.Packaging classes directly. This is because all we’re doing is working with text in the document. If we were working with images or embedded objects it would be easier to use the SDK. In the next post we’ll add photos of the employees on each order into the document, but for this post let’s just focus on how to merge the text.

So the first thing we need to do is Import some namespaces including an XML namespace that we’re going to use:

Imports <xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
Imports System.IO
Imports System.IO.Packaging

Next we need to set up some variables and copy the Doc1.docx template to a new file I’m calling AllLetters.docx.

Dim uri As New Uri("/word/document.xml", UriKind.Relative)
Dim contentType = "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"
Dim sourceFile = CurDir() & "\Doc1.docx"
Dim letterDir = CurDir() & "\Letters\"
My.Computer.FileSystem.CreateDirectory(letterDir)

Dim mergeFile = letterDir & "AllLetters.docx"
My.Computer.FileSystem.CopyFile(sourceFile, mergeFile, True)

Now we can open the template package and load the main document part as an XElement:

Using p As Package = Package.Open(mergeFile)

    'get the main document part (document.xml)
    Dim mainPart = p.GetPart(uri)
    Dim mainDocumentXML As XElement




    Using sr As New StreamReader(mainPart.GetStream)
        mainDocumentXML = XElement.Load(sr)
    End Using

The next part is where it gets fun. A word document has a top element structure like this:

<w:document>
    <w:body>
       ...
    </w:body>
</w:document>

So what we need to do is grab the body of the template, replace it with the first customer’s document body we have and then append the rest of the elements inside the bodies of the rest of the documents. A word document can only have one <w:body> element for it to be legal. The way we get the <w:body> XElement from the document is using the descendants syntax with the three dot notation (…):

    Dim mainBody = mainDocumentXML...<w:body>.First()
    Dim i = 0

    For Each letter In letters
        Dim nextBody = letter.Document...<w:body>.First()
        If i = 0 Then
            'Replace the first body contents in the template
            mainBody.ReplaceNodes(nextBody.Elements())
        Else
            'Append the new contents for the rest of the customers
            mainBody.Add(nextBody.Elements())
        End If
        i += 1
    Next

Now that we’ve built up the right body with all our letter data in it, we can replace the main document.xml part in the package and close it.

    'Delete the current document.xml file in the template
    p.DeletePart(uri)
    'Replace that part with our new merged XDocument
    Dim replace As PackagePart = p.CreatePart(uri, contentType)

    Using sw As New StreamWriter(replace.GetStream())
        mainDocumentXML.Save(sw)
        sw.Close()
    End Using

    p.Close()
End Using

Now when we run this, all the letters will be mail merged into the same document for easy printing:

As I mentioned if we have embedded images or objects that we need to replace it gets a little trickier. In the DevProConnections Article I have an example of how to create multiple documents with embedded pictures of the employee’s photo. In the next post I’ll show you how we can use the Open XML SDK to create a single document with embedded pictures as well.

Until then, have a look at the complete code I put up on Code Gallery.

[UPDATE: Merging Text & Photos into a Word Document using Open XML SDK]

Enjoy!

DevProConnections Article: Taking Advantage of LINQ and XML in Microsoft Office 2007

Beth Massi — Mon, 17 Aug 2009 20:05:00 GMT

This month I have an article on DevProConnections:

Taking Advantage of LINQ and XML in Microsoft Office 2007

In this article, I talk about how a lot of applications that need to take advantage of Microsoft Office can do so without going through COM. Many programs that need to process documents often require manipulation of the file formats directly and doing that through the Office component object model won’t scale very well. It also requires that Microsoft Office be installed to run. A better route in a lot of these cases is to use the Open XML SDK. With the release of Office 2007, Word documents, Excel spreadsheets and PowerPoint presentations are based on an open standard for packaging XML files called Open XML. Using Visual Basic’s powerful and simple implementation of LINQ to XML you can work with these new document formats much easier than ever before.

I show a couple practical examples of reading data from Word documents and updating a database as well as reading data from a database to create Word documents – all without COM. No Office applications need to be installed in order to read and write to these formats directly.

This article is based on the two episodes I did on DnrTV:

[UPDATE: Here's code samples (also includes a presentation pptx)]

Working with Open XML in Visual Basic

More resources:

Open XML Format SDK 2.0

Open XML Resource Center

Microsoft Visual Studio Tools for the Office System Power Tools v1.0.0.0

Word 2007 Content Control Toolkit

VSTO Developer Center

Visual Basic Developer Center

Enjoy!

Using Windows Presentation Foundation in Office Clients

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

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

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

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

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

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

OBA Part 1 - Exposing Line-of-Business Data

OBA Part 2 - Building and Outlook Client against LOB Data

OBA Part 3 - Storing and Reading Data in Word Documents

OBA Part 4 - Building an Excel Client against LOB Data

OBA Part 5 - Building the SharePoint 2007 Workflow

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

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

Enjoy!

Community Article: Automate Common Office Tasks

Beth Massi — Fri, 26 Jun 2009 01:34:52 GMT

If you haven’t seen it yet, we’ve got a new article from Robert Green (VSTO MVP) up on the Visual Basic and VSTO Dev Centers. In this article, learn how you can use Visual Basic to build application-level add-ins that automate common Microsoft Office tasks. It’s a good introduction to Office development with Visual Studio so check it out!

Create an Application-Level Add-In to Automate Common Office Tasks

Enjoy!

Getting a Count of Unread Email in Outlook

Beth Massi — Tue, 28 Apr 2009 19:02:00 GMT

Last post I was talking about DataSets and aggregating data with LINQ and the example I gave was around finding rows of data where the Status = “Unread”. This got me thinking about how we could do this by asking Outlook for my unread email count – one of the programs I spend a lot of time in ;-). This actually is a pretty easy thing to do if you use the Primary Interop Assembly (PIA) for Outlook – Microsoft.Office.Interop.Outlook. Add a reference to your project and then import the namespace at the top of your program.

Imports Microsoft.Office.Interop.Outlook

Then you can write the following code:

Dim OutlookApp As New Application()
Dim myMail As [NameSpace] = OutlookApp.GetNamespace("MAPI")

myMail.Logon(ShowDialog:=True, NewSession:=False)
Dim count As Integer = myMail.GetDefaultFolder(OlDefaultFolders.olFolderInbox).UnReadItemCount

Note that if you have selected an Outlook Add-in project template in Visual Studio then you already have reference to the Application and you’re already logged in so the code is even simpler:

Dim myMail As [NameSpace] = Me.Application.GetNamespace("MAPI")
Dim unread As Integer = myMail.GetDefaultFolder(OlDefaultFolders.olFolderInbox).UnReadItemCount

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!

dnrTV: Showing off the Open XML SDK and LINQ

Beth Massi — Wed, 08 Apr 2009 01:05:00 GMT

Yesterday Carl posted another dnrTV show with yours truly. This time I’m talking about the Open XML SDK, something that I’ve written and spoken about many times. In this episode I show how to use Word 2007 content controls and map them to custom XML parts so that you can query structured data from unstructured documents using Visual Basic’s LINQ to XML. What’s really cool about the Open XML format is that you don’t need Office installed at all – no COM Interop needed. You’re working with the file formats directly. And it’s super simple using VB’s XML literals and LINQ with the SDK.

Unfortunately I didn’t have a lot of time when I did the show with Carl and I couldn’t finish my demos. So this morning I filmed another quick episode that shows how to create documents from database data directly, so keep on the lookout for the follow up show :-).

dnrTV Show: Beth Massi on the Open XML SDK

And here are the links from the show:

[UPDATE: Here's code samples (also includes a presentation pptx)]

Working with Open XML in Visual Basic

Enjoy!