ProConcepts Migrating to ArcGIS Pro - Esri/arcgis-pro-sdk GitHub Wiki

This document provides a brief introduction to development with the ArcGIS Pro SDK and an overview of considerations and resources for developers migrating traditional ArcGIS Desktop customizations to Pro.

    Language:      C#
    Subject:       Framework
    Contributor:   ArcGIS Pro SDK Team <[email protected]>
    Organization:  Esri, http://www.esri.com
    Date:          10/06/2024 
    ArcGIS Pro:    3.4  
    Visual Studio: 2022

• Overview
• Transitioning to ArcGIS Pro
• Customization Options
• Extensibility Patterns
• Programming Patterns
• Learning the Pro SDK

This document provides a brief introduction to development with the ArcGIS Pro SDK for .NET, and an overview of considerations and resources for developers migrating traditional ArcGIS Desktop customizations to Pro.

NOTE: ArcGIS Pro 3.0 includes changes for Pro 2.x add-in code. Consult the ProConcepts 3.0 Migration Guide for more information. For other ArcGIS Pro 2.x project and file migration information, see the Migration from ArcGIS Pro 2.x to 3.0 document.

This document includes the following sections:

• Transitioning to ArcGIS Pro – Links to resources for learning ArcGIS Pro to better understand the many differences from traditional Desktop, before you get started with development.

• Customization Options – A review of the customization options available with ArcGIS Pro.

• Extensibility Patterns – The key Pro SDK extensibility patterns for customizing ArcGIS Pro.

• Programming Patterns – The programming patterns used when programming with the Pro SDK, such as using the Pro APIs, WPF, MVVM, asynchronous programming and related considerations.

• Learning the Pro SDK – Tips and resources for learning the Pro SDK, with suggestions on getting started.

This section includes considerations links to resources for learning ArcGIS Pro to better understand the many differences from traditional Desktop.

As you begin to plan your migration, you'll want to consider how you can take advantage of the many advances and capabilities in Pro that can enhance your existing solution. You may also want to 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. It's helpful to have a good 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 Training Catalog – Explore the many ArcGIS Pro training courses available

• 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

• What's New in ArcGIS Pro - Review new functionality in Pro and the product roadmap

• ArcGIS Pro Terminology Guide – Learn Pro terminology

• Esri Press – Find books on learning ArcGIS Pro

When migrating, it’s helpful to consider the options for customizing Pro in terms of level of effort and complexity. You have three general options or approaches you can take in customizing 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. These types of updates can meet many organizations needs and are easy to manage when upgrading your version of Pro.

• 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. Using GP and Python in Pro is extremely powerful, and it is important to note that many aspects of working with Pro in processes and routines, are only possible via this option. With this said, GP tools and Python scripts can also be integrated with Tasks and larger workflows with the Pro SDK.

• 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 ArcGIS Pro SDK. Using Microsoft Visual Studio and .NET, it’s possible to develop sophisticated Pro customizations integrated directly into the Pro UI to provide a streamlined workflow and user experience. Pro SDK developers can choose from the four Pro extensibility patterns, building on the SDK project templates to develop either an add-in, managed configuration, plugin datasource or CoreHost app. Each of the patterns are discussed in the next section.

In evaluating the above customization options, there are some implementation trade-offs with each. For example, the easier "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, that approach is usually easiest to implement and maintain as no programming or development time is required. Future upgrades of Pro will usually not require rework as there are no custom code changes to consider. Configuration can also 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.

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.

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 should consider extending Pro with 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.

The ArcGIS Pro SDK is based on the add-in extensibility pattern, first introduced with ArcGIS 10.0, and leverages modern .NET features and patterns. There are four Pro extensibility patterns which can be built with the SDK:

• Module Add-in (.esriAddinX file) – provides extensive Pro customization capabilities to build new tools and functionality. These customizations are packaged within a single, compressed, zip file which can be easily shared and installed.

• Managed Configuration (.proConfigX file) – provides all the capabilities of traditional module add-ins, plus additional customization of the Pro UI and user experience.

• Plugin Datasource (.esriPlugin) – a specialized pattern which allows developers to build custom data source integration with Pro.

• CoreHost Application – (.exe) - another specialized pattern which allows developers to build stand-alone WPF and console apps with a subset of the Pro assemblies, for 64-bit geodatabase and geometry access.

We'll now take a look at each of the patterns.

The module add-in is the most popular extensibility pattern as it provides the developer with flexibility and many capabilities. Use the add-in pattern to create new tools and commands with custom functionality which access the Pro APIs, geoprocessing tools, modify the Pro Ribbon by creating custom tabs and add/move/remove tools, and make a workflow in Pro more efficient.

The development of a module add-ins is discussed in the ProConcepts Framework document, where foundational concepts are introduced for new developers. Add-ins are normally intended for more focused functionality, such as a specific tool or set of tools, a specific UI customization or a custom workflow.

Opportunities with add-ins:

• Powerful, and provide most of what your users are looking for
• Developers can customize the UI by building new custom tools, buttons and panes
• Build custom processes with .NET
• Integrate third party libraries

Screenshot of the QA Review Tool SDK Sample

Considerations for using one of the more specialized SDK patterns:

• Do you need full control over Pro's start-up process? >> Explore Managed configurations
• Do you have a data format that you want to use as a layer or table? >> Explore Plugin datasources
• Do you need to run a scheduled geodatabase process? >> Explore CoreHost apps

Managed Configurations are discussed in detail in the ProConcepts Configurations document.

Opportunities with managed configurations:

• 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

Screenshot of the ConfigWithStartWizard SDK Sample

In addition to the above managed configuration sample, the ConfigWithMap configuration sample, provides developers with a view of all of the unique UI/UX capabilities possible with the pattern. You can also consult the ProGuide

Also with configurations, developers can provide a single configuration that support multiple user roles. Although only one managed 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 managed 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. In that document you can also find guidance on controlling the startup of your configuration and different options for handling it such as registry settings or a desktop shortcut.

For a walk-through on creating your first configuration, see the ProGuide Configurations document.

Plugin datasources provide custom data integration with Pro. Developers can use this to bring their own custom dataset into Pro and use them like read-only feature layers or tables. Also, plugin datasources allow developers to integrate data sources like relational databases such as MySQL, non-relational databases and other proprietary and file-based data stores such as image files and GPS data.

Access to your data in Pro is in the form of tables or feature classes, and is read-only. You can interact with the data in standard ways in Pro, although to edit your custom data, you would need to develop your own tools in Pro.

Screenshot of the ProDataReader SDK Sample

For details, see the ProConcepts Plugin Datasources and the ProGuide Plugin Datasource documents.

You can find all the plugin datasource samples here as well.

The last pattern is the CoreHost Application, which allows developers to build standalone console and WPF applications with access to Pro’s Geodatabase and Geometry API functionality. To run these apps, ArcGIS Pro needs to be installed on the machine, but there’s no interaction with the Pro UI required to run and use the .exe application.

As described in the document, it's important to remember that the API access is limited to ArcGIS.Core with its 64-bit access to the Geodatabase and Geometry classes. CoreHost apps can be used for scheduled geodatabase update routines or viewing and updating tables in standalone mode.

Screenshot of the CoreHostGDB SDK Sample

See the ProConcepts CoreHost document for information and resources. You can find all the CoreHost App samples here as well.

For further information on the four patterns -- Explore the ArcGIS Pro SDK Documentation site and the Approaches for Pro Extensibility session, one of the many Dev Summit 2022 Technical Sessions.

This section provides general information on some of the programming patterns used with the Pro SDK and links to resources.

The ArcGIS Pro SDK is built on Microsoft .NET. Development is performed within the Microsoft Visual Studio Integrated Development Environment (IDE) using Windows Presentation Foundation (WPF) which provides capabilities for modern desktop application development. Along with WPF, a best practice pattern used with the SDK is 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 code for the MVVM pattern. A good introduction is provided in this Microsoft document, which describes the benefits. There are other good sources of information on the MVVM pattern on the web, and the ProConcept Framework doc provides important guidance for implementing with 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, tabs and other controls that will be positioned on the Pro ribbon and UI in general. As Pro starts, its UI is updated based on the DAML code from your item templates and other elements you've defined in the Config.daml of your add-in.

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. Coming from traditional Desktop development, this is an important capability and pattern to implement to keep the UI responsive and build a great user experience.

The best resources to get started with are the Working with Multithreading in ArcGIS Pro section of the ProConcepts Framework document, and building on that is the ProConcepts Asynchronous Programming in ArcGIS Pro document.

It is important to become familiar with using the QueuedTask class. Most of your code will be executed using QueuedTask and will run in the background on Pro's Main CIM Thread (MCT), also called the background or worker thread. Functionality executed using QueuedTask is "queued" and executed sequentially 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. 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.

The Esri Cartographic Information Model, or CIM, is a map content specification used to document how information that describes various project components is persisted when saved, read, referenced, or opened. The specification is represented as JSON and is used for maps, scenes, layouts, layers, symbols, and styles in ArcGIS applications and APIs.

A good introduction to using the CIM with the SDK can be found in this Dev Summit technical session with slides and video. Also, an SDK guide that walks through a workflow in getting started working with the CIM is the ProGuide Templates document. Also, the ArcGIS.Core.CIM Namespace in the API Reference provides a list of CIM objects.

Also, see the CIM Resources document for links to other CIM resources.

In some cases, such as productizing an add-in or configuration that you wish to sell, it will be important to consider a licensing approach and manage access to your add-in.

As a Pro add-in developer, you are free to build your own licensing mechanism in .NET, or you can also acquire and integrate third-party .NET licensing components. Many third-party options exist which you can research and choose from.

In terms of migration, if you developed a licensing approach for your traditional Desktop add-in, it is possible that you may be able to leverage that approach for your new Pro add-in.

In terms of implementation, there are two approaches – one for add-ins, and one for configurations.

Module Add-ins: For add-ins, you have API access to control the enabling and disabling of your add-in UI components on the Pro ribbon using the IExtensionConfig interface. The resources for learning include the ProGuide: License Your Add-In document, and the associated Licensing Community Sample.

Managed configurations: For configurations, you have API access to the OnValidateLicense override which gives the configuration a chance to perform a license check at start-up. If the check returns false, this will terminate the application startup and the Pro application will shut down. See the ProConcepts Configurations document for further information.

The following are links to resources in getting started and learning the Pro SDK.

• Documentation - This is the site you are currently on. Consult the Table of Contents along the right-hand margin for the many ProConcept and ProGuide documents, code snippets, and other resource links. Tip: When getting started, review the ProConcepts Framework document first.

• API Reference – The complete ArcGIS Pro API reference.

• Tutorials - The Pro SDK tutorials offer easy, walk-through steps for getting started building add-ins with code samples.

• Code Samples – Use the many ready-to-compile samples to get started and understand best practices. You can also integrate the samples into your own project. Samples are categorized by Pro functional area – Framework, Content, Editing, Geodatabase, etc. following the SDK topic areas seen in the documentation. Also, download the sample data for use with the samples. There is a helpful guide on how to begin to use the samples here.

• Code Snippets – This is the full listing of code snippets by SDK topic area.

• FAQ – Be sure to review the “Migration from 10x” section.

• ArcGIS Pro SDK Group on the Esri Community – This is the Pro SDK developer community space on the Esri Community. Collaborate with the community, post your questions and search by keyword for existing threads from earlier posts which can help guide you to previously answered question threads. You can also post your feedback and requests for new SDK features.

• Videos – Here you can find a series of playlists on the Pro SDK Community with the recordings of technical sessions from past Esri Developer Summits, hosted on YouTube and the Esri Videos channel.

• Blog posts – The ArcGIS Blog and Esri Community group above contain helpful updates and resource links.

The growth of the Pro SDK is driven by user needs and feedback. You can send your feedback in a post via the ArcGIS Pro SDK Group on the Esri Community or post a new idea to the ArcGIS Pro Ideas site using the "SDK" label.

Esri Partners can list their add-in products on the ArcGIS Marketplace. It's also helpful for all Pro users to explore the listing for ideas on available products and opportunities with ArcGIS Pro add-ins built with the SDK.

If you’re in need of an ArcGIS Pro trial to get started, you can register for a free trial here.