Best practices: Getting started

ArcGIS Viewer for Silverlight includes an extensibility application programming interface (API) that provides developers access to the map and selected layer, methods to show the user interface (UI) in dialog boxes, and the ability to store and load configuration data. The extensibility API is included in the ArcGIS Extensbility SDK for Silverlight. To get started, first determine whether you will create a tool or a behavior. Once you have decided on the type of add-in to create, see the following section on Working with the Map and Selected layer for detailed information on accessing the map from your add-in.

Tools and behaviors

Tools provide a simple way to surface logic that should be initiated by the user. If it makes sense to have the functionality you are implementing initiated by having a user click a button on the toolbar, then you should encapsulate this functionality in a tool. An identify tool is an example of a situation where you would provide a button on the toolbar for the user.

Map behaviors provide a simple way to surface functionality that should always be enabled. Map behaviors provide functionality without the need for user interaction. If you are developing functionality to add a capability or modification that should always be present, then this should be encapsulated as a map behavior. Map behaviors can be used, for instance, to constrain the map extent, show mouse coordinates on the mouse pointer, or display an introductory dialog box when the application loads.

For more information and examples, see Creating a tool and Creating a map behavior.

Working with the map and selected layer

The map and selected layer can be accessed through properties on the static ESRI.ArcGIS.Client.Extensibility.MapApplication object. The MapApplication object is available via the MapApplication.Current property. To access the map object, use MapApplication.Current.Map in your add-in code. To access the selected layer, use MapApplication.Current.SelectedLayer. The code for the simple command in the Creating a tool topic demonstrates accessing the map in the CanExecute method. The following code shows an example of a simple command where the selected layer's ID is shown when the tool is executed and the logic in the CanExecute method is such that the tool will be enabled only if a GraphicsLayer is selected.

[Export(typeof(ICommand))]
[DisplayName("Show GraphicsLayer ID")]
[Category("My Tools")]
[Description("Shows the ID of the selected GraphicsLayer")]
[DefaultIcon("Path to icon, ex: "/Viewer.Addins;component/Images/Identify.png"")]
public class ShowGraphicsLayerIdCommand : ICommand
{
     public void Execute(object parameter)
     {
          // Show the selected layer's ID.
          MapApplication.Current.ShowWindow("Layer ID", new TextBlock()
            {
                Text = MapApplication.Current.SelectedLayer.ID,
                TextWrapping = TextWrapping.Wrap,
                Margin = new Thickness(30),
                MaxWidth = 480
            });
   
     }    
 
     public bool CanExecute(object parameter)
     {
          // Return true (that is, make the command executable) only if the selected layer is a GraphicsLayer.
          return MapApplication.Current.SelectedLayer is GraphicsLayer;
     }
 
     public event EventHandler CanExecuteChanged;
}

The extensibility API provides an event that fires when the selected layer changes and methods to retrieve and set the names of layers. Layer names are how layers are identified in the Configure layers panel. These differ from a layer's ID in that they are meant to be a intuitive name to identify a layer to end users of the Viewer, whereas IDs are meant to uniquely identify a layer in the map's layer collection from a programmatic perspective. The selected layer changed event can be accessed via MapApplication.Current.SelectedLayerChanged. Layer names can be retrieved and set through the MapApplication.Current.GetLayerName and MapApplication.Current.SetLayerName methods. The following code shows a simple behavior that displays the selected layer's name in a message box when the selected layer changes:

[Export(typeof(Behavior<Map>))]
[DisplayName("Show Selected Layer Name Behavior")]
[Category("My Behaviors")]
[Description("Shows a message box with the selected layer name")]
public class ShowSelectedLayerNameBehavior : Behavior<Map>
{
     protected override void OnAttached()
     {
          base.OnAttached();
 
          // Add a handler to the applications's SelectedLayerChanged event.
          MapApplication.Current.SelectedLayerChanged += ShowSelectedLayerName;
     }
 
     private void ShowSelectedLayerName(object s, EventArgs args)
     {
          // Show a message box with the selected layer name.
          string layerName = MapApplication.Current.SelectedLayer.GetValue(MapApplication.LayerNameProperty) as string;
          MapApplication.Current.ShowWindow("Layer Name", new TextBlock()
            {
                Text = layerName,
                TextWrapping = TextWrapping.Wrap,
                Margin = new Thickness(30),
                MaxWidth = 480
            });
     }
 
     protected override void OnDetaching()
     {
          // Remove the handler from the application's SelectedLayerChanged event.
          MapApplication.Current.SelectedLayerChanged -= ShowSelectedLayerName;
     }
}