This tip allows to prevent VSTO runtime from reflecting on your entry point assembly. We see considerable startup improvements especially for add-ins that have WPF controls - because reflecting on such assemblies means reflecting over some WPF types - these are huge.

Typically, people would try to cast an object returned by aforementioned property to object[]. This causes an exception stating – “Unable to cast object of type 'System.Object[*]' to type 'System.Object[]”. Truth to be told I’ve never heard of a type called System.Object[*] so I asked some people that do know and was informed that this merely indicates a non-zero bound array.  So, the exception is basically telling us that one cannot cast a non-zero-bound array to a zero-bound array.  Great! Now we know that Excel returns a single-dimensional one-bound (i.e. its lowest index is one and not zero) array. We also know that C# does not really have a good syntax to deal with such arrays. Hence we need to go lower. Meet System.Array type.

Armed with this knowledge we could write this code:

// <DOESNT WORK>

Workbook workbook = Globals.ThisAddIn.Application.ActiveWorkbook;

SlicerCache slicerCache = workbook.SlicerCaches["Slicer_Customer_Geography"];

System.Array a = (System.Array)(slicerCache.VisibleSlicerItemsList);

// <DOESNT WORK>

Unfortunately, this would also throw an exception if you are compiling for .NET Fx 4.0 and using C#’s new Embed Interop Types aka /link feature (I really hope you do that because of all the wonderful things you can do with type embedding). This has to do with the fact that using /link also activates C# 4.0’s auto-dynamic feature – meaning methods returning object type are automatically promoted to be dynamic (see the COM Interop section on that page). That's exactly our case here since VisibleSlicerItemsList is typed as generic object in the Excel's Primary Interop Assembly. Consequently the cast of dynamic to System.Array is handled by the Dynamic Binder which also does not currently play well with non-zero based arrays. The only way to avoid Dynamic Binder is to cast first to object and then cast back to System.Array:

// WORKS

Workbook workbook = Globals.ThisAddIn.Application.ActiveWorkbook;

SlicerCache slicerCache = workbook.SlicerCaches["Slicer_Customer_Geography"];

System.Array a = (System.Array)((object)slicerCache.VisibleSlicerItemsList);

// WORKS

Live becomes much easier once we do have a System.Array object in hand. Here is the simplest way to iterate over the collection:

foreach (object slicer in a)

    System.Windows.Forms.MessageBox.Show(slicer.ToString());

Or, if you prefer the more controlled access to the array – use Rank property to make sure there is only single dimension to the array, use GetLowerBound/GetUpperBound to determine the boundaries of each dimension and retrieve values using  GetValue method.

For the information on why it is important to isolate shared add-ins using a COM shim please refer to this article. You can find here all the details why and how you need to digitally sign the shim and also how shim provides certain level of isolation for the managed add-in by placing it in a separate AppDomain.

There is a separate article explaining the architecture of the shimmed solution and also shows how to use the COM Shim Wizards to easily create a shim around your existing managed add-in.

So, let's start enumerating the changes the COM Shim Wizards went through when compared to the one we had in the last release:

• The MSI package attached to this post will install project templates for Visual Studio 2010 only. Notice that VS 2010 should be installed on the machine first. There is no option to install to VS 2008 / VS 2005.
• Only the project template for AddIn Shim is now installed. Shims for RealTimeData and SmartTags were dropped – neither I or Andrew saw a lot of demand for these and we decided to not invest the required time into the required support.
• When harvesting information from the assembly we have a new data field called "Image Version". This data is important. In particular if the image's version v2.0.50727 – the generated shim will use CLR 1.0 hosting interfaces, if the image's version is different – the generated shim will use CLR 4.0 hosting interfaces. I explain the nuances about hosting interfaces below.
• Fixed the bugs in ManagedAggregator.cs and CLRLoader.cpp that could cause the host application to not property shutdown (see the comment in the MSDN article regarding these bugs)
• As in the last release, the created shim is a 32-bit native DLL. Please follow the steps outlined in the "Taking COM Shim Wizards to 64-bit" to compile a 64-bit version

CLR Hosting Interfaces

The way we host CLR is the only significant change in the code that is being generated by the AddIn Shim template. In the previous version of the shim we used what is called CLR 1.0 Hosting Interfaces – i.e. these are the hosting interfaces that were available in the initial release of .NET Framework 1.0

The assumption back then was that only one version of the CLR can be loaded into the process. This assumption lasted through .NET Fx 3.5. However, CLR 4.0 allows hosting multiple versions of CLR side-by-side in the same process and the hosting interfaces needed to reflect this.

Some hard decisions had to be made and one of those decisions is that using CLR 1.0 hosting interfaces is only good to host CLR versions up to 2.0 (i.e. .NET Framework 3.5). The only way to host .NET Framework 4.0 as well as future version of .NET is by using the new hosting interfaces.

So, how do you decide whether you want to use the new hosting interfaces or the legacy hosting interfaces? My thinking is that if you compiled against CLR 2.0 – you probably want to run in the CLR 2.0 and not require CLR 4.0 to be installed– so you will use the legacy hosting interfaces to load the CLR 2.0.

On the other hand if you compiled against CLR 4.0 or above – you have to use the new hosting interfaces to load CLR 4.0 or above.

To control which hosting interfaces to use you only need to comment out/ uncomment one line of code in CLRLoader.cpp file that is generated by the wizard. This line is at the very top of the file and is accompanied by a hefty comment:

// When loading assemblies targeting CLR 4.0 and above make sure

// the below line is NOT commented out. It enables starting

// CLR using new hosting interfaces available in CLR 4.0 and above.

// When below line is commented out the shim will use legacy interfaces

// which only allow loading CLR 2.0 or below.

#define USE_CLR40_HOSTING

By default, when we harvest the version information from the assembly we will also detect which CLR runtime the assembly is targeting – this information is available in the assembly's metadata and the Assembly Harvesting step of the wizard displays this information in the "Image Version" field. If the assembly has been compiled against CLR 2.0 - the "Image Version" field will show v2.0.5727 – the above "magic" line of code will be commented out when the files are generated.

However, if the "Image Version" does not start with v2 – the "magic" line is uncommented and this causes new hosting interfaces to be used to load the CLR

Notice that in order to use the new hosting interfaces CLR 4.0 (or above) is required to be installed on the machine. The shim compiled to use new hosting interfaces will fail to load if CLR 4.0 (or above) is missing.

When using the new hosting interfaces it is possible to load any version of the CLR installed on the box. So, the logic we are using goes like this – we first try to load the same version of the CLR the image was compiled against. This, however, can fail e.g. because this particular versoin is not installed. In this case, the shim will enumerate all the CLRs installed on the machine and pick up the latest one. The decision is made in BindToCLR4OrAbove function in CLRLoader.cpp. I am mentioning this just in case you would like to play with it.

Some sharp minds may have noticed that it is possible to use new hosting interfaces to load CLR 2.0 – however, I wanted to call out that this may not be the best course of action since you would still be requiring CLR 4.0 to be installed on the machine.

Debugging add-ins targeting CLR 2.0 in Visual Studio 2010

I had some problems debugging add-ins if those were loading in CLR 2.0. I would press F5, Excel would start up and my add-in would run but the breakpoints were not getting hit. So I wanted to share what's going on and how to set up your environment in such a way that F5 experience is not completely broken.

There is no magic in the way I usually go about debugging the shared add-in - either shimmed or unshimmed. I set a breakpoint in the OnConnection method in Connect.cs file, open project's properties, go to the Debug section, select the "Start External Program" option and set the full path to my Office application (e.g. "C:\Program Files\Microsoft Office\Office12\EXCEL.EXE"). Next I right click on the project node in the Solution Explorer and select "Set As Startup Project". When I press F5 my breakpoint is hit.

In Visual Studio 2010 the breakpoint is not hit if my add-in is loaded in CLR 2.0. What's going on is that debugger cannot attach to both CLR 4.0 and CLR 2.0 - it actually needs to know before the fact whether it should be using CLR 2.0 debugging engine or CLR 4.0 debugging engine. When you press F5 debugger tries to guess which CLR will be started in the process. The heuristic is based on reading the EXE's .config file where required runtime version is u8sually specified and if the .config file is not found than the debugger fires up the CLR 4.0 debugging engine. As we all know Office application are not bound to any particular version of the CLR so the heuristic miserably fails.

There are actually two ways of dealing with it – one is to put an <YourApp>.exe.config file alongside the.exe itself e.g. when debugging Excel 2007 I will create Excel.exe.config and leave it in the "C:\Program Files\Microsoft Office\Office12" folder.

But my preferred way of dealing with this is different. In the Solution Explorer I will right click on my solution node and select "Add" -> "Existing Project" and open "C:\Program Files\Microsoft Office\Office12\EXCEL.EXE". Next, I will right click on this newly added project and select "Set As Startup Project". Next, I will open the properties for this project and will set the "Debugger Type" property to "Managed (v2.0, v1.1, v1.0)". Now, I will F5 and the breakpoint I've set in OnConnection method will be hit.

Happy shimming everyone!

COMShimWizardSetup.msi

"If the target framework of an Office project is changed to the .NET Framework 4 from an earlier version of the .NET Framework, some additional steps might be required to continue to run the solution on development and end user computers"

I though I will re-use the old email thread on the issue and hopefully some people can find this information useful. Below is the slightly edited copy&paste of the email. It contains some abbreviations that might not be obvious so here is rough translation table:

M.O.T = Microsoft.Office.Tools
M.VS.T.A. = Microsoft.VisualStudio.Tools.Application
NoPIA = CLR 4.0 functionality for Type Equivalence and Type Embedding. It can be activated in Visual Studio 2010 by setting "Embed Interop Types"  property on the assembly referenes to 'True'

From: Misha Shneerson
Subject: RE: Bug Discussion on VSTO Technology

> Since then though my solution is looking to distribute the new utilities.v4 assemblies and causing a distribution issue at the moment, could you elaborate a little on this so can help me understand.

This is actually by design. Let me try and explain the overall picture and where the utilities assemblies fit in.

All our new core assemblies with public APIs – i.e. M.O.T.Common, M.O.T.Excel etc (well, that’s all except M.VS.T.A.Runtime.dll) do contain interfaces. This is instead of classes that the user code derived from in the previous version.

So, for example, Microsoft.Office.Tools.Excel.Workbook is now an interface.

At this point you should be going like “Huh! Why in the world would they do that?”.

In CLR4 there is a new feature available which is codenamed NoPIA (I hope you did hear about this – if not there are couple of posts on my blog on the topic) where the original idea is that compilers will embed PIA interfaces (thus creating local copy of the interface in the assembly itself) and CLR will consider multiple copies of the same interface to be equivalent. Basically, that means that if assembly A has a method Foo(M.O.I.Excel.Application xlapp) and assembly B wants to call Foo(xlapp) – each one will operate on its own copy of the M.O.I.Excel.Application interface but the code will still work. And all this w/o even loading Microsoft.Office.Interop.Excel.dll into memory!

So, we have applied same NoPIA principles to VSTO Object Model as well – VSTO’s core OM now consists of interfaces which do qualify for type equivalence.

So, why we are doing all this? This is actually to allow VSTO runtime and VSTO code to version independently of each other. I.e. if the user code does take dependency on VSTO’s runtime assembly – and then we rev up our runtime (and all assemblies that come with it) – we still want to load the same code w/o recompilation. Using interfaces and type equivalence allow us to do so.

Now, everything is good – so why all these Utilities assemblies and what are they for?

In the past user’s ThisWorkbook derived from VSTO’s Microsoft.Office.Tools.Excel.Workbook class. This did allow for some very nice syntax where developers could write their code using familiar VBA notation e.g. Me.ActiveSheet.

But the problem with making Microsoft.Office.Tools.Excel.Workbook an interface is that now user code cannot derive from this interface. In order to maintain the nice old Me.XXX syntax we needed user’s ThisWorkbook to derive from another class which just redirects all its calls to Microsoft.Office.Tools.Excel.Workbook interface. Now, welcome to Microsoft.Office.Tools.Excel.WorkbookBase class in the Utilities assembly! That’s exactly what it is doing – just redirecting calls to M.O.T.Workook interface methods. Actually, if you look into the Utilities assembly you will see that all of these are just thin calls through on methods from one or another interface.

The bad part is that the versioning of classes is different than versioning of interfaces. But since user code takes dependency on these Utilities assemblies – those assemblies and user assemblies are now tightly coupled together and need to be deployed together (e.g. if VSTO runtime would rev up those assemblies and user code tried to bind to the rev’d up assemblies – it would fail). From the versioning perspective user code and utilities assemblies are now one coherent unit. This coherent unit talks to VSTO runtime classes through interfaces.

We feel safe for the developers to deploy these assemblies alongside with their code since we never intend to services these (these are just thin wrappers w/o state/code or anything that would require servicing).

What is the guidance around the core VSTO OM interfaces? How they version and can developers implement those interfaces.

Typical question I expect to hear is “Since M.O.T.Excel.Workbook is an interface – can developer just implement this interface to provide custom behaviour for some of Workbook methods?”. The short answer is – NO, do not implement these interfaces.

The long answer is – VSTO reserves the right to version these interfaces in the future versions. I.e. we want to be able to add new methods to these interfaces (similarly to what Office does with its interfaces). If we add new methods that user code does not implement – something will be broken there, either compile time or runtime or, most probably, both.

So, in our documentation we will specify which interfaces are expected to be implemented by the user. The rule of thumb is – if interface’s name starts with ‘I’ e.g. IExtension, IWorkbookExtension, ISmartTagExtension – the interface can be implemented by 3^rd parties – it is locked down and we guarantee to not modify it in next version.

Hope this helps to clarify the picture,

Misha

From: ...

To: Misha Shneerson; Rachel Falzone Schaw
Subject: RE: Bug Discussion on VSTO Technology

I have managed to get a little further, one of the developers had changed the Codebehind Partial class and this rename had knocked out the build and then it was me trying to reference old assemblies that caused the problem. I have since created a fresh project and noticed that the utilities class had the functionality and it was looking for a needle in a haystack because was a simple case naming error in my class L.. Since then though my solution is looking to distribute the new utilities.v4 assemblies and causing a distribution issue at the moment, could you elaborate a little on this so can help me understand.

Thanks for your response.

Ideally I would love to announce that we have released a version of COM Shim wizards that is working with VS 2010 – but this is not the case yet and in fact I haven’t started investigating yet what would it take to make this work. So, while I am looking for answers there, you can use the wizards on VS 2008 and then migrate your solutions to VS 2010. I know such solution is less than ideal so please accept my apologies…

UPDATE March 23 2010 - Version of COM Shim wizards for VS 2010 is now available

Another question is how to get a working 32-bit shim wizard to work with 64-bit of Office. That’s the question that I want to address in this post.

The environment I am working in is as follows:

• Windows 7 64-bit
• Visual Studio 2008 RTM
• Excel 2010 64-bit (Release Candidate of Microsoft Office Professional Plus 2010 64-bit)

For the information on why it is important to isolate shared add-ins using COM shim please refer to this article. You can find here all the details why and how you need to digitally sign the shim and also how shim provides certain level of isolation for the managed add-in by placing it in a separate AppDomain.

There is a separate article explaining the architecture of the shimmed solution and also shows how to use the COM Shim Wizards to easily create shim around your existing managed add-in.

The first thing I am going to do is create a simple Shared Add-In for Excel 2010 called DemoTest so if you already know how to do this then just skip this part.

Creating basic shared add-in

In VS 2008 I opened the “New Project” dialog and selected “Other Project Types” –> “Extensibility” –> “Shared Add-in”:

Here are the options that I have selected in the Shared Add-In Wizard :

Upon wizard completion I can see 2 projects created for me: DemoTest and DemoTestSetup

So, the first thing that I want to see is my add-in running. To do that I will add a simple message box to the OnConnection method, compile and start up Excel.

Well, I did not see the message box and looking at Excel’s “COM Add-Ins” dialog I can see that Excel has no idea it needs to load an add-in:

Calling upon my psychic powers I conclude that the add-in is only registered for 32-bit Office and so 64-bit Office is completely oblivious to it. Time to do some registry hacking!

<start registry hacking>

Open regedit tool and navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Office\Excel\Addins\DemoTest.Connect, right click on this key and export it into a .reg file e.g. %temp%\addin.reg%

Next, let’s open HKEY_CLASSES_ROOT\DemoTest.Connect\CLSID key and notice that the (Default) value of this key on my machine is {DD16A145-E2F0-40B9-9993-5018BA8B64B3} (NOTICE: this value must be different for you. In fact, it must be unique for every add-in. During project creation such unique value is created and stored as the value of the Guid attribute on the Connect class in Connect.cs). In order to reduce the confusion I will further refer to this cryptic string as just a bunch of Xs e.g. {XXXX}.

Now let’s open HKEY_CLASSES_ROOT\Wow6432Node\CLSID\{XXXX} key and export it to %temp%\clsid.reg

Using notepad.exe open %temp%\addin.reg, remove all occurrences of Wow6432Node\ and save the file, repeat for %temp%\clsid.reg

Go back to regedit. Use File->Import command to import %temp%\addin.reg first, then repeat the same with %temp%\clsid.reg

<end registry hacking>

Opening Excel 2010 now produces the desired result – our little message box shows up:

This exercise shows that pure IL code is platform agnostic - same exact assembly will run without recompilation in both 32- and 64-bit Office processes. Unfortunately, this is not the case with native code and since COM shim for the managed add-in is written in native code it needs to be recompiled.

Creating a 64-bit shim for the basic shared add-in

Now, for myriad of reasons mentioned elsewhere, we need to shim the add-in. I have already re-read the article Andrew Whitechapel and I wrote a while ago (and I am assuming you’ve done so as well so that we are on the same page) and now I am able to zoom through all the options of the COM shim wizard to create my shim project. Once the wizard is completed we now have 2 new projects added to our solution:

• ManagedAggregator
• DemoTestShim

Important: check out the fixes to the code that you are getting from the wizards – COM Shim 2.3.1.0 Bug Fixes fixes are located at the very bottom of the article

Notice that our solution builds 3 DLLs: 2 managed (both are platform agnostic) and 1 native (this one is currently targeting 32-bit platforms). Now we need to configure our solution so that we can build 64-bit native DLL . To do that we need to use Configuration Manager (available through the menu Build –> Configuration Manager …). In the “Active Solution” combo box select “<New…>” and this will bring up the New Solution Platform dialog where you need to select the platform you want to target. Here are the choices I made:

Once you press ‘OK’ all the project in your new x64 configuration will now target x64 – we want to revert both managed projects back to target Any CPU.

Now, we are almost ready to compile the project. One little thing that is left to do is to fix the location where Framework and Windows SDK libraries are picked up from for 64-bit compilation. So, right click on DemoTestShim project, select Properties and navigate to Configuration Properties -> Linker -> General
Find "Additional Library Properties" setting and append "\x64" to the already existing "$(FrameworkSDKDir)lib" to make it "$(FrameworkSDKDir)lib\x64"

Now let’s compile and run Excel, bring up the COM Add-Ins dialog and we can see that our add-in is being loaded through the 64 bit shim we just compiled

Fixing up the deployment project

Let’s not forget about the setup project that is there for us. By making the right adjustments we can get a nice MSI that is capable of deploying our shimmed add-in to 64-bit consumers.

First of all, I opened the File System view for the deployment project (DemoTestSetup) and added the outputs for both the DemoTestShim and the ManagedAggregator projects to the Application Folder

I also verified that none of these components will be self-registering by setting the Register property for each one of these to vsdrpDoNotRegister.

Next, I specified that my setup package is targeting x64 platform (TargetPlatform=x64). Additionally, I want this package to be installed for All Users on a machine (InstallAllUsers=True).

One last thing that is left to do is to add the correct registry keys to the Registry View. The the registry view that I currently have only contains the HKLM\Software\Microsoft\Office\Excel\AddIns\DemoTest.Connect

We are missing HKCR\DemoTest.Connect key and HKCR\CLSID\{XXXX} key. To add both of these keys:

1. Open regedit and navigate to HKCR\CLSID\{XXXX} 

2. Right click and export this registry key to %temp%\clsid.reg

3. In Registry View in VS right click on Registry on Target Machine, click Import … and select %temp%\clsid.reg

4. Modify the (Default) value for CLSID\{XXXX}\InprocServer32 to point to the location where the shim will be installed. For me I need to change c:\Temp\DemoTest\DemoTestShim\x64\Debug\DemoTestShim.dll to [TARGETDIR]DemoTestShim.dll

5. Open regedit and navigate to HKCR\DemoTest.Connect and export it to %temp%\progid.reg

6. Back in VS’s Registry View import %temp%\progid.reg

That’s it! The deployment project should be ready.

Installing and Running the packaged add-in

Let’s compile the entire solution, right click on the DemoTestSetup project node in the Solution Explorer , choose “Install…” and complete the installation process.

Now open Excel and see your add-in happily loaded through the shim that was installed under %ProgramFiles% folder!

Happy shimming to everyone, now available on 64-bit! My sample solution is attached for all your exploratory needs.

DemoTest.zip

1. Video: Raja Krishnaswamy and Jesse Kaplan from the CLR discuss the NoPIAssness aspect of the feature on Channel9

2. Video: Raja and Vance Morrison from the CLR discuss the Type Equivalence aspect of NoPIA on Channel9 and the intricacies of the type system

3. Blog Post: Sam Ng introduces Type Equivalence from the C# compiler perspective (and promises that more is to come)

One of the limitations for 'Embed Interop Types' feature has been that classes cannot be used when embedding an assembly. This limitation has to do with servicing - it is safe to embed metadata but not anything that can potentially contain executable code (class types contain metadata AND code while interfaces only contain metadata). When you try to references a class type from an Interop Assembly for which the "Embed Interop Types" is set to TRUE compiler do issue a warning. But in most cases you do not need to use classes from interop assemblies and minor code tweaking is needed to successfully compile with EIT=true.

Let's address the most common case of this error first.I will also address the cases when the user code uses constants from VSIP assemblies such as EnvDTE.Constants / VSLangProj.PrjKind below...

In most cases (such as error for the usage of UPnPNATClass as noted in one of the comments) this error is the result of code which tries to instantiate a COM object e.g. here piece of code starting up Excel: