ProGuide Diagnosing ArcGIS Pro Add ins
Language: C# and Visual Basic
Subject: Framework
Contributor: ArcGIS Pro SDK Team <[email protected]>
Organization: Esri, http://www.esri.com
Date: 12/30/2016
ArcGIS Pro: 1.4
Visual Studio: 2013, 2015
.NET Target Framework: 4.6.1
In this guide, you'll find solutions to the following issues sometimes encountered when developing with ArcGIS Pro add-ins:
- Add-in not loaded by ArcGIS Pro after building it in Visual Studio
- ArcGIS.Core.CalledOnWrongThreadException exception occurs
- Image does not load on a Button control
- Assembly name mismatch causes Visual Studio to display a compile warning
- Namespace mismatch causes controls to not work or disappear
- Error in Visual Studio Designer while working with ArcGIS Pro controls
- Utilities to troubleshoot add-ins
- View the DAML elements loaded at startup: dumpcombineddaml
- Enable dynamic mode event logging: enablediagnostics
####Add-in not loaded by ArcGIS Pro after building it in Visual Studio
######Issue
You launch ArcGIS Pro using the Visual Studio debugger or directly. Your add-in does not load in ArcGIS Pro and is missing from the ribbon.
There are multiple causes for this issue.
######Cause 1
- You've deleted the add-in file (*.esriAddinX file) from the C:\Users\<UserName>\Documents\ArcGIS\AddIns\ArcGISPro folder.
- Without making any code changes, you build the add-in project in Visual Studio and start ArcGIS Pro or click the Start button in Visual Studio to start the debugger.
######Solution
From the Visual Studio Build menu, click the Rebuild Solution menu item. This creates the add-in file (*.esriAddinX file) under the C:\Users\<UserName>\Documents\ArcGIS\AddIns\ArcGISPro folder. When you start ArcGIS Pro, your add-in will now load.
When you Build the add-in project, Visual Studio performs an incremental build. This means that if there are no code changes since the last build, the assemblies and add-ins are not recreated. Since you've deleted the add-in file (*.esriAddinX file) from the C:\Users\<UserName>\Documents\ArcGIS\AddIns\ArcGISPro folder, ArcGIS Pro cannot load it. A Rebuild in Visual Studio will remove all the intermediary and compiled files (including C:\Users\<UserName>\Documents\ArcGIS\AddIns\ArcGISPro\*.esriAddinX file) and recreate them after compilation.
######Cause 2
The add-in you are attempting to load has a higher (newer) desktopVersion attribute value in the config.daml file than the ArcGIS Pro version on your machine. For example, you have ArcGIS Pro 1.2 on your machine, but the add-in you're loading was created using ArcGIS Pro 1.3 SDK. You can find the version of the add-in from the desktopVersion attribute value in the config.daml file.
...
<AddInInfo id="{979319f4-267c-4bf9-981b-a7e41c0cc9cc}" version="1.0" desktopVersion="1.3.xxxx">
<Name>ProAppModule1</Name>
<Description>ProAppModule2 description</Description>
<Image>Images\AddinDesktop32.png</Image>######Solution
Upgrade the ArcGIS Pro version on your machine to match the add-in version. The add-in could be using API calls that are available only in the newer version of ArcGIS Pro.
The following two utilities can be used to troubleshoot issues with ArcGIS Pro add-ins:
######Cause 3 The add-in you are attempting to load might not be digitally signed. ArcGIS Pro on your system could be configured to load only digitally signed add-ins. These settings are defined in ArcGIS Pro using the Add-In Manager. Add-In Manager can be accessed from Pro's backstage. Using the Add-In Manager you can configure ArcGIS Pro to load only digitally signed add-ins.
######Solution
To check the settings defined in the Add-In Manager, launch ArcGIS Pro. From the start-up page access the backstage by clicking on "About ArcGIS Pro". Click on the "Add-In Manager" tab. Click on Options. You can see the different settings that can be used to control the loading of add-ins. Check to see if you have either one of the first two radio button options checked on.
Note: You can also perform some advanced configurations of ArcGIS Pro to control loading of Add-ins using registry keys.
####ArcGIS.Core.CalledOnWrongThreadException exception occurs
######Issue
When you're debugging or using an add-in, you receive an ArcGIS.Core.CalledOnWrongThreadException error.
######Cause
If a method on a particular object in your add-in is called on the wrong thread, the call generates an ArcGIS.Core.CalledOnWrongThreadException exception. Refer to Tasks and the task asynchronous pattern topic in the ProConcepts: Framework wiki.
######Solution
The ArcGIS Pro framework provides a custom Task scheduler that should be used when dispatching Tasks that make calls to synchronous methods within ArcGIS Pro SDK. Add-in developers should call QueuedTask.Run.
Task t = QueuedTask.Run(()=>
{
// Call synchronous SDK methods here
});The method in your add-in that is throwing this error is a synchronous method. Synchronous methods should be called on the worker thread only. Methods of this type are annotated within the API reference, and a code tip will appear when hovering over the method. The code tip will say "This method must be called on the MCT. Use QueuedTask.Run."
####Image does not load on a Button control
######Issue
- You add an image file to your add-in project in Visual Studio.
- You then reference your image in the config.daml file to be used by the button element like this:
<button id="MyButton" caption="MyButton" className="MyButton" loadOnClick="true"
smallImage="Images\CustomImage16.png"
largeImage="Images\CustomImage32.png">
<tooltip heading="Tooltip Heading">Tooltip text<disabledText /></tooltip>
</button>- You compile your add-in and start ArcGIS Pro. You notice that the button loaded on the ArcGIS Pro ribbon does not display the custom image.
######Cause
The Build Action property of the image in your Visual Studio project is set as "Resource."
######Solution
Change the Build Action property for the image file to "AddInContent".
Custom images used by a button control in ArcGIS Pro need to be added to the Visual Studio add-in project as "AddInContent." By default, an image added to a WPF project (ArcGIS Pro add-in project) in Visual Studio has the Build Action set as "Resource."
When ArcGIS Pro starts, it does not auto-load the add-in's dll (by default). Hence, images included as "resources" in the add-in's assembly are not available when ArcGIS Pro starts. Only the UI elements defined in the add-in's config.daml are loaded by ArcGIS Pro at start-up. If the image is included in the add-in by setting its "Build Action" to "AddInContent," ArcGIS Pro will extract the image from within the add-in (*.esriAddInX file) and load it on the ribbon.
####Assembly name mismatch causes Visual Studio to display a compile warning
######Issue
When you compile an add-in project, you get a warning in Visual Studio that says "<AddInAssembly.dll> was not found. The value of the defaultAssembly attribute in the config.daml should match the name of the of the assembly for the add-in project."
######Cause
The config.daml file in an ArcGIS Pro add-in specifies the name of the assembly using the defaultAssembly attribute. If the assembly does not exist in the add-in package (.esriAddInX file), a warning appears in Visual Studio when the add-in is compiled.
######Solution
Find the defaultAssembly attribute value listed in your config.daml file. Access your add-in project's Properties page through its context menu. Confirm that the entry in the Assembly Name text box matches the defaultAssembly attribute value from the config.daml file.
<?xml version="1.0" encoding="utf-8"?>
<ArcGIS defaultAssembly="MyRenamedAssembly.dll" defaultNamespace="MyRenamedAssembly" xmlns="..." xmlns:xsi="..." xsi:schemaLocation="...">
<AddInInfo id="...
....
####Namespace mismatch causes controls to not work or disappear
######Issue
When you click a button on the ArcGIS Pro ribbon created by your add-in, the button disappears.
######Cause
The button's class (or code behind) is not found by the ArcGIS Pro add-in framework. This is most likely because the namespace declared in the config.daml file and the namespace of the button’s class file do not match.
######Solution
Find the defaultNamespace attribute value listed in your config.daml file.
<?xml version="1.0" encoding="utf-8"?>
<ArcGIS defaultAssembly="ProAppModule1.dll" defaultNamespace="MyRenamedAddin" xmlns="..." xmlns:xsi="..." xsi:schemaLocation="...">
<AddInInfo id="...
....
Access your add-in project's Properties page through its context menu. Confirm that the entry in the Default Namespace text box matches the defaultNamespace attribute value from the config.daml file. All newly added classes receive the default namespace specified in the project’s properties.
If your button class (or any ArcGIS Pro Control) is inside a folder in the add-in project or inside a nested namespace, enter the fully qualified class name for the button's className attribute in the config.daml file. The following example shows a button class in the "RenderingAddin.Ribbon.ActivateButton" namespace:
<button id="RenderingAddin_Ribbon_ActivateButton"
caption="ActivateButton"
className="RenderingAddin.Ribbon.ActivateButton"...
For certain controls (Coordinate System picker) you will get the following error in the Visual Studio designer: "Cannot create an instance of CoordinateSystemsControl".
######Cause
This error is caused because of missing references in your project that are required by the control to view them in the Visual Studio designer.
######Solution
If you are having problems viewing these controls in the Visual Studio Designer, you may need to add these additional dependencies from the ArcGIS Pro installation folder to your Visual Studio project. Note: Esri.ArcGIS.ItemIndex.dll has a dependecy on System.Web.dll. None of these are required for run-time.
- ArcGIS.Desktop.Shared.WPF.dll
- ArcGIS.Desktop.DataGrid.Contrib.Wpf.dll
- Esri.ArcGIS.itemIndex.dll
- System.Web.dll
