You are here

Customizing ArcGIS Pro with WPF,
Part 1: Configurations

Customizing ArcGIS Pro

Esri’s new Utility Network structure is bringing some big changes to the ways we think about GIS. This includes tons of new features and tools in ArcGIS Pro that let you get a handle on utilities like never before. Not least of these features is the switch to the use of Windows Presentation Foundation (WPF) to customize all sorts of menus and settings in Pro. WPF offers huge extensibility and workability gains over its predecessor, Windows Forms, and Esri provides an entire framework for customizing ArcGIS Pro with WPF. Esri calls this a Configuration. This configuration model lets users customize everything from the toolbar ribbons to the splash screen, allowing you to bring a completely tailored, streamlined, and efficient product to your workflow. 

If you caught the SSP Productivity demo at GeoConX, then you’ve already had a taste of what Pro can offer. SSP Productivity offers a streamlined start page and a fully customized SSP ribbon to make common workflows easy and convenient. Over the course of this article series, we’re going to walk through some of the steps required to build your own configuration for ArcGIS Pro, including a splash screen, start page, and basic dockpane. 

A Couple Notes Before We Start 

  • WPF (especially in ArcGIS Pro) is generally built with the MVVM design pattern in mind. This eliminates the clutter of using a code-behind in views, and allows for further de-coupling of the designer’s work and the engineer’s work. For the sake of this article series, we’ll occasionally break slightly from this convention, and I’ll note the reasons for doing so as we go.
  • You’ll need a copy of Visual Studio 2015 and the Utility Network SDKs to get started. You can find Visual Studio Community edition here, and the SDKs can be found in VS’s extensions library (Tools → Extensions and Updates…) pictured below. These will need to match the version of Utility Network in ArcGIS Pro you have installed (as of this writing, this is version 2.1). Older versions can be found on the Utility Network  SDK site.

Customizing ArcGIS Pro

If that’s all done, then let’s get started!

First Steps for Customizing ArcGIS Pro with WPF

The first thing to do is to create a new configuration project. Open up Visual Studio, click “New Project…”, and search for “ArcGIS Pro Managed configuration.” This can also be found under

Installed → Templates → Visual C# → ArcGIS → ArcGIS Pro Add-ins.

Give the project an appropriate name and location, and click OK. Visual Studio will bring you into your new project. This template already includes complete basic functionality, so let’s take a quick tour of the project. There are several files to be mindful of, and understanding each of their functions is crucial to building the app.

Config.daml

This is likely the file Visual Studio popped in front of you when you loaded the project. This config file defines the tools and controls that we’ll be adding to ArcGIS Pro. Note the <ConfigurationManager …> tags. These define the class that in turn defines the custom UI. Removing this definition will run Pro without any custom startup, but will still load the tools defined in <module>. The <module …> tag defines the toolset that will be built to add to pro. Configurations and Add-ins are treated separately and install using different assemblies, so they have separate definitions in the .daml. For now, we can leave this file alone. We’ll come back later to add a tool to our module.

ConfigurationManager1.cs

This file is created at the top level of the project hierarchy, and it is the core controller for the configuration. This file contains methods that define the behavior of all the custom UI. In most projects, I recommend changing the file and class names to be more descriptive. If you do so, remember to update the definition in Config.daml to reflect your new name. Note that this class inherits from ConfigurationManager. This class provides all the overrides needed to define our custom UI, and includes methods to intercept module DAML code and rewrite it before ArcGIS Pro loads that module. This is a handy feature that can be used to customize toolsets based on user authentication or environment settings. Let’s walk through some of the members of ConfigurationManager:

  • ApplicationName – customizes the application name of Pro, as seen along the top of the window. This defaults to your project’s name.
  • Icon – customizes the favicon of Pro. This defaults to a provided icon found in Images/favicon.ico in your project.
  • OnShowStartPage() – this method is called before Pro is fully started up, and provides the logic to build a custom Start Page. The template method loads a basic custom ViewModel, creates a new page (view), then sets the DataContext of the view to that ViewModel. This DataContext binding is an important piece of the WPF puzzle. The View declares bindings for the UI that pull information and logic from the ViewModel. After those are built, OnShowStartPage() returns the new View. We’ll customize these two pieces later to build a custom Start Page, but we can leave those be for now. If you want to use the default Pro Start Page, simply return null from this method, and Pro will load its default settings. 
  • OnApplicationInitializing() – this method is called after ArcGIS Pro has loaded Portal libraries and some core desktop functionality. This is handy for portal authentication or for loading certain components that need to be active before the Start Page is shown.
  • OnApplicationReady() – this method is called immediately before the Start Page is shown. Calls to the Pro worker threads are safe to call at this point, and other extension modules can be accessed from here.
  • OnShowSplashScreen() – this is where the custom splash screen is loaded. This method is structured just like OnShowStartScreen(), except only a basic view is loaded by default. Splash screens need very little logic, and rarely use a ViewModel, but one can be loaded here as needed.
  • OnOverrideAboutPage() – this method is used to override a small section of the About page in ArcGIS Pro’s backstage. You can use this for some custom branding, or maybe some information about how to use your configuration and tools. 

UI/StartPage.xaml

Here we see our first example of a WPF design. When you open it, Visual Studio will give you a split view of the design and of the .xaml that drives it. This file in particular has a lot of complex ideas behind it, but on a high-level you’ll notice it follows principles of any high-level markup language, like HTML. We’ll break down parts of this file later, as it has some handy pieces we can re-use for our own Start Page. Note: If you look at the end of the topmost UserControl tag (line 13) you can see that the View itself can set the DataContext to its ViewModel. This is useful if you don’t have a way to instantiate your view in the first place.

StartPageViewModel.cs

This file represents all the data and logic for the StartPage view. The template project has given us a small collection of custom behavior for 

  • ProProjects – this property returns a list of project files, and is used to populate the recent projects tab in the View
  • SelectedProjectFile – this property binds to the selection list in the View, and allows the business logic to know which project is selected without needing to call the UI code directly. When this property is changed (via a mouse click, for instance) the property setter is called. This can also be set programmatically, and when the setter is called, the SetProperty() call will notify any UI that the value was updated.
  • OpenProjectCommand – this property binds button behavior to double-click in the View. Commands tend to be associated with UI events like button clicks.
  • OpenSelectedProject – like above, this command will find the selected project and open it. It binds to a button in the View.

Module1.cs

This class allows us to programmatically find a reference to the custom module that this project loads. If your tool requires logic when it closes, you can pause the application close using CanUnload() here. 

On a high level, that’s all the important items to point out on our tour through this project. We just need to make one last stop.

Launching your Configuration 

Right-click on your project in Solution Explorer, and navigate to the Debug options. Under Command line arguments, you’ll see: 

/config:<your_project_name>

This is the flag that tells ArcGIS Pro to load your configuration. You can remove this flag if you ever want to test Pro without the config attached. This also comes in handy if you want to make a shortcut to ArcGIS Pro and include your configuration. Keep in mind, this command will only search the folders you have configured within ArcGIS Pro’s settings. Pro adds the following path by default, and this is where your project will build the assembly to launch the configuration.

C:\Users\Public\Documents\ArcGIS\ArcGISPro\Configurations 

In Conclusion...

That’s most of the hot-points for the tour of Pro’s configuration template. As you might guess, there are a lot of places where you can extend functionality and develop custom UI. In Part 2 we’ll dig much deeper into WPF and build out a custom splash screen to include in our project. 

Further Reading

ArcGIS Pro SDK Wiki
ProConcepts: Configuration
ProGuide: Configuration

Author Information

Add new comment