ProGuide Diagnosing ArcGIS Pro Add ins
Language: C#
Subject: Framework
Contributor: ArcGIS Pro SDK Team <arcgisprosdk@esri.com>
Organization: Esri, http://www.esri.com
Date: 10/02/2023
ArcGIS Pro: 3.2
Visual Studio: 2022
In this guide, you'll find solutions to the following issues sometimes encountered when developing with ArcGIS Pro add-ins:
- 2.x Add-in not loaded by ArcGIS Pro 3.0
- 2.x Add-in does not compile in ArcGIS Pro 3.0
- 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
- Copy-local=No is not working
- Utilities to troubleshoot add-ins:
Addins are not forwards compatible across major releases. You will have to migrate you add-in to 3.0
ArcGIS Pro 3.0 is a breaking change release. ArcGIS Pro 3.0 has moved from .NET Framework 4.8 to .NET 6.0. You will have to migrate you add-in to 3.0, recompile, and fix any breaking changes.
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.6 on your machine, but the add-in you're loading was created using ArcGIS Pro 2.9 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: ArcGIS Pro 3.0 is a breaking change release. All 2.x addins must be migrated to 3.0 before they can be run on ArcGIS Pro 3.0.
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
Consult ProGuide Content and Image Resources, Image Content on options for including image content with an add-in.
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="ChangedAssemblyName.dll" defaultNamespace="ChangedAssemblyName" xmlns="..." xmlns:xsi="..." xsi:schemaLocation="...">
<AddInInfo id="...
....
Notice that the defaultAssembly and defaultNamespace attribute values in the Config.daml do not match the corresponding assembly name and default namespace name shown below in the Visual Studio project properties in this example. So either the Config.daml or the Visual Studio values would need to be changed so that they match.
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.
Note: As of Visual Studio 2022, Visual Studio uses the following macro to determine the default namespace name based on the name of the .csproj/.vbproj: $(MSBuildProjectName.Replace(" ", "_"))
This macro can cause a mismatch if you change the name of your project file in addition to the defaultNamespace in the Config.daml. Also notice that the default namespace macro will remove underscored "_" if they are present in the project name. Using underscores, therefore, in the project name should be avoided.
Find the defaultNamespace attribute value listed in your config.daml file.
<?xml version="1.0" encoding="utf-8"?>
<ArcGIS defaultAssembly="ProAppModule1.dll" defaultNamespace="ChangedAssemblyName" xmlns="..." xmlns:xsi="..." xsi:schemaLocation="...">
<AddInInfo id="...
....
Access your add-in project's Properties page through its context menu. Make sure that the defaultNamespace attribute in the Config.daml matches the Default Namespace in the Visual Studio project properties. Notice that, in this case, the Config.daml defaultNamespace is set to ChangedAssemblyName whereas the Default Namespace for the project is set to ProAppModule1. Therefore, to fix this issue, either the value in the Config.daml or the value in the Visual Studio properties would need to be changed so that they match.
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 "ProAppModule1.Ribbon.ActivateButton" namespace:
<button id="ProAppModule1_Ribbon_ActivateButton"
caption="ActivateButton"
className="ProAppModule1.Ribbon.ActivateButton"...
An add-in that had previously worked on the previous 3.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 = Yes 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 = Yes settings to Copy Local = No. 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.
Setting the Copy Local=No assembly property has no effect. The assembly is still copied locally (and is deployed with the addin)
MSBuild actually uses a "False" tag to control the copy local behavior. See MSBuild project items.
At the time of writing, 4/25/22, Visual Studio 2022 v17.1.6 or less does not currently add a <Private>False | True</Private> tag into the .csproj/.vbprj to control copy local behavior. If you are experiencing issues with the copy local behavior of Visual Studio 2022, try adding a <Private> tag to the relevant assembly reference in the .csproj/.vbprj.
<!-- Before -->
<Reference Include="SomeCustom3rdparty">
<HintPath>C:\Data\bin\SomeCustom3rdparty.dll</HintPath>
<CopyLocal>False</CopyLocal>
</Reference>
<!-- After -->
<Reference Include="SomeCustom3rdparty">
<HintPath>C:\Data\bin\SomeCustom3rdparty.dll</HintPath>
<CopyLocal>False</CopyLocal>
<Private>False</Private>
</Reference>
