Visual Studio Code – Outlook add-in will not load in Release mode on Visual Studio — and is that needed for deployment of the add-in?

After several days and many hours of research and experimenting, I finally have my add-in installing, loading and running as-expected in Outlook on a test machine. To perhaps help anyone else struggling with these questions in the future, here is essentially a "brain dump" of what I learned:

The "Start" Button in "Debug" versus "Release" mode

As I mentioned in the second "Update" to my question, I had a "eureka" moment when I realized that running the add-in by hitting the "Start" button in Visual Studio is very different from doing so by launching Outlook directly outside of Visual Studio. As I discuss at the end of this post, I am fairly new to the Visual Studio IDE, and I had never seen this distinction discussed in documentation or forum postings.

Importantly, hitting the Start button inside of Visual Studio in "Release" mode triggers the following pop-up dialog window (at least initially -- see below):

As I discuss in my question, the first time I saw this, I clicked "Stop Debugging" and my add-in would not load in Outlook, in either Release or Debug mode. I was able to get this pop-up to reappear only after rolling back to a backup copy of my solution from before creating the Setup project. I discovered that accidentally by inadvertently clicking "Start" while in "Release" mode, rather than launching Outlook directly.

This time I clicked "Disable Just My Code and Continue" -- and my add-in loaded up fine inside of Outlook. Although I suspect that if I were trying to debug with breakpoints -- those likely would not have worked.

Also, the pop-up now still reappears when I hit Start in Release mode. I was never able to figure out why it permanently disappeared after I had hit "Stop Debugging" that first time. Maybe I had accidentally hit the last option with "(Don't Ask Again)" -- but I swear that I had hit the first option.

As for "Just My Code", here is a good SO question and answer discussing what that means.

"Optimized" Code and "Release Bugs" in Release Mode

Although I was able to get my add-in to load in Outlook in Release mode, it was exhibiting some strange behavior. After reading this SO question and several of the answers, especially this one, it dawned on me that this was being caused by one or more "release bugs" as a result of the optimization Visual Studio was doing to my code.

I decided that rather than spend countless hours trying to debug the IL ("intermediate language") code generated by Visual Studio -- I would instead see if I can just deploy the Debug version of the solution, which as I discuss below, I was able to do just fine.

Although there are clearly (and hotly debated) pros and cons to deploying a "Debug" version of an add-in (see the above SO link), such as maybe a performance/speed hit -- for me the choice was clear, given that the Debug version runs completely as expected without the weird behavior exhibited by the Release version.

The Registry and "Debug" versus "Release" mode

I also knew that for VSTO add-ins, in addition to writing/deleting files to "bin/Debug" and "bin/Release", Visual Studio also writes/deletes entries to the registry. When Outlook starts, that is where it checks to see if any add-ins should be loaded, as described by MS here.

However, I was not familiar with exactly how this works. I used the info provided by Microsoft at the link above to search the registry on my development machine to find the subkeys and values actually generated and deleted by Visual Studio each time I did a "build" and a "clean."

This was not as simple as looking in the "HKEY_LOCAL_MACHINE" and "HKEY_CURRENT_USER" sections (or "hives") of the registry. When I did that, my add-in was not under "SOFTWAREMicrosoftOfficeOutlookAddins" in either hive. After doing a "find" for "Addins" -- and hitting F3 repeatedly -- after about 20 minutes or so I finally found it. (In hindsight -- I should have searched for the name of the add-in, oh well.)

For whatever reason, Visual Studio was instead saving the keys to my specific "HKEY_USERS" hive of my registry -- where there were 9 subdirectories based on various accounts I had setup on my development PC over the years. The hive for my currently active account was labeled with a long cryptic numeric string:

Finding this was crucial to my understanding, because then I could "build" and "clean" the solution in both Debug and Release mode, and see the changes Visual Studio was making to the registry each time.

Every VSTO add-in must have a subkey in the proper Outlook/Addins hive, and must have all four of the values shown in the image above ("Description", "FriendlyName", "LoadBehavior", and "Manifest").

The "Manifest" value is the one that tells Outlook where to find (somewhat confusingly) the "add-in.vsto" file (not the "add-in.manifest" file). It must begin with "file:///" and end with "|vstolocal".

Because my add-in uses a FormRegion, the FormRegions subkey was also important to track and learn how to use properly. The FormRegions subkey must contain a subkey for each type of Outlook item that your FormRegion is used for. In my case, it is only used for a MailItem, which in the registry is called (somewhat confusingly) "IPM.Note". The format for the value in that subkey is:

Name: [Add-in name].[FormRegionName]
Type: string (REG_SZ)
Data: =[Add-in Subkey name under Addins]

For example, if your add-in is named "TestOutlookAddin" with a FormRegion called "FormRegion1", and the main add-in subkey is named "TestCompany.TestOutlookAddin", then this subkey should look like this:

MS Setup Instructions Did Not Work for my add-in

I obtained all of the above info pretty much as a result of my frustration using the instructions provided by Microsoft for creating a VSTO add-in installer, with my add-in repeatedly failing to load on my test machine. It was failing whether I tried "Click Once" or the standalone Windows Installer method.

As for Click Once, after reading this Code Magazine article, I determined that that method was not appropriate for my add-in, especially because there are configuration settings the user can set, and a local SQLite database saved on the user's machine.

As for the stand alone installer method, when I couldn't get that to work with my add-in, I experimented with creating a very simple add-in with no third-party libraries -- and I was able to get the add-in installed and working using the above instructions from Microsoft. But I simply could not get my full add-in to load and run using that method.

I believe this is (partially) due to the fact that my add-in uses several third-party Nuget packages, and two class libraries that I coded myself.

On a whim -- assuming that it wouldn't work -- I tried simply copying the entire "bin/Release" folder to my test machine, and then manually created the appropriate keys in the registry (as I discussed above). It worked.

It worked, despite not having Visual Studio installed on that machine, the add-in loaded and ran when I started Outlook. However, the add-in was exhibiting the strange "release bug" behavior I discussed above.

So I tried again, this time copying over the "bin/Debug" folder instead. It worked.

It loaded and ran on my test machine exactly as it did on my development machine.

So I learned (the hard way) -- that deploying a VSTO add-in (or at least MY add-in) requires essentially two steps:

1. Copy all of the files from either bin/Debug or bin/Release to the target machine.
2. Create the appropriate keys and values in the registry pointing Outlook to where those files are located.

And oh... I should add to that a "Step Zero":

0. Check for and install the .Net Framework and VSTO Runtime

Manual Copying versus Windows Installer -- Likely Security/Trust Problem

With the above in mind, I went back and created a Setup project in Visual Studio that simply copied all of the files from bin/Debug to the target machine and sets up the registry keys.

I did the install, but on launching Outlook, my add-in initially loads, and then mysteriously unloads silently.

I believe -- although have not 100% confirmed -- this is due to the way the security/trust settings are handled by Outlook when the add-in is "manually" copied to the machine versus being installed via a Windows Installer.

With the Windows Installer, I get the standard "UAC" type of warning message:

However, "manually" copying the files to the test machine and manually setting the registry keys, triggers instead the following "Microsoft Office Customization Installer" message upon starting Outlook:

Clicking the "Install" button results in the add-in loading and running properly.

I believe what is happening -- although it is a guess really -- is that the Windows Installer is not properly designating the security/trust settings on all of the .dll files used by my add-in, causing Outlook to disable it silently after starting to load it. There may be a way to configure the Setup project in Visual Studio to fix this -- short of going through the whole process of making the entire solution "trusted" with a certificate, etc. However, I have been unable to find any documentation on that.

Regardless, "manually" copying over the files and setting the registry keys triggers the "Microsoft Office Customization Installer" message, which then seems to properly configure all the trust settings to allow the add-in to install and load. Also -- that message appears only the first time Outlook is started with a new "manually installed" add-in.

Inno Setup To the Rescue

I did some more research and found the excellent free and open-source Inno Setup installer builder for Windows. This allowed me to create my own Installer that simply compresses the files in my bin/Debug folder into a single .exe file. Running that .exe on the target machine simply copies the files to the designated location on the target machine, and then writes the needed keys and values to the registry. Launching Outlook then brings up the above MS Office "Customization Installer" message, and clicking "Install" loads and runs the add-in which then runs perfectly fine.

What's great about this is that it is free, and provides the same "Installer" and "Uninstaller" type of functionality as the VS Setup project is supposed to. And there are scripts people have developed and shared for checking whether .Net is installed, etc.

Most importantly, it just works.

Final Note

Although all this was difficult to figure out on my own, it forced me to learn a great deal about the differences between "Debug" and "Release" builds in Visual Studio and VSTO, and for that I am grateful. I recently returned to coding after a 12 year hiatus, and this is my first attempt at an Outlook VSTO com add-in; and I had had only cursory prior experience with the Visual Studio IDE.

The Stack Overflow community and knowledge base has been a tremendous help to me, and I hope this Answer is a worthy addition to that. Although Microsoft appears to be moving away from VSTO com add-ins in favor of web-based add-ins -- there is still a place for com add-ins, particularly for accessing the user's local storage, which web-based add-ins cannot do (as far as I can tell). So -- although perhaps unlikely -- maybe this Answer will help someone in the future who is also struggling with "Debug" versus "Release" mode and how to deploy their VSTO com add-in.