ArcGIS Pro SDK for.net Beginning Pro Customization. Charles Macleod

ArcGIS Pro SDK for.net Beginning Pro Customization Charles Macleod

Session Overview Extensibility patterns - Add-ins - Configurations Primary API Patterns - QueuedTask and Asynchronous Programming - async and await - Model, View, View Model or MVVM

ArcGIS Pro SDK for.net Add-ins Extends ArcGIS Pro through: - Buttons, Tools, Checkboxes - Combo Boxes, Edit Boxes, Spinners - Menus, Context Menus, Dynamic Menus - Galleries, Button and Tool Palettes, Split Buttons - Tabs, Groups, Contextual Groups - Property Pages/Sheets, Wizards - Views and Docking Panes - Custom (XAML) controls - Backstage Tabs, Backstage Button - Use Add-ins to add new functionality to Pro or to - Augment existing.

ArcGIS Pro SDK for.net Addins Characteristics - Archive (.esriaddinx) - Xcopy or double-click deployment (via RegisterAddin.exe) - C:\users\<username>\Documents\ArcGIS\Addins\ArcGISPro - Multiple Add-ins can be loaded per user (per Pro session). - Admin and per-user settings for: - Well known folders - Add-in security level, etc.

ArcGIS Pro SDK for.net Addins Consists of A module ( Module1.cs ) An xml Configuration file (Config.daml) and code files, etc.

ArcGIS Pro SDK for.net Addins Module - Hub and central access point - Singleton instantiated automatically by the Framework - Can use Module to centralize shared logic internal class Module1 : Module { private static Module1 _this = null; /// <summary>retrieve the singleton instance to this module here /// </summary> public static Module1 Current{ get { return _this?? (_this = (Module1)FrameworkApplication.FindModule("ProAppModule7_Module")); } }

ArcGIS Pro SDK for.net Addins Config.daml - Declarative add-in definition for UI and related UI state - Contains framework element declarations (buttons, dockpane, galleries) <insertmodule id="mvvm_module" classname="module1" autoload= false" caption="module1"> <tabs> <tab id="mvvm_tab1" caption="mvvm Demo" keytip="t1"> <group refid="mvvm_group1" /> </tab> </tabs> <groups> <group id="mvvm_group1" caption="mvvm Demo" keytip="g1"> <button refid="mvvm_mvvmdockpane_showbutton" size="large" /> </group> </groups> <controls> <button id="mvvm_mvvmdockpane_showbutton" caption="show Bookmark DockPane"...> </button> </controls>

ArcGIS Pro SDK for.net Addins Configurations

ArcGIS Pro SDK for.net Configurations Introduced at 1.4 - All of the functionality of an Add-in plus. - Change the application title and icon - Change the application splash and start page - Conditional customization of the UI - Eg via the a user s permissions, role, portal group membership, etc - Use Configurations when a deeper level of customization is required beyond what an Add-in provides - Eg You need to customize the Pro start-up process and/or streamline its functionality for some specific workflow

ArcGIS Pro SDK for.net Configurations Characteristics - Archive.proConfigX - Xcopy or double-click deployment (via RegisterAddin.exe) - C:\Users\Public\Documents\ArcGIS\ArcGISPro\Configurations - One configuration can run per instance of Pro - Specify via Command line: - /config:{configuration_name} - Admin registry key to force Pro to run under a specific configuration: - HKLM\Software\ESRI\ArcGISPro\Settings\ConfigurationName https://github.com/arcgis/arcgis-pro-sdk/wiki/arcgis-pro-registry-keys

ArcGIS Pro SDK for.net Configurations ConfigurationManager class The Central Component of a Configuration is the ConfigurationManager - Defined in DAML (generated automatically by the template) <Configuration appname= GeocodeConfiguration"> <ConfigurationManager classname="configurationmanager1"/> </Configuration> - 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();...

ArcGIS Pro SDK for.net Configurations Demo

ArcGIS Pro SDK for.net Configurations Patterns in Pro - QueuedTask and Asynchronous Programming - MVVM

ArcGIS Pro SDK.NET Asynchronous Programming ArcGIS Pro is a multi-threaded 64 bit application - Primary purpose is to allow the UI to remain responsive

ArcGIS Pro SDK.NET Asynchronous Programming ArcGIS Pro SDK developers only need to worry about two threads: - The GUI thread (Graphical User Interface thread) - By default, your Add-in is running on the UI thread - A specialized worker thread called the Main CIM Thread, MCT - All work/business logic using API should run on the MCT - To access the MCT we use use ArcGIS.Desktop.Framework.Threading.Tasks.QueuedTask

ArcGIS Pro SDK.NET Asynchronous Programming We need to consider two Categories of Methods: - Coarse-grained asynchronous methods: - Can be called on any thread - Returns immediately - Fine-grained synchronous methods: - Must be called using the QueuedTask class

Coarse-Grained Asynchronous Methods - Return type of Task and method names end with Async - Can be called from any thread, typically the UI - Execute internally on the worker threads via MCT - Use them with async/await semantic if you need to wait for them to finish protected async override void OnClick() { //Execute a Geoprocessing Tool await Geoprocessing.ExecuteToolAsync("SelectLayerByAttribute_management", new string[] {"parcels","new_selection", "description = 'VACANT LAND'"}); MapView.Active.ZoomToSelectedAsync(new TimeSpan(0, 0, 3));

Fine-Grained, Synchronous Methods Must be called using the QueuedTask class* - A much greater number of fine grained methods and classes - Designed for aggregation into your own coarse-grained async methods - i.e. you can write your custom business logic as background tasks await ArcGIS.Desktop.Framework.Threading.Tasks.QueuedTask.Run(() => { var layers = MapView.Active.Map.FindLayers("Parcels").OfType<FeatureLayer>().ToList(); var parcels = layers[0] as FeatureLayer; QueryFilter qf = new QueryFilter() { WhereClause = "description = 'VACANT LAND'", SubFields = "*" }; parcels.select(qf, SelectionCombinationMethod.New); }); - *Will throw a CalledOnWrongThread exception

ArcGIS Pro SDK.NET Asynchronous Programming Demo

ArcGIS Pro SDK.NET MVVM Pattern MVVM: Model View ViewModel Design pattern used to separate implementation aspects - UI separated from business logic and data Central to the ArcGIS Pro SDK - Pro Framework handles instantiating the View and View Model and binds them together

ArcGIS Pro SDK.NET MVVM Pattern MVVM is used for many of the Framework elements - Dockpane, Property Page, Ribbon Custom Control, Embeddable Control, Pane, - Backstage tab, etc. Simply run the relevant Pro SDK item template - Adds the relevant View and View Model pair to your project - Updates the Config.daml as needed

ArcGIS Pro SDK.NET MVVM Pattern Assume we added a Dockpane. In the project you get: - A new Dockpane View (User Control) - A new Dockpane ViewModel (Code behind file) In the Config.daml you get - A dockpane declaration with View and View Model - A button declaration which can be used to show your view - Implementation is added in to the bottom of the view model code behind file

ArcGIS Pro SDK.NET MVVM Pattern Add your desired UI to the Dockpane using WPF Add your desired code-behind/properties/etc to the Dockpane View Model - Optionally add your own Model class Bind your ViewModel properties to your View UI elements public string Heading => _heading; <DockPanel Grid.Row="0" LastChildFill="true" KeyboardNavigation.TabNavigation="Local" Height="30"> <TextBlock Grid.Column="1" Text="{Binding Heading}" Style="{...}">...

ArcGIS Pro SDK.NET MVVM Pattern Demo

ArcGIS Pro SDK.NET MVVM Pattern Questions?

What is the ArcGIS Pro SDK for.net? Easy to use project and item templates (in the Visual Studio IDE) - Currently Visual Studio 2015 and 2017 - Integrated with Visual Studio Gallery - Version 2.1 -.NET 4.6.1+ Resources - Github: Concept docs, Samples, Snippets API Reference (pro.arcgis.com)

What is the ArcGIS Pro SDK for.net?.net APIs exposed by the ArcGIS Pro extensions - Installed as part of Pro (not as part of the SDK) - Modern API - Uses.NET features - UI is WPF Core Catalog Mapping Layout Editing Sharing Search GP Raster GDB

ArcGIS Pro SDK for.net Configurations Start Page - User Control View + View Model pair - Shown at the conclusion of Pro initialization - Shown only once - Start Page is responsible for initiating the Pro session - Either: Open an existing project - Or: Create a new project - Note: Closed automatically by Pro when the project is being opened

ArcGIS Pro SDK.NET Asynchronous Programming To access the MCT use ArcGIS.Desktop.Framework.Threading.Tasks.QueuedTask - Threading infrastructure tailored to reduce complexity - Serializes or Queues access to Pro s internal thread pool - Functionality can execute sequentially and asynchronously -.Hence allowing the UI to remain responsive while ensuring consistency of the underlying application state

Plug-Ins Many customizations are purely declarative - Eg Menus Others (such as Controls ) have an active (code-behind) component Inherit from common base class PlugIn Most methods and properties do not need to be overridden - Provided by the DAML public abstract class PlugIn : PropertyChangedBase { public string Caption { get; set; } public string DisabledTooltip { get; set; } public bool Enabled { get; set; } protected internal string ID { get; }... - Most Controls generated automatically out-of-the-box by the SDK

Plug-Ins (Controls) Cannot exist un-tethered or stand-alone They have to be defined in a Module Require a unique ID Have a code behind file (or class file) linked to the DAML <insertbutton id="esri_subsystem_button1" classname="testbutton" caption="test /> public sealed class TestButton : Contracts.Button { protected override void OnClick() { this.caption = New Caption ; this.tooltip = New Tooltip ; this.checked = true; }...

Hooking Existing ArcGIS Pro Commands in Code Use the ArcGIS Pro Framework s GetPlugInWrapper method with any ArcGIS Pro element s Id to get the IPlugInWrapper interface All buttons implement the ICommand interface - with Execute() and CanExecute() // ArcGIS Pro's Create button control DAML ID. var commandid = DAML.Button.esri_mapping_createBookmark; // get the ICommand interface from the ArcGIS Pro Button // using command's plug-in wrapper // (note ArcGIS.Desktop.Core.ProApp can also be used) var icommand = FrameworkApplication.GetPlugInWrapper(commandId) as ICommand; if (icommand!= null) { // Let ArcGIS Pro do the work for us if (icommand.canexecute(null)) icommand.execute(null); } Using the above pattern you can use any ArcGIS Pro button functionality to your code

ICommand Pattern in MVVM Adding a button to the Dockpane to run the Close ArcGIS Pro Command - Use Data Binding in UI declaration to bind to an ICommand view model property - Define the reference ICommand property in your viewmodel Adding a button to the Dockpane with our custom behavior using RelayCommand RelayCommand implements ICommand and allows you to specify your own implementation of Execute and CanExecute

Delegate Commands A pattern for simplifying the creation of buttons Declare the button as a static method in the Module OnUpdate logic can be implemented as a static bool getter property <insertmodule id="workingwithdaml" classname="module1" autoload="false" caption="module1">... <insertbutton id= TestButton1" classname= WorkingWithDAML:OnCustomButtonClick" caption="test /> internal class Module1 : Contracts.Module { internal static void OnCustomButtonClick() { IPlugInWrapper wrapper = FrameworkApplication.GetPlugInWrapper("TestButton1"); wrapper.caption = "New Caption"; wrapper.tooltip = "New Tooltip"; //TODO - something on click... } internal static bool CanOnCustomButtonClick { get { return true; } }

States & Conditions Simplifies coding by reducing event wiring associated with more traditional models. Example: A button is activated only when a example_state_condition is met. States - are named values which describes a particular aspect of the application s overall status. - Activate or deactivate in code Conditions - Declared in DAML - Expressions composed of one or more states - AND, OR, NOT - Used for triggering the activation of framework elements.

States and Conditions (continued) <conditions> <insertcondition id="example_state_condition" caption= Custom Condition"> <state id="example_state" /> </insertcondition> </conditions> if(frameworkapplication.state.contains( example_state ) FrameworkApplication.State.Deactivate( example_state ); else FrameworkApplication.State.Activate( example_state ); <!-- associate our condition with the enabled state of the button --> <button id="esri_sdk_respondtoappstatebtn" caption="respond to state" condition="example_state_condition"> </button>

States & Conditions (continued)

States and Conditions (continued) <!--Some conditions from ADMapping.daml in Pro--> <conditions> <insertcondition id="esri_mapping_mappaneorlayoutpane"> <or> <state id="esri_layouts_layoutpane"/> <state id ="esri_mapping_mappane"/> </or> </insertcondition> <insertcondition id="esri_mapping_singlelayerselectedcondition" caption="a single layer is selected"> <and> <state id="esri_mapping_layerselectedstate" /> <state id="esri_mapping_singletocitemselectedstate" /> <not> <state id="esri_mapping_grouplayerselectedstate" /> </not> </and> </insertcondition>

ArcGIS Pro SDK.NET MVVM Pattern The Basic Pattern is: - ViewModel declared in DAML and implemented in code - View referenced in DAML and implemented as WPF UserControl - Use standard WPF and Xaml - Model is optional your own custom C# or VB.Net class Pro Framework handles instantiating the View and View Model and binds them together

ArcGIS Pro SDK.NET MVVM Pattern Dockpane example - Run the Pro SDK Dockpane item template