Upload
others
View
18
Download
0
Embed Size (px)
Citation preview
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.
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)
- 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>
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
- *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);
});
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
- 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)
• <!-- associate our condition with the enabled state of the button -->
• <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)
<!--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…