ProConcepts Migrating to ArcGIS Pro
This document is an overview of approaches, best practices, and implementation considerations for migrating ArcMap customizations to ArcGIS Pro, using the ArcGIS Pro SDK for Microsoft .NET.
Language: C# and Visual Basic
Subject: Framework
Contributor: ArcGIS Pro SDK Team <arcgisprosdk@esri.com>
Organization: Esri, http://www.esri.com
Date: 5/16/2018
ArcGIS Pro: 2.2
Visual Studio: 2015, 2017
This document covers common, high-level approaches for migrating traditional desktop customizations for developers and managers who are new to the ArcGIS Pro SDK and are approaching initial strategy, architecture and application design decisions.
The ArcGIS Pro SDK is released along with each new release of ArcGIS Pro. The Pro SDK is based on the add-in extensibility pattern, first introduced with ArcGIS 10.0, and leverages modern Microsoft .NET features and patterns. These customizations known as "add-ins" are packaged within a single, compressed, zip file which can be easily shared and installed. Add-ins are flexible, and can provide for different levels of customization which tailor ArcGIS Pro for specific users’ needs, such as providing a new set of custom Pro tools for a complex editing workflow, or a custom spatial analysis processing routine.
This document is divided into four sections:
-
Customization Patterns – The common patterns for customizing ArcGIS Pro. This includes approaches and considerations such as when to use an add-in or a solution configuration.
-
Programming Patterns – The main patterns used when programming with the Pro SDK, such as WPF, MVVM, and asynchronous programming.
-
Learning ArcGIS Pro – Tips and resources for learning ArcGIS Pro, as having a good understanding of Pro and its new capabilities is essential for your customization work.
-
Learning the ArcGIS Pro SDK – Tips and resources for learning the Pro SDK, with suggestions on the key concepts to focus on when getting started.
When approaching ArcGIS Pro customization, it’s helpful to consider the level of extensibility you need. The following are three approaches to extending ArcGIS Pro, listed from lowest to highest complexity:
-
Configure UI through settings, and workflows through Tasks. This low complexity approach works best when the functionality you need is covered by existing Pro tools and capabilities, and you want to organize your Pro project and workflow. In this case you may just need to make some modifications to the UI, such as in customizing the Pro ribbon. You can also use Pro Tasks, which allow you to configure repeatable workflows and embed Pro's out of the box tools, geoprocessing tools, and your own geoprocessing models.
-
Automate using geoprocessing and Python. The next approach, is the creation of geoprocessing models with ModelBuilder, and the development of Python scripts using ArcPy. With this approach, you can create powerful, repeatable scripts for the automating of common tasks and operations.
-
Extend with your own custom tools and solutions using the Pro SDK. The most advanced approach is development of your own add-ins with the Pro SDK. Using Microsoft Visual Studio and .NET, it’s possible to develop sophisticated Pro add-ins which integrate your tools and workflows directly into the Pro UI to provide a seamless user experience. Also, developers can build solution configurations, a more advanced form of add-in, which can provide users with a custom start-up experience tailored for your organization or industry.
In evaluating these options, there are some implementation trade-offs with each. For example, the lower-complexity "Configure" option will leverage core, out-of-the-box tools with some configuration steps, such as using Tasks. This approach can be easier and faster to implement and maintain. Sometimes, using a set of core, out of the box tools configured in a set of steps within a task may be all you require. From a project standpoint, this approach usually is the easiest (of the three) to implement and maintain. No programming or development time is required and future upgrades of Pro will not require rework as there are no custom code changes to consider.
Also, configuration may be a simple way for a small team to get started quickly, confirm if the workflow steps and information products are indeed required for the solution, and then later consider improvements. However, if your workflow is used frequently, or involves a large number of complex steps, it may become somewhat unwieldy for your users. They may prefer a solution that is more tailored, allowing them to complete their tasks faster, and in a more automated way. This is a good opportunity to consider advancing your approach and automate steps with Python or geoprocessing, or consider developing a custom add-in with the Pro SDK.
Developers, analysts and managers are encouraged to opt for a lean approach which will give users the efficiency and functionality needed for the least amount of development. In some cases, the right option may be a combination of all three approaches. For example, if a single team's project requires a streamlined UI with a data management function, it's possible that simply customizing the Pro ribbon and providing a geoprocessing tool in the Pro favorites as part of a shared project could be a viable approach, rather than the more involved development of an add-in or solution configuration.
Still, when you require new Pro tools which involve interaction with maps, scenes, etc. and go beyond basic configuration and automation, or require customizing the Pro UI, this is when you will need to consider developing an add-in using the Pro SDK. Developing an add-in with the SDK can be an excellent choice for accuracy and productivity. Also, when you want to consistently refine or streamline the Pro UI, and provide new, unique and time-saving capabilities, this is where an add-in can be very beneficial.
There are two customization patterns for Pro add-ins:
-
Traditional add-ins (.esriAddinX file) – which provide extensive Pro customization capabilities
-
Solution Configurations (.proConfigX file) – which provide the capabilities of traditional add-ins, plus additional start-up capabilities for custom branding, UI and user experience.
The development of traditional add-ins are discussed in the ProConcepts Framework document, which introduces foundational concepts for new developers.
Solution Configurations are discussed in detail in the ProConcepts Configurations document, and provide:
-
Solution branding of the Pro UI – you can create a highly customized UI and start-up user experience for Pro, with a custom splash screen, start up page, application icon, and more
-
Conditional / role-based customization – allows you to build logic into the Pro start-up experience and tailor the Pro UI ribbon based on conditions, logins, etc.
-
Add-in capabilities – configurations provide the standard customization capabilities of add-ins
-
Control over add-ins – you can choose how and which add-ins are loaded in Pro
The following screenshot shows an example of a solution configuration, with a streamlined UI and workflow. This is the ConfigWithMap solution configuration community sample which is one of many Pro SDK community samples which are available for developers to build from.
The following is a brief comparison of the capabilities of add-ins and configurations:
-
Similarities
- Built from Pro SDK project templates
- Allow for customization of the Pro UI
- Compiled and deployed with the standard double-click installation
-
Differences
-
Add-in:
- Multiple add-ins allowed per Pro session
-
Configuration:
- One configuration per Pro session
- Custom start-up experience – splash screen and startup page, conditional start-up logic, e.g. user roles, etc.
-
Configurations are intended for developers looking to provide a complete "solution" experience (which may or may not support multiple user roles). It requires a much more extensive amount of customization effort than an add-in. Add-ins are intended for more focused functionality, such as a specific tool or set of tools, a custom UI, or a specific custom workflow.
Although only one solution configuration can be used per Pro session, the same Pro session can include multiple add-ins. This can provide more flexible extensibility options within your Pro sessions. Also, as a solution configuration can define the loading order of add-ins, this allows you another level of control over how those add-ins get used and displayed within the Pro UI.
This brings up the topic of how to implement a solution with multiple add-ins, which you may want to do in order to enhance the capabilities of an existing add-in, or perhaps incrementally release functionality across a set of add-ins. This is described in the ProConcepts Advanced Topics document.
The two main approaches for implementing licensing on your add-ins and solution configurations include:
- Use the Pro SDK for enabling your add-in
- Leverage your existing ArcMap solution licensing process
If you would like to create an add-in licensing procedure specifically for ArcGIS Pro, the following options are available:
- Add-in: Use the IExtensionConfig interface
- Resources: ProGuide: License Your Add-In, and the Licensing Community Sample
- Solution Configuration: Use the OnValidateLicense method of the ConfigurationManager class
If you plan to package and deploy your ArcMap customization with your ArcGIS Pro add-in, and you have already developed a licensing approach for your ArcMap customization, it may be possible to incorporate and leverage this licensing approach for the enabling of your new Pro add-in.
This section will provide general information on some of the key programming patterns which developers use in writing Pro add-ins.
The ArcGIS Pro SDK is built on Microsoft .NET. Development is performed within the Microsoft Visual Studio Integrated Development Environment (IDE). Within Visual Studio, developers create Desktop applications using Windows Presentation Foundation (WPF) which provides key capabilities for modern desktop application development.
The Pro SDK takes advantage of WPF, as well as Model-View-ViewModel (MVVM). These patterns can be seen implemented within the Pro SDK documentation and samples.
MVVM is a popular design pattern for XAML-based development and separates the UI components of your add-in from the data and business logic components. The Pro SDK uses MVVM to implement custom panes, dockpanes, dialogs, property sheets, and embedded controls. The ArcGIS Pro SDK item templates generate much of the required boiler plate code for the MVVM pattern. A good introduction is provided in this Microsoft document, which describes how MVVM makes applications easier to test, maintain, and improves code re-use opportunities. There are other good sources of information on the MVVM pattern on the web, and the ProConcept Framework doc provides some important considerations for the SDK.
Desktop Application Markup Language (DAML) is introduced and discussed in depth in the ProConcepts Framework document. DAML is defined in an add-in project's Config.daml file. It is used to declare the buttons, tools, menus, dockpanes, tabs, etc. that your add-in contains and will be used to customize the Pro UI. Their implementation lives in separate "code-behind" files that are automatically added in to the project by the Pro SDK item templates.
With the Config.daml, you can also develop contextual behavior in the Pro UI using States and Conditions. These are introduced in their own section in the ProConcepts Framework document, and there is a walk-through provided in the ProGuide Code Your Own States and Conditions.
One of the key features of the Pro SDK is asynchronous development. This pattern is still new for many GIS developers. It’s an important place to get started in learning the capabilities of Pro, and how you can keep the UI responsive, building a great user experience.
The best resource is the Working with Multithreading in ArcGIS Pro section of the ProConcepts Framework document. It is important to become familiar with using the QueuedTask class. Most of your custom code will be executed using QueuedTask and will run in the background on Pro's Main CIM Thread (MCT), also called the background/worker thread. Functionality executed using QueuedTask is "queued" and executed sequentially (but still in the background leaving the UI responsive). Whatever is being executed on the QueuedTask must complete before anything else on the QueuedTask can be executed. In other words, your functionality will execute asynchronously but in a predictable, sequential, order which is crucial when coding multi-step workflows.
Microsoft also has a number of resources including this article on asynchronous programming.
The Pro SDK provides a number of styles, brushes, and colors that you can use in your custom UIs. Use the ArcGIS Pro SDK styles on your WPF UI elements to the greatest extent possible to have your add-ins blend in with Pro. Pro styles will automatically flip to the correct color scheme whenever the corresponding light or dark theme of Pro is changed. The resources listed below provide specifics to consider on styling the main WPF controls with Pro styles in a custom UI:
-
ProGuide Style Guide – This ProGuide provides styling considerations for each of the different WPF UI controls.
-
Esri Brushes – This page lists the Esri XAML brushes.
-
Esri Colors – This page lists the Esri XAML colors.
-
ProGuide – Applying Custom Styles – This ProGuide provides a walk-through of custom styling to support both light and dark themes.
-
Custom Styling community sample – This community sample provides a dockpane with a custom Pro user control which has been styled to support both light and dark themes.
As you begin to plan your migration, you'll want to consider how you can take advantage of the capabilities in Pro that can enhance your existing solution (e.g., Tasks, 3D scenes). You should also think about how you might address workflows with core, out-of-the-box functionality where needed. For example, consider how your users will interact with Pro and how the contextual ribbon UI will change the way in which your UIs need to be implemented. Make sure you have a solid understanding of the Pro application before getting too far into the design of your add-in.
To help you get familiar with the new Pro UI elements and terminology, there is a comprehensive set of Pro training, documentation and quick start guide resources:
-
ArcGIS Pro Training Catalog – Choose from the many Pro training courses
-
ArcGIS Pro Resources – Leverage quick-start tutorials and migration guides
-
Migrating to ArcGIS Pro – Find migration information and videos
-
ArcGIS Pro Documentation – Get access to all the documentation
-
ArcGIS Pro Terminology Guide – Learn Pro terminology
-
Esri Press – Find books on learning ArcGIS Pro
When migrating customizations from ArcObjects, your ArcObjects code will need to be rewritten to use the Pro SDK. Here are some general tips for getting started in learning the Pro SDK and your first programming efforts:
-
The Pro SDK documentation, community samples and snippets are written in C#.
-
Your UIs will be written using WPF and XAML, not Windows Forms. The primary pattern to become familiar with is MVVM.
-
The Pro SDK is an asynchronous API. This will be new to many desktop developers. Consult the Microsoft documentation on asynchronous programming and the Pro SDK documentation on the use of QueuedTask.
-
Leverage the Pro SDK community samples for a view of best practices, and integrate the code as needed.
-
Leverage the Pro Concepts, Pro Guides, and Pro Snippets for step-by-step "how to's" as well as code snippets of many common tasks. Tip: Start with the "Framework" topic found on the margin of the SDK wiki page and work your way through these ProConcepts documents first.
-
Use the GeoNet ArcGIS Pro SDK Group for both questions on SDK functionality and best practices as well as requests for new feature functions.
The following is a list of the main Pro SDK learning resources:
-
Pro SDK Documentation - This is the site you are currently on. Consult the Table of Contents, TOC, for many foundational ProConcept and ProGuide documents, code snippets, and resource links.
-
Extending ArcGIS Pro with Add-Ins - This Esri instructor-led course provides a comprehensive introduction to the Pro SDK. Formal training can help you to jumpstart your migration development project.
-
Community Samples – Samples are categorized by Pro functional area – Framework, Content, Editing, Geodatabase, Map Exploration and so on. Also, download the sample dataset for use with the samples. There is a helpful guide on how to begin to use the samples here.
-
Pro SDK Snippets – This is the full listing of code snippets (in this current github wiki) also by Pro functional area.
-
FAQ – Be sure to review the “Migration from 10x” section.
-
GeoNet ArcGIS Pro SDK Group – This is the Pro SDK developer community space on GeoNet. Search for answers to your questions from earlier posts, and post your own questions here.
-
API Reference – The complete ArcGIS Pro API reference.
-
Videos – The recordings of Pro SDK technical sessions at the Esri Developer Summit and User Conference are all available hosted on YouTube at the Esri Events channel.
-
Blog posts – The ArcGIS Blog and GeoNet group above contain helpful updates and resource links.
In general, spending some time getting familiar with each of the above sites can usually help you to find the specific information you need.
If you’re in need of an ArcGIS Pro trial to get started, you can register for a free trial here.
An important opportunity for providing your feedback is after you have conducted a significant prototyping effort with the Pro SDK. Like many of our SDKs, the ArcGIS Pro Team is growing the Pro SDK based upon your input on needs and requirements. Please send your feedback in a post via the ArcGIS Pro SDK Group on GeoNet. You can also contact your Esri account manager to share your feedback.
A final note on the ArcGIS Marketplace where ArcGIS solutions can be found. The site now provides listings of ArcGIS Pro add-ins, and helpful information on becoming a provider. If you are an Esri Partner and are interested in placing your Pro add-in on the ArcGIS Marketplace, contact your Esri partner manager for more information.
