ArcGIS Pro SDK for .NET: Add-in Fundamentals and Development Patterns

1. ArcGIS Pro SDK for .NET: Add-in Fundamentals and Development Patterns Wolf Kaiser, Uma Harano

2. SessionOverview • What is the ArcGIS Pro SDK? • What is an ArcGIS Pro add-in? • ArcGIS Pro Add-ins: • How to write an Add-in • Declarative programming with DAML • Contextual UI: using states and conditions • Asynchronous Programming • Async / Await • Using the ProFramework’s QueuedTask

3. What is the ArcGIS Pro SDK ? • Customization with Tasks • Arcpy for automating Pro (Python 3.4) • Modern asynchronous API (native .NET) • .NET Add-ins for extending Pro (C#, VB) • Pro SDK Resources • ProSamples • ProConcepts • ProTutorials • ProSnippets • API Reference • … more

4. What is the ArcGIS Pro SDK ? (Continued) • ArcGIS Pro SDK: Conceptual documentation, Code Snippets, Tutorials • https://github.com/Esri/arcgis-pro-sdk/wiki • ArcGIS Pro SDK Community Samples • https://github.com/Esri/arcgis-pro-sdk-community-samples • ArcGIS Pro SDK API Reference Guide • http://pro.arcgis.com/en/pro-app/sdk/api-reference

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

6. What is an ArcGIS Pro add-in? (Continued) • Uses a declarative-based framework (config.daml) • Authored using .NET • .NET Add-ins are using: • 64-bit platform • WPF (Windows Presentation Foundation) with .NET 4.6.1 + MVVM pattern (Model View ViewModel) • Asynchronous Patterns: Multiple threads • ArcGIS Pro API which comes with ArcGIS Pro out-of-box

7. What is the ArcGIS Pro SDK for .NET? • Easy to use project templates and wizards (in Visual Studio 2013 and 2015) • New installation experience • Integrated with Visual Studio gallery

8. What is the ArcGIS Pro SDK for .NET? (Continued) • .NET APIs exposed by the Pro Extensions (Installed as part of Pro) • Modern API • Native .NET • UI is WPF and XAML Core Catalog Mapping Layout Editing Search GP Raster GDB Sharing …

9. ArcGIS Pro add-ins: Key concepts • Module • Config.daml • Plug-ins • States and Conditions

10. Module • Hub and central access point for a subsystem • Similar to the Extension object used in the 10.x framework • Singletons instantiated automatically by the Framework internalclassModule1 : Module { privatestaticModule1 _this = null; ///<summary> /// Retrieve the singleton instance to this module here ///</summary> publicstaticModule1 Current{ get { return _this ?? (_this = (Module1)FrameworkApplication.FindModule("ProAppModule7_Module")); } }

11. Config.daml: Defines the UI • Declarative add-in definition – tabs, groups and controls • XML like tags Button

12. Config.daml (continued) • Can add, modify or delete elements in other modules. Default Navigate group Customized Navigate group <!--Modifying Core Map Tab--> <updateModulerefID="esri_mapping"> <groups> <updateGrouprefID="esri_mapping_navigateGroup"> <insertButtonrefID=“custom_bookmarkButton" /> <deleteButtonrefID="esri_mapping_bookmarksNavigateGallery"></deleteButton> </updateGroup> </groups> </updateModule> </modules>

13. Creatinganadd-indemo

14. Diagnosing ArcGIS Pro add-ins C:\Program Files\ArcGIS\Pro\bin>ArcGISPro.exe /dumpcombineddaml • View the DAML elements loaded at startup • Consolidates DAML file in the user’s temp folder • Enable dynamic mode event logging • Single application wide logging ability • ProGuide: Diagnosing ArcGIS Pro add-ins • https://github.com/Esri/arcgis-pro-sdk/wiki/ProGuide-Diagnosing-ArcGIS-Pro-Addins C:\Program Files\ArcGIS\Pro\bin>ArcGISPro.exe /enablediagnostics

15. Add-inmanager • Add more well-known folders • Manage installed add-ins

16. 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 classPlugIn: PropertyChangedBase{ publicstring Caption { get; set; } publicstring DisabledTooltip { get; set; } publicboolEnabled { get; set; } protected internal string ID { get; } ...

17. States & Conditions

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

19. States and Conditions (continued) <conditions> <insertCondition id="example_state_condition" caption=“Custom Condition"> <state id="example_state" /> </insertCondition> </conditions> <!-- associate our condition with the enabled state of the button --> <buttonid="esri_sdk_RespondToAppStateBtn"caption="Respond to state" condition="example_state_condition"> </button> if(FrameworkApplication.State.Contains(“example_state”) FrameworkApplication.State.Deactivate(“example_state”); else FrameworkApplication.State.Activate(“example_state”);

20. States and Conditions demo

21. States & Conditions (continued) • ArcGIS Pro is contextual for example: • Ribbon tabs and commands respond to the active view • Buttons become enabled / disabled based on contextual conditions • ArcGIS Pro DAML Reference wiki page: • https://github.com/Esri/arcgis-pro-sdk/wiki/ArcGIS Pro DAML ID Reference

22. States & Conditions (continued) esri_mapping_mapPane condition

23. States and Conditions (continued) <!--Some conditions from ADMapping.daml in Pro--> <conditions> <insertConditionid="esri_mapping_mapPaneOrLayoutPane"> <or> <stateid="esri_layouts_layoutPane"/> <stateid ="esri_mapping_mapPane"/> </or> </insertCondition> <insertConditionid="esri_mapping_singleLayerSelectedCondition" caption="A single layer is selected"> <and> <stateid="esri_mapping_layerSelectedState" /> <stateid="esri_mapping_singleTOCItemSelectedState" /> <not> <stateid="esri_mapping_groupLayerSelectedState" /> </not> </and> </insertCondition>

24. Asynchronous Programming • ArcGIS Pro is a multi-threaded 64 bit application • Important asynchronous programming patterns for the SDK: • Async / Await • Using the ProFramework’s QueuedTask

25. ArcGIS Pro Internal Threading Model • ArcGIS Pro is multi-threaded • Incorporates the latest asynchronous language features from Microsoft • Implements a threading infrastructure tailored to reduce complexity. • Add-In developers should only need to contend with two threads: • The GUI thread • A single specialized worker thread called the Main CIM Thread, MCT • Internally, ArcGIS Pro uses a large number of threads for: • Rasterization, rendering, data loading, GP • Isolated from the API • Pro delegates to the internal threads on the API’s behalf. • Simplifies coding, ensures consistency of Pro state.

26. Async / Await Demo

27. Three Categories of Methods in ArcGIS Pro API • Coarse-grained asynchronous methods: • Can be called on any thread • Finer grained synchronous methods: • Must be called within a QueuedTask • Non-API “.NET” methods can be called on System threads as you wish • Synchronous methods: • Must be called on the GUI thread only • These types of methods are usually associated with WPF and UI updates

28. Coarse Grained Methods • Can be called from any thread. Typically invoked from the UI thread • They execute in the background on Pro internal threads • Use async/await semantic • Aggregation of these methods into larger coarse grained async methods is not encouraged //Adding a Geodatabase: stringgdbPath = "@C:\\myDataFolder\\myData.gdb"; varnewlyAddedGDB = awaitProject.Current.AddAsync(ItemFactory.Create(gdbPath)); //Execute a GP Tool awaitGeoprocessing.ExecuteToolAsync("SelectLayerByAttribute_management", newstring[] {"parcels","NEW_SELECTION", "description = 'VACANT LAND'"}); awaitMapView.Active.ZoomToSelectedAsync(newTimeSpan(0, 0, 3));

29. Coarse Grained Demo

30. Fine Grained, Synchronous Methods Must be called within a QueuedTask • A much greater number of fine grained methods and classes • No async/await. Runs on the MCT • Designed for aggregation into your own coarse-grained async methods awaitArcGIS.Desktop.Framework.Threading.Tasks.QueuedTask.Run(() => { var layers = MapView.Active.Map.FindLayers("Parcels") .OfType<FeatureLayer>().ToList(); var parcels = layers[0] asFeatureLayer; QueryFilterqf = newQueryFilter() { WhereClause = "description = 'VACANT LAND'", SubFields = "*" }; parcels.Select(qf, SelectionCombinationMethod.New); });

31. Using QueuedTask • Pro framework’s custom Task scheduler. • Used to run synchronous ArcGIS Pro SDK methods in the background • These synchronous methods are listed in the API Reference guide like this: “This method must be called on the MCT. Use QueuedTask.Run” • Example of synchronous methods in Pro: GetSpatialReference, QueryExtent, SetDefinition (members in FeatureLayer class) Task t = QueuedTask.Run(() => { // Call synchronous SDK methods here });

32. Fine Grained Demo

33. Sample Demo • Show a sample that highlights the benefits of an asynchronous add-in

34. ArcGIS Pro SDK Resources • ArcGIS Pro SDK: Conceptual documentation, Code Snippets, Tutorials • https://github.com/esri/arcgis-pro-sdk/wiki • ArcGIS Pro SDK Community Samples • https://github.com/esri/arcgis-pro-sdk-community-samples • ArcGIS Pro SDK API Reference Guide • http://pro.arcgis.com/en/pro-app/sdk/api-reference

35. ArcGIS Pro SDK for .NET Sessions

36. Please take our Survey Your feedback allows us to help maintain high standards and to help presenters Find your event in the Esri Events App Find the session you want to review Scroll down to the bottom of the session Answer survey questions and submit