Troubleshooting VSTO add-ins for Office

If an Office add-in that is created with Visual Studio Tools for Office (VSTO) does not load, one has a hard time debugging since no error messages are displayed. However, there is a remedy.

Showing add-in load errors with VSTO_SUPPRESSDISPLAYALERTS

To force Office to display exception details if an add-in fails to load, add an environment variable

VSTO_SUPPRESSDISPLAYALERTS = 0

in System Properties > Advanced > Environment Variables:

Environment variables in legacy Windows XP.

(Found at http://stackoverflow.com/questions/4668777.)

Having set this environment variable, when you start the Office application, you may receive an exception report like this:

Exception report for VSTO add-in in Excel.

System.Runtime.InteropServices.COMException (0x8004063E): 
  Exception from HRESULT: 0x8004063E
    at System.Runtime.InteropServices.Marshal.
      ThrowExceptionForHRInternal(Int32 errorCode, IntPtr errorInfo)
    at System.Runtime.InteropServices.Marshal.
      ThrowExceptionForHR(Int32 errorCode, IntPtr errorInfo)
    at Microsoft.VisualStudio.Tools.Office.Runtime.DomainCreator
      .CreateCustomizationDomainInternal(String solutionLocation, 
      String manifestName, String documentName, 
      Boolean showUIDuringDeployment, IntPtr hostServiceProvider, 
      Boolean useFastPath, IntPtr& executor)
    at Microsoft.VisualStudio.Tools.Office.Runtime.DomainCreator.
      Microsoft.VisualStudio.Tools.Office.Runtime.Interop.
      IDomainCreator.CreateCustomizationDomain(String solutionLocation,
      String manifestName, String documentName, 
      Boolean showUIDuringDeployment, IntPtr hostServiceProvider, 
      IntPtr& executor)

(Line wrapping added by me.)

Which leads to the question: WTF?!

Missing .NET runtime causes ThrowExceptionForHRInternal to throw COMException 0x8004063E

There are numerous reports on the web about the method ThrowExceptionForHR. However, non of the proposed solutions solved the problem for me, and in the end it turned out to be really simple.

I had erroneously assumed that .NET 4.0 and the VSTO runtime is installed automatically with Excel 2010 or newer. My setup program checked if Excel 2007 was installed and would download the VSTO runtime if needed; but for Excel 2010 and newer this check was not performed.

As soon as I had downloaded and installed the VSTO runtime and the .NET 4.0 runtime, the add-in loaded just fine on the test machine.

Add/Remove Programs with .NET and VSTO runtimes installed.

According to Microsoft, the VSTO runtime should be installed with Office 2010 SP1 (SP1 is required). It says:

You can install the Visual Studio 2010 Tools for Office Runtime in three ways:

When you install Visual Studio 2013.

When you install Microsoft Office 2013 or Office 2010.

When you install the Visual Studio 2010 Tools for Office Runtime redistributable.

VSTO runtime matrix (source)

However, if the corresponding .NET framework is not installed, the VSTO runtime will not be set up by the VSTO runtime installer, as explained further down on the page.

I am therefore amending my add-in installer with a function to download the .NET 4.0 runtime as well. Previously only a check for the VSTO runtime was made and only if Excel 2007 was installed, but clearly I have to change that.

If you are interested, you can find the install script at

https://sf.net/p/xltoolbox/ng-code/ci/master/tree/publish/ng.iss

It’s an InnoSetup script.

Blog index

Atom newsfeed

Comments