ArcGIS Pro SDK for .NET: Beginning Pro Customization and … · 2018. 4. 10. · ArcGIS Pro SDK for...

ArcGIS Pro SDK for .NET

Beginning Pro CustomizationCharles 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.


• Consists of

▪ A module (“Module1.cs”)

▪ An xml Configuration file (Config.daml)

▪ and code files, etc.


• 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"));

}}


• 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>


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


• 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

https://github.com/arcgis/arcgis-pro-sdk/wiki/ArcGIS-Pro-Registry-Keys


• ConfigurationManager class

• The Central Component of a Configuration is the ConfigurationManager

- 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();...

<Configuration appName=“GeocodeConfiguration"><ConfigurationManager className="ConfigurationManager1"/>

</Configuration>


• Demo


• 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 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


• 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

- *Will throw a “CalledOnWrongThread” exception

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);

});


• 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


• 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


• 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


• 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="{....}">....


• Demo


• 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

…


• 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


• 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

- Most Controls generated automatically “out-of-the-box” by the SDK

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; }...

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()

• Using the above pattern you can use any ArcGIS Pro button functionality to your code

// 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 usif (iCommand.CanExecute(null))

iCommand.Execute(null);}

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)

• 

• <button id="esri_sdk_RespondToAppStateBtn" caption="Respond to state"

• condition="example_state_condition">

• </button>

<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”);

elseFrameworkApplication.State.Activate(“example_state”);

States & Conditions (continued)

States and Conditions (continued)

<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>


• 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


• Dockpane example

- Run the Pro SDK Dockpane item template…

ArcGIS Pro SDK for .NET: Beginning Pro Customization and … · 2018. 4. 10. · ArcGIS Pro SDK for...

Documents

Transcript of ArcGIS Pro SDK for .NET: Beginning Pro Customization and … · 2018. 4. 10. · ArcGIS Pro SDK for...