Misha Shneerson : VSTO

VSTO 2005 Second Edition - hot off the press

Misha Shneerson — Thu, 14 Sep 2006 21:50:00 GMT

VSTO 2005 Second Edition Beta (aka VSTO2005SE) - this is a new free product that complements VSTO 2005. See this announcement from KD Hallman if you want to know general details about the product and the roadmap.

I am here to discuss technical details of what it is. First of all - there is a new design time experience for building managed Add-Ins for Office 2003 applications (Excel, Word, Outlook, Visio and PowerPoint - this is for those who use Office 2003 and VS 2005) as well as support for building managed Add-Ins for Office 2007 applications (InfoPath jumped on this band wagon as well).

There is not much difference between Office 2003 and Office 2007 projects. Here, I can count those differences below:

Office 2003 projects by default reference Office 2003 PIAs while Office 2007 by default references Office 2007 PIAs
Office 2007 projects (except for Visio) do have CustomTaskPanes collection that allows you to easily put WinForm controls onto app level task panes.
Office 2007 projects (except for Visio and InfoPath) do support easier creation of Ribbon.xml files and hooking those up. So, getting a vanilla Ribbon takes about 30 secs.

The VSTO2005SE projects are very similar to what the Outlook Add-In project looked in VSTO 2005. The very first difference is that the name of the entry point class has changed - it is not longer ThisApplication, but is rather ThisAdd. So, instead of writing this.Inspectors to get to the Outlook's Inspectors collection you will write this.Application.Inspectors.

If you want to take advantage of new Office 2007 functionality that is exposed to add-ins you will need to implement a ComVisible public class deriving from any arbitrary interface e.g. IRibbonExtensibility, FormRegionStartup (one does not have to implement ICustomTaskPaneConsumer - VSTO runtime takes care when you call ThisAddin.CustomTaskPanes.Add(new UserControl(), "My task pane"). Next you will need to return this class from ThisAddIn's RequestService override. Here is a little example:

public partial class ThisAddIn

{

private Ribbon1 ribbon;

protected override object RequestService(Guid serviceGuid)

{

if (serviceGuid == typeof(Office.IRibbonExtensibility).GUID)

{

if (ribbon == null)

ribbon = new Ribbon1();

return ribbon;

}

return base.RequestService(serviceGuid);

}

[ComVisible(true)]

public class Ribbon1 : Office.IRibbonExtensibility

{

Unless I missed something that pretty much concludes the general design time discussion. In my next posts I will probably talk more about how to add a Ribbon to VSTO add-ins.

We will also be shipping a new VSTO runtime redist. Unlike, VSTO 2005 Design Time - the new redist is not a new product, but is rather an upgrade for the original runtime redist. The reason for the runtime upgrade is that it incorporates this addition CustomTaskPanes functionality and support for arbitrary services that VSTO customizations can now expose. Also, we fixed a number of breaking changes in Excel's ListObject functionality that affected the behavior of ListObject's data-binding on Office12.

One final note - you MOST probably will have trouble using this software if you ever installed VSTO v3 CTP - unfortunately, due to the poor setup support in VSTO v3 CTP, uninstalling it won't solve the problem. You may try to uninstall any the CTP, VSTO 2005 and all the traces of Visual Studio from the machine - then it MIGHT solve the problems. However, the most reliable solution is just re-installing the OS. That is not fun and I am profusely apologizing that you might have to do that. We did much better job with this release to ensure we do have a clear servicing path for this product.

Must read for everyone trying to deploy VSTO solutions

Misha Shneerson — Fri, 06 Jan 2006 09:21:00 GMT

I am breaking the silence to get the word out (to those loyal souls that still aggregate my blog) about 2 articles on VSTO deployment. First article is an in depth overview of VSTO deployment models and proposed solutions. The second one is a complete walkthrough for setup project creation with code samples. Most important - this is a must read for every VSTO developer. If your setup does not install pre-requisites - tons of people won't be able to use your add-in. If your setup does not make sure PIAs are on the machine - tons of people won't be able to use your add-in. If your setup does not deploy CAS policies correctly - tons of people ... But If your setup does deploy CAS policy incorrectly and allows evil hackers take control over the machine - you are done (if you are not Microsoft, of course:)). The articles address all these points.

Deployment is VSTO's pain point. Part of it is because of the extremely scrutinous security model. Another part is because of our initial desire to support ClickOnce-like capabilities for offline scenarios when ClickOnce was not ready yet to support VSTO-like solutions. The above articles do not remove the pain but help controlling it. In the future we are loooking at removing it at all and making deployment complete part of VSTO experience as it should be - easy and sometimes pleasantly surprising :).

Any development in this area should not go without mentioning some excellent work that has been done by VSTO community. In the past Mads Nissen (helped by Peter Jausovec ) posted a solution for VSTO deployment. What Mads has done is very good work even though it suggested to manipulate CAS policies using the CAS APIs (Peter Torr would not be very happy about this because manipulating security APIs directly is prone to errors. And security bugs may be very costly to both you and your customer).

Finally I wanted to congratulate my colleagues Lubo, Darryn and McLean for getting this article out.

Spaces in SmartTag.Terms collection

Misha Shneerson — Mon, 31 Oct 2005 21:18:00 GMT

When you add non-terms into the SmartTag.Terms collection do you expect those terms to be recognized? If you do this is a false expectation. The simplest code to add a SmartTag to a Word document looks like this:

private void ThisDocument_Startup(object sender, System.EventArgs e)
{
    SmartTag st = new SmartTag("http://www.microsoft.sample.com#foo", "Foo term");
    st.Terms.Add("foo");
    st.Terms.Add("One Two");
    Action action = new Action("Do nothing");
    st.Actions = new Action[] { action };
    this.VstoSmartTags.Add(st);
}

If you run VSTO solution with the code as above and type foo followed by a space you will notice that foo is almost immediatly "tagged". However if you type One Two followed by a space it would not have the same effect. Why is that?

It is happening because Terms collection should be used only if you need to recognize single tokens. The default implementation of SmartTag will match the members of Terms collections against the TokenList collection as passed into ISmartTagRecognizer2.Recognize2 method.

TokenList Tokenized representation of Text parameter. Strings, punctuation, and white space are broken down into actual words for use by the recognizer. This enables streams of tokens to be passed to the recognizer in addition to raw text.

Terms collection is not much of use if you want to teach your smart tag a vocabulary of people's names which usually is more than a single word. But you can still use SmartTag.Expressions collection like this:

st.Expressions.Add(new RegEx(@"\bOne Two\b"));

This approach will work pretty well unless you are looking into very large vocabularies. We use pretty dumb sequential algorithm when we just iterate over collection of regular expressions and try to match it against the text that is passed in. Recognition of smart tags happens on the background thread and the extensive load on the processor will not be horribly noticeable but still the experience would be suboptimal.

I havent given this much thought yet, but it is probably possible to come up with a more effective algorithm. And if you know the characteristics of your vocabulary that is an extra advantage. In this case you can pre-sort you vocabulary, define one single regular expression matching the characteristics of your terms and upon a regex match do quick binary seach to verify that matched text is actually in the sorted array.

Anyone done this or has other ideas?

Getting help on VSTO topics

Misha Shneerson — Fri, 07 Oct 2005 00:45:45 GMT

This post is prompted by a comment left yesterday on my blog. The comment was quite big in size. It went something like this - "my assembly has an ActionsPane and can not be loaded, here is the error message I am getting .... ". This brief introduction was followed by 300 lines of the VSTO error message including the stack at the point of failure + all the assemblies that are loaded in the AppDomain". I removed the comment.

I like to help out, I really do. And the purpose of this blog is to provide information to help our users troubleshoot some of the issues. I do accept requests to talk about mechanics or details of a particular feature. However, if you are stuck please count on the community to get help. I do not really scale very well and can not do much all by myself.

The preferable way to post your VSTO questions and help requests is to use VSTO forums. IMHO the forums format is way better than the newsgroups format. The main feature there is that a thread can be marked as resolved. This allows us to better manage our resources on open issues and not look through questions that have been already answered.

I should say that before the forums were launched I used to answer question on Google Groups. But as soon as I learned about the forums format my monitoring of the newsgroups came to almost complete halt.

Last, but not least. I would like to call upon people to read our forums and answer the questions. As a prize for the contributions you will learn a lot about the technology and might become Microsoft MVP (those MVPs have access to many more resources than mere mortals).

managed addins support in Office 12

Misha Shneerson — Tue, 20 Sep 2005 22:19:00 GMT

At the PDC we have announced support for managed Add-ins across most Office applications. Superficially it is not real news considering today we already have "Shared add-in" project. This project type is there since Visual Studio .NET and this thing is still alive for VS 2005. However, the devil is in the details and when facing the reality of deploying solution generated by such project you would soon learn this is just a beginning of the journey. You will run into incompatibility issues with Office security system, managed code isolation problems, objects lifetime management issues and so on.

Regasm'ing is not good enough for addins

The way shared add-in project works is by throwing at you a skeleton of a class that inherits from IDTExtensibility2 interface. The idea is that all you need to do is implement methods on this interface as you would normally do in VB6. IDTExtensibility2 interface is the relic of the COM extensibility model and consists of five methods (only 2 of those are usually used - OnConnection and OnDisconnection). When you compile the project VS would write some registry keys and values to

Let the host application know there is a new add-in.
Allow the host application instantiate your add-in through a call to CoCreateInstance (which is a standard COM API to instantiate COM objects). Such registration may be also achieved by running regasm myaddin.dll command and that is why I call the registration process regasming.

CoCreateInstance receives a parameter (CLSID) which tells it where to look at the registry for the actual DLL that needs to be loaded. Then it loads this DLL into memory and tries to call a native method called DllGetClassObject that must be exposed by the DLL. But guess what - the assembly you justed compiled did not implement the DllGetClassObject and, even if it did, CoCreateInstance looks for the native method - our assembly is completely managed. To workaround the problem regasm actually registers another native DLL which is called mscoree.dll and that is the DLL CoCreateInstance talks to (well, it is a little bit more complicated but let's assume for the sake of this discussion that mscoree.dll IS the CLR). In turn, mscoree tries to obscure the fact the COM object is managed code and implements the native plumbing that is needed for the code to run. It does this to the best of its ability but there are fundamental differences that just can not be bridged.

One example of such differences is, of course, the memory management models. In COM a memory resource is immediately released when no one references it. Let's take for example this line of Outlook code - Application.Inspectors(1).CurrentItem. In VB6, After the execution of this line of code completes you are left with only one reference into the Outlook OM - you still reference Application object. In .NET this would result in 3 additional COM objects being reference - one for Inspectors collection, one for the Inspector object and one for the CurrentItem. Those references are kept by implicitly generated managed objects aka as RCWs. Those references are not released as long as the correspondent RCWs are not being collected. In .NET the memory is reclaimed when garbage collector runs which will eventually happen but is hard to predict when. Usually a good way to ensure memory is reclaimed is to unload the AppDomain altogether. (In .NET 1.1 unloading AppDomain would automatically mean running GC, in .NET 2.0 there is a lazy appdomain unloading which does not generally guarantee memory resources are released, but RCWs are special cased and will be releazed before AppDomain fully unloads). However, if your managed assembly was regasmed it will load into default AppDomain which can only be unloaded with the termination of the entire process. And that might create egg-and-the-chicken problem when you do not terminate the process while there are managed references into the object model, but you do not remove the references until the process shuts down.

Types isolation problem

Now suppose you have 2 addins in your managed code. Both these add-ins are not placed into GAC and both are not strong named. Each add-in uses a helper library called GoodLibraryForAddins.dll which is shipped by some third party. Except that one of the add-ins uses the v1 version of the library while another one uses the v2 version of the library. The versions are not completely compatible. For example class GoodLibrary.SmileyFace now has additional property Color. When first add-in is loaded into the default AppDomain it will try to use GoodLibrary.SmileyFace class and it will cause the v1 version of the correspondent assembly to be loaded. Next when the second add-in will try to use GoodLibrary.SmileyFace class the CLR will re-use the type information it already knows about and return the class that has been already loaded - the v1 version. Second add-in will then try to use the Color property and will get an unexpected exception.

Each add-in needs its own AppDomain

So, the realization that each Add-in needs its own AppDomain is pretty simple. But that is not what you would get with the "Shared Add-in" project because it uses regasming. The good news are that dedicating an AppDomain on per add-in basis is something you would get if you use VSTO 2005 Outlook Add-in project. The bad news is only Outlook is currently supported. Basically, VSTO 2005 has shipped a native DLL which is called AddinLoader.dll. When CoCreateInstance now tries to create the managed add-in we will essentially create a native add-in implemented by the AddinLoader.dll. The latter will load your managed code, handle the lifetime management issues (e.g. it will unload the AppDomain in OnDisconnection call), and place each managed addin into a separate AppDomain. There is additional plumbing as well, for example the reverse P/Invokes throwing unhandled exception would not crash the host applications. In addition, there is support for remote deployment and the VSTO security.

The reason we currently only support Outlook might look lame, but it is the real reason and there is nothing we could do about it. We just did not have enough QA resources to test how the aforementioned AddinLoader will work with applications other than Outlook. And since we did not test it we can not tell you to use it.

Getting this little hiccup cleared out there is another little hiccup left. The one that is generally referred to as "COM Add-ins blacklisting mechanism". Suppose you have several VSTO 2005 Outlook add-ins. Now, one of those horribly crashed during application startup (or was just plainly killed while showing a message box). Office remembers the name of the DLL CoCreateInstance called into and will permanently disable this DLL from running (unless told otherwise from the "Disabled Items ..." dialog). In this case the AddinLoader.dll is getting blacklisted. And this will cause all of the VSTO 2005 Outlook add-ins be disabled. All because of one rotten apple.

Office 12 knows to do better

For Office 12 we have improved the AddinLoader and added support for managed COM add-ins in the following applications: Access, Excel, FrontPage, InfoPath, Project, Outlook, PowerPoint, Publisher, Vision and Word. Office now would be able to natively distinguish between managed add-in and native add-ins. All you need to do is to put some additional registry values to HKCU\Software\Microsoft\Office\<Application>\<AddinName>. The name of the values would be ManifestLocation and ManifestName. ManifestLocation should point to the directory where the VSTO manifest file resides. ManifestName should indicate the name of the manifest file in the directory. Those are exactly same values we are registering today for Outlook add-ins in the HKCR\<YourAddinCLSID> hive. Also note that our tools currently register ManifestLocation and ManifestName in both hives although only the registry values in HKCR are currently used. I should really stress that when you deploy your add-in projects please duplicate those registry values as well to ensure you have good migration story into Office 12.

Office also addresses the blacklisting problem. If a managed add-in causes host application to crash it will be still blacklisted but other managed add-ins will not. This is because the criteria for blacklisting managed add-ins is now the correspondent manifest file, not the entry point DLL (i.e. AddinLoader.dll).

Additional goodies for managed Add-ins will include the regular VSTO stuff. Slightly better programming model, built-in custom task panes support and the advantages of using Visual Studio IDE to write and manage your projects. And might be a lot more.

Happy VSTOing.

Back from PDC

Misha Shneerson — Sun, 18 Sep 2005 09:49:00 GMT

I am back from PDC and I can finally post to my blog! I was not able to do it from LA because 2 weeks before PDC I accidentally ran over my laptop with my van. No surprises here - the laptop is quite useless now. So in LA I had access to computers only at the Convention Center and there I was busy chatting with people that know our VSTO stuff pretty well or do not know anything about it or only used previous v1 version of VSTO and were totally blown away with the v2 demos. I had a chance to talk to the people I heard from before but never met face to face (Peter, Bill, Darren and many others, those who have public blogs and those who do not). Many people offered their views and gave us reasons to work on our next version. Should I really say I am grateful for this? Well, I am.

I spoke at the pre-conference where we had about 10 hours long series of sessions covering VSTO v2. I was doing two sessions: one about ActionsPane and SmartTags support and another one about VSTO security. The first session went pretty good. Even the LA power outage that caused us to delay the talk was great because we used it up entirely for the Q&A. The other one was quite difficult. I was told before that CAS related talks are the hardest ones but now I got the chance to experience it myself. I believe I started losing the audience while giving quick overview of CAS - code groups, evidences, four policy levels and intersection of permission sets are just too much to digest in 15-20 minutes of the overview. I completely lost the bravest souls when I pulled up the slide which presented the VSTO AppDomain policy level in the form you usually would see when running caspol -lg (to get this slide I actually copied code from the caspol into my VSTO assembly and modified it to only list the codegroups for the AppDomain policy level). The rational behind the slide was to show the inner workings of our security policy as opposed to presenting VSTO security as a black box with a set of rules that you have to follow. I believe the talk made good to the sales of Eric's book though and only one guy came up to me and thanked for sharing my views :)

We announced VSTA at the PDC. There were a lot of questions about how VSTO is related to VSTA. Both technologies are developed by the same team and hence are closely related. Here is the deal. VSTO roughly can be divided into 2 pieces a) a generic runtime and design time support which does not make any assumptions about what host application is and b) integration of this runtime with Word, Excel and Outlook. As a side note, due to this architecture we were able to build our Outlook support in record time - the first prototype of Outlook support was only done in March 2005. VSTA is even more improved version of VSTO's host agnostic part with additional support for managed hosts (VSTO runtime is primarily addressed at native hosts). However, this time instead of doing the integration part ourselves we will offer the ISVs to integrate VSTA into their applications. I should also say that a lot of new concepts were introduced such as contract and more generally MAF - Managed Addins Framework. BTW, for the deep architectural insights of what it takes to design extensible hosts keep an eye on TQ's blog. Tom is a light version of The Matrix's architect but he actually does make sense :)

I did get an interesting feedback about our blogs. We have a lot of bloggers but we rarely say how we are related organisationally to each other and this sometimes makes things difficult to connect. So here it goes - I do not have any reports and I report to Eric Carter. We primarily are buildng the VSTO runtime and our team is called the frameworks team. Eric reports to JackG, TQ is an architect on our team, he is freelancing here and there and also reports to Jack. Andrew Whitechapel is my and Eric's PM. Paul Stubbs is a PM working on VSTA. John Durant is also a PM driving our Outlook subsidiary. And there is a lot of other great people who not chose yet to go public.

What else? Ah, feedback. I love feedback. If you made it through the end of this post please add your comments, experiences, requests.

To sum it up - the conference was great, I am awfully tired, I missed my family and I am happy to see my kids and wife. Happy VSTOing to all of you.

VSTO PDC sessions

Misha Shneerson — Wed, 07 Sep 2005 07:26:00 GMT

PDC is just in a week and I will be there. I will present during the preconference with Eric Carter and Andrew Whitechapel. The reason three of us are doing this session is because it is 6 hours long! Since we all work directly on the VSTO code base, get ready for deep coverage and bring your toughest questions. One thing I can tell is that the VSTO preconference slide deck is very impressive and it is oriented at developers.

I also previously mentioned that Eric (who happens to be my manager) got me and some other folks to work in Office's building. We were working on integrating our early VSTO 3.0 thinking into Office12 or ... it might be the other way around :) Considering we had only 3 weeks to get something working, while keeping an eye on the last phases of shipping VSTO v2, we did a good job. Many Office sessions in the conference will show the first bits of VSTO vNext. For complete list check out this compiled guide. And do not miss the last 2 sessions in this guide.

Also, the rumor is there will be new book signing by Eric.

Have fun, I know I will.

Getting plain VSTO ActionsPane to work.

Misha Shneerson — Tue, 16 Aug 2005 10:49:00 GMT

Adding programmable task pane aka ActionsPane with VSTO is a piece of cake. All you really need to do is just add controls to the ActionsPane object using the familiar WinForms paradigm. Here is how you would show a button on the task pane in Word.

Globals.ThisDocument.Controls.Add(new Button());

This code produces less than sofisticated task pane but if you remember to do this you are only "this" close to be the ActionsPane expert . If you need to construct something more fancy you do not write any code at all - you use the WinForms designer. Couple clicks to add new UserControl to your project, then couple drag&drops to design the UserControl and set all the right properties in the Property Browser (especially useful is setting the left and right anchors for the text boxes - then those text boxes can resize with the task pane). Then write this code in ThisDocument_Startup event handler:

Globlas.ThisDocument.Controls.Add(new MyUserControl());

if you still have not removed the code that adds the empty button then you should see the UserControl stack below the button. This automatic stacking is useful when you want to conditionally add/remove additional UserControls (e.g. you would like to display a currency converter when user fills in expenses part of the trip report - I know the scenario is lame but just bear with me for a moment [:)]).

Additionally your document just became a SmartDocument. It has an XML Expansion Pack (XEP) attached to it. Check out the Tools->Templates and Add-ins ... dialog. You will see that your document references ActionsPane.xsd schema (which is empty and is there because a schema is required to get whole SmartDocs mechanism get going) and has "Microsoft Actions Pane" XEP as well.

Here is a fun thing to try: delete the "Microsoft Actions Pane" XEP. It is hard to get rid of. It is not the case with other SmartDoc solutions, but this one seems to have an extra protection. Any insights on what is going on here?

P.S. I am making my posts shorter and aimed to deliver a short point and I am still on the fence whether this is the right thing to do. Is this better than cramming vacations and introductions into the same post? Or sacrificing the readability and delivering as much information as possible is gonna be more useful when people look for answers later?

Back from vacation. ActionsPane, Part 0.

Misha Shneerson — Wed, 10 Aug 2005 22:55:00 GMT

I took some time off from work for a family vacation. We spent our relaxation week on Vancouver Island in Canada. Here is more info since already couple of people have asked. The place we stayed at is called Beach Acres in Parksville, BC. We rented an ocean view unit with kitchenette and 2 bedrooms. It was just half a minute away from getting to the sand of the beautiful Rathtrevor Beach. The beach is located in the bay which keeps the waters incredibly calm (just like in the pool but with presence of some marine life and without getting allergies from the chlorine). It is very shallow so despite being generally part of the Pacific the water warms up in this place. It also makes for a nice walk during the low-tide. One can wade hundreds of meters into the ocean and dig up the abundant shellfish, catch crabs, build sand castles that are destroyed with the next tide. The kids had fantastic time as well. The only thing that still puzzles me is some irregularity of the tides - one day it would be 2 tides, another day it is 3. It all would happen during different times of the day without any easily understandable cycle. One low-tide could go up to 400 meters away others would be just 200. No recognizable pattern for me whatsoever although reading the local newspapers could help - they do run the tides guide.

So, it was then and now I am back in my office. Oh, not exactly. Eric made some arrangements for part of our team to go on an offsite and spend some time in building 36 with Office. Nothing super secretive but I can not tell you about it to not spoil anything that might come out of this.

In other news - in mid-September I am getting out of my Redmond office and going to PDC. Meeting the customers and seeing their side is always fun and gives us inspiration as well. I am looking forward for this especially since Office has so much content to present they even got a separate track in the conference.

Now back to the ActionsPane. The conception of ActionsPane was a perfect example of a customer driven inspiration. Chris Kunicki was the early adopter of then new SmartDocs technology in Office 2003. SmartDocs umbrella has more than just a programmable task pane but the programmable task pane is the pivotal feature. You could finally plug your own rich UI into Office. Chris was understandably excited and he even contracted to put together samples of SmartDocs that went out as part of Office 2003 Beta programs. He did this only to realize there is something missing to make SmartDocs a success.
Putting together a programmable task pane using SmartDocs technology is not for weak hearted. To name a few difficulties:

The central piece is an ISmartDocument interface with 25 methods in it most of which need to be implemented to show a single button control.
The controls in the SmartDocs are stateless. Once the cursor moves from one XML element to another the controls were destroyed and re-created again. So it was up to the developer to maintain the controls state.
You could have only 1 button click event handler which was called if any of the buttons were clicked. So if you had 5 buttons you needed to assign every one of those an ID. When button was clicked this ID was passed to the event handler (which is just another method on the interface) and you would go from there. Messy...

I can go on and on with the list ... And there was no designer whatsoever! So during the early planning days of VSTO Chris sent an e-mail and ask for the designer experience. Then he asked again. And we would reply that it is very hard to put up a designer to support ISmartDocument interface - it took several years to develop WinForms designer we just did not have the resources. But he would ask again.
And then the light bulb went off. We realized we did not need to create the ISmartDocument designer. All we needed is just to find a way to host WinForms inside the task pane. This WinForm would fill the entire pane area and would serve as a container for the components designed by the developers.
Then things started to happen with the speed of light. The first prototype was just positioning a WinForm form on top of the task pane. It had some message routing problems but it did gave people the ability to see the potential behind the concept. The right hosting solution is to host the WinForms natively e.g. the way IE does it - through ActiveX interfaces. Next, Office added the capability to stretch the ActiveX control to fill the task pane area entirely. This was especially incredibly because it happened only 2 months before Office 2003 shipped. Next Brian fixed for us the issues in WinForms that cause some focus management issues - you can see those issues if you use .NET Fx 1.1 to show UserControl in the task pane.

And it was ready. Chris likes to say ActionsPane is his favorite feature and I could not agree more.

In my next posts I will talk about creation of vanilla ActionsPane, then using UserControls to design ActionPane components, adding context sensitivity to the ActionsPane using new XMLNode's ContextEnter and ContextLeave events, discuss some usability aspects of the ActionsPane, answer questions (if any) and possibly provide some peek under the hood.

NewsGator and VSTO Outlook support

Misha Shneerson — Tue, 26 Jul 2005 00:57:00 GMT

Until recently people had "tough" choice to make - in your Outlook either run NewsGator or Outlook COM Add-ins with VSTO support. Both of these did not work together. This is because NewsGator did not support .NET Fx 2.0 which is required by VSTO.

Now .NET Fx 2.0 is supported by NewsGator and the issue seems to be resolved. But I still wonder whether NewsGator could use VSTO loader in the future? Then they will run in their own AppDomain without stepping on the toes of other managed Outlook COM Add-ins.

Thanks to Andrew Coates for keeping an eye on this.

Closing Documents Programmatically is not simple

Misha Shneerson — Fri, 22 Jul 2005 21:38:00 GMT

Both Word and Excel OMs have APIs that allow closing documents programmatically. I suppose there are some scenarios when people would like to call ThisWorkbook.Close() from within their document customizations. This has some interesting effects when such call is made from within managed VSTO customizations.

First of all closing the document will also cause the current AppDomain be unloaded. This is the basic feature of VSTO loader to ensure managed code does not hold references to the document that has just been closed. Note that AppDomain unloading happens while there is code from this AppDomain on the managed stack. This is kind of an interesting situation but CLR folks have found a way to deal with it. They try to unwind the stack as aggressively as possible to the frame where first method from the unloading AppDomain has been entered. To accomplish that CLR throws System.Threading.ThreadAbortException. In the documentation you will find that when this exception is thrown you can run but you cannot hide: ThreadAbortException is a special exception that can be caught, but it will automatically be raised again at the end of the catch block. Chris Brumme explains the whole process in much more details so you might want to read his excelleny blog entry.

When ThreadAbortException reaches the base-most frame the exception turns into the DomainUnloaded exception and, in our case, the execution transitions into the native code. And now the fun begins.

First scenario: the document was closed from within an event handler for Excel or Word event such as Worksheet.SelectionChange. In this case CLR realizes the host application calls the managed code as a regular COM call and the failure should be communicated according to COM conventions. The convention is that failure code is returned. In this case it is COR_E_APPDOMAINUNLOADED. Excel/Word ignore the return value and execution continues normally.

Second scenario: the document was closed from within a WinForms event handler. For example a button on a modeless from was pressed and Button.Click event was raised. In this case the point of entry into the managed code is a windows procedure (WndProc) implemented in the depths of System.Windows.Forms assembly - all managed code. Such invocation is called "Reverse P/Invoke" as it is the reverse situation from when managed code calls native API through mechanism known as Platform Invoke. Contrary to the COM scenario CLR does not know about any convention to communicate errors to the native callers. So, it just throws an exception, particularly Windows SEH. There is another long but outstanding post on this from Chris Brumme. So, now this SEH is thrown right into Excel/Word. But these application are designed to pop up a Dr. Watson dialog (informing that the application has crashed and suggesting to send a report to Microsoft) if they see an unhandled and unrecognized exception come their way. And they do! So, if you were seeing that Document.Close causes host application to crash this is why.

Another variation of "unhandled exception in reverse P/Invoke" crash is when your are debugging Word/Excel and there is an unhandled exception thrown from Button.Click event handler. Normally WinForms would internally catch unhandled exceptions but debugging mode is special cased. When WinForms detect managed debugger is attached they would let the exception go through to benefit from the Visual Studio debugger behavior which always breaks on unhandled exceptions. But when WinForms are hosted inside native application this trick causes crashes. In order to force WinForms into always catching the exception just install an event handler for System.Windows.Forms.Application.ThreadException event.

Those crashes were a big bummer for VSTO. Starting with VSTO v2 Beta2 you would not (usually :)) see those crashes. What is the trick? We decided that we want to be in control. If managed WndProc misbehaves we are going to deal with it right away without letting the SEH propagate and destabilize the entire application. Our VSTO loader sub-classes every WinForms "managed" window and redirects the WndProc to our own native WndProc. The latter calls into original managed WndProc and if the SEH is thrown we just swallow it.

Some internal implementation details (that are not guaranteed to stay this way in the future but this is the way things are now). We sub-class the window inside WH_CALLWNDPROCRET windows hook after WM_CREATE message is processed by WinForms. We check whether an HWND belongs to our AppDomain by calling System.Windows.Forms.NativeWindow.FromHandle(hwnd) from inside the AppDomain. The original WndProc is stuffed into GWL_USERDATA slot in the window.

Menus for VSTO Smart Tags are dynamic

Misha Shneerson — Thu, 21 Jul 2005 20:37:00 GMT

One quick tip today. Since VSTO Beta2 we have added SmartTags support for document level customizations. How to create those is covered by Paul Stubbs here and in a video tutorial here . However what is not obvious is that one can dynamically change the caption on the menu items displayed for a particular SmartTag. The SmartTag class has a collection of Actions that represent the menu item. The Action class exposes BeforeCaptionShow event. One can register an event handler for this event. In the event handler just change the value of your Action.Caption property to whatever string value you want. Since the tagged text, the property bag and the either Word's or Excel's Range object are passed in as parameters you can make quite educated decision about what the caption should be. If you set the value to an empty string (either null or String.Empty) the corresponding menu item would not appear at all. On the related note, do not use this event handler for actually modifying the range object. This event is only designed to get values from the OM and set the Caption property.