Troubleshooting add-ins

Summary
This topic lists a number of commonly encountered problems with add-in development, behavior, and deployment and suggests actions to help resolve these issues.

In this topic

Compilation errors

The majority of the issues discussed in this topic are behavioral, as most compilation errors are identified and can be fixed by referring to the errors and warnings window in Visual Studio.

Type not defined error

If you receive an error about an ArcGIS Explorer type not being defined (for example, "Polygon is not defined"), refer to the following:
  • Verify that your ArcGIS Explorer references are set correctly in the project by doing the following:
    • Open the Solution Explorer in Visual Studio, select the ESRI.ArcGISExplorer reference, check that its CopyLocal and Specific Version properties are set to false, and the Path property points to the correct location for the correct version of the ArcGIS Explorer installation on disk. If any properties are incorrect, remove the reference, save the project, add the reference again, then ensure you set the CopyLocal and SpecificVersion properties to false. Repeat the process for the ESRI.ArcGISExplorer.Application reference.
  • Verify that you have fully qualified each ArcGIS Explorer type (for example, ESRI.ArcGISExplorer.Geometry.Polygon, instead of just polygon), or that you have using statements (C#) and Imports statements (VB .NET) at the top of the class file where the problem occurred.

Ambiguous reference error

You might encounter compilation errors like one or more of the following:
  • Point is an ambiguous reference between System.Drawing.Point and ESRI.ArcGISExplorer.Geometry.Point.
  • Cannot implicitly convert type ESRI.ArcGISExplorer.Geometry.Point to System.Drawing.Point.
  • Point is an ambiguous reference between ESRI.ArcGISExplorer.Geometry.Point and System.Drawing.Point.
The errors can indicate other class names besides the Point class. This is due to having two imported namespaces in one class file, which both declare a type with the same name. This commonly happens with the ESRI.ArcGISExplorer.Geometry.Point class (clashes with System.Drawing.Point) and the ESRI.ArcGISExplorer.Application.Application class (clashes with
System.Windows.Forms.Application), although it can happen for other types too, and the error you receive depends on the order namespaces are imported in. The solution is to fully qualify these type declarations or remove one of the conflicting using and Imports statements if possible.

Runtime errors

ThreadingException

An ESRI.ArcGISExplorer.ThreadingException may be thrown when an ArcGIS Explorer object is accessed on a different thread to the one on which it was created. This can happen in a number of circumstances, including cases where a new thread was not consciously started in the code of the add-in. The ThreadingException help topic lists a number of situations in which a ThreadingException can occur.
For example, a ThreadingException can occur if using ArcGIS Explorer objects in the download completion events on the System.Net.WebClient class. This is because these events may occur on a worker thread. In this case, make use of the InvokeRequired method on the WebClient class in order to pass control back to the main User Interface (UI) thread from where ArcGIS Explorer objects can safely be accessed.
See also the Threading namespace overview for a list of best practices when working with the ESRI.ArcGISExplorer.Threading.BackgroundWorker class.

Behavioral issues

The following discusses some behavioral issues:
Your add-in compiles, but the Button, CheckBox, ComboBox, DockWindow, and Gallery is not enabled as expected on the Ribbon. An add-in control can be disabled as follows:
  • Application conditions—Defined in the Addins.xml file in your project and can be used to disable Buttons, CheckBoxes, ComboBoxes, DockWindows, and Galleries based on what is selected in the application. Select the "condition" attribute on the Button, CheckBox, ComboBox, DockWindow, or Gallery element.
  • Your add-in class can set the Button.Enabled, DockWindow.Enabled, CheckBox.Enabled, ComboBox.Enabled, or Gallery.Enabled property to false to indicate that it is disabled; verify the code in your Button, CheckBox, ComboBox, DockWindow, or Gallery class file.
Your Button, CheckBox, ComboBox, DockWindow, and Gallery did not appear as expected on the Add-Ins tab on the Ribbon. Verify the following if ArcGIS Explorer failed to load your add-in:
  • Rebuild the add-in. Check the Output window in Visual Studio. Did the Visual Studio Tools for ArcGIS Explorer report that the add-in .eaz file was successfully generated, verified, and copied to the ArcGIS Explorer AddIns folder? If not, check for build errors or warnings. For more information, see Building add-in projects.
  • In ArcGIS Explorer, verify that the add-in can be viewed on the AddIns dialog box (see the Glossary for more information). If the add-in can be seen on this dialog box, verify that the Buttons, CheckBoxes, ComboBoxes, DockWindows, and Galleries in your add-in project are defined in the project's Addins.xml file.
  • Debug the add-in project and check if exceptions occurred in your add-in class constructors or other initialization code. For more information, see  Debugging add-ins from Visual Studio.
Extension add-ins do not have any user interface (UI) and do not appear on the Add-Ins tab.
ArcGIS Explorer does not start:
  • If you are using a beta version of ArcGIS Explorer, ensure all add-ins built against beta software are deleted from the cache before starting the application.
ArcGIS Explorer does not recognize the tab order on the DockWindow:
  • You might notice that TabStop properties of the controls on the DockWindow are recognized, but the TabIndex property is ignored. This might be due to problems in the underlying native code that hosts your managed DockWindow. To work around this issue, change the order in which the controls are added to the form to match the tab order you require.

    You do not need to reconstruct your DockWindow; you can edit the designer code for the DockWindow, which is the part of the DockWindow that Visual Studio creates automatically. Generally, this form is not edited manually; incorrectly editing this file can indicate that your DockWindow is corrupted and cannot be compiled; therefore, only edit this file if you are familiar with the process.
Geodatabase feature class layers with an Unknown coordinate system may cause instability if added to the map:
  • If a geodatabase feature class has an Unknown coordinate system, it should not be added to the map. After connecting to a feature class, check the CoordinateSystem property before attempting to add it to the map if the data to avoid this issue.

Deployment issues

The following discusses some deployment issues:
How you can update your add-in users with a new version of the add-in:
  • If you are using an application configuration to deploy your add-in, you can edit the configuration to include the new add-in, then redeploy the configuration to your users. If users directly add your add-in to the Add-Ins tab, they need to manually remove and re-add the new add-in .eaz file in the same way.
A DockWindow fails to load on some machines but works correctly on others:
  • Deleting the ArcGIS Explorer application settings file may resolve this issue. Note that the application settings file contains various settings for the ArcGIS Explorer application, in addition to DockWindow information, which will be lost if the file is deleted. Ensure you take a backup of this file before deleting. The settings file can be found in the folder which contains the Addins cache folder, at "%APPDATA%\esri\arcgis explorer".

Getting more help

If the previous tips have not helped you to troubleshoot your problems, see the following resources: