ProGuide Diagnosing ArcGIS Pro Add ins - kataya/arcgis-pro-sdk GitHub Wiki
Language: C#
Subject: Framework
Contributor: ArcGIS Pro SDK Team <[email protected]>
Organization: Esri, http://www.esri.com
Date: 11/24/2020
ArcGIS Pro: 2.7
Visual Studio: 2017, 2019
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
- ArcGIS Pro cannot load your Add-in
- 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
- Add-in causes Pro to crash on start-up
- Error in Visual Studio Designer while working with ArcGIS Pro controls
- ArcGIS Pro SDK Templates not found in Visual Studio
- Utilities to troubleshoot add-ins:
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.
- 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.
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.
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 2.0 on your machine, but the add-in you're loading was created using ArcGIS Pro 2.2 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="2.2.xxxx">
<Name>ProAppModule1</Name>
<Description>ProAppModule2 description</Description>
<Image>Images\AddinDesktop32.png</Image>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:
Note: if the add-in you are attempting to load has a desktopVersion attribute value in the config.daml file of 1.4 or earlier you must migrate your add-in to 2.0 or later. 2.0 was a breaking change release. You may incur compiler errors when migrating your add-in that will have to be fixed. Consult the ProConcepts 2.0 Migration Guide, Migration Procedure for the migration procedure.
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.
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.
When you're debugging or using an add-in, you receive an ArcGIS.Core.CalledOnWrongThreadException error.
If an API 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.
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."
- Your add-in has been successfully installed on a client machine
- Your add-in worked fine on a previous release
- Your add-in is no longer being loaded by Pro, even after you have deleted the assembly cache folder for the add-in.
Copy Local on at least one of your ArcGIS Pro assembly references is set to true.
Check the properties of all your ArcGIS Pro assembly references in your add-in project. Ensure the Copy Local setting is set to false. By default, whenever a .NET assembly reference is added to your project, the default Visual Studio behavior is to set "Copy Local" to true (You cannot change this default behavior in Visual Studio). Whenever you manually add an ArcGIS Pro assembly reference to your add-in project make sure to set Copy Local to false. This is detailed in ProConcepts Advanced Topics, ArcGIS Pro Assembly references in your project
- 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.
The Build Action property of the image in your Visual Studio project is set as "Resource."
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.
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."
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.
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="...
....
When you click a button on the ArcGIS Pro ribbon created by your add-in, the button disappears.
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.
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"...
An add-in that had previously worked on the previous 2.x release of Pro crashes the application after an upgrade of Pro.
Assuming that this is not a coding issue (null variable, bad path or name in your code, etc,etc), check your Pro API assembly references in the Visual Studio IDE. The most common cause of unexplained add-in crashes after a Pro upgrade are Pro API assembly references with the Copy Local property set to true. By default, Visual Studio sets Copy Local = true for any assembly reference added to a .NET project. There is no way to change this default behavior. Any assembly with Copy Local = true semantics is copied to the Pro add-in (or configuration or plug-in) assembly cache at runtime. If the Pro API assembly copied is the wrong version then when the add-in loads it, it (and Pro) will crash.
In Visual Studio, check your Pro API assembly properties. Change any Copy Local = true settings to Copy Local = false. Recompile and redeploy your add-in (double-click, xcopy, if it was being loaded from a well-known folder)
Note: The Pro SDK project templates ensure that Pro API references automatically added (by the template) when a project (.csproj or .vbproj) is created have Copy Local = false. Copy Local = true only occurs for references you add "by hand" at some point after the project has been created.
For certain controls (Coordinate System picker) you will get the following error in the Visual Studio designer: "Cannot create an instance of CoordinateSystemsControl".
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.
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
In Visual Studio, when you attempt to create a new Add-in\Configurations project you are not able to see the templates listed under the ArcGIS Pro Add-ins folder.
The .NET Framework version selected in the New Project dialog does not meet the minimum required version for the ArcGIS Pro SDK.
ArcGIS Pro SDK requires .NET Framework 4.8.0 or higher. In the New Project dialog in Visual Studio, select .NET Framework 4.8.0 in the combo box. You will now be able to see the ArcGIS Pro Add-in project types.
If .NET Framework 4.8.0 is not available and you are using Visual Studio 2017, you have to download and install the ".NET Framework 4.8 Developer Pack". If .NET Framework 4.8.0 is not available and you are using Visual Studio 2019, you can use the Visual Studio Installer, choose to "modify Installation Details", check the ".NET Framework 4.8 development tools" checkbox, and then click "Modify" as shown here:
Please consult technical support article How To: Convert a version 2.0 to 2.4 ArcGIS Pro SDK add-in solution to Pro 2.5 and later versions for more information
