ProGuide Configurations

Language:      C#
Subject:       Framework
Contributor:   ArcGIS Pro SDK Team <arcgisprosdk@esri.com>
Organization:  Esri, http://www.esri.com
Date:          10/02/2023
ArcGIS Pro:    3.2
Visual Studio: 2022

An ArcGIS Pro Managed Configuration is an advanced customization pattern for the application. Configurations are similar to add-ins except they have several additional opportunities to configure and extend the application. This ProGuide is split into two parts:

1. Using Managed Configurations for Organizational Branding
2. Using Configurations to Customize the User Interface and Functionality

Please refer to the ProConcepts: Configurations for more detailed information.

In this ProGuide

• Using Configurations for Organizational Branding
• Using Configurations to Customize the User Interface and Functionality

Using Configurations for Organizational Branding

In order to demonstrate organizational branding we create a new Configuration using the Pro SDK's Managed Configuration template. Organizational branding in the context of Managed Configurations means that I can customize user interface elements like application icons, splash screen, startup screen, and about page to reflect my organization's brand. This section demonstrates how to customize these UI elements.

Step 1: Create a new Configuration using the Managed Configurations template

Open Visual Studio, select File | New | Project, drill down to Installed | Templates | Visual C# | ArcGIS | ArcGIS Pro Add-ins | ArcGIS Pro Managed Configuration. Name the solution "MyConfiguration".

Step 2: Debugging a Configuration project

In Visual Studio build the project and open the properties page of the MyConfiguration project, select the Debug tab. Note that the ArcGISPro.exe is run using the /config:{configuration name} ArcGIS Pro command line parameter.

The Managed Configuration template adds the correct command line parameter to your project automatically. When the project is built, a configuration package with a .ProConfigX file extension is installed to the default location for configurations: C:\Users\<Username>\Documents\ArcGIS\AddIns\ArcGISPro\Configurations.

Note: If you change the name of your configuration in the project you must also change the name of the configuration in the command line switch on the Debug tab.

To debug, set breakpoints as normal and click 'start' to run the configuration (ensuring your active Visual Studio configuration is Active (Debug)).

Step 3: Overriding the Splash Screen

Open "ConfigurationManager1.cs". Scroll to the OnShowSplashScreen override method. The Managed Configurations template will have added a default implementation of a splash screen window for you in "SplashScreen.xaml" that you can customize (or delete the callback or return null to retain the stock splash screen).

Step 4: Overriding the Startup Page

Open "ConfigurationManager1.cs". Scroll to the OnShowStartPage override method. The Managed Configurations template adds a default implementation of a startup page for you in "StartPage.xaml" that you can customize (or delete the callback or return null to retain the stock startup page). Configurations use the Model-View-ViewModel, MVVM, pattern so the startup page view also has a companion view model: "StartPageViewModel.cs". It is your responsibility to initialize the startup page datacontext with the view model for purposes of binding as shown here:

	if (_vm == null)
	{
	  _vm = new StartPageViewModel();
	}
	var page = new StartPage();
	page.DataContext = _vm;//Initialize the datacontext
	return page;

Your startup page is automatically closed when an ArcGIS Pro project file is opened. You do not have to close it:

	if (dlg.ShowDialog() ?? false)
	{
	  var item = dlg.Items.FirstOrDefault();
	  if (item != null)
	  {
	    Project.OpenAsync(item.Path);//Automatically closes the startup page
	  }
	}

To see a variety of startup page implementations please refer to following community sample:

ConfigWithStartWizard community sample code

A number of UI controls are provided in the API to help you create a custom start page providing a similar look and feel to the standard Pro start page. See SignOn control, Recent Projects control and Recent Templates control for more information.

*The Open project and New project backstage tabs should also be replaced to ensure a consistent user experience. These are separate views from the start up page. Delete the existing backstage tabs via standard DAML (i.e. <deleteTab .... />) and add custom Open and New Project tabs to your Configuration using the "ArcGIS Pro Backstage Tab" template.

Step 5: Overriding the Application Icon

Open "ConfigurationManager1.cs". Scroll to the Icon and override it. By default, it shows the "favico.ico" that comes with the "new Configuration" template. The icon in the title bar is changed (it will revert back to the Pro icon though when the configuration is not run) but the icon in the Windows task bar is not changed. The task bar always shows the Pro icon. Changing the Icon is optional. Delete the property to use the Pro application default icon.

The Application Icon on Startup

The Application Icon with a Project Open

Note: Use the full pack URI format as shown below. Set the icon file's build action to "Resource" in your Visual Studio project:

protected override ImageSource Icon
{
    get
    {
        return new BitmapImage(
             new Uri(
               @"pack://application:,,,/MyConfiguration;component/Images/favicon.ico"));
    }
}

Step 6: Overriding the About Page

Open "ConfigurationManager1.cs". Scroll to the OnShowAboutPage override method. Optionally override this method to return a System.Windows.FrameworkElement (usually a User Control) that is hosted within the Pro about tab. The Managed Configurations template adds a default implementation of about page content for you in "AboutPage.xaml" that you can customize (or delete the callback to leave the stock about page unchanged).

Using Configurations to Customize the User Interface and Functionality

We will use the MyConfiguration solution we created in the previous steps for Organizational Branding. A reference implementation is also provided with the following community sample:

ConfigWithMap community sample code

Step 1: Customizing the UI of MyConfiguration

Open the MyConfiguration solution we built in the previous section. Click the Start button in Visual Studio to start a debug session. Note the default ArcGIS Pro Ribbon is unchanged (assuming other add-ins are not installed on your system).

Close ArcGIS Pro and stop debugging.

Step 2: Delete All the Tabs on the Ribbon

Note: To examine the complete DAML for each session of ArcGIS Pro add the following command line option /dumpcombineddaml to ArcGISPro.exe:

ArcGISPro.exe /config:MyConfiguration /dumpcombineddaml

Open "ConfigurationManager1.cs". Within ConfigurationManager1, add an override for the OnUpdateDatabase method:

#region Override DAML Database

protected override void OnUpdateDatabase(XDocument database)
{
}

#endregion

Notice that OnUpdateDatabase override method takes a single parameter XDocument database. During startup, all of the DAML files from Pro (bin\Extensions), detected add-ins, and the configuration, are merged into a single DAML database (i.e. XML) (this database can be examined using the previously mentioned /dumpcombineddaml command line option). We are going to add code in our OnUpdateDatabase callback to remove all the tab elements on the Ribbon. Use extreme caution when editing this XML in your configurations. It defines the entire application UI.

The code snippet below collects all the tab elements from the XML database into a HashSet and then removes them. Insert this snippet into your OnUpdateDatabase override method.

using System.Xml.Linq;
...
...
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");
     //Add your own id prefix here to skip deleting your own tabs
     if (id == null) continue;
     elements.Add(tabElement);
   }
   // remove the elements
   foreach (var element in elements)
   {
     element.Remove();
   }
}

Step 3: Add Custom Tabs

We are going to add some custom controls and tabs to the Pro UI. Right click on the MyConfiguration project and select Add | New Item from the project context menu. Add an ArcGIS Pro Button to the configuration (select Visual C# Items | ArcGIS | ArcGIS Pro Add-ins | ArcGIS Pro Button). Name the button "TestUserInterface".

Open the newly added "TestUserInterface.cs" file. Add a MessageBox.Show("test"); line to its OnClick method.

Edit the project's "Config.daml" file. Add a new tab to the Config.daml. Ensure it contains a reference to the MyConfiguration_Group1 group:

<tabs>
  <tab id="MyConfiguration_Tab1" caption="Test UI Tab" keytip="Z0">
    <group refID="MyConfiguration_Group1"/>
  </tab>
</tabs>

Change appearsOnAddInTab="true" to appearsOnAddInTab="false" on the <group ...> element. We do not want to show the Add-ins tab on the Ribbon:

<groups>
  <group id="MyConfiguration_Group1" caption="Group 1" appearsOnAddInTab="false">
    <button refID="MyConfiguration_TestUserInterface" size="large" />
  </group>
</groups>

Next, we want to exclude our newly added tab from our removal code in our OnUpdateDatabase override. Notice the //Add your own id prefix here to skip deleting your own tabs comment in the OnUpdateDatabase override. Replace the existing if (id == null) continue; expression with if (id == null || id.Value.StartsWith("MyConfiguration")) continue; to skip our own tab element. Note: Change ...StartsWith("MyConfiguration") to be whatever is your own tab id prefix if it is different:

protected override void OnUpdateDatabase(XDocument database)
{
   ...
   foreach (var tabElement in tabElements)
   {
      ...
      //Add your own id prefix here to skip deleting your own tabs
      if (id == null || id.Value.StartsWith("MyConfiguration")) continue;//Skip our tabs

Save your changes and Build the project. Run the application from Visual Studio. Open a project. Verify that you see your "Test UI Tab" displayed on the Ribbon. Verify that all of Pros other standard tabs have been deleted from the ribbon. Click your custom TestUserInterface button. Your message box should be displayed.

We have now changed the ArcGIS Pro user interface and functionality using a Managed Configuration. You can download the complete sample from ConfigWithMap community sample code