Best practices: Creating configurable add-ins

Making tools and behaviors configurable

The Extensibility API provides the ability to make your tools and behaviors configurable. If a tool or behavior is configurable, you can configure the component when creating a Viewer. To expose configuration on a tool or behavior, you need to implement the ESRI.ArcGIS.Client.Extensibility.ISupportsConfiguration interface. This interface requires you to implement the following methods:

For an example of a configurable tool, suppose you have implemented a simple UserControl that contains the default code-behind and a textbox. The Extensible Application Markup Language (XAML) for this control may appear as follows:

<UserControl x:Class="MyExtension.ConfigurationDialog"
     d:DesignHeight="300" d:DesignWidth="400">
    <Grid x:Name="LayoutRoot" Background="Transparent">
        <StackPanel Margin="10" Background="Transparent">
            <TextBlock Text="Configuration Input:" Margin="0,0,0,5" />
            <TextBox Name="InputTextBox" Width="200" />

This control could be used in a simple configurable tool as follows:

[DisplayName("Configurable Command")]
[Category("My Tools")]
[Description("Example of a configurable command")]
[DefaultIcon(Path to icon, ex: "/Viewer.Addins;component/Images/Identify.png")]
public class ConfigurableCommand: ICommand, ISupportsConfiguration
        private ConfigurationDialog configDialog = new ConfigurationDialog();

        #region ISupportsConfiguration Members

        public void Configure()
            // When the dialog box opens, it shows the information saved from the last 
												//time the command was configured.
            MapApplication.Current.ShowWindow("Configuration", configDialog);

        public void LoadConfiguration(string configData)
            // If the saved configuration is not null, apply it to the configuration dialog box.
            configDialog.InputTextBox.Text = configData ?? "";

        public string SaveConfiguration()
            // Save the information from the dialog box, and 
            return configDialog.InputTextBox.Text;


        #region ICommand Members

        public bool CanExecute(object parameter)
            // Return true so that the command can always be executed.
            return true;

        public event EventHandler CanExecuteChanged;

        public void Execute(object parameter)
            // Show the configuration data. 
            MapApplication.Current.ShowWindow("Configuration", new TextBlock()
                Text = configDialog.InputTextBox.Text,
                TextWrapping = TextWrapping.Wrap,
                Margin = new Thickness(30),
                MaxWidth = 480


Clicking Configure on the Add Tool dialog box invokes the tool's Configure method. With the implementation previously shown, this display the following dialog box:

Configuration dialog box

When the Viewer is deployed or saved, the text in the textbox is persisted as a string. When the Viewer loads, this string is passed to the LoadConfiguration method and used to initialize the configuration String variable. Executing the command—by clicking the command's button—displays a message box that shows the saved configuration string:

Dialog box with saved configuration string