Visual Studio Tools: Best Practice when adding References to Projects

David Meego - Click for blog homepageI am writing this article after seeing the side effects of Visual Studio Tools developers not following Best Practice when adding references to their projects.

Two mistakes made by the developer in this example resulted in Microsoft Dynamics GP failing to launch with the “An exception occurred while trying to load or initialize the addin” error.

It took a while to understand exactly what was happening, but once the cause was discovered everything made perfect sense and the fix was fairly simple.

When working with Visual Studio Tools for Microsoft Dynamics GP using either Visual C# or Visual Basic.Net, you need to add references to the Dictionary Assembly DLL files for the Dexterity dictionaries used in your code, as well as a reference to the Dexterity Bridge.

Shown below are some example references from a C# project and an excerpt of code showing the using statements:

using Microsoft.Dexterity.Bridge;
using Microsoft.Dexterity.Applications;
using Microsoft.Dexterity.Applications.MenusForVisualStudioToolsDictionary;<span class="mce_SELRES_start" style="width: 0px; line-height: 0; overflow: hidden; display: inline-block;" data-mce-type="bookmark"></span>

The best practice I am promoting is to change the Copy Local property for each of the added DLL file references to “False”. This setting defaults to “True” when the reference is added and should be changed.

If you forget to make this change, then at least when you ship your code, DO NOT copy the referenced DLL files into the Addins folder on the target machine.


I hear you ask “Why?…. it has never caused problems before”.

The issue is that you have now duplicated the referenced DLL files, they now exist in both the application folder AND in the Addins folder.

If you upgrade any of the products or install a service pack, the Dictionary Assembly files in the application folder will be upgraded as expected, but the duplicates in the Addins folder will not be upgraded (as they should not be there).

When launching Microsoft Dynamics GP, the old DLLs in the Addins folder will be used before the newer (and correct) DLLs in the application folder and this is very likely to cause an exception when an addin attempts to reference an new object that does not exist in the old version of the DLL.

In the support case I was dealing with, we had checked the versions of the Dictionary in the application folder, the Dictionary Assembly DLL in the application folder, and the Addin DLL in the Addins folder. All of them were the correct version, but GP still failed to launch.

I asked for a screenshot of the Addins folder and it contained a number of files that should not have been there, including an old version of the Dictionary Assembly DLL that was causing the issue.

  • Applications.Dynamics.dll
  • Applications.Dynamics.ModifiedForms.dll
  • Applications.MenusForVisualStudioTools.dll
  • Applications.ProjectAccounting.dll
  • Applications.ProjectAccounting.ModifiedForms.dll
  • Microsoft.Dexterity.Bridge.dll
  • Microsoft.Dexterity.Shell.dll

I provided the following instructions which helped fix the issue:

  • Move Application.*.ModifiedForms.dll files in the Addins folder to the application folder, They should not be in the Addins folder.
  • Check all the Application.*.dll files; if they exist in the application folder, delete the duplicates from the Addins folder. They should not be in the Addins folder.
  • Check all the Microsoft.Dexterity.*.dll files; if they exist in the application folder, delete the duplicates from the Addins folder. They should not be in the Addins folder.

To avoid issues like this in future:

  1. Change Copy Local to False immediately after adding the reference.
  2. Don’t copy DLL files which already exist in the application folder into the Addins folder as this creates duplicates.
  3. Dictionary Assembly DLLs created using the DAG.exe tool should only be in the application folder.

Hope this helps.


This article was originally posted on

3 thoughts on “Visual Studio Tools: Best Practice when adding References to Projects

  1. Great article Dave, this is the first thing I do for this reason and because the referenced dll may be the wrong version causing all sorts of issues.


Please post feedback or comments

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.