Advanced Customization. Charles Macleod, Steve Van Esch

Transcription

1 Advanced Customization Charles Macleod, Steve Van Esch

2 Advanced Customization and Extensibility Pro Extensibility Overview - Custom project and application settings - Project options - Multiple Add-ins - UI Customization via DAML - Versioning - Categories - Embeddable Controls for plug and play UI

3 Advanced Customization Project Settings Project settings are persisted in the project Override OnReadSettingsAsync and OnWriteSettingsAsync on the Module class Your custom settings are passed in via OnReadSettingsAsync - Whenever a project is opened (that contains your custom settings) Your custom settings are saved to the project via OnWriteSettingsAsync - Whenever a project is saved.

4 Advanced Customization Project Settings Settings are stored as key-value pairs. Values must be strings. Settings are added to the ModuleSettingsWriter during a save internal class Module1 : Module { private bool hassettings = false; //Called on Save project protected override Task OnWriteSettingsAsync(ModuleSettingsWriter settings) { settings.add( Setting1, Custom_setting_val1 ); settings.add( Setting2, Custom_setting_val2 );... return Task.FromResult(0); }

5 Advanced Customization Project Settings Settings are retrieved via OnReadSettingsAsync. Use the ModuleSettingsReader - OnReadSettingsAsync is called when the project is opened (if you have any settings) - You are responsible for your own defaults in the case of a project not having custom settings internal class Module1 : Module { private bool hassettings = false; //Called on project open protected override Task OnReadSettingsAsync(ModuleSettingsReader settings) { hassettings = true; //Set our flag true } var setting1 = settings[ Setting1 ]; var setting2 = settings[ Setting2 ];... return Task.FromResult(0); ProjectOpenedEvent.Subscribe((args)=> { if (!hassettings) //We did NOT have custom settings ProjectClosedEvent.Subscribe((args) => hassettings = false); //reset our flag

6 Advanced Customization Application Settings Application settings get added via.net property settings - In Visual Studio, add a new item type of settings to your Add-in - Visual studio will automatically generate a settings class for you - Settings stored in an app.config in the project - At runtime, dynamically stored in a user.config in the user s AppData folder

7 Advanced Customization Application Settings Use the property designer to add your application properties Visual Studio generates a settings class with the same properties. - Get and set the properties in code just like a regular class - Call Save() on the settings class to persist the settings Settings1.Default.ShowLastSave = false; Settings1.Default.Save();

8 Advanced Customization Demo

9 Advanced Customization Project Options Pro Options Property Sheet

10 Advanced Customization Project Options Add Project and Application options to the Pro Options Property Sheet - Provide a property page for both project and application options - Use the Pro SDK Property Sheet item template - Update property sheet with refid= esri_core_optionspropertysheet - Config.daml

11 Advanced Customization Project Options Add Project and Application property pages - Add New Item -> ArcGIS -> ArcGIS Pro Property Sheet - Adds an individual property page view + view model - Adds a custom property sheet container declared in the Config.daml - Adds a button to show the custom property sheet container - For our purposes we only need the page(s) view and view models - The rest of the generated content can either be deleted or ignored.

12 Advanced Customization Property Page Page View: Implement using standard WPF (User Control) Page View Model: - Derives from ArcGIS.Desktop.Framework.Contracts.Page - You must implement a CommitAsync override for your Save logic. - CommitAsync is called when the user clicks OK on the property sheet - It is only called if your page is dirty (IsModified = true) - Set this.ismodified = true whenever a property value is changed - Marks the page as dirty. if (SetProperty(ref _trackchanges, value, () => TrackChanges)) this.ismodified = true; - Override InitializeAsync and Uninitialize as needed: - Executed when the page is loaded and destroyed respectively.

13 Advanced Customization Project Options - Config.daml Delete extra content resulting from template generation <modules> <insertmodule id=..."...> <controls> <button id="advcustomizationstart_ui_showpropertysheet" caption="show PropertySheet 1" classname=..." loadonclick="true"...></button> <propertysheets> <insertsheet id="advcustomizationstart_ui_propertysheet1"...> <page id="advcustomizationstart_ui_projectoptions" caption= Project Tracking" classname="projectoptionsviewmodel" group="group 1"> <content classname="projectoptionsview" /> </page> </insertsheet> </propertysheets>

14 Advanced Customization Project Options - Config.daml Delete extra content resulting from template generation <modules> <insertmodule id=..."...> <controls> <button id="advcustomizationstart_ui_showpropertysheet" caption="show PropertySheet 1" classname=..." loadonclick="true"...></button> <propertysheets> <insertsheet id="advcustomizationstart_ui_propertysheet1"...> <page id=" AdvCustomizationStart_UI_ProjectOptions" caption="project Tracking" classname="projectoptionsviewmodel" group="group 1"> <content classname="projectoptionsview" /> </page> </insertsheet> </propertysheets>

15 Advanced Customization Project Options - Config.daml <propertysheets> <updatesheet refid="esri_core_optionspropertysheet"> </updatesheet> </propertysheets>

16 Advanced Customization Project Options - Config.daml <propertysheets> <updatesheet refid="esri_core_optionspropertysheet"> <!--Use group=project for the Project section in the settings--> <insertpage id="advcustomizationstart_ui_projectoptions" caption= Project Tracking classname="projectoptionsviewmodel" group= Group 1"> <content classname="projectoptionsview" /> </insertpage> </updatesheet> </propertysheets>

17 Advanced Customization Project Options - Config.daml <propertysheets> <updatesheet refid="esri_core_optionspropertysheet"> <!--Use group=project for the Project section in the settings--> <insertpage id="advcustomizationstart_ui_projectoptions" caption= Project Settings classname="projectoptionsviewmodel" group="project"> <content classname="projectoptionsview" /> </insertpage> </updatesheet> </propertysheets>

18 Advanced Customization Project Options - Config.daml <propertysheets> <updatesheet refid="esri_core_optionspropertysheet"> <!--Use group=project for the Project section in the settings--> <insertpage id="advcustomizationstart_ui_projectoptions" caption= Project Settings classname="projectoptionsviewmodel" group="project"> <content classname="projectoptionsview" /> </insertpage> <!--Use group=application for the Application section in the settings--> <insertpage id="advcustomizationstart_ui_applicationoptions" caption= Save Tracking classname="applicationoptionsviewmodel" group= Group 1"> <content classname="applicationoptionsview" /> </insertpage> </updatesheet> </propertysheets>

19 Advanced Customization Project Options - Config.daml <propertysheets> <updatesheet refid="esri_core_optionspropertysheet"> <!--Use group=project for the Project section in the settings--> <insertpage id="advcustomizationstart_ui_projectoptions" caption= Project Settings classname="projectoptionsviewmodel" group="project"> <content classname="projectoptionsview" /> </insertpage> <!--Use group=application for the Application section in the settings--> <insertpage id="advcustomizationstart_ui_applicationoptions" caption= Save Tracking classname="applicationoptionsviewmodel" group="application"> <content classname="applicationoptionsview" /> </insertpage> </updatesheet> </propertysheets>

20 Advanced Customization Demo

21 Advanced Customization Multi and Versioned Add-ins There may be scenarios where you want to deploy: - Newer versions of the same Add-in - Augment an existing Add-in with additional capabilities - or both

22 Advanced Customization - Multi and Versioned Add-ins Versioning your Add-in(s): Deploy bug-fixes and feature enhancements - Update the version attribute on <AddInInfo> in the Config.daml - Pro will always load the latest version of an Add-in regardless of its location <ArcGIS defaultassembly= Acme_Corp_Addin.dll"...> <AddInInfo id="{b705ce83-52aa-453f-8095-f6ae60994ce3}" version="1.0" desktopversion= 2.1"> <Name>Acme Corp. Addin</Name> <Description>Adds standard Acme workflows to Pro for... <AddInInfo - <AddInInfo version="1.0" version="1.0 Earliest <AddInInfo version=" " version=" <AddInInfo... version="1.0.1 <AddInInfo... version="1.0.1" <AddInInfo... version="1.3" <AddInInfo version= 2.0" version="1.3 Latest

23 Advanced Customization - Multi and Versioned Add-ins Multi Add-ins - Deploy functionality incrementally across multiple Add-ins - Core or Basic Add-in + other Add-ins as optional packages or extensions - Eg extra tools or UI components core or basic options or enhanced

24 Advanced Customization - Multi and Versioned Add-ins Use regular daml to update the core Add-in module typically updatetab but you can update menus, property sheets, groups, etc. <updatemodule refid= AdvCustomizationStart_Module"> <tabs> <updatetab refid="advcustomizationstart_tab1"> <insertgroup refid="externalcustomizations_group1"/> </updatetab> </tabs> </updatemodule> Option: Add a daml dependency to the core Add-in in any Add-in that needs to modify or enhance it. - Important if the enhancements Add-ins load before the core Add-in it needs to modify. <dependencies> <dependency name="aacc0821-e d-90c6-92fa5eb67b2f"/> </dependencies>

25 Advanced Customization Categories

26 Advanced Customization Categories DAML Categories provides a custom extensibility mechanism - Allows you, the Add-in developer, to provide your own extensibility beyond what DAML out of the box provides - Eg optional filters or analysis algorithms or other capabilities that can be augmented by additional add-ins - There are two roles involved: - The Host or Owner : defines the category and is responsible for loading any customizations - Main module add-in - Component providers: responsible for providing any customizations - Enhancement/options add-ins

27 Advanced Customization Categories - The Host or Owner: - Creates the category in the Config.daml - Defines the requirements to be in the category - Eg Implement a proprietary interface, etc. - Uses Framework to find and retrieve category components at runtime - Use Categories.GetComponentElements( Your_Category_Id") - It is the Host s responsibility to document and enforce requirements for a category!

28 Advanced Customization Categories The Host Defines the category ID in the Config.daml <categories> <insertcategory id="testcategories"/> </categories> Documents category requirements these are your requirements - Eg: custom daml attributes and xml content. An interface that must be implemented, etc. public interface IMyCategoryProvider { string Label { get; } void Doit(MapPoint pt); }

29 Advanced Customization Categories - Component Provider(s) - Component providers are external modules (to the host). - Implement the component - Typically just a standard.net class - Implements any interfaces required by host (eg IMyCategoryProvider ) - Register component within the category in the Config.daml - Note: Components will be instantiated by the Host.

30 Advanced Customization Categories The Provider Add an updatecategory element with refid= the target category <categories> <updatecategory refid="testcategories"> </updatecategory> </categories>

31 Advanced Customization Categories The Provider Add an insertcomponent child element - classname must point to the code-behind file that contains the category implementation <categories> <updatecategory refid="testcategories"> <!-- This element is required --> <insertcomponent id="advcategoriesprovider1" classname= CategoryProvider"> </insertcomponent> </updatecategory> </categories>

32 Advanced Customization Categories The Provider Add a child content element to the insertcomponent. It has no attributes or children.unless.! <categories> <updatecategory refid="testcategories"> <!-- This element is required --> <insertcomponent id="advcategoriesprovider1" classname= CategoryProvider"> <! A content element is REQUIRED. All attributes are custom!--> <content/> </insertcomponent> </updatecategory> </categories>

33 Advanced Customization Categories The Provider The Category host requires custom content eg custom attributes or custom xml child content.in which case it must be added to the Config.daml <categories> <updatecategory refid="testcategories"> <!-- This element is required --> <insertcomponent id="advcategoriesprovider1" classname= CategoryProvider"> <! A content element is REQUIRED. All attributes are custom!--> <content version="1.0" name= custom" label= etc,etc > <!-- add any custom xml content here --> <param1... /> </content> </insertcomponent> </updatecategory> </categories>

34 Advanced Customization Loading Categories The Host Implement loading the category components (e.g. in Module Initialize, etc) - Use Categories.GetComponentElements( Your_Category_DAML_Id") - Returns an enumeration of ArcGIS.Desktop.Framework.ComponentElement - Each ComponentElement represents a component record (from add-in Config.damls) - For each ComponentElement: - Use GetContent() to return the <content/> element from the Config.daml - Returns a System.Xml.Ling.XElement. - Query it for custom attributes and child elements - Use CreateComponent() to instantiate a custom class instance

35 Advanced Customization Loading Categories The Host Implement loading the category components (e.g. in Module Initialize, etc) _items = new List<IMyCategoryProvider>(); XNamespace ns = " foreach (var component in Categories.GetComponentElements("TestCategories")) { var content = component.getcontent();// this is the content from Config.daml var version = content.attribute("version").value; var param1 = content.element(ns + "param1"); } //test the component var instance = component.createcomponent() as IMyCategoryProvider; if (instance!= null) _items.add(instance);

36 Advanced Customization Categories and Embeddable Controls Embeddable Controls

37 Advanced Customization Categories and Embeddable Controls Assume we want to provide an extensibility pattern..as before.. And.it requires a dynamic UI

38 Advanced Customization Categories and Embeddable Controls We need to use something called an Embeddable Control This is an aspect of the Pro SDK - ArcGIS Pro Embeddable Control item template - An embeddable control consists of: - A view component WPF User Control - A view model component - Derives from ArcGIS.Desktop.Framework.Controls.EmbeddableControl

39 Advanced Customization Categories and Embeddable Controls For dynamic UI: As the Host we: - Define a category same as before - Define any required custom interfaces, xml content (as before) - Require providers to register embeddable controls in our category - Not vanilla.net classes as before

40 Advanced Customization Categories and Embeddable Controls For dynamic UI As the Provider we: - Implement the component using the Embeddable Control pattern - Run the Pro SDK Embeddable Control item template - Implement any required interfaces on the VewModel - Register the embeddable control in the category as the category component

41 Advanced Customization Categories and Embeddable Controls - Registering the EmbeddableControl in the target category in the Config.daml <! Note: item template generates this for you!! --> <updatecategory refid="testcategory"> <! - simply switch out esri_embeddablecontrols --> <! - In this case, the component is the EmbeddableControl (ie the View Model ) --> <insertcomponent id="custom_embeddablecontrol" classname="embeddablecontrolviewmodel"> <! The content element is the view (i.e. UserControl) <content classname="extensionembeddablecontrolview" version=..."> <!-- add any custom xml content here as needed --> <param1... /> </content> </insertcomponent> </updatecategory>

42 Advanced Customization Loading Categories and Embeddable Controls As the Host: - Use Categories.GetComponentElements( Your_Category_DAML_Id") as before - Can use GetContent(), etc as needed to check for custom attributes, etc. - Use EmbeddableControl.Create() in lieu of CreateComponent() to create the embeddable control. - EmbeddableControl.Create returns a Tuple<EmbeddableControl, UserControl> - The EmbeddableControl should be tested for any required interfaces - Host the UserControl in the UI (per requirements, whatever they are ) - Standard WPF pattern is to use a <ContentPresenter />

43 Advanced Customization Loading Categories and Embeddable Controls Host: Implement loading the category components (e.g. in Module Initialize, etc) _items = new List<Tuple<IMyCategoryProvider, UserControl>>(); foreach (var component in Categories.GetComponentElements("TestCategories")) { //get the content var version = component.getcontent().attribute("version").value; } //test the component - note: we are using EmbeddableControl.Create! var t = EmbeddableControl.Create(component.ID, "TestCategories", null, false); if (t.item1 is IMyCategoryProvider)//Item1 is the EmbeddableControl component items.add(new Tuple<IMyCategoryProvider, UserControl>( (IMyCategoryProvider)t.Item1,t.Item2));

44 Advanced Customization Loading Categories and Embeddable Controls Host: Show the UI (as/when needed) - In the Host UI View place a ContentPresenter as the placeholder in the xaml <UserControl x:class=..."> <DockPanel LastChildFill="True" HorizontalAlignment="Stretch" Height="{Binding ControlHeight}"> <ContentPresenter Content="{Binding ProviderContent} /> </DockPanel> </UserControl> - In the Host UI View Model, set category provider s UserControl as the ContentPresenter content: _items = new List<Tuple<IMyCategoryProvider, UserControl>>();... this.providercontent = _items[0].item2;//item2 is the UserControl NotifyPropertyChanged( ProviderContent );

45 Advanced Customization Demo

46 Advanced Customization Summary Override Module Read and Write Settings methods to implement custom project settings Use.NET for Application properties - Add Property pages to Project Options for configurable UIs Use DAML and AddInInfo version attribute to support multi-addin deployments Implement Categories and custom interfaces for runtime extensibility - Require providers to implement embeddable controls for dynamic UI

47 ArcGIS Pro SDK for.net Tech Sessions Date Time ArcGIS Pro SDK for.net Tech Sessions Location 1:00 pm - 2:00 pm An Overview of the Geodatabase API Mojave Learning Center Tue, Mar 06 2:30 pm - 3:30 pm Beginning Pro Customization and Extensibility Primrose A 5:30 pm - 6:30 pm Beginning Editing and Editing UI Patterns Mojave Learning Center 10:30 am - 11:30 am Mapping and Layout Pasadena/Sierra/Ventura Wed, Mar 07 1:00 pm - 2:00 pm Advanced Pro Customization and Extensibility Santa Rosa 2:30 pm - 3:30 pm Pro Application Architecture Overview & API Patterns Mesquite G-H 4:00 pm - 5:00 pm Advanced Editing and Edit Operations Santa Rosa Thu, Mar 08 9:00 am - 3:30 pm Getting Started Hands-On Training Workshop Mojave Learning Center 5:30 pm - 6:30 pm Working with Rasters and Imagery Santa Rosa 8:30 am - 9:30 am An Overview of the Utility Network Management API Mesquite G-H Fri, Mar 09 10:00 am - 11:00 am Beginning Pro Customization and Extensibility Primrose A 1:00 pm - 2:00 pm Advanced Pro Customization and Extensibility Mesquite G-H

48 ArcGIS Pro SDK for.net Demo Theater Sessions Date Tue, Mar 06 Wed, Mar 07 Time ArcGIS Pro SDK for.net Demo Theater Presentation Location 1:00 pm - 1:30 pm Getting Started Demo Theater 1 - Oasis 1 4:00 pm - 4:30 pm Custom States and Conditions Demo Theater 2 - Oasis 1 5:30 pm - 6:00 pm New UI Controls for the SDK Demo Theater 2 - Oasis 1 6:00 pm - 6:30 pm Raster API and Manipulating Pixel Blocks Demo Theater 2 - Oasis 1 ArcGIS Pro Road Ahead Sessions Date Time ArcGIS Pro SDK for.net Demo Theater Presentation Tue, Mar 06 4:00 pm 5:00 pm ArcGIS Pro: The Road Ahead Oasis 4 Location Thu, Mar 08 4:00 pm 5:00 pm ArcGIS Pro: The Road Ahead Primrose B

49 Advanced Customization Questions?

50

51 Advanced Customization - Multi and Versioned Add-ins Inter-Module Access - Enhancement add-ins [can] access (your) main module settings - Use FrameworkApplication.FindModule with the core module id to retrieve the desired module instance (in this case the one that has the settings) - Implement an interface of your own design if needed to avoid referencing the Module1 class //Access the "core" module using Pro Framework. Cast it to your proprietary interface //to provide access to underlying settings, properties, as needed... var config = FrameworkApplication.FindModule( AdvCustomizationStart_Module") as IModuleProps; var val = config.someproperty;...

52 Advanced Customization Multi and Versioned Add-ins Optional: Export custom events from your Core-Addin module - Define Event Args class and Event class also in your separate assembly AcmeLib.dll`* - Reference ArcGIS.Core.dll - Reference ArcGIS.Desktop.Framework.dll - Event derives from: ArcGIS.Core.Events.CompositePresentationEvent<CustomEventArgs> - Implement a static Subscribe, Unsubscribe, Publish. - Wrap FrameworkApplication.EventAggregator.GetEvent<Your_Custom_Event>() - Core Module calls Publish to broadcast the event. Listeners call Subscribe and Unsubscribe. - *Again, this is a preference, not a requirement

53 Advanced Customization Event Implementation public class CustomOptionsEventArgs : EventArgs {... public Text IAcmeConfig AcmeConfigProperties => _configprops; } public class CustomOptionsEvent :CompositePresentationEvent<CustomOptionsEventArgs> { public static SubscriptionToken Subscribe(Action<CustomOptionsEventArgs> action, bool keepsubscriberreferencealive = false) { return FrameworkApplication.EventAggregator.GetEvent<CustomOptionsEvent>().Register(action, keepsubscriberreferencealive); } public static void Unsubscribe(Action<CustomOptionsEventArgs> subscriber) { FrameworkApplication.EventAggregator.GetEvent<CustomOptionsEvent>().Unregister(subscriber); } public static void Unsubscribe(SubscriptionToken token){ FrameworkApplication.EventAggregator.GetEvent<CustomOptionsEvent>().Unregister(token); } public static void Publish(CustomOptionsEventArgs payload) { FrameworkApplication.EventAggregator.GetEvent<CustomOptionsChangedEvent>().Broadcast(payload); } }