ProConcepts Advanced Topics

Language:              C# and Visual Basic
Subject:               Framework 
Contributor:           ArcGIS Pro SDK Team <[email protected]>  
Organization:          Esri, http://www.esri.com  
Date:                  11/6/2017  
ArcGIS Pro:            2.1  
Visual Studio:         2015  , 2017
.NET Target Framework: 4.6.1  

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

• Configure build server to build add-ins and configurations
• Add-in 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
  • Control order of loading using DAML
• Configuration loading scheme
• Loading 3rd Party Assembly References
• Obfuscation

---

Configure build server to build add-ins and configurations

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.

To configure your build server without installing ArcGIS Pro, 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 depends upon to a C:\Program Files\ArcGIS\Pro\bin folder and C:\Program Files\ArcGIS\Pro\bin\Extensions folder on your build server respectively.

An add-in/configuration out of the box created using the Pro SDK templates requires the following assemblies to compile:

C:\Program Files\ArcGIS\Pro\bin\ArcGIS.Core.dll
C:\Program Files\ArcGIS\Pro\bin\ArcGIS.Desktop.Shared.Wpf.dll
C:\Program Files\ArcGIS\Pro\bin\ArcGIS.Desktop.Framework.dll
C:\Program Files\ArcGIS\Pro\bin\Extensions\Catalog\ArcGIS.Desktop.Catalog.dll
C:\Program Files\ArcGIS\Pro\bin\Extensions\Core\ArcGIS.Desktop.Core.dll
C:\Program Files\ArcGIS\Pro\bin\Extensions\DesktopExtensions\ArcGIS.Desktop.Extensions.dll
C:\Program Files\ArcGIS\Pro\bin\Extensions\Editing\ArcGIS.Desktop.Editing.dll
C:\Program Files\ArcGIS\Pro\bin\Extensions\Layout\ArcGIS.Desktop.Layouts.dll
C:\Program Files\ArcGIS\Pro\bin\Extensions\Mapping\ArcGIS.Desktop.Mapping.dll

Add-in/configurations 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

1. Copy C:\Program Files\ArcGIS\Pro\bin\Esri.ProApp.SDK.Desktop.targets and C:\Program Files\ArcGIS\Pro\bin\proapp-sdk-MSBuild.dll 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.

1. Modify the add-in/configuration .csproj or .vbproj file to change the custom "PackageAction":

• Find the element called <PackageAction>BuildDefault</PackageAction> in the .csproj or .vbproj file.
• Change its value from BuildDefault to BuildZipPostProcess.
• Save the project file and reload the project.

Before

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
  <PackageAction>BuildDefault</PackageAction>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
  <PackageAction>BuildDefault</PackageAction>
</PropertyGroup>

After

 <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
  <PackageAction>BuildZipPostProcess</PackageAction>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
  <PackageAction>BuildZipPostProcess</PackageAction>
</PropertyGroup>

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

Add-in Versioning

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="1.4.6116">
   ...
</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=1.2.xxxx (build number is ignored for desktopVersion). It requires as a minimum, ArcGIS Pro 1.2 to load but can additionally be loaded by ArcGIS Pro 1.3 and ArcGIS Pro 1.4 (and a 1.5, 1.6, etc.). It cannot be loaded by ArcGIS Pro 1.1 (no backward compatibility). It cannot be loaded by an ArcGIS Pro 2.0 or later (forwards compatible across minor versions only).

An add-in was created with a desktopVersion=1.4.xxxx (build number is ignored for desktopVersion). It requires as a minimum, ArcGIS Pro 1.4 to load but could additionally be loaded by a ArcGIS Pro 1.5, 1.6, etc. It cannot be loaded by ArcGIS Pro 1.3 or earlier (no backward compatibility). It cannot be loaded by an ArcGIS Pro 2.0 or later (forwards compatible across minor versions only).

Consult ProConcepts 2.0 Migration Guide, Migration Procedure if you need to migrate your 1.x add-in or configuration to 2.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.

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.

Add-in Loading Scheme

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.

1. Configurations defined 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>

2. Admin well-known folders

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.

3. Current User well-known folders

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.

4. Default folder

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.

Control order of loading using DAML

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.

To control the order of add-in loading, relative to your add-in, add a <dependencies> DAML element to your Config.daml with a <dependency name="..."> child element per add-in your add-in is dependent on. 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.

Configurations Loading Scheme

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 ConfigurationFolder registry key.
2. The default configuration folder: C:\Users\Public\Documents\ArcGIS\ArcGISPro\Configurations

Only one configuration can be loaded per session.

Loading 3rd Party Assembly References

In certain cases, your Add-in or Configuration may need to reference 3rd party assemblies for added functionality. This may be to integrate additional UI controls (such as Telerik), Nugets, utility libraries, etc. Pro probes the following locations, in order, when attempting to resolve references within your Add-in or Configuration:

1. The Add-in or Configuration assembly (default)
2. The ArcGIS Pro bin folder
3. The Add-in or Configuration install folder
4. The Add-in or Configuration assembly cache folder*
5. The GAC**

*3rd party assembly references are added to the .esriAddinX archive or .proConfigX archive respectively within a folder called "Install" during compilation. At runtime, the archive's Install folder contents along with the Add-in or Configuration dll are copied to the ArcGIS Pro assembly cache. The assembly cache is updated by Pro Framework on start-up whenever the date of an Add-in or Configuration 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 or Configuration. When an Add-in or Configuration 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).

**The GAC is probed for strong named assemblies only.

Obfuscation

Obfuscation helps to protect the intellectual property contained in .NET Framework 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 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.