ProConcepts Configurations
An ArcGIS Pro configuration is similar to add-ins but offers additional ways to extend the application. It can help you design a version of ArcGIS Pro that more closely reflects your organization’s brand and workflows.
Language: C# and Visual Basic
Subject: Framework
Contributor: ArcGIS Pro SDK Team <[email protected]>
Organization: Esri, http://www.esri.com
Date: 6/06/2019
ArcGIS Pro: 2.4
Visual Studio: 2017, 2019
In this topic
- Overview
- Structure
- Compilation
- Runtime
- Installation
- DAML Schema
- Configuration Manager
Managed Configurations are a higher-level of customization than an Add-in. Whereas the customizations of an Add-in are restricted to ArcGIS Pro UI enhancements primarily, configuration customizations can go much deeper. Configurations can raise the add-in security level and add non-admin specified well-known folders. Configurations can provide more extensive customizations than Add-ins as well as runtime modifications to the DAML - perhaps based on logged on user role.
Only one configuration (i.e. solution) can be run per session of ArcGIS Pro though multiple configurations can be installed to an individual machine. This is different from add-ins where multiple add-ins can be both installed and loaded per session.
Some of the key things you can do with configurations include:
- Make a custom splash screen and a custom start page
- Change the application title and icon
- Rearrange or remove infrequently-used controls; insert new controls
- Inject logic during startup to check licensing or alter the user interface depending on user roles
- Control which add-ins load
- Filter commands (command notification and the option to disable them ).
A configuration can also expose new functionality like modules, buttons, and dock panes, exactly like an add-in.
A configuration is a zip archive file with extension .proConfigX and an internal structure identical to an add-in. It (and an add-in) is composed of a number of parts including:
- A DAML (Desktop Architecture Markup Language) file that describes the configuration as well as its customizations
- Compiled code (for the configuration manager and its associated module)
- Images
- Resources
- Any 3rd party assemblies
The ArcGIS Pro SDK Managed Configuration project template generates a configuration project including DAML and configuration manger and module class files. Build the project to generate the configuration archive file (eg ProConfiguration1.proConfigX) and install it to the default well-known folder (C:\Users\<UserName>\Documents\ArcGIS\AddIns\ArcGISPro\Configurations). For the most part, a configuration's DAML is authored using the same set of ArcGIS Pro SDK item templates used for Add-ins (for instance to add a button, map tool, dockpane, etc. to the configuration).
Configurations are singletons. Although any number of configurations can be installed on a single system, only one configuration can ever be active. A configuration is activated by specifying it on the ArcGISPro.exe command line with the /config:{Configuration_name} command-line option. For example: C:\ArcGIS\bin\ArcGISPro.exe /config:Acme will start ArcGISPro with the Acme.proConfigX configuration active.
Typically, you create a desktop short-cut per configuration you wish to run. Each shortcut contains the relevant /config:{Configuration_name} argument to make launching the different configurations trivial; this also allows you to easily jump between different configurations and the default application simply by starting Pro with a different desktop shortcut.
A configuration can also be specified in the registry. When the registry is used, the configuration named in the registry is always run for every session of Pro. The registry overrides any configuration specified on the command line. Consult ArcGIS Pro Registry Keys, ConfigurationName and ArcGIS Pro Registry Keys, Configuration Folders for more details.
Configurations use the same installation pattern as add-ins. Double-click the .proConfigX file to run "RegisterAddin.exe". "RegisterAddin.exe" validates the configuration and copies it to the configurations' well-known folder: C:\Users\<UserName>\Documents\ArcGIS\AddIns\ArcGISPro\Configurations. Users are given an opportunity to review the author, description, version, and digital signature information of the configuration before proceeding. If a configuration has the same name as an existing configuration installed to the same folder (default folder or well-known folder), the existing configuration will be overwritten.
Configurations are declared in Config.daml within a <Configuration ...></Configuration> section specified as a child of the root <ArcGIS ...></ArcGIS> element.
<ArcGIS defaultAssembly="ProConfiguration1.dll"
defaultNamespace="ProConfiguration1"
xmlns="http://schemas.esri.com/DADF/Registry"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.esri.com/DADF/Registry file:///C:/arcgis/bin/ArcGIS.Desktop.Framework.xsd">
<AddInInfo ...>
...
</AddInInfo>
<Configuration blockCustomizeDialog="false" blockPerfMeter="true" checkForUpdatesAtStartup="false">
<ConfigurationManager className="ConfigurationManager1"/>
<AddIns securityLevel="1">
<AdditionalWellKnownFolder>\\NetworkShare\public\add-ins</AdditionalWellKnownFolder>
</AddIns>
</Configuration>
There can only be on Configuration element per DAML. The Configuration element has three optional attributes: blockCustomizeDialog, blockPerfMeter, and checkForUpdatesAtStartup
blockCustomizeDialog Default value: false
When set to true, the blockCustomizeDialog attribute removes the “Customize the Ribbon” option from the ArcGIS Pro options property sheet. This blocks all user level customizations made from the ‘Customize the Ribbon’ page in the ‘Options’ property sheet.
"Customize the Ribbon" will be removed when blockCustomizeDialog="true".
blockPerfMeter Default value: false
When set to true, the blockPerfMeter attribute blocks users from being able to start the ArcGIS Monitor.
CheckForUpdatesAtStartup Default value: true
When set to false, the checkForUpdatesAtStartup attribute prevents ArcGIS Pro from checking for updates when the application starts.
The ConfigurationManger element is required. This class provides several, optional, extensibility points to help create your configuration. The extensibility points are implemented as callbacks which are overridden in your derived ConfigurationManager class.
The ConfigurationManger element has a single required attribute className.
className Default value: none
Specifies the ConfigurationManager class. The ConfigurationManager class must derive from the ArcGIS.Desktop.Framework.Contracts.ConfigurationManager contract class.
<Configuration>
<ConfigurationManager className="ConfigurationManager1"/>
</Configuration>The Addins element can be used to specify an add-in security level or raise the existing add-in security levels* and add additional admin well-known folders.
securityLevel Default value: 0
The securityLevel attribute can be set with an integer value from 0 to 5 specifying the add-in security level. These levels are identical to the BlockAddins add-in security levels that can be set in the registry.
*BlockAddins security levels (both HKLM and HKCU) can only be raised by a configuration. They cannot be lowered. A securityLevel value lower than a BlockAddin security level is ignored.
<Configuration>
<ConfigurationManager className="ConfigurationManager1"/>
<AddIns securityLevel="1"/>
</Configuration>Sets the add-in security level to 1 (signed add-ins only).
Default value: none
Provides the full path to a local folder or network share that will be treated as an admin add-in folder. Zero or more AdditionalWellKnownFolder child elements may be specified. AdditionalWellKnownFolders are probed for add-ins before any other folders (whether specified in the registry or otherwise).
<Configuration>
<ConfigurationManager className="ConfigurationManager1"/>
<AddIns>
<AdditionalWellKnownFolder>\\AddInShare\Public\Add-Ins</AdditionalWellKnownFolder>
<AdditionalWellKnownFolder>C:\Data\Common\Add-Ins</AdditionalWellKnownFolder>
</AddIns>
</Configuration>
Adds the folders \\AddInShare\Public\Add-Ins and C:\Data\Common\Add-Ins to the list of admin add-in folders.
All configurations must implement a configuration manager class that derives from ArcGIS.Desktop.Framework.Contracts.ConfigurationManager. ConfigurationManager callbacks are optional. Override only those ones for which you want to override that aspect of ArcGIS Pro. By default, the SDK Managed Configuration template generates a configuration manager class for you that implements default overrides for the application name, icon, start page, splash screen, and about page content callbacks.
Configurations are instantiated very early on in the startup sequence of Pro. The active configuration is loaded before any other module (Core or otherwise). Many of the configuration callbacks are executed before the host WPF application has been constructed and the underlying window and background threads of ArcGIS Pro have been started. This means that implementing configurations imposes rigid constraints on developers when executing custom code in callbacks during the Pro startup sequence relevant to the underlying application state.
Failure to follow these constraints will crash the Pro application. Correct handling of the callbacks is described in the following sections.
//The ConfigurationManager contract
public class ArcGIS.Desktop.Framework.Contracts.ConfigurationManager {
//Gets the new application name
protected internal virtual string ApplicationName { get; }
//Gets the new application icon
protected internal virtual ImageSource Icon { get; }
//Gets a replacement DAML file at run-time.
protected internal virtual string RuntimeDamlFile { get; }
//Called when the application is initializing. Denotes it is now safe to
//communicate with Portal at this time. The DAML records have not been processed
//at this point.
//
//cancelEventArgs: false signals a problem has occurred. The application will shut down.
protected internal virtual void OnApplicationInitializing(CancelEventArgs cancelEventArgs);
//Called when the application has fully initialized.
protected internal virtual void OnApplicationReady();
//CommandFilter - gives a configuration the ability to disable commands.
//
//cmdID: The DAML ID of the command about to execute.
//moduleID: The command's parent module DAML ID.
protected internal virtual bool OnCanExecuteCommand(string cmdID, string moduleID);
//Opportunity for the configuration to provide DAML at run-time.
//
// Returns: The DAML to process in the form on an XML string.
protected internal virtual string OnCreateDaml();
//Opportunity for the configuration to provide a list of commands to show in the
//quick access toolbar. It occurs after the start page has been closed and the first
//project is opening.
//
// Returns: A list of commands to be used on the QAT
protected internal virtual List<Tuple<string, bool>> OnCreateQuickAccessToolbar();
//CommandFilter - gives a configuration the ability to reject a command's execution
//cmdID: The DAML ID of the executing command.
//moduleID: The command's parent module DAML ID.
protected internal virtual bool OnExecuteCommand(string cmdID, string moduleID);
// Allows the configuration to inject some custom user interface into the about page.
//
// Returns: The element to add to the about page.
protected internal virtual FrameworkElement OnShowAboutPage();
//The custom splash screen for the configuration.
//
// Returns: The custom window to show during startup.
protected internal virtual Window OnShowSplashScreen();
//The custom start page (landing page) to show once the application starts.
//
// Returns: The start page
protected internal virtual FrameworkElement OnShowStartPage();
//The last chance for the configuration to manipulate the DAML before it is processed.
//
//database: The entire merged DAML database.
//
//Remarks:
// A configuration may find it necessary to edit the raw database to achieve a desired
// look. For example, a configuration may want to delete all the tabs in the system
// except for its own. This is the raw DAML database in XML form, edit with extreme caution.
protected internal virtual void OnUpdateDatabase(XDocument database);
//License validation
//
//Remarks:
// Gives the configuration the chance to perform its own license checking. Returning
// false signals a licensing problem has occurred. The application will shut down.
protected internal virtual bool OnValidateLicense();
}Configuration callbacks fall into three categories relevant to the ArcGIS Pro application state: Pre-initializing, Initializing, and Ready. In the pre-initializing state no Pro API modules are loaded and there is no UI. Within initializing, the Pro WPF application is created and any portal or online connections are initialized. Finally, during ready, the application is fully loaded. The application state only goes forward. Once the application transitions to the ready state it stays in the ready state for the duration of the session.
The configuration callbacks are listed below in the exact order in which they are called. With the exception of OnShowAboutPage, OnCanExecuteCommand, and OnExecuteCommand, callbacks are called only once per session (with one exception - refer to Options Reset).
- Pre-initializing Callbacks
- OnShowSplashScreen
- RuntimeDamlFile
- Initializing Callbacks
- OnApplicationInitializing
- OnCreateDaml
- ApplicationName
- OnUpdateDatabase
- Icon
- OnValidateLicense
- OnShowStartPage
--- the application window becomes visible here ---
- Ready Callbacks
- OnApplicationReady
--- your start page is shown --- - OnCreateQuickAccessToolbar()
- OnShowAboutPage (not ordered*)
- OnCanExecuteCommand (not ordered*)
- OnExecuteCommand (not ordered*)
- OnApplicationReady
*occurs in response to a UI event. May be invoked multiple times per session.
The transition between the three application states is demarcated by two callbacks: OnApplicationInitializing and OnApplicationReady. OnApplicationInitializing marks the transition from Pre-initializing to Initializing. OnApplicationReady marks the transition from Initializing to Ready.
The only thing you should really do in pre-initializing is provide a splash screen (if you choose to override the default). You are very early in the Pro lifecycle at this stage. The Pro WPF application has not been started yet so making any calls that assume there is a functioning UI thread (eg showing a message box) will crash the application. As none of the Pro extension assemblies have been loaded yet, making any Pro API calls during pre-initialization will crash the application.
During pre-initializating do:
- Show a custom splash screen
During Pre-initializing, do not:
- Call any Pro API method to include
QueuedTask.Run - Access any Pro WPF resource (style, brush, color, icon, image)
- Subscribe to any Pro events (this includes in your ConfigurationManager constructor)
- Make any WPF call that depends on a UI thread (eg
Dispatcher.Invoke) - Show any custom UI (eg Message Boxes)
Override this function to display a custom splash screen on startup. The splash screen should be a borderless WPF window. The ArcGIS Pro SDK Configuration template adds a splash screen window to your Configuration that can be customized. If a null Window is returned Pro’s default splash screen is displayed.
Override this function if you want your configuration’s DAML to come from a different XML file (than the default Config.daml). DAML returned from RunTimeDamlFile superseeds any DAML read from the default Config.daml (it is a replace, not a "combine"). If you want to supply DAML content based on logic that requires the Pro API you should use OnCreateDAML instead.
Within Initializing, the configuration typically has two tasks:
- Perform any modifications to the Pro UI based on configuration workflows, permissions, roles, etc.
- Provide a start page to initiate the Pro session. Your start page is shown only once.
Initializing begins with the OnApplicationInitializing callback. Initializing is the first time you get access to the Pro API but it is still limited. You can safely call EsriHttpClient, ArcGISPortalManager, and ArcGISPortal in the API but that's about it. You can use the OnApplicationInitializing callback as a convenient location to consolidate your code for accessing portal and online. For example, if your configuration needs to access portal content or portal settings, roles, etc. to influence the configuration of the upcoming Pro session.
None of the other aspects of Pro are instantiated during Initializing (there are no maps, layers, projects, etc. in existence at this time) and there is still no parent WPF application though it will be created during Initializing and shown immediately after the OnShowStartPage callback. The Pro main background thread or "MCT" has not been started yet either so QueuedTask should not be used to wrap any portal calls or this will crash the app. As you are not on the UI thread during Initializing, calls to the portal API classes in any of the Initializing callbacks can be made safely without being wrapped in a QueuedTask.Run.
In general, no custom UI should be shown during Pro Initializing as it can hang the app. There are some exceptions, for example: you require a login be made to a resource (database, website, etc.) and failure to login requires your configuration to terminate the app (Similarly, the underlying Pro licensing and portal classes can trigger an OAuth popup during startup whenever authentication is required). You can show your UI during Initializing as long as it does not use Pro WPF resources in the xaml.
The OnShowStartPage is the last callback within Initializing. After the start page callback returns the application continues to load, shows the main WPF window, completes the loading of the API extensions, starts the MCT, and concludes by showing your start page if you provided one. Your start page is actually shown in the Pro Ready state even though it was requested during Initializing. Because your start page is shown during Ready, it is safe to use Pro WPF styles, brushes, and colors and you can safely access any Pro API method in your start page logic. However, as the UI thread has now started, the normal rules of QueuedTask usage apply. Be aware that when accessing the Pro API in your start page, many classes and properties that you normally expect to be instantiated when coding typical add-in logic will still be null.
If you provide a start page then your start page takes responsibility for initiating the Pro session. Start the session either by creating a new project or opening an existing one. You do not have to close the start page. That happens automatically when the session is started. Your start page is only shown once at the initiation of the Pro session.
During Initializing do:
- Call portal or online using the Pro API (without using the QueuedTask)
- Provide custom DAML (if needed)
- Modify the DAML database (if needed)
- Provide a custom start page if you want custom logic and UI for initiating the Pro session
- Use Pro WPF styles, etc. within your start page
- Call any Pro API aspect in your start page logic (using the QueuedTask when required)
During Initializing, do not:
- Call any Pro API method not in
ArcGIS.Desktop.Coreto includeQueuedTask.Run. - Attempt to access any plugins, panes, dockpanes, or any UI element, or other modules.
- Subscribe to any Pro events
- Access any Pro WPF resource (style, brush, color, icon, image) except in your start page.
- Make any WPF call that depends on a UI thread (eg
Dispatcher.Invoke). - Show any custom UI
Failure to follow these constraints will crash the application.
*See Subscribing to Application Events for how to subscribe to Pro events in a configuration prior to application Ready.
*The startup page is safe to show.
*A custom login UI or similar is appropriate as needed. Do not use Pro WPF resources.
This function is the first opportunity the ConfigurationManager has to call into a few parts of the application the most important of which is the API for Online and Portal communication. This callback is also passed a CancelEventArgs and if its Cancel property is set to true the application will immediately shutdown.
Override this function to provide DAML in the form of an XML string at run-time. For example, if you’ve determined previously in OnApplicationInitializing that the current user has the role of Editor versus Manager (eg via a query to portal or online), and this role requires different DAML be provided. DAML provided via OnCreateDaml will superseed any DAML previously read from the Configuration (with the exception of the Configuration DAML element itself - that cannot be changed after the fact).
Override this property to specify the name for the application title bar. Application name can be called more than once.
During startup, all of the DAML files from Pro (bin\Extensions), detected add-ins, and the configuration, are merged into one DAML database (XML). That XML database is passed as the parameter to this function. You can modify the final merged database in OnUpdateDatabase before it is processed to define the Pro UI. As an example, the following implementation of OnUpdateDatabase deletes all of the tabs from the Pro Ribbon except those of the configuration.
protected override void OnUpdateDatabase(XDocument database) {
var nsp = database.Root.Name.Namespace;
// select all elements that are tabs
var tabElements = from seg in database.Root.Descendants(nsp + "tab") select seg;
// collect all elements that need to be removed
var elements = new HashSet<XElement>();
foreach (var tabElement in tabElements)
{
// skip root and backstage elements
if (tabElement.Parent == null
|| tabElement.Parent.Name.LocalName.StartsWith("backstage"))
continue;
var id = tabElement.Attribute("id");
if (id == null || id.Value.StartsWith("MyConfiguration")) continue;//Skip our tabs - "MyConfiguration"
elements.Add(tabElement);
}
// remove the elements
foreach (var element in elements)
{
element.Remove();
}
}Refer to ProGuide Configurations for a more in-depth example.
Override this property to customize the application icon in the application title bar. Icon can be called more than once.
This callback gives the configuration a chance to perform its own license checking at start-up. Return false to signal a licensing problem has occurred. Returning false will terminate the application startup and the application will shut down.
The custom startup page (landing page) to show once the application is ready. If a null FrameworkElement is returned Pro’s default startup page is displayed. The startup page can safely reference ArcGIS Pro resources in its xaml.
Refer to ProGuide Configurations for an example.
Note: Your start page is requested during Initializing and shown in Ready.
Users can customize the appearance of the application via the (project) Options property page accessible from the Pro Backstage (use <Configuration blockCustomizeDialog="false" ...> to prevent ribbon customization). If users change the ribbon or Quick Access Toolbar, QAT, or reset customizations on the ribbon or QAT they have previously made (during the session on the options dialog) then the application re-initializes the ribbon and/or QAT resulting in your OnApplicationInitializing, OnCreateDaml and OnUpdateDatabase callbacks being called as well as the application name and icon. This allows your configuration to respond to customization changes made via the application UI once it is already up and running and re-apply any modifications, etc.
Application State
When the application is completely initialized and the startup page (whether custom or default) is shown, the application is said to be ready. The ready state begins with the OnApplicationReady callback. It is now safe to access the entire system.
During Ready state there are no restrictions.
Note: just because it is safe to call a Pro API aspect does not mean, necessarily, that many properties or classes will not be null. For example, if a project has not been opened yet the Project.Current and MapView.Active properties will be null even though they can now be safely accessed.
Called after the application has fully initialized. This is called right after the ArcGIS.Desktop.Framework.Events.ApplicationReadyEvent and right before the ArcGIS.Desktop.Framework.Events.ApplicationStartupEvent are published. Both events represent, for all intents and purposes, the same thing as OnApplicationReady.
Called after the application has closed the start page and is opening the first project of the session. Use the OnCreateQuickAccessToolbar to overwrite the default configuration of the application Quick Access Toolbar. The purpose of the OnCreateQuickAccessToolbar is to provide an initial configuration of the QAT. The configuration of the QAT that your Configuration Manager provides via the callback is persisted to a C:\Users\username\AppData\Local\ESRI\{ApplicationName}Settings.xml file by the application after the first time the configuration has been run.
After the configuration has been run the first time, the Pro application _will use the persisted {ApplicationName}Settings.xml file for the QAT configuration for subsequent sessions running under your Configuration Manager (not its OnCreateQuickAccessToolbar callback even though it will still be called). Changes made to the QAT via the options dialog (by users) on the Pro backstage will be saved to that settings file (so they can be re-applied the next time the Pro application is started under your Configuration Manager).
For example, given the following OnCreateQuickAccessToolbar implementation:
protected override List<Tuple<string, bool>> OnCreateQuickAccessToolbar()
{
List<Tuple<string, bool>> cmds = new List<Tuple<string, bool>>();
//set the second argument "true" ("ischecked") to add to the QAT toolbar otherwise the
//command will only show on the QAT pulldown menu.
Tuple<string, bool> item1 = new Tuple<string, bool>("esri_mapping_clearSelectionButton", true);
Tuple<string, bool> item2 = new Tuple<string, bool>("esri_core_newProjectButton", true);
Tuple<string, bool> item3 = new Tuple<string, bool>("esri_core_saveProjectButton", true);
Tuple<string, bool> item4 = new Tuple<string, bool>("esri_core_undoSplitButton", true);
cmds.Add(item1);
cmds.Add(item2);
cmds.Add(item3);
cmds.Add(item4);
return cmds;
}The QAT will be as shown:
The application will persist the following {ApplicationName}Settings.xml file to be used on subsequent sessions (using the given Configuration Manager):
<?xml version="1.0" encoding="utf-8"?>
<ArcGIS>
<QAT>
<Commands>esri_mapping_clearSelectionButton;esri_core_newProjectButton;esri_core_saveProjectButton;esri_core_undoSplitButton;</Commands>
<Position>1</Position>
<IsRibbonCollapsed>False</IsRibbonCollapsed>
</QAT>
</ArcGIS>Resetting the QAT configuration on the (project) Options will reset the QAT to the QAT configuration persisted in the {ApplicationName}Settings.xml file for the given Configuration Manager.
Return a user control that will add "about" information into the application’s About page. This callback is invoked each time the Pro about page tab is accessed. The ArcGIS Pro SDK Managed Configuration template adds a user control to your Configuration that can be customized to provide your about page information.
Refer to ProGuide Configurations for an example.
OnCanExecuteCommand and OnExecuteCommand callbacks act as a command filter. Command filters can be implemented to prevent execution of relevant commands. The OnCanExecuteCommand callback is passed the DAML ID of the command and its parent module each time the user "mouses over" an underlying command button on the Ribbon. OnCanExecuteCommand can return false to disable the given command. A false value will override the underlying enabled state of the command. Returning true is the default return value which does not modify the underlying enable/disable state of the command. Therefore if the command was enabled, it remains enabled. If the command was disabled then it remains disabled.
This callback is passed the DAML ID of the command and its parent module prior to each OnClick event. Return false to prevent execution of the command (OnClick is not executed). Return true to allow execution to proceed.
Note: Add-ins can implement a limited form of the command filter pattern. Consult the Command Filter community sample.
Do not attempt to subscribe to any ArcGIS Pro events in any of the ConfigurationManager callbacks or constructor prior to application Ready. If you need to subscribe to early events like ArcGIS.Desktop.Framework.Events.ApplicationReadyEvent and ArcGIS.Desktop.Framework.Events.ApplicationStartupEvent subscribe to them in your configuration module class in its overriden Initialize method and set autoLoad="true" in the DAML.
internal class Module1 : Module {
protected override bool Initialize() {
//Immediately preceeds OnApplicationReady callback
ArcGIS.Desktop.Framework.Events.ApplicationReadyEvent.Subscribe((a) => {
Debug.WriteLine("ApplicationReadyEvent");
});
//Immediately follows OnApplicationReady callback
ArcGIS.Desktop.Framework.Events.ApplicationStartupEvent.Subscribe((a) => {
Debug.WriteLine("ApplicationStartupEvent");
});
return true;
}and in the Config.daml:
<modules>
<insertModule id="..." className="Module1" autoLoad="true" ...> 