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:
- Configure—Invoked when a designer clicks the configure button for the tool or behavior. Your configuration logic should be initiated here. Usually this involves displaying a dialog box to get input from the designer.
- SaveConfiguration—Invoked when the input is saved. The string you return from this method is persisted and passed back to the command or behavior when the tool is loaded.
- LoadConfiguration—Invoked when the tool initializes. The last string you returned from SaveConfiguration is passed to this method.
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"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d"
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" />
</StackPanel>
</Grid>
</UserControl>
This control could be used in a simple configurable tool as follows:
[Export(typeof(ICommand))]
[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;
}
#endregion
#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
});
}
#endregion
}
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:
![]() |
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:
![]() |