ProConcepts Configurations

Uma Harano edited this page Jun 26, 2018 · 4 revisions

About 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 <arcgisprosdk@esri.com>
Organization:  Esri, http://www.esri.com
Date:          6/7/2018
ArcGIS Pro:    2.2  
Visual Studio: 2015, 2017

In this topic

Overview

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.

Structure

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

Compilation

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

ManagedConfiguration

Runtime

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.

Installation

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.

install-configx

DAML Schema

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>

Configuration Element

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-ribbon.png

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

Configuration Child Elements

ConfigurationManager Element

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>

Addins Element

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

AddIns Child Elements

AdditionalWellKnownFolder

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.

Configuration Manager

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();

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

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.

  1. Pre-initializing Callbacks
    • OnShowSplashScreen
    • RuntimeDamlFile
  2. Initializing Callbacks
    • OnApplicationInitializing
    • OnCreateDaml
    • ApplicationName
    • OnUpdateDatabase
    • Icon
    • OnValidateLicense
    • OnShowStartPage
      --- the application window becomes visible here ---
  3. Ready Callbacks
    • OnApplicationReady
      --- your start page is shown ---
    • OnShowAboutPage (not ordered*)
    • OnCanExecuteCommand (not ordered*)
    • OnExecuteCommand (not ordered*)

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

Pre-initializing

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)

OnShowSplashScreen

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.

custom-splash

RuntimeDamlFile

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.

Initializing

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.Core to include QueuedTask.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.

OnApplicationInitializing

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.

OnCreateDaml

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

ApplicationName

Override this property to specify the name for the application title bar.

OnUpdateDatabase

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.

Icon

Override this property to customize the application icon in the application title bar

OnValidateLicense

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.

OnShowStartPage

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.

Ready

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.

OnApplicationReady

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.

OnShowAboutPage

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.

about-page

Refer to ProGuide Configurations Manager for an example.

OnCanExecuteCommand

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.

OnExecuteCommand

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.

Subscribing to Application Events

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

Home

Developing with ArcGIS Pro


Framework

    Add-ins

    Configurations

    Customization

    Styling


Content


CoreHost


DataReviewer


Editing


Geodatabase


Geometry

    Relational Operations


Geoprocessing


Layouts


Map Authoring


Map Exploration

    Map Tools


Raster


Sharing


Tasks


Utility Network


Workflow Manager


Reference

    2.0 Migration

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.