ProConcepts Advanced Topics - 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 

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
• 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
  • 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

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

2. 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.

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, DADFLib.dll and zlibwapi.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. 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>

5. 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.

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="2.2.12813">
   ...
</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=2.1.xxxx (build number is ignored for desktopVersion). It requires as a minimum, ArcGIS Pro 2.1 to load but can additionally be loaded by ArcGIS Pro 2.2 (and a 2.3, 2.4, etc.). It cannot be loaded by ArcGIS Pro 2.0 or any ArcGIS Pro 1.x (no backward compatibility). Note: It could not be loaded by an ArcGIS Pro 3.0 or later when that becomes available (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. 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.

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="2.3" />

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.

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.

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.

This is for versions 2.0 and 2.1 only. As of version 2.2+, the use of a <dependency/> element is no longer needed.

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.

In versions 2.0 and 2.1, a <dependency/> element is required to control the add-in loading order. At version 2.2 and later, ArcGIS Pro automatically sequences add-in loading order to resolve any "cross-addin" dependencies within the Config.daml.

At 2.0 and 2.1, to control the order of add-in loading, relative to your add-in, you must 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>

   <!-- Required for ArcGIS Pro 2.0 and 2.1 only -->
   <!--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 you add ArcGIS Pro Assemblies as references to your project in Visual Studio, Visual Studio sets the Copy Local attribute for the assemblies to be True by default (you cannot change this default behavior). You have to change this setting to False after adding the assemblies. If you do not change this setting, the assemblies will be copied to the Assembly Cache when ArcGIS Pro loads your Add-in or Configuration. When you upgrade ArcGIS Pro to a newer version, the application will crash when it encounters mis-matched (older versions) assemblies in the Assembly Cache.

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

1. The add-in, configuration, or plugin assembly (default)
2. The ArcGIS Pro bin folder
3. The add-in, configuration, or plugin install folder
4. The add-in, configuration, or plugin assembly cache folder*
5. The GAC**

*3rd party assembly references are added to the .esriAddinX, .proConfigX, or .esriPlugin archive respectively within a folder called "Install" during compilation. At runtime, the archive's Install folder contents (i.e. the dlls) 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 2.3, plugin assemblies would be copied to C:\Users\<user_name>\AppData\Local\ESRI\ArcGISPro2.3\AssemblyCache, at 2.4 C:\Users\<user_name>\AppData\Local\ESRI\ArcGISPro2.4\AssemblyCache, and so forth.

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

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 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 AddInContent.

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: