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.

Comments

• Anonymous
  April 10, 2008
  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?
• Anonymous
  April 11, 2008
  Hi JaimieUnfortunately, 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.
• Anonymous
  April 12, 2008
  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
• Anonymous
  April 12, 2008
  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.
• Anonymous
  April 15, 2008
  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, andhave 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
• Anonymous
  April 15, 2008
  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)?
• Anonymous
  April 15, 2008
  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
• Anonymous
  April 15, 2008
  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
• Anonymous
  April 18, 2008
  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.)
• Anonymous
  April 18, 2008
  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.
• Anonymous
  April 18, 2008
  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 HKLMSoftwareMicrosoftOfficePowerPointThis 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.
• Anonymous
  April 18, 2008
  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
• Anonymous
  April 19, 2008
  Andrew, thanks.  Read the linked information and will give it some thought on the best way to implement it.
• Anonymous
  April 19, 2008
  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.
• Anonymous
  April 22, 2008
  Bekanntlich sind Informationen direkt von der Quelle die besten, da nicht misinterpretiert. Andrew Whitechapel
• Anonymous
  April 24, 2008
  This post is both the continuation of part I and part II installments but it also addresses new product
• Anonymous
  April 30, 2008
  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.
• Anonymous
  April 30, 2008
  Raymond - thanks for the kind comment - it's nice to know there's folks out there who appreciate the effort. :-)
• Anonymous
  May 09, 2008
  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
• Anonymous
  May 09, 2008
  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.
• Anonymous
  May 11, 2008
  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?
• Anonymous
  May 11, 2008
  Just got information that the OS is Vista.
• Anonymous
  May 12, 2008
  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?
• Anonymous
  May 21, 2008
  Thank you for information about loading sequence.  It helps for troubleshooting.
• Anonymous
  August 13, 2008
  I created a ribbon in Excel using VSTO 2008. My ribbon contains a button, on which I have provided screen tip & super tip as well as keyboard shortcut, after deploying it to excel; I am getting an extra tag in screen tip pop-up asking user to “Press F1 for more help”. While pressing F1 key it is opening MS online help; is it possible to customize this shortcut, I want a *.chm file to be opened which provide context help with perspective of my project.
• Anonymous
  August 14, 2008
  Hi Abhinav,Unfortunately, no it is not possible to use a custom CHM help file or hide the "Press F1 for more help" text in Office 2007. :(
• Anonymous
  August 29, 2008
  Visual Studio Tools for Office 3.0 (VSTO) is the latest release of VSTO since the 2005 SE release. If
• Anonymous
  September 08, 2008
  Andrew,This is a bit off topic, I hope you don't mind, I'm desperate for information.I've developed an Outlook Add-in for OL2003 using VSTO 2005SE - so its a managed-code add-in. I want to deploy it for "All-Users".  I tried modifying the set-up project to move the addin Key from HKCU to HKLM but this has not worked - Outlook does not display the add-in in its COM Add-ins list.I've seen lots of stuff about how to do this for OL2007 but I think it relies on something in Office 2007 and its a lot of work to embark on if its not going to work.Can you point me in the right direction?thanksAlan
• Anonymous
  September 08, 2008
  Alan - first, prior to Office 2007, add-ins registered to HKLM are not displayed in the COM add-ins dialog. This doesn't mean they're not loaded, simply that they're not reported in this dialog.Second, note that VSTO 2005SE uses persisted CAS policy for its security checks. So, if you want to deploy an add-in for all users, you must modify the caspol security policy that you're deploying so that it affects all users - the simplest way to do this is to set it at machine level instead of at user level.
• Anonymous
  September 15, 2008
  There's a quite straight forward reason for needing to develop on the two platforms: the Ribbon.  It is nice to be able to program around the Ribbon in Office 2007;  but when some of your potential users are still on Office 2003, then you have to program for them too, and use the Toolbar model.I see that I'm going to need two PCs, unshared code, etc., to do that.Now, I know that nothing's impossible with computers, so there's a challenge for Visual Studio Service Pack 2!!  :)
• Anonymous
  September 25, 2008
  BelowmateriaisfromAndrewWhitechapel'sblog,whichisforVisualStudio,OfficeandotherNonsen...
• Anonymous
  September 25, 2008
  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,
• Anonymous
  September 25, 2008
  After chatting with a few people about Visual Studio Tools for Office (VSTO) recently, it’s clear that the technology is not that well understood (even though, in my opinion, Microsoft have done a pretty good job of articulating it – much better than
• Anonymous
  February 16, 2009
  My application uses ServerDocument to add customization to user files before opening them.  If I convert to a VSTO 2008 doc-level solution, can I use the same ServerDocument version to add customization to both 2003 and 2007 documents?
• Anonymous
  February 16, 2009
  Diana - there are different versions of the ServerDocument class. See the documentation on MSDN for details of how to write code that uses both versions to work with Office 2003 and 2007 documents: http://msdn.microsoft.com/en-us/library/bb772081.aspx
• Anonymous
  February 17, 2009
  Does this mean that our developers need both Office 2007 AND Office 2003 installed on their systems?
• Anonymous
  February 17, 2009
  Diana - each version of the VSTO runtime (including ServerDocument) is specific to a corresponding version of Office. This means that on a dev machine, you need to have at the least the version of the Office PIAs that correspond to the version of the VSTO runtime. This is enough for a solution to build.If you also want to run the solution on that machine, then you will need both versions of Office also.
• Anonymous
  April 14, 2009
  Andrew,I built a Excel 2003 application Addin with VSTO SE v2 using VS 2005. I upgraded my IDE to VS 2008 and our compnay upgraded our Office to 2007. I imported my xls 03 addin project to VS 2008 but I can't seem to get to compile.The addin seems to run just fine in xls 2008 from VS 2005.I don't care about backwards complatblity to 03. but I would like to be able to dev and deploy with MSI installer on xls 07any insight would be great.  
• Anonymous
  April 14, 2009
  mlstanley - First, you don't need to recompile, as your add-in should just continue to work in Excel 2007. That said, if you want to continue developing, the import wizard that migrates your VS2005 project to VS2008 should have just worked - it would have given you an error report if it found any problems.If the migrated project doesn't compile, why not? That is, what are the compiler error messages?
• Anonymous
  April 15, 2009
  Thanks for the quick reply,I am getting  this error that starts the chain of what seem to be related errors.Error 1 Type 'Microsoft.VisualStudio.Tools.Applications.Runtime.IStartup' is not defined. "pathinfo"Addin.Designer.vb 22 16 "myprojextname"
• Anonymous
  April 15, 2009
  mlstanley - looks like you're missing some critical VSTO assemblies. IStartup is part of the VSTO 2005/SE runtime - so if the compiler can't find it, you probably don't have the VSTO 2005/SE runtime installed - or the installation is corrupt in some way. You can get the runtime here: http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=8315654b-a5ae-4108-b7fc-186402563f2b
• Anonymous
  April 17, 2009
  Hmm, well I re-installed then said repair. I am still getting the error. I am applying the VS 2008 sp1 now lets see if that helps.