Runtime Extensibility Framework

For Runtime .NET 10.2.7

Updated: 2017-03-02

The Runtime Extensibility Framework is a simple, open-source component that enables development of extensible, configurable, MVVM applications using the ArcGIS Runtime .NET SDK. Emphasis is placed on the following concepts:

RTReader, available for download, provides not only a ready-to-use application, but also an example of configuring and supporting the Extensibility Framework. This documentation will draw primarily upon it for examples.

Supporting the Extensibility Framework

In order to support the Extensibility Framework, a class in the application (typically the MainWindow class) must implement the IMainWindow interface:

When the application launches, the main window initializes the Extensibility Framework by initializing the MapApplication object as follows:

MapApplication.Init(pMainWindow);

where pMainWindow is an instance of a class that implements IMainWindow. If the argument is null, MapApplication checks the application main window to see if it implements IMainWindow.

The MapApplication class also exposes the following members:

Three subfolders are expected to exist under the application executable, or else to be created and populated from corresponding subfolders under the folder defined by the UpdateLocation property:

Note that view and extension assemblies must have unique names. A view assembly cannot have the same name as an extension assembly.

The main layout in a view library is a UserControl which is declared in the configuration file (see below). Controls in the layout bind their data contexts to the DataContexts[KEY] property, where the key is a model extension provided by an extension class library. Here is an example of a typical tool button:

<RadioButton
   DataContext="{Binding DataContexts[QueryAddin.QueryTools]}"
   Command="{Binding IdentifyCommand}"
   ToolTip="Identify"
   Style="{StaticResource LayoutToolStyle}"
   IsChecked="{Binding IdentifyToolChecked}">
   <Image
      Source="Images/Identify.png"
      Style="{StaticResource LayoutIconStyle}"/>
</RadioButton>
Also, a ContentPresenter control binds its Content property to the DataContexts[MapViewContainerContent] property, which is an instance of the MapView control. Multiple MapViews are currently not supported.

<ContentPresenter
   Grid.Column="1"
   Content="{Binding DataContexts[MapViewContainerContent]}" />
The following is a list of interfaces to be implemented by the developer:

Various helper classes also exist for the benefit of the developer:

The Configuration File

The configuration file is named after the Configuration property (plus an .xml extension). [See the configuration file for RTReader for an example.] There are two main sections in the configuration file: "MainLayout" and "Extensions".

The "MainLayout" section contains the application title, the name of view assembly containing the main UI, and the name of the main UI class in the view assembly. [All UIs defining the main application and any child windows are expected to be subclasses of UserControl.]

The "Extensions" section contains the declaration and configuration for each extension to be used in the application. Each "Extension" entry can have the following (optional) sections: Model extensions and view extensions may optionally implement the IConfigurable interface. In that case, a "ConfigData" section in the XML configuration provides a string which may be parsed appropriately by the extension upon loading.

Core Extensions

In addition to the main Extensibility component, code is also provided for several core extensions. Binaries are only provided for those extensions that are used in RTReader (NavAddin and QueryAddin). It is up to the developer to compile the other extensions.

NavAddin

Provides support for map navigation, opening Runtime content, table of contents, map copy/export, and GPS location display.

The following commands are exposed to the UI:

Data Context KeyCommand
NavAddin.NavCommandsExportMapCommand
NavAddin.NavCommandsExitCommand
NavAddin.NavCommandsCopyMapCommand
NavAddin.NavCommandsUserSettingsCommand
NavAddin.NavToolsZoomInCommand
NavAddin.NavToolsZoomOutCommand
NavAddin.NavCommandsZoomInFixedCommand
NavAddin.NavCommandsZoomOutFixedCommand
NavAddin.NavToolsPanCommand
NavAddin.NavCommandsZoomFullCommand
NavAddin.NavCommandsZoomPrevCommand
NavAddin.NavCommandsZoomNextCommand
NavAddin.NavCommandsGPSCommand

The following bindable properties are also exposed:

Data Context KeyPropertyType
NavAddin.MapModelExtTOCObservableCollection<TocDataItem>
NavAddin.MapModelExtStatusTextstring
NavAddin.MapModelExtCoordinateTextstring
NavAddin.MapModelExtProgressVisibilityVisibility
NavAddin.NavModelExtMapReadybool
NavAddin.NavModelExtScaleItemsSourceObservableCollection<string>
NavAddin.NavModelExtScaleSelectedIndexint
NavAddin.NavModelExtScaleTextstring
NavAddin.NavToolsZoomInToolCheckedbool
NavAddin.NavToolsZoomInToolCheckedbool
NavAddin.NavToolsPanToolCheckedbool

The following views are expected to exist in the referenced view library:

The "ConfigData" section for the MapModelExt model extension can have the following (optional) entries:

Here are some example entries:

   <Map Type="RuntimeContent" Path="C:\apps\Data\Runtime\RuntimeContentTest" />
   <Map Type="SimpleTestMap" />
   <EnableTOC>True</EnableTOC>
   <DataModelTOC Assembly="NavAddin" ClassName="TocDataItem" />
   <DataModelTOC Assembly="WebAddin" ClassName="TocWebDataItem" />
The "ConfigData" section for the MapViewExt view extension can set the following MapView properties: MinScale and MaxScale.

Here are some example entries:

   <MaxScale>1000</MaxScale>
   <MinScale>4000000</MinScale>

QueryAddin

Provides support for Identify, Find, Go to XY, Measure, Highlight/Erase, and Text tools.

The following commands are exposed to the UI:

Data Context KeyCommand
QueryAddin.QueryCommandsFindCommand
QueryAddin.QueryCommandsGoToXYCommand
QueryAddin.QueryToolsIdentifyCommand
QueryAddin.QueryToolsMeasureCommand
QueryAddin.QueryToolsHighlighterCommand
QueryAddin.QueryToolsHighlighterMenuCommand
QueryAddin.QueryToolsEraserCommand
QueryAddin.QueryToolsEraserMenuCommand
QueryAddin.QueryToolsTextCommand

The following bindable properties are also exposed:

Data Context KeyPropertyType
QueryAddin.QueryToolsIdentifyToolCheckedbool
QueryAddin.QueryToolsMeasureToolCheckedbool
QueryAddin.QueryToolsHighlighterIconImage
QueryAddin.QueryToolsHighlighterToolCheckedbool
QueryAddin.QueryToolsHighlighterTextString
QueryAddin.QueryToolsEraserIconImage
QueryAddin.QueryToolsEraserToolCheckedbool
QueryAddin.QueryToolsEraserTextString
QueryAddin.QueryToolsTextToolCheckedbool

The following views are expected to exist in the referenced view library:

The "ConfigData" section for the QueryModelExt model extension can have the following (optional) entries:

Here are some example entries:

   <Identify ResultCollection="Tree" QueryRelated="True" />
   <QueryLayerHelper Assembly="QueryAddin" ClassName="BasicQueryLayerHelper" />
   <QueryLayerHelper Assembly="WebAddin" ClassName="WebQueryLayerHelper" />
   <AttachmentDialogModel Assembly="EditAddin" ClassName="EditAttachmentDialog" />

LayoutAddin

Provides support for map layouts that can be printed or exported to XPS.

The following commands are exposed to the UI:

Data Context KeyCommand
LayoutAddin.LayoutModelExtOpenLayoutCommand

The following views are expected to exist in the referenced view library:

The "ConfigData" section for the LayoutModelExt model extension can have a "Layouts" entry containing one or more "Layout" entries. Each "Layout" entry must specify values for "Name", "DisplayName", "PageWidth", and "PageHeight" (using 96 dpi). A Layout may have optional "Property" entries to populate text blocks:

Here is an example XAML mark-up for a layout:

<UserControl x:Class="LayoutTest.AdHocLetterPortrait"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
             xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
             mc:Ignorable="d"
             d:DesignHeight="1056" d:DesignWidth="816">
   <UserControl.Resources>
      <TextBlock x:Key="Title" Text="Ad Hoc Letter Portrait" />
      <Size x:Key="PageSize" Height="1056" Width="816" />
   </UserControl.Resources>
   <Canvas Height="1056" Width="816" Background="White">
      <Border Canvas.Left="48" Canvas.Bottom="48" Width="720" Height="960" BorderBrush="Black" BorderThickness="3">
         <Grid>
            <Grid.RowDefinitions>
               <RowDefinition />
               <RowDefinition Height="48" />
            </Grid.RowDefinitions>
            <Border Grid.Row="0" Margin="12, 12, 12, 0" BorderBrush="Blue" BorderThickness="3">
               <ContentPresenter Content="{Binding MapViewContainerContent}" />
            </Border>
            <Canvas Grid.Row="1">
               <TextBlock Canvas.Bottom="12" Canvas.Left="12" FontSize="24" Text="{Binding LayoutProperties[Title], FallbackValue=Title}" />
               <TextBlock Canvas.Top="6" Canvas.Left="440" FontSize="10" Text="Scale:" />
               <TextBlock Canvas.Top="6" Canvas.Left="480" FontSize="10" Text="{Binding LayoutProperties[Scale], FallbackValue=N/A}" />
               <TextBlock Canvas.Top="24" Canvas.Left="440" FontSize="10" Text="Date:" />
               <TextBlock Canvas.Top="24" Canvas.Left="480" FontSize="10" Text="{Binding LayoutProperties[Date], FallbackValue=N/A}" />
            </Canvas>
         </Grid>
      </Border>
   </Canvas>
</UserControl>
And here is an example configuration for it:

    <Layout Name="AdHocLetterPortrait" DisplayName="Ad Hoc Letter Portrait" PageWidth="816" PageHeight="1056">
       <Properties>
          <Property Name="Title" Type="Input" Label="Map Title" />
          <Property Name="Scale" Type="Scale" PageUnit="Inch" DistanceUnit="Feet"/>
          <Property Name="Date" Type="Date" FormatString="MM-dd-yyyy" />
       </Properties>
    </Layout>

WebAddin

Provides support for map services and map packages [map packages require Runtime Standard licensing]. In order to work with QueryAddin, the "QueryLayerHelper" entry should be set as follows:

   <QueryLayerHelper Assembly="WebAddin" ClassName="WebQueryLayerHelper" />
In order to work with NavAddin, the "DataModelTOC" entry should be set as follows:

   <DataModelTOC Assembly="WebAddin" ClassName="TocWebDataItem" />
An optional "Map" entry in the "ConfigData" section causes a map to be loaded at startup. Optional attributes include "Extent", "MaxScale", and "Black". If the "Black" attribute is set to "True" the map background will be black; otherwise, it will be white.

A variety of layer types may be specified. Disconnected map layers can be "TilePackageLayer" or "MapPackageLayer". Connected map layers can be "TileServiceLayer", "ImageServiceLayer", "MapServiceLayer", or "FeatureServiceLayer". A "Token" value may be supplied for connected layers (a value of "dummytest" is ignored).

Here are some example map entries:

   <Map Extent="231000, 10986000, 2482000, 13835000" MaxScale="10" Black="False">
      <TilePackageLayer Path="C:\apps\FieldApp\Data\uesg_cache" ID="Basemap_TilePackage" DisplayName="AZ Imagery" Visible="False" />
      <MapPackageLayer Path="C:\apps\FieldApp\packages\AZ Gas.mpk" ID="AZGas_MapPackage" DisplayName="AZ Gas" />
   </Map>

   <Map Extent="-12994805, 3654000, -11931194, 4449000" MaxScale="10">
      <TileServiceLayer ServiceUri="http://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer" ID="WS_TileService" DisplayName="World Street Map" Visible="False" />
      <ImageServiceLayer ServiceUri="http://utility.arcgis.com/usrsvcs/servers/d201145841164058b64fee0875bc0f3e/rest/services/USA_Critical_Habitat_Mexican_Spotted_Owl/ImageServer" ID="SO_ImageService" DisplayName="Mexican Spotted Owl Habitat" Visible="False" Token="dummytest"/>
      <MapServiceLayer ServiceUri="http://myserver:6080/arcgis/rest/services/UES/AZLandbase/MapServer" ID="AZLandbase_DynamicService" DisplayName="AZ Landbase" />
      <MapServiceLayer ServiceUri="http://myserver:6080/arcgis/rest/services/UES/AZGas/MapServer" ID="AZGas_DynamicService" DisplayName="AZ Gas" />
      <FeatureServiceLayer ServiceUri="http://myserver:6080/arcgis/rest/services/UES/Field_ESRP/FeatureServer/1" ID="RedLine_FeatureService" DisplayName="RedLine" />
   </Map>

EditAddin

Provides support for online/offline editing via the Sync Framework [offline editing requires Runtime Standard licensing].

The following commands are exposed to the UI:

Data Context KeyCommand
EditAddin.EditModelExtDeleteGDBCommand
EditAddin.EditModelExtSynchronizeCommand

The following bindable properties are also exposed:

Data Context KeyPropertyType
EditAddin.EditModelExtSynchronizeVisibilityVisibility

The following views are expected to exist in the referenced view library:

In order to work with QueryAddin, the "AttachmentDialogModel" entry should be set as follows:

   <AttachmentDialogModel Assembly="EditAddin" ClassName="EditAttachmentDialog" />
The "ConfigData" section for the EditViewExt view extension must have the following entries:

The optional "PortalAuth" entry specifies the URL for Portal or ArcGIS Online authentication. If "AutoUserName" is "True", then the user's OS sign-in ID is automatically used.

Here is an example configuration:

   <RemoteFeatureService Url="http://myserver:6080/arcgis/rest/services/UES/Field/FeatureServer" />
   <LocalGeodatabase Path="C:\apps\FieldApp\Data\FieldEditTest.geodatabase" />
   <EditLayers GroupLayerName="Field Data" Visible="False">
      <EditLayer Name="RedPoint" />
      <EditLayer Name="RedLine" />
      <EditLayer Name="RedPoly" />
   </EditLayers>
   <AOI XMin="-116" YMin="30" XMax="-108" YMax="38" />
Here is an example of a Portal service:

   <RemoteFeatureService Url="https://gis.myserver.com/arcgis/rest/services/Gas/FieldMeter/FeatureServer" />
   <PortalAuth Url="https://gis.myserver.com/portal/sharing/rest" AutoUserName="True"/>

AppUpdateAddin

Provides support for application updates, Runtime updates, local file updates, and local dataset updates. Multiple dataset/Runtime update locations are supported. The extension makes the following assumptions:

The following commands are exposed to the UI:

Data Context KeyCommand
AppUpdateAddin.UpdateModelExtSetLocationCommand

The following bindable properties are also exposed:

Data Context KeyPropertyType
EditAddin.EditModelExtLocationVisibilityVisibility

The following views are expected to exist in the referenced view library:

The extension should be the first in the "Extensions" section of the config file. The "ConfigData" section for the UpdateModelExt model extension is optional. The following entries may or may not be present:

Here is a sample configuration:


   <SetUpdateFolder>True</SetUpdateFolder>
   <RuntimeDeployment Name="ArcGISRuntime10.2.7" Package="ArcGISRuntime10.2.7_FieldApp64.zip" />
   <FileUpdates>
      <File Source="Packages\AZ Gas.mpk" Destination="c:\apps\FieldApp\packages" />
      <File Source="Packages\AZ Gas Black.mpk" Destination="c:\apps\FieldApp\packages" />
      <File Source="Packages\TraceGasNetwork.gpk" Destination="c:\apps\FieldApp\packages" />
      <File Source="Packages\GasTraceResults.mpk" Destination="c:\apps\FieldApp\packages" />
   </FileUpdates>
   <DatasetUpdates>
      <Dataset Name="AZLandbase.gdb" Destination="C:\apps\FieldApp\Data" />
      <Dataset Name="AZGas.gdb" Destination="C:\apps\FieldApp\Data" />
   </DatasetUpdates>

Configuration Examples for Core Extensions

Creating an Extension

More to come (hopefully)!


Return to ArcGIS Runtime page