Welcome to MSDN Blogs Sign in | Join | Help

Andrew Whitechapel

Visual Studio, Office and other Nonsense
VSTO Loader and Runtime Components

Perusing the forums over the last few months, it’s clear that there’s some confusion about the various VSTO loader and runtime components. At the time of writing, there are 4 versions of VSTO in existence, including 4 sets of design-time tooling and 3.5 versions of the VSTO runtime. I say 3.5 versions, because the VSTO 2005 SE runtime was an in-situ replacement for the VSTO 2005 runtime, and both are considered VSTO v2 (2005 SE was purely additive to 2005). Other versions – that is, VSTO 2003 (v1) and VSTO 2008 (v3) – are SxS with v2.

Right now, each VSTO solution runs against the version of the VSTO runtime that it was built against, regardless of the version of Office that is hosting it. It can be confusing to figure out which version will be used, so here’s a breakdown. The 4 versions of VSTO in existence at the time of writing are:

·         VSTO 2003 (VSTO v1 runtime), which supported doc-level customizations for Excel and Word 2003 only, in a very simple fashion.

·         VSTO 2005 (VSTO v2 runtime), which provided very much broader and deepter runtime support for Excel/Word 2003 doc-level customizations, and introduced app-level add-in support for Outlook 2003.

·         VSTO 2005 SE (VSTO v2 runtime), which maintained the v2 runtime support for Excel/Word 2003 doc-level customizations, and replaced the app-level add-in support – extending it to cover Excel, Outlook, PowerPoint, Visio and Word 2003, and Excel, InfoPath, Outlook, PowerPoint, Visio and Word 2007.

·         VSTO 2008 (VSTO v3 runtime), which maintained the v2 runtime support for Excel/Word 2003 doc-level customizations, and added v3 runtime support for Excel/Word 2007 doc-level customizations. Also maintained the v2 runtime support for app-level add-ins for Excel, Outlook, PowerPoint, Visio and Word 2003, and added Project 2003. Also added v3 runtime support for app-level add-ins for Excel, InfoPath, Outlook, PowerPoint, Project, Visio and Word 2007. Plus, added design-time support for SharePoint 3.0 Workflow.

The runtime versions are used as follows, first the doc-level solution types:

·         A VSTO 2003 v1 doc-level solution will always run with the VSTO v1 runtime. You could only create a VSTO 2003 solution for Excel/Word 2003, but the solution should continue to run without change in Excel/Word 2007 – and it will continue to use the VSTO v1 runtime.

·         A VSTO 2005 v2 doc-level solution will always run with the VSTO v2 runtime. There’s no such thing as a VSTO 200 SE doc-level solution, because VSTO 2005 SE was additive to VSTO 2005, adding only app-level add-in support. Again, a VSTO 2005 doc-level solution built against Excel/Word 2003 should continue to run unchanged in Excel/Word 2007 and will continue to use the VSTO v2 runtime.

·         A VSTO 2008 doc-level solution for Excel/Word 2003 will use the VSTO v2 runtime. It should also continue to run without change in Excel/Word 2007 and will continue to use the VSTO v2 runtime.

·         A VSTO 2008 doc-level solution for Excel/Word 2007 will use the VSTO v3 runtime. It will not run in Excel/Word 2003.

Similar patterns hold true for app-level add-ins:

·         A VSTO 2005 v2 Outlook add-in will run against the VSTO 2005 v2 runtime so long as VSTO 2005 SE is not installed. If VSTO 2005 SE is installed, then the add-in will run against the VSTO 2005 SE v2 runtime.

·         A VSTO 2005 SE v2 add-in for Excel, Outlook, PowerPoint, Visio or Word 2003 will run against the VSTO 2005 SE v2 runtime. It will not run if the VSTO 2005 SE runtime is not installed. It will continue to run without change in Excel/Outlook/PowerPoint/Visio/Word 2007, and it will continue to use the VSTO 2005 SE v2 runtime.

·         A VSTO 2005 SE v2 add-in for Excel, InfoPath, Outlook, PowerPoint, Visio or Word 2007 will run against the VSTO 2005 SE v2 runtime. It will not run if the VSTO 2005 SE runtime is not installed. It will not run in Office 2003 because it requires the Office 2007 PIAs which are not designed to be used with Office 2003.

·         A VSTO 2008 add-in for Excel, Outlook, PowerPoint, Project, Visio or Word 2003 will run against the VSTO 2005 SE v2 runtime. It will not run if the VSTO 2005 SE runtime is not installed. It will continue to run without change in Excel/Outlook/PowerPoint/Project/Visio/Word 2007, and it will continue to use the VSTO 2005 SE v2 runtime.

·         A VSTO 2008 add-in for Excel, InfoPath, Outlook, PowerPoint, Project, Visio or Word 2007 will run against the VSTO 2008 v3 runtime. It will not run if the VSTO 2008 runtime is not installed. It will not run in Office 2003 because it requires the Office 2007 PIAs which are not designed to be used with Office 2003.

The different versions of the VSTO runtime include different loader components. The load sequence therefore varies according to the version of the solution. For doc-level customizations, the load sequences are:

·         VSTO 2005: Otkloadr.dll à VSTOLoader.dll à VSTORuntime.dll à solution

·         VSTO 2005 SE Office 2003: Otkloadr.dll à VSTOLoader.dll à VSTORuntime.dll à solution

·         VSTO 2005 SE Office 2007: Otkloadr.dll à VSTOLoader.dll à VSTORuntime.dll à solution

·         VSTO 2008 Office 2003: Otkloadr.dll à VSTOLoader.dll à VSTORuntime.dll à solution

·         VSTO 2008 Office 2007: VSTOEE.dll à VSTOLoader.dll à solution

The load sequences for app-level add-ins are:

·         VSTO 2005: AddinLoader.dll à solution

·         VSTO 2005 SE Office 2003: AddinLoader.dll àVSTORuntime.dll à solution

·         VSTO 2005 SE Office 2007:  VSTOEE.dll àAddInLoader.dll à VSTORuntime.dll à solution

·         VSTO 2008 Office 2003: AddInLoader.dll à VSTORuntime.dll à solution

·         VSTO 2008 Office 2007: VSTOEE.dll à VSTOLoader.dll à solution

Why do we have so many runtime versions, you might ask? Why is it so seemingly complicated? Well, the runtimes are designed for the opposite purpose – the intention is to make life simple for users – users should not need to worry about which version is used, and we have multiple versions to ensure that all solutions will continue to run without change in the face of new versions of Office. A major factor in this is the requirement that a deployed solution should continue to work without any user/admin intervention even though the user might upgrade the version of Office on their machine. They might have multiple solutions deployed which were built over time against multiple versions of VSTO – and all of them should just continue to work.

Posted: Wednesday, April 02, 2008 7:06 PM by andreww

Comments

Jaimie Birk said:

I am getting bogged down in version confusion.

I have a document level customization created in VSTO SE.  It opens and runs ok in both Excel 2003 and Excel 2007.  Once someone saves it as an Excel 2007 document (xlsm), I can't figure out how to use the ServerDocument on it.

If I use the SE ServerDocument (in VS.Tools.Applications.Runtime), it tells me "Could not create a persistence object for the specified file".  If I try to use the VSTO3 ServerDocument (int VS.Tools.Applications.ServerDocument.v9.0) it tells me "The document was customized using an earlier version of Visual Studio Tools for Office."

So, how do I open an Excel 2007 document customized with VSTO SE?

# April 10, 2008 4:00 PM

andreww said:

Hi Jaimie

Unfortunately, that is a difficult situation. The VSTO v2 (2005/2005SE) runtime connects a document with its associated customization via a hidden ActiveX control. On the other hand, the VSTO v3 (2008) and later runtimes do not use an ActiveX control - instead, the customization metadata is stored in a custom XML part. Switching the file format is not enough to switch the VSTO v2 runtime that will work with the file.

If you have a VSTO v2 (2005/2005SE) doc-level solution, then it targets Office 2003 and it uses the Office 97-2003 binary file format. If the user saves this document into the Office 2007 OOXML file format (as an xlsx/xlsm), we'll persist the VSTO customization information in a separate ActiveX control stream associated with a custom XML part.

Unfortunately, ServerDocument is version-specific: that is, the ServerDocument v2 only understands how to work with v2 customizations in the original file format. The ServerDocument v3 only understands how to work with v3 customizations. So, when you change the file format from 97-2003 to OOXML, this prevents the ServerDocument v2 from working with it; and the ServerDocument v3 cannot work with a v2 customization (even if it is using the OOXML file format) because the manifest metadata is different and the storage mechanism for the manifest is different.

The good news is that if the user opens the xlsx file, the customization should still work (still using the VSTO v2 runtime). If the user then re-saves this xlsx back to xls format, again the customization metadata is persisted, so that if they later open the new xls, the customization will still work (v2 runtime). So, a fair amount of roundtripping is supported. Plus, of course, ServerDocument v2 can continue to work with the xls file even after roundtripping.

If you need to use ServerDocument v2 on a file that has been saved to OOXML, then the simplest thing is to re-save the file back to 97-2003 format first, before attempting to process it.

# April 11, 2008 5:45 PM

Jacob Thomas said:

I have an Excel2003 Addin developed in VS2008. In my development pc i have Excel2007. I works fine in the development PC(even though I don’t have 2003), but in deployment PC it doesn’t. My Addin is suppose to create a menu next to data menu, it’s not happening.

Any Suggestions

# April 13, 2008 3:45 AM

andreww said:

Jacob - your setup is not a supported configuration. If you want to develop add-ins for Excel 2003, then you need to have Excel 2003 on your machine and not Excel 2007. See here for more details: http://blogs.msdn.com/andreww/archive/2007/06/08/why-is-vs-development-not-supported-with-multiple-versions-of-office.aspx.

I expect what's happening is that your project is referencing the Excel 2007 PIAs which of course are not available on the deployment PC.

# April 13, 2008 4:04 AM

AUSTISM said:

I am dizzy....

This is my situation that I can't seem to figure out yet. I have both VS2005 & VS2008 on my local PC, and

have VS2008 on my virtual server that has Office 2007 software and Moss 2007 running.

so when I try to install VSTO for 2005 on my local PC, it says it can't do it because I don't have any SharePoint installed. So which version of VSTO do I try to install on my virtual server that is running VS2008 and MOSS 2007???

SMA

# April 15, 2008 1:09 PM

andreww said:

Austism - I'm not completely sure what you're trying to do. VS2008 includes VSTO 2008. Only some versions of VS2005 include VSTO: specifically, the VS/VSTO 2005 SKU, and all the VS Team System SKUs.

So, you already have VSTO 2008 on your virtual server and on your local PC.

Also, installing VSTO 2005 should not complain about SharePoint because SharePoint is not a pre-requisite for VSTO. Are you trying to install the VS Extensions for SharePoint (VSEWSS)?

# April 15, 2008 1:29 PM

SMA said:

Oh your correct. I just wanted the templates that show up in VS 2005 for SharePoint to show up in VS 2008. How do I get the Web Part, List Definition, Team Site Definition templates to show up under project types for new project in VS 2008. If it isn't with VSTO then what?

SMA

# April 15, 2008 1:53 PM

andreww said:

SMA - those are the VSEWSS templates. The current release only works with VS2005, and only on a machine with SharePoint on it. They are unrelated to VSTO.

The next release of VSEWSS will work with VS 2008, see here for details: http://blogs.msdn.com/sharepoint/archive/2008/02/11/announcing-the-final-release-of-vsewss-1-1-and-the-upcoming-version-1-2.aspx

# April 15, 2008 2:00 PM

Austin said:

The problem I am having is that with Office 07 we built our adding to make extensive use of the Ribbon and task panes.  As compared to Command Bars and forms we used in earlier versions of Office.

Our snag is that many of our users have more than one version of Office installed for compatibility and testing issues.

Is there some simple way to determine which version the user is starting and then load the version specific add-in for it?

(Note, our add-ins are for PowerPoint.)

# April 18, 2008 2:55 PM

andreww said:

Austin - the simplest way to detect (a) if a particular application is actually running, and (b) which version, is to use Marshal.GetActiveObject, cast the return to the type of application you expect and then access that object's Version property.

For example:

try

{

   PowerPoint.Application ppt = (PowerPoint.Application)Marshal.GetActiveObject("PowerPoint.Application");

   MessageBox.Show(ppt.Version);

}

catch (Exception ex)

{

   MessageBox.Show(ex.ToString());

}

If the app is not running, GetActiveObject will throw an exception. The Version property is obviously common to multiple versions of PowerPoint.Application.

# April 18, 2008 3:13 PM

Austin said:

Andrew, I hear what you are saying however the issue is that when I create and pubish the add-in, its installation includes a reg key HKLM\Software\Microsoft\Office\PowerPoint

This key sets the load behavior for PowerPoint/Com Add-in when PowerPoint starts and this key seems to be generic in that it is present regardles of any other reg keys that are spcific to the version of Office.  (There are version specific keys but the load behavior is always directed to this common key.)

I've hacked around the registry but find no way to get around this problem.

# April 18, 2008 4:05 PM

andreww said:

Austin - sorry, I should have been clearer. You're correct - COM add-ins (including VSTO add-ins) are registered per app, regardless of app version.

I was suggesting that you detect the version programmatically as your add-in is loaded, and then your add-in code would branch to the version-specific functionality. See here for more details on this approach: http://blogs.msdn.com/andreww/archive/2007/06/15/can-you-build-one-add-in-for-multiple-versions-of-office.aspx

# April 18, 2008 4:40 PM

Austin said:

Andrew, thanks.  Read the linked information and will give it some thought on the best way to implement it.

# April 19, 2008 5:08 PM

Austin said:

I meant to add.  You point out that Microsoft has "moved on" and developers should to.  Now if I were raking in billions a year and didn't really care about supporting my existing clients like Microsoft I might agree, but I am not making billions and fully 2/3 of my clients are not moving to Office 07.  Wish that were not the case, but it is what it is so I am stuck trying to meet real world clients and their needs.

# April 19, 2008 5:15 PM

Open XML, VSTO, Deployment, .NET und anderes said:

Bekanntlich sind Informationen direkt von der Quelle die besten, da nicht misinterpretiert. Andrew Whitechapel

# April 23, 2008 5:22 AM

Misha Shneerson said:

This post is both the continuation of part I and part II installments but it also addresses new product

# April 24, 2008 7:17 PM

Raymond said:

Andrew - Thanks for this article! I could'nt find that matrix on MS sites (I mean on one site ;-))

And, though I do not have a question which meets the scope of this article, your responsiveness gets your site in my top 10 favs. Great.

# April 30, 2008 3:55 PM

andreww said:

Raymond - thanks for the kind comment - it's nice to know there's folks out there who appreciate the effort. :-)

# April 30, 2008 4:54 PM

asurachman said:

dear Andrew.

I have a client installed the add-ins package distributed to him.  No errors at all.  All prerequisites were installed.  But Word ribbon didn't come up.  No errors message though the option already ticked.  In word add-ins option, the package should be loaded and the options also ticked.  It was under Active Add-ins.

But the ribbon didn't come up.

The same installer already test to other computers, and it worked fine.

It confused me.

Regards,

-Aguss

# May 10, 2008 1:21 AM

andreww said:

Aguss - it's not clear from your description what's going on. I suggest you run the VSTO Troubleshooter on the machine to see if there are any pre-req issues. You can get the Troubleshooter here: http://www.microsoft.com/downloads/details.aspx?FamilyId=46B6BF86-E35D-4870-B214-4D7B72B02BF9&displaylang=en. Also, in Word, you should turn on the ribbon error reporting: Word Options | Advanced | General | Show add-in user interface errors.

# May 10, 2008 2:15 AM

asurachman said:

The problem is dealt with HP Tablet with Vista.

The error came up: Install UtilLib.dll:Unkown error.

I distributed VSTO developed using VS 2005 with VSTO SE.

With machine which has already has 3.0 and 3.5, what should I do? Will it work?

# May 11, 2008 10:35 PM

asurachman said:

Just got information that the OS is Vista.

# May 12, 2008 2:57 AM

andreww said:

Asurachman - it still not at all clear what you're doing. What is UtilLib.dll? Is this your DLL or a DLL that you're referencing? Did you install this will your add-in?

# May 12, 2008 3:05 PM

asurachman said:

Thank you for information about loading sequence.  It helps for troubleshooting.

# May 21, 2008 8:15 PM
Leave a Comment

(required) 

(required) 

(optional)

(required) 

Comment Notification

If you would like to receive an email when updates are made to this post, please register here

Subscribe to this post's comments using RSS

Page view tracker