Wolf KaiserUma Harano

ArcGIS Pro SDK for .NET:Beginning Pro Customization Showing Pro Extensibility Patterns of the SDK

Session Overview

• The Pro SDK supports Two Main Extensibility patterns- ArcGIS Pro Module Add-ins - ArcGIS Pro Managed Configurations

• Declarative Markup for Pro UI Elements: DAML- How to change the ArcGIS Pro UI with your Add-in

• New (in 2.4+) Pro SDK Extensibility patterns- ArcGIS Pro CoreHost Application- ArcGIS Pro Plugin (Datasource)

What is the ArcGIS Pro SDK for .NET?

• ArcGIS Pro SDK for .NET extends ArcGIS Pro using .NET• Extensibility patterns provided by Pro SDK:

- ArcGIS Pro Module Add-ins - ArcGIS Pro Managed Configurations- ArcGIS Pro CoreHost Application- ArcGIS Pro Plug-in Datasource (new in Pro 2.3)

• Includes Visual Studio item templates for most UI elements• Installation is integrated with Visual Studio Marketplace• ArcGIS Pro API comes with ArcGIS Pro out-of-box

- File based references (No Global Assembly Cache)

What is the ArcGIS Pro SDK for .NET?

• Noteworthy ArcGIS Pro SDK features and patterns- 64-bit platform- .NET Framework 4.8 at ArcGIS Pro release 2.5- UI based on WPF (Windows Presentation Foundation) - MVVM pattern (Model-View-ViewModel)- Asynchronous Patterns: Multiple threads

What is an ArcGIS Pro add-in ?

• Extends ArcGIS Pro through:- Buttons- Tools- Dockpanes- Embeddable control- ..

• Packaged within a single, compressed file with an .esriaddinX file extension

- c:%Homepath%\Documents\ArcGIS\AddIns\ArcGISPro

What are the ArcGIS Pro Add-in core components?

• Declarative-based framework to define the UI elements - Declarative framework is defined in a config.daml file- XML formatted, contains ArcGIS Pro framework elements (buttons,

dockpane, galleries) and Add-in UI elements• The Module class

- Hub and central access point for each add-in- Similar to the Extension object used in the ArcObjects 10.x

framework- Singletons instantiated automatically by the Framework

<ArcGIS defaultAssembly="WorkingWithDAML.dll" defaultNamespace="WorkingWithDAML"xmlns="http://schemas.esri.com/DADF/Registry"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://schemas.esri.com/DADF/Registryfile:///C:/Program%20Files/ArcGIS/Pro/bin/ArcGIS.Desktop.Framework.xsd"><AddInInfo id="{c6226a24-d69b-46c6-b5e7-9eee4ddad45d}" version="1.0" desktopVersion="1.1.2850">

…</AddInInfo><modules>

<insertModule id="WorkingWithDAML" className="Module1" autoLoad="false" caption="Module1"><tabGroups>

<!--The new Tab Group is created here--><tabGroup caption="Example State Solution" id="working_with_DAML_ExampleStateTabGroup"><color A="255" R="238" G="170" B="90" /><borderColor A="0" R="251" G="226" B="195" />

</tabGroup></tabGroups>

Declarative Markup for Pro UI Elements: DAML• Add-Ins use “Declarative Markup” (DAML) language for UI Elements

- Buttons, Dockpane, Galleries, Property Sheets, Tools, …

• DAML uses XML Syntax - stored in a Config.daml file• Using DAML, you can add, modify, delete any User Interface element • Pro also uses DAML: <Install Location>\bin\Extensions folder

Declarative Markup for Pro UI Elements: DAML• DAML is transactional and is processed in the order the Pro Extension or Add-in is

loaded- 3 distinct actions: Insert, Update, and Delete- The type of action is determined by the element name: updateModule, updateGroup,

deleteButton

<updateModule refID="esri_mapping"><groups>

<updateGroup refID="esri_mapping_navigateGroup"><deleteButton refID="esri_mapping_bookmarksNavigateGallery“ /><insertButton refID="working_with_DAML_ToggleStateButton" />

</updateGroup></groups>

</updateModule>

In the DAML transactional model the ‘last’ transaction wins !

Declarative Markup for Pro UI Elements: DAML

• Example: Update ArcGIS Pro Map and Layer Context menus with a new button.…<updateModule refID="esri_mapping">

<menus><updateMenu refID="esri_mapping_layerContextMenu">

<!--Note: New Button will show up in the Layer's Context menu--><insertButton refID="WorkingWithDAML_ToggleLegend" placeWith="esri_mapping_selectedLayerSymbologyButton" />

</updateMenu><updateMenu refID="esri_mapping_mapContextMenu"><!--Note: New Button will show up in the Map's Context menu --><insertButton refID="WorkingWithDAML_ToggleLegend"

placeWith="esri_mapping_addDataButton" /></updateMenu>

</menus></updateModule> …

How to use DAML to change the UI of other Add-ins or existing Pro UI

• Ensuring the proper DAML processing order• If your Add-in changes another Add-in or a Pro Extension

- Use the Dependencies tag in your DAML- Add-in Example that changes another Add-in (using the “other” Add-in’s AddInInfo

tag’s id attribute as identifier)

<dependencies><dependency name="{c1a60c8f-2f6f-4198-a5d6-ea964ebf678c}" />

</dependencies>

How to use existing Pro UI elements in Your Add-in

• Use any existing ArcGIS Pro framework elements on your Add-in tab including Buttons, Tools, Galleries

• Find the element ID of any existing ArcGIS Pro Control and use the ID in your config.daml markup to add, delete, modify that element

• Example: Add Pro’s Navigate Bookmarks button to my Add-in toolbar- button tag references existing element ID:

esri_mapping_bookmarksNavigateGallery

<group id="HookingCommands_Group1" caption="Hooking Commands" keytip="G1"><button refID="esri_mapping_bookmarksNavigateGallery" />

</group>

How to find existing ArcGIS Pro Element Ids

• SDK Help: ArcGIS Pro DAML ID Referencehttps://github.com/Esri/arcgis-pro-sdk/wiki/ArcGIS-Pro-DAML-ID-Reference

• Pro Generate DAML Ids tool in Visual Studio- Allows Intellisense to find IDs:

i.e. DAML.Button.esri_mapping_addDataButton

• ArcGIS Pro ‘Customize the Ribbon’: Show IDs option

Demo: Add-in and DAML

What is an ArcGIS Pro Managed Configuration?

• Includes all functionality of an add-in plus- Change the application title and icon- Change the application splash, start page, and about page- Optionally customize and streamline the UI (the Pro Ribbon) for a specific workflow

• Packaged within a single, compressed file with a .ProConfigX file extension- c:%Homepath%\Documents\ArcGIS\AddIns\ArcGISPro\Configurations

Default start page Custom start page

What is an ArcGIS Pro Managed Configuration?(Continued)

• Running an ArcGIS Pro Managed Configuration- Use the ArcGIS Pro “/config” command-line option

- Only one configuration can run per instance of Pro

• ConfigurationManager class - Defined in DAML (generated automatically by the template)- Provides a set of methods by which a developer can override “that” aspect of Pro

public abstract class ConfigurationManager {protected internal virtual Window OnShowSplashScreen();protected internal virtual FrameworkElement OnShowStartPage();protected internal virtual FrameworkElement OnShowAboutPage();...

C:\ArcGIS\bin\ArcGISPro.exe /config:Acme

Demo: Configurations

What is an ArcGIS Pro CoreHost Application?

• Stand-alone application with a subset of Pro Assemblies- ArcGIS.CoreHost assembly – API to manage CoreHost functions- ArcGIS.Core assembly – Includes Geodatabase and Geometry

classes• CoreHost Applications have 64-bit access to

- Geodatabase and - Geometry classes used by ArcGIS Pro

• CoreHost Applications can be - Windows Console application - WPF application

How to create an ArcGIS Pro CoreHost Application

• CoreHost Project Template for Console 64 bit application (optional WPF standalone application)

• Uses COM single-threaded apartment (STA) threading model • ArcGIS Pro has to be installed & licensed• Call Host.Initialize ()

C:\Data\Admin\AdminData.gdb

Demo: CoreHost Sample App

What is an ArcGIS Pro Plugin DataSource?

• ArcGIS Pro supports spatial and tabular data from many data sources and formats:- File based data such as Shape File, File Geodatabase, etc.- Relational databases like Oracle, SQL Server, IBM DB2, etc.- Web based services like ArcGIS Server, OGC Web services

• But many other formats are not supported• The “ArcGIS Pro Plugin DataSource” extensibility pattern is used to

integrate those unsupported formats like:- Unsupported relational databases such as MySQL- Non-relational databases such as MongoDB- Many other proprietary or obscure file-based data stores or web services

What is an ArcGIS Pro Plugin DataSource?

• With the Plugin Datasource framework you can:- Show custom data as a feature class or as a standalone table

- In essence features and rows are supported- Consume any format and data source (file, database, web)

• Plugin Datasource limitations- Access in Pro is read-only- Access is in form of tables or feature classes- Access starts file based:

- My custom data source is a file or a folder- My ‘connection file’ to my custom datasource is a file

Providing a plugin datasource for your custom data

• Basic high-level data access objects in ArcGIS Pro- Connector defines a connection to a data source

- Used to create or open a datastore- Datastore is a specific instance of a data source

- Used to open one or more tables or feature classes- Tables or Feature classes contain data rows

- Can be queried and return a cursor- Cursors can be used to iterate through data rows (or features)

Implementing plugin datasource for your custom data

• The ‘ArcGIS Pro Plugin’ Project Template stubs out all code for you• Creates three concrete classes that inherit from these API classes

- PluginDatasourceTemplate- Used to manage one or more tables or feature classes

- PluginTableTemplate- Can be queried and return a cursor

- PluginCursorTemplate- Data Rows are returned by iterating using a cursor

• Update config.daml to register your Plugin Datasource with ArcGIS Pro

<ArcGISPro><PluginDatasources>

<PluginDatasource id="ProSqlPluginDatasource" class="ProSqlPluginDatasourceTemplate" /></PluginDatasources>

</ArcGISPro>

Demo: Plugin DataSourceTemplate

Examples of Custom data source used in the upcoming demos

• Jpg photos with GPS metadata- Smart phone and digital cameras have the option to capture GPS

information when a photo is taken• Gpx File data

- GPX (the GPS eXchange Format) is a data format for exchanging GPS data between programs and implemented by many GPS tracking devices

• SQL Server Express- An example of a free relational database that contains data copied

from classic personal geodatabases

SQL Server Express – custom data source

• Contains data copied from a classic personal geodatabases

• Copy all tables and feature classes• And GDB_GeomColumns, GDB_Items,

GDB_SpatialRefs

Using a custom plugin datasource in ArcGIS Pro• Define a connection to a data source instance

- Use PluginDatasourceConnectionPath with the PluginDataSource name and the path to the data source file

• Use the connection to create a datastore to your data source instance• Use the datastore to access tables and feature classes

var conSql = new PluginDatasourceConnectionPath("ProSqlExpressPluginDatasource", filePathUri);QueuedTask.Run(() =>{

using (var pluginSql = new PluginDatastore(conSql)){foreach (var tableName in pluginSql.GetTableNames()){

using (var fc = pluginSql.OpenTable(tableName) as FeatureClass){//Add as a layer to the active map or sceneLayerFactory.Instance.CreateFeatureLayer(fc, MapView.Active.Map);

}}

}});

C:\Data\PluginData\SQLExpressData\SqlExpress.sqlexpress

Demo: Plugin DataSource Sample

Better integration of custom plugin datasource in ArcGIS Pro

• A better user experience is:- Custom content is integrated both into the Pro

catalog and its browse experience

• Use the ‘Custom Project Item’ item template in your Add-in- Pairing a custom item with a plugin datasource allows

your custom content to be integrated into the Pro catalog and open file dialog

Demo: Plugin DataSource Sample

Learning Customization and Extensibility

• Session materials are available here:

- https://github.com/esri/arcgis-pro-sdk/wiki/tech-sessions#2020-palm-springs