ProConcepts Advanced Topics - Esri/arcgis-pro-sdk GitHub Wiki

Language:      C#
Subject:       Framework 
Contributor:   ArcGIS Pro SDK Team <[email protected]>  
Organization:  Esri, http://www.esri.com  
Date:          10/06/2024 
ArcGIS Pro:    3.4  
Visual Studio: 2022 

This guide contains advanced concepts regarding ArcGIS Add-ins and Configurations.

• Configure build server to build add-ins and configurations
  • Method 1: Using ArcGIS Pro Extensions Nuget
  • Method 2: Manual configuration of build server
• Command line build
• Add-in versioning
  • Plugin versioning
• Add-in loading scheme
  • 1. Configurations defined well-known folders
  • 2. Admin well-known folders
  • 3. Current User well-known folders
  • 4. Default folder
  • 5. Plug-in Default folder
  • Plug-in Loading Scheme
  • Control order of add-in loading using DAML
• Configuration loading scheme
• ArcGIS Pro Assembly references in your project
• Loading 3rd Party Assembly References
• Obfuscation
• Display End user license agreement, EULA, with Addin installation
• Bypassing Pro Shortcut Key Filtering on Dockpanes

The standard build process of an ArcGIS Pro add-in and configuration will install the add-in or configuration for debugging purposes after the compilation completes. The installation process will fail if ArcGIS Pro is not installed on the build machine resulting in a build failure. Although not an issue for developers actively coding, compiling, debugging, etc. on their own machines, requiring an install of ArcGIS Pro can be a problem for a build server environment.

Therefore, since version 1.4, build servers can be configured to compile add-ins and configurations without installing ArcGIS Pro. It is still necessary to deploy the ArcGIS Pro extension assemblies, etc. to the build server in their correct locations to satisfy compilation requirements.

The recommended approach to build add-ins and configurations on a server is to use the ArcGIS Pro Extensions NuGet.

Refer to the instructions for using the ArcGIS Pro Nuget to build add-ins and configurations on build machines with continuous integration.

If for some reason, you do not want to use the NuGet, follow these steps (Substitute your ArcGIS Pro bin folder location for C:\Program Files\ArcGIS\Pro\bin):

1. From a machine that has ArcGIS Pro installed, copy the assemblies that your add-in/configuration references to a C:\Program Files\ArcGIS\Pro\bin folder and C:\Program Files\ArcGIS\Pro\bin\Extensions folder on your build server respectively (assuming that the references use the default Pro location). Add-in/configurations/plugins also use the DAML schema (which is not necessary for compilation but will result in compilation warnings if not found): C:\Program Files\ArcGIS\Pro\bin\ArcGIS.Desktop.Framework.xsd
   
   Note: In order to build an ArcGIS CoreHost application on a build server, you only need the following 2 ArcGIS Pro assemblies:

   • ArcGIS.Core.dll
   • ArcGIS.CoreHost.dll

   Both these assemblies are found in the C:\Program Files\ArcGIS\Pro\bin folder. (Substitute your ArcGIS Pro bin folder location for C:\Program Files\ArcGIS\Pro\bin)

2. Copy C:\Program Files\ArcGIS\Pro\bin\Esri.ProApp.SDK.Desktop.targets to your build server.
   Note: If space is not an issue, it may be simpler to copy the entire ArcGIS Pro bin folder and subfolders to your build server rather than attempting to resolve just those few dlls and files that are referenced by add-ins or configurations.

3. If you sign your add-in or configuration during the compilation process, you will also need ArcGISSignAddIn.exe. To sign the add-in using ArcGISSignAddIn.exe, copy ArcGISSignAddIn.exe, ArcGISSignAddIn.dll, ArcGISSignAddIn.runtimeconfig.json and DADFLib.dll to your bin folder. Alternatively, you can download the ArcGISSignAddIn.zip file from the ArcGIS Pro SDK Resource download location. This zip file contains the files you will need to sign the add-in/configuration on a build server.

4. Build your Pro add-in or configuration. The .esriAddInX, .proConfigX, or .esriPlugin file will be created in your project's output folder. It will not be installed.

Use MSBuild.exe to build ArcGIS Pro Add-ins, Configurations, Plugins and Core Host Applications. Here is the command line syntax to be used to build these Pro SDK projects.

"<Path-to-MSBuild>\MSBuild.exe" "MyAddIn.csproj" -t:rebuild

Add-ins and configurations contain two versions:

• desktopVersion
• version

The versions are stored as attributes on the DAML AddInInfo element:

<AddInInfo id="{43ea84e4-7b44-4d76-80ba-44095ba768b4}" version="1.0" desktopVersion="3.2.49714">
   ...
</AddInInfo>

These attributes are required.

desktopVersion
This is the minimum version of ArcGIS Pro that is required to load a particular add-in or configuration. It is generated when the add-in or configuration Visual Studio project is created. It should not be changed unless you intend to migrate your add-in or configuration to a different version of Pro.

Add-ins and configurations are forwards compatible across all minor versions of ArcGIS Pro. Add-ins and configurations are not forward compatible across major versions (eg 2.x, 3.x, etc). Add-ins and configurations are not backwards compatible across any versions of ArcGIS Pro.

For example:

An add-in was created with a desktopVersion=3.0.xxxx (build number is ignored for desktopVersion). It requires as a minimum, ArcGIS Pro 3.0 to load but can additionally be loaded by ArcGIS Pro 3.1 (and a 3.2, 3.3, etc.). It cannot be loaded by ArcGIS Pro 2.x (no backward compatibility). Note: It could not be loaded by an ArcGIS Pro 4.0 or later when that becomes available (forwards compatible across minor versions only).

An add-in was created with a desktopVersion=2.8.xxxx (build number is ignored for desktopVersion). It requires as a minimum, ArcGIS Pro 2.8 to load. It can also be loaded by ArcGIS Pro 2.9. It cannot be loaded by ArcGIS Pro 2.7 or earlier (no backward compatibility). It cannot be loaded by an ArcGIS Pro 3.0 or later (forwards compatible across minor versions only).

Consult the ProConcepts 3.0 Migration Guide if you need to migrate your 2.x add-in or configuration to 3.0.

version
version is the version of the add-in or configuration and is metadata provided to the add-in or configuration author for their own use. It should be edited by hand as necessary.

If multiple versions of the same Add-in are installed on the same machine (eg in different well-known folders) then the latest add-in version is the version that will be loaded regardless of the order in which the well-known folders and default user folder are processed. Version comparison is evaluated for Major.Minor.Build.Revision components. The order or precedence being from left (Major version component - highest precedence) to right (Revision version component - lowest precedence).

For example:

Assuming no issues with desktopVersion: Two versions of an add-in are installed on a system. One DAML contains version=1.0.3. One DAML contains version=1.1.0.0. The version=1.1.0.0 of the add-in will be the version that loads.

Assuming no issues with desktopVersion: Two versions of an add-in are installed on a system. One DAML contains version=1.4. One DAML contains version=3.0. The version=3.0 of the add-in will be the version that loads.

Plugin data sources contain a Config.xml, not a Config.daml as is the case with add-ins and configurations. Plugins' schema follows 10x addins. They have a <Version.../> element specifying the version of the plugin and a <Target .../> element with a version attribute specifying the minimum version of ArcGIS Pro. An example Config.xml is shown below:

<ESRI.Configuration ...>
  <Name>Example SimplePointPlugin Datasource</Name>
  ...
  <Version>1.0</Version>
  ...
  <Targets>
    <Target name="ArcGISPro" version="3.0" />

Other than that, the rules for versioning of plugins apply the same as described for add-ins and configurations.

ArcGIS Pro framework will detect and load add-ins from "well-known" folders and the logged on user's default folder at start-up. The order of precedence in processing well-known folders and the default folder for add-ins is as follows:

1. Well-known folders declared within the DAML of a Configuration. See Addins Child Elements
2. Admin well-known folders. See HKLM Add-in Folders
3. Current user well-known folders. See HKCU Add-in Folders
4. Default folder

Add-ins within a given well-known folder are loaded in alphabetical order determined by their id. Consult Manage Add-ins in the Pro application help for more information on the add=in manager and well-known folders.

If you are running an ArcGIS Pro Managed Configuration you can define well-known folders for add-ins as part of your configuration DAML definition. Configurations are defined in DAML using a Configuration top-level element. Within the configuration DAML, add an AddIns child element that, in turn, can contain a collection of AdditionalWellKnownFolder elements, 1 per well-known folder. Any well-known folder specified as part of a configuration will be processed before any others (admin, user, default). See ProConcepts Configurations, AdditionalWellKnownFolder for more details.

In the following DAML snippet a managed configuration has been defined that defines one additional well-known folder \\NetworkShare\public\add-ins-config. When ArcGIS Pro runs this particular configuration it will scan its well-known folder first for any add-ins.

<Configuration>
  <ConfigurationManager className="ConfigurationManager1"/>
   <AddIns>
    <AdditionalWellKnownFolder>\\NetworkShare\public\add-ins-config</AdditionalWellKnownFolder>
   </AddIns>
</Configuration>

System administrators can define "Admin" folders by adding the [Add-In Folders] registry key to the HKEY_LOCAL_MACHINE hive. Add a string value, which is the full path to the well-known folder, for each well-known folder you want to add. ArcGIS Pro will search these folders at runtime for add-ins. See HKLM Add-in Folders

For example: This operation adds the following registry key to the HKEY_LOCAL_MACHINE hive

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\ArcGISPro\Settings\Add-In Folders]
"\\NetworkShare\public\add-in-hklm"=""

The folder \\NetworkShare\public\add-in-hklm would be searched before user specified well-known folders but after any well-known folders declared within a (active) configuration.

At the user level, you can define well-known folders via the Add-In manager on the ArcGIS Pro backstage. In the Add-In Manager, click on Options > Add Folder... The folders defined here will be stored under [HKEY_CURRENT_USER\SOFTWARE\ESRI\ArcGISPro\Settings\Add-In Folders] in the registry. ArcGIS Pro will search any user-specified well-known folders at start up after any well-known folders declared within a configuration and any well-known folders specified in HKLM\...\Add-In Folders. See HKCU Add-in Folders.

For example: This operation adds the following registry key to the HKEY_CURRENT_USER hive

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\SOFTWARE\ESRI\ArcGISPro\Settings\Add-In Folders]
"D:\add-in-hkcu"=""

The folder D:\add-in-hkcu would be searched before the default user folder but after any well-known folders declared within a (active) configuration or the HKEY_LOCAL_MACHINE hive.

By default when you install an add-in using the Esri supplied Add-in Installation Utility ("RegisterAddin.exe") or build an add-in within Visual Studio, it gets installed to C:\Users\<userName>\Documents\ArcGIS\AddIns\ArcGISPro. At start-up ArcGIS Pro will always load add-ins from this default location. The default location will be scanned last.

By default when you install a plug-in datasource using the Esri supplied Add-in Installation Utility ("RegisterAddin.exe") or build a plugin datasource within Visual Studio, it gets installed to a versioned ArcGISPro folder. The version corresponds to the installed version of Pro, e.g. C:\Users\<userName>\Documents\ArcGIS\AddIns\ArcGISPro3.3 where "3.3" is the installed version. In addition, because Plugins support forwards compatibility across minor versions (same as addins), previously installed plugins with the same major version and lesser minor version will also be loaded. So, in this example, assuming the installed version of ArcGIS Pro was 3.3, plugins within an ArcGISPro3.0, ArcGISPro3.1, and/or ArcGISPro 3.2 folder would all be loaded (assuming they were not the same plugin). A plugin datasource installed to an ArcGISPro3.4 folder would not.

Plugins follow the same scheme as add-ins with the exception that additional well-known folders for plugins cannot be specified within the DAML of a Configuration.

In certain situations, you may need one add-in to be able to update the UI created by another add-in (eg to add or remove a button to/from a group defined in the another add-in's DAML). In this case, you need the add-in you are updating to be loaded before your add-in (so your DAML can update it), regardless of which well-known folder it is located in.

A <dependency/> element is required to control the add-in loading order and to resolve any "cross-addin" dependencies within the Config.daml. Add a name attribute to the <dependency> element set to the id of the add-in you depend on. The id of an add-in can be found in its Config.daml on the AddinInfo element.

For example:

<ArcGIS ...>
   <AddinInfo ...>
      ...
   </AddinInfo>

   <!--Add-in "A" will include this snippet in its Config.daml-->
   <dependencies>
     <dependency name="{c1a60c8f-2f6f-4198-a5d6-ea964ebf678c}" /> <!-- id of "Add-in B" -->
  </dependencies>

  <modules>

In this case, the given add-in, "Add-in A", will load after its add-in dependency, "Add-in B", regardless of their location within any well-known folders or default folder.

When a configuration is specified on the command line or in the registry, the ArcGIS Pro framework will probe for the configuration in the following order:

1. A well-known folder declared within the Configuration Folders registry key.
2. The default configuration folder: C:\Users\<UserName>\Documents\ArcGIS\AddIns\ArcGISPro\Configurations

Only one configuration can be loaded per session.

Note: Refer to Registry Keys: UsePublicConfigurationFolders for use of UsePublicConfigurationFolders registry key. This alters the probed configuration folder location.

When adding additional ArcGIS Pro Assembly references to your project in Visual Studio, ensure the Copy Local property is either empty or set to No. Setting Copy Local to Yes on ArcGIS Pro Assembly references can cause the ArcGIS Pro application to crash if it encounters mis-matched (older versions of) assemblies in the addin Assembly Cache.

In loading your addin assemblies, ArcGIS Pro uses the AssemblyLoadContext: System.Runtime.Loader.AssemblyLoadContext.Default for .NET. AssemblyLoadContext.Default is documented here.

If an assembly or dependency cannot be resolved by the AssemblyLoadContext.Default resolver, Pro will probe the following locations, in order:

1. The ArcGIS Pro bin folder
2. The add-in, configuration, or plugin install folder
3. The add-in, configuration, or plugin assembly cache folder*

*3rd party assembly references are added to the .esriAddinX, .proConfigX, or .esriPlugin archive respectively within an archive folder called "Install" during compilation. Additional dlls (e.g. native dlls) can also be added to the Install folder by adding them into the project as content at the root level with Build Action None and "Copy to Output Directory" set to either "Copy always" or "Copy if newer".

At runtime, the archive's Install folder contents (i.e. the dlls and whatever else has been added there) are copied to the ArcGIS Pro assembly cache. The assembly cache is updated by the Pro Framework on start-up whenever the date of an archive being loaded is more recent than the date of its corresponding assembly cache folder.

Each archive's Install content is copied to a subfolder within the AssemblyCache named with the GUID id of its parent add-in, configuration, or plugin. When the archive is loaded, 3rd party assemblies in its assembly cache are also loaded (on demand, when types within them are referenced).

The Assembly cache is located at C:\Users\<user_name>\AppData\Local\ESRI\ArcGISPro\AssemblyCache folder but is hidden by default (within Windows Explorer). Change your folder view settings to see the AssemblyCache directory (uncheck 'Hide protected operating system files' in Folder Options). Note: plugins are deployed to a versioned ArcGIS Pro assembly cache folder. So, for example, at ArcGIS Pro 3.0, plugin assemblies would be copied to C:\Users\<user_name>\AppData\Local\ESRI\ArcGISPro3.0\AssemblyCache, at 3.1 C:\Users\<user_name>\AppData\Local\ESRI\ArcGISPro3.1\AssemblyCache, and so forth.

**.NET does not support the GAC. The GAC is supported for .NET Framework applications only.

Obfuscation helps to protect the intellectual property contained in .NET applications. Obfuscation tools rearrange code blocks to complicate decompiling. They also might encrypt strings that contain sensitive data. ArcGIS Pro add-ins and configurations can be obfuscated using any 3rd party obfuscating tools. However there are certain guidelines to follow while obfuscating the add-ins and configurations so that you do not encounter run-time issues.

All classes that derive from ArcGIS.Desktop.Framework.Contracts should not be obfuscated. This includes the Module, ConfigurationManager, Button, Dockpane classes as well as all Plugin template classes in your add-in. UserControls in your add-in that serves as the View in the Framework's MVVM should also not be obfuscated. This includes the XAML user controls and the code behind class for UI elements such as Dockpane, Pane, Property Sheet, etc in the add-in.

To display an End user license agreement (EULA) when an Add-in or a Configuration is being installed add your EULA information to the add-in as a EULA.rtf file. The file must be an rtf. It must be named "EULA". Include the EULA file at the root of the add-in .csproj or .vbproj project file. Set the Build Content property of the Eula.rtf to Content.

When the add-in is installed using RegisterAddin.exe (as opposed to simply copying it) the EULA file will be extracted from the Add-In metadata and displayed in the Esri ArcGIS Add-In installation utility dialog. The end user will have to click the "I agree" check box in order to enable the "Install Add-In" button and proceed with your installation.

If localized Eula files are included in your add-in, the Add-In installation utility will display the localized version of the EULA. The localized Eula displayed will match ArcGIS Pro's language setting. So, for example, if ArcGIS Pro is set to the French language, Eula.fr.rtf will be displayed in the installation dialog.

In order to display a localized EULA, the localized EULA files must follow the specific naming convention shown below:

Pro framework filters for particular keypress combinations that are made within the application that can have global shortcuts assigned to them. Starting at Pro 3.3, you can turn off/block Pro's global shortcut filtering using the BlockShortcuts attached property within your dockpane .xaml declaration. Consult the ProGuide Dockpanes Bypassing Pro Shortcut Key Filtering on Dockpanes topic for more information.