Beth Massi - Sharing the goodness that is VB : SharePoint

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!

Channel 9 Interview: Implementing a Silverlight SharePoint WebPart with Visual Studio 2010

Beth Massi — Wed, 25 Nov 2009 17:37:35 GMT

Mike Morton is back at it again, this time showing how easy it is to develop, package and deploy a Silverlight WebPart to SharePoint 2010. He also walks us through the solution, package and file properties available to you in Visual Studio 2010. You'll see me giggling in this one because I can't believe how easy it is.

Channel 9 Interview: Implementing a Silverlight SharePoint WebPart with Visual Studio 2010

For more information on SharePoint Development in Visual Studio 2010 please see:

Also if you missed them, check out these interviews as well:

And please give us your feedback in the SharePoint Development Forums!

Enjoy!

Channel 9 Interview: Using the SharePoint Business Data Connectivity Designer in VS 2010

Beth Massi — Mon, 23 Nov 2009 17:33:45 GMT

This time I interview a good friend of mine, Boris Scholl, a Program Manager on the Visual Studio Team building tools for SharePoint development. Boris shows off the new Business Data Connectivity designer in Visual Studio 2010 and how it allows you to describe data coming from multiple data sources and how to work with them in SharePoint. He builds a master/detail association across entities coming from separate data sources (a database and a service) and demonstrates how the entities can be displayed and edited.

Channel 9 Interview: Using the SharePoint Business Data Connectivity Designer in Visual Studio 2010

For more information on SharePoint Development in Visual Studio 2010 please see:

Also if you missed them, check out these interviews as well:

And please give us your feedback in the SharePoint Development Forums!

Enjoy!

Channel 9 Interview: SharePoint Feature and Package Designers in Visual Studio 2010

Beth Massi — Thu, 19 Nov 2009 18:21:30 GMT

In this interview I sit down with Lily Ma, a Program Manager on the Visual Studio Team building tools for SharePoint development. Lily shows off the new SharePoint feature and package designers in Visual Studio 2010 and how they make packaging up and deploying your SharePoint customizations easy. As she dives deeper into the tools, she also demonstrates the flexibility and control you have in specifying what features go in what packages across projects in your solution as well as how to modify the manifests to meet a variety of developer needs.

Channel 9 Interview: SharePoint Feature and Package Designers in Visual Studio 2010

Also if you missed it, check out these interviews as well:

For more information on SharePoint Development in Visual Studio 2010 please see:

SharePoint Development in Visual Studio 2010 Walkthroughs

SharePoint Development in Visual Studio 2010 Samples

SharePoint 2010 Development Resources

SharePoint Team Blog

Office Development in Visual Studio Team Blog

And please give us your feedback in the SharePoint Development Forums!

Enjoy!

Channel 9 Interview: Importing SharePoint Solution Packages (WSP) into Visual Studio 2010

Beth Massi — Wed, 18 Nov 2009 20:47:10 GMT

In this interview I sit down with Saaid Khan, a Program Manager on the Visual Studio team developing tools for SharePoint development. Saaid shows us the WSP Import Wizard in Visual Studio 2010 that allows developers to take SharePoint Solution packages developed with SharePoint Designer and bring them into Visual Studio 2010 to further customize them there.

Channel 9 Interview: Importing SharePoint Solution Packages (WSP) into Visual Studio 2010

Also if you missed it, check out Overview of SharePoint Development in Visual Studio 2010 which I posted on Monday.

For more information on SharePoint Development in Visual Studio 2010 please see:

SharePoint 2010 Development Resources

SharePoint Development in Visual Studio 2010 Walkthroughs

SharePoint Development in Visual Studio 2010 Samples

SharePoint Team Blog

Office Development in Visual Studio Team Blog

And please give us your feedback in the SharePoint Development Forums!

Enjoy!

Channel 9 Interview: Overview of SharePoint Development in Visual Studio 2010

Beth Massi — Mon, 16 Nov 2009 23:53:00 GMT

In this interview I catch up with Mike Morton, a Senior Program Manager on the Visual Studio team developing tools for SharePoint development. Mike gives us a great introduction and overview of these tools from the Visual Studio Developer perspective. Mike shows us how easy it is to build, package, deploy and debug SharePoint 2010 customizations by walking through a site workflow, event receiver, visual web part, the feature and package designers as well as other goodies. This is a great intro for Visual Studio developers looking to get into SharePoint development, but seasoned SharePoint developers will also appreciate the new tools presented here:

Channel 9 Interview: Overview of SharePoint Development in Visual Studio 2010

For more information on SharePoint Development in Visual Studio 2010 please check out:

SharePoint 2010 Development Resources

SharePoint Development in Visual Studio 2010 Walkthroughs

SharePoint Development in Visual Studio 2010 Samples

SharePoint Team Blog

Office Development in Visual Studio Team Blog

And give us your feedback in the SharePoint Development Forums!

Enjoy!

New Channel 9 Videos on Visual Studio 2010

Beth Massi — Tue, 27 Oct 2009 18:29:19 GMT

I’ve noticed that folks have been busy creating video content on the newly released Visual Studio 2010 Beta 2 while I’ve been gone! (I’ve got a couple up my sleeve that I’ll post soon as well ;-))

For instance, Kathleen’s continuing her series of Visual Studio 2010 interviews, this time she’s got Norm Estabrook talking us through how to create a SharePoint external list using the BDC designer in Visual Studio 2010 and Mick Alberts on the “no PIAs” feature, Embedding Type Information from Microsoft Office Assemblies. I’m told she’ll be releasing another one with Norm this week on building a SharePoint Web part with VS2010 so keep an eye out on her blog.

A lot of other folks are creating content on Channel 9 around Visual Studio 2010 so check out the feed. Some recent notables:

Stay tuned on this channel for more….

Enjoy!

OBA Part 5 - Building the SharePoint 2007 Workflow

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

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

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

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

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

Creating a Document Library for the Purchase Order Documents

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

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

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

For this example I added the following columns:

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

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

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

Adding the Order Number to Northwind

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

USE Northwind
GO

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

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

Options on Hosting the Data Service for Workflow Development

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

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

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

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

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

Creating the SharePoint Workflow

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

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

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

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

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

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

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

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

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

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

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

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

Parsing the Order Document (CodeActivity parseOrder)

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

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

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

Public Class Shredder

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

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

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

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

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

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

Public Class ProcessOrder
    Inherits SequentialWorkflowActivity

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

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

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

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

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

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

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

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

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

    End Sub

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

Querying the Database Periodically (WhileActivity waitForProcessed)

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

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

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

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

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

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

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

    End Sub

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

Imports OBADemoWorkflow.NorthwindServiceReference

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

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

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

            Return theOrder

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

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

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

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

>Net Stop SPTimerV3
>iisreset
>Net Start SPTimerV3

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

Wrapping Up the Workflow (History Logging and Creating Tasks)

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

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

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

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

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

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

Testing the Workflow

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

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

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

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

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

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

Enjoy!

OBA Part 3 - Storing and Reading Data in Word Documents

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

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

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

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

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

Content Controls

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

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

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

Creating and Mapping the XML

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

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

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

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

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

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

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

Using the Open XML SDK to Retrieve the Order Data

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Now we can write our main program:

Module Module1

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

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

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

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

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

        Console.ReadLine()
    End Sub

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

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

Module Extensions

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

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

        Return xdoc
    End Function
End Module

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

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

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

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

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

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

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

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

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

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

                Next
            End If
            wordDoc.Close()
        End Using

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

    Return orderData
End Function

Updating the Database through the Data Service

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

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

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

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

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

        If cust IsNot Nothing Then

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

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

            Dim o As New Order()

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

            ctx.AddToOrders(o)

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

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

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

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

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

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

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

                    ctx.AddToOrder_Details(detail)

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

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

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

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

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

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

Enjoy!

Building an Office Business Application for TechReady 8

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

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

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

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

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

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

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

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

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

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

Until next time....

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