UserControlTask Manager integration

Click here to get the sample associated with this walkthrough.

In this topic

About UserControlTask control integration with Manager

Beginning with ArcGIS 9.3.1, Manager support was enhanced to configure tasks by allowing the use of user controls to configure Web tasks that can be configured and deployed in the Manager application. Manager provides a Tasks panel that lists the available tasks when designing a new Web application.
While out-of-the-box tasks are included by default, you can extend this list by adding your custom task. Manager maintains a list of configured tasks in the Tasks.xml file located in the App_Data folder for the Manager Web application (for example, C:\Inetpub\wwwroot\ArcGIS\Manager\App_Data). You need to add the custom task to the Available Task list for the task to be available in Manager.
When uninstalling or reinstalling the Web Application Developer Framework (ADF), the Tasks.xml file is overwritten. As a result, you need to re-add the custom task item.
The ESRI.ArcGIS.ADF.Web.UI.WebControls.IWebConfigurator interface provides the basic framework for implementing task usage, appearance, and integration in Manager. Once finished, the Tasks panel in Manager provides the option to add and configure the custom task. If a Web configurator is available, it can be used to set the task properties in Manager.

Integrating a custom UserControlTask with Manager

Manager is a Web application. Since you are creating a class that will be used to visually configure the custom task in Manager at run time, it must also be a composite Web control referred to as "configurator." The custom task and configurator must be deployed in Manager to use and configure the custom task.

Creating a Web control to configure a custom server task in Manager

To integrate a custom UserControlTask with the task configuration framework in Manager, the IWebConfigurator interface is implemented. IWebConfiguratorValidation and IDefaultWebConfiguration can also be implemented (optional). The IWebConfiguratorValidation interface is used by Manager to validate that the task has been configured correctly before publishing. The IDefaultWebConfiguration interface is used by Manager when the task supports a default configuration.
Do the following steps to accomplish the integration:
  1. Add a new Web user control item in your project and implement IWebConfigurator, IWebConfiguratorValidation, and IDefaultWebConfiguration. See the following code example:
[C#] 
public partial class SimpleUserControlTaskWebConfigurator: System.Web.UI.UserControl,
    IWebConfigurator, IWebConfiguratorValidation, IDefaultWebConfiguration
{
  1. Open the Web control in design view and create the interface for the UserControlTask configuration. A text box to add the default text and a color picker to change the control's background color has been added. Add the OK and Cancel buttons to accept or cancel the changes. See the following screen shot:


  2. Add member variables to store the values read from the UserControlTask's configuration. See the following code example:
[C#] 
private string defaultText = string.Empty;
private Color backColor;
  1. Register the OK and Cancel button to handle the Asynchronous JavaScript and XML (AJAX) partial postback. Get the reference of the ScriptManager using GetCurrent(Page) and register the buttons. See the following code example:
[C#] 
//Register the buttons to handle asynchronous postback.
if (ScriptManager.GetCurrent(Page) != null)
{
    ScriptManager sm = ScriptManager.GetCurrent(Page);
    sm.RegisterAsyncPostBackControl(btnOk);
    sm.RegisterAsyncPostBackControl(btnCancel);
  1. IWebConfigurator exposes a property called ControlToConfigure that returns a reference to an instance of the UserControlTask being configured. See the following code example:
[C#] 
UserControlTask _controlToConfigure;
public Control ControlToConfigure
{
    get
    {
        return _controlToConfigure;
    }
    set
    {
        if (!(value is UserControlTask))
        {
            throw new ArgumentException();
        }
        _controlToConfigure = value as UserControlTask;
    }
}
  1. Enable the OK and Cancel buttons in the Web configurator control to hook into implementation methods for the IWebConfigurator interface, that is, OnWebConfiguration* event handlers. See the following code example:
[C#] 
protected void cancel_Clicked(object sender, EventArgs args)
{
    //Fire the WebConfigurationCanceled event.
    if (WebConfigurationCanceled != null)
        WebConfigurationCanceled(sender, EventArgs.Empty);
}

protected void ok_Clicked(object sender, EventArgs args)
{
    //Fire the WebConfigurationCompleted event.
    if (WebConfigurationCompleted != null)
    {
        // Parse the JSON string and set the configuartion values.
        _controlToConfigure.Configuration = ToJsonString(); //Helper function. 
        FromJsonstring(_controlToConfigure.Configuration); //Helper function. 
        WebConfigurationCompleted(sender, new WebConfigurationCompleteEventArgs
            (_controlToConfigure, getMarkup(AdditionalControls)));
    }
}
  1. If the custom UserControlTask has already been configured and, for example, you attempt to edit an existing Web application that contains the custom UserControlTask, you'll need to reload the current control settings. The current settings are stored in the configuration attribute in the UserControlTask tag and should be retrieved on Page_Load. See the following code example:
[C#] 
//Populate UI from the task's configuration settings.
if (!ScriptManager.GetCurrent(Page).IsInAsyncPostBack)
{
    if (ControlToConfigure != null && !string.IsNullOrEmpty((ControlToConfigure as
        UserControlTask).Configuration))
        FromJsonstring((ControlToConfigure as UserControlTask).Configuration);
    //Helper function. 
    txtLabelText.Text = defaultText;
    colorPicker.ChosenColor = backColor;
}
  1. Define the custom tags that are added to the page when the custom UserControlTask is written to the Web application created by Manager as shown in the following code example. The getDesignTimeTag() method defines the content of the output, which is essentially a set of strings to declaratively define the custom task control.
[C#] 
private string getMarkup(ControlCollection additionalControls)
{
    #region Find task result control to buddy with
    ArrayList taskResultControls = new ArrayList();
    if (additionalControls != null && additionalControls.Count > 0)
        FindControls(typeof(TaskResults), additionalControls, ref taskResultControls)
            ;
    else
        FindControls(typeof(TaskResults), Page.Controls, ref taskResultControls);
    string taskResultsID = string.Empty;
    if (taskResultControls != null && taskResultControls.Count > 0)
    {
        taskResultsID = (taskResultControls[0] as TaskResults).ID;
    }
    #endregion 

    #region Create tag for task results property
    StringBuilder taskResultsTag = new StringBuilder();
    if (!string.IsNullOrEmpty(taskResultsID))
    {
        taskResultsTag.Append("<TaskResultsContainers>");
        taskResultsTag.AppendFormat("<esri:BuddyControl Name=\"{0}\" />",
            taskResultsID);
        taskResultsTag.Append("</TaskResultsContainers>");
    }
    #endregion 

    #region Create markup for the user control task 
    string color = (backColor == null || backColor == Color.Transparent || backColor
        == Color.Empty) ? "White" : ColorTranslator.ToHtml(backColor);
    return string.Format(
        "<esriTasks:UserControlTask runat=\"server\" Width=\"200px\" Transparency=\"35\" BackColor=\"{0}\" " + "TitleBarColor=\"WhiteSmoke\" TitleBarSeparatorLine=\"False\" TitleBarHeight=\"20px\" Visible=\"False\" " + "BorderColor=\"LightSteelBlue\" BorderStyle=\"Outset\" BorderWidth=\"1px\" Font-Names=\"Verdana\" " + "Font-Size=\"8pt\" ForeColor=\"Black\" TaskControl=\"~/App_Data/UserControlTasks/SimpleTask/SimpleTask.ascx\" Configuration=\"{1}\">", color, _controlToConfigure.Configuration) + taskResultsTag.ToString() + "</esriTasks:UserControlTask>";

    #endregion 
}
  1. Implementing IDefaultWebConfiguration allows users to add a task without configuring it. See the following code example:
[C#] 
public string GetDefaultTag(ControlCollection AdditionalControls)
{
    return getMarkup(AdditionalControls);
}
  1. If there is a need to perform validations, you can implement IConfigurationValidation. In this case, you are not doing any validation; therefore, implementation is simple. See the following code example:
[C#] 
public bool IsConfigurationValid(out string message)
{
    message = string.Empty;
    return true;
}

Deploying a UserControlTask in Manager

Do the following steps to add a custom UserControlTask via ArcGIS Server Manager:
  1. If one does not exist, create a TemplateExtensions folder under ${ArcGIS-Instance}\Manager\Modules\Applications.

  2. If one does not exist, create a UserControlTasks folder under ${ArcGIS-Instance}\Manager\Modules\Applications\TemplateExtensions. See the following screen shot:


  3. Create a folder under UserControlTasks with a unique name to represent the name of the task. Place all the content files (.ascx) and supporting media (JavaScript files, .css files, image files, and so on) under this folder. See the following screen shot:
  4. Add the following code example to the Tasks.xml file under ${ArcGIS-Instance}\Manager\App_Data. The task appears in the Tasks step of the publishing wizard and can be added to Web applications. See the following screen shot:
[XML] 
<Task
  Name="UserControlTask"
  DisplayName="Simple UserControl Task"
  Type="ESRI.ArcGIS.ADF.Web.UI.WebControls.UserControlTask, ESRI.ArcGIS.ADF.Web.UI.WebControls, Version=10.0.0.0, Culture=neutral, PublicKeyToken=8FC3CC631E44AD86"
  TagPrefix="esriTasks"
  TaskControl="SimpleTask/SimpleTask.ascx"/>

Configuring your UserControlTask using a (user control) configurator

Do the following steps to configure the UserControlTask from a server Manager application using a user control configurator. For more information on how to create a configurator control, see the Creating a Web control to configure a custom server task in Manager section in this topic.
  1. If one does not exist, create a TemplateExtensions folder under ${ArcGIS-Instance}\Manager\Modules\Applications .
  2. If one does not exist, create a UserControlConfigurators folder under ${ArcGIS-Instance}\Manager\Modules\Applications\TemplateExtensions .
  3. Create a nested folder that will contain all the elements of your configurator. Use <TaskName>WebConfig (for example, SimpleTaskWebConfig) as the naming convention for this folder. See the following screen shot:
  4. Add all the content files (.ascx) and supporting media (JavaScript files, .css files, image files, and so on) under this folder. See the following screen shot:
  5. Add the following code example to the Tasks.xml file under ${ArcGIS-Instance}\Manager\App_Data:
If you have already added the code example while adding the task, only update the UserControlConfigurator attribute.
[XML] 
<Task
  Name="UserControlTask"
  DisplayName="Simple UserControl Task"
  Type="ESRI.ArcGIS.ADF.Web.UI.WebControls.UserControlTask, ESRI.ArcGIS.ADF.Web.UI.WebControls, Version=10.0.0.0, Culture=neutral, PublicKeyToken=8FC3CC631E44AD86"
  TagPrefix="esriTasks"
  TaskControl="SimpleTask/SimpleTask.ascx"
  UserControlConfigurator="SimpleTaskWebConfig/SimpleTaskWebConfigurator.ascx"/>
  • The task can now be configured in Manager. See the following screen shot:
  • When the application runs and the task is selected, it appears with the default text and color in the configurator. See the following screen shot:


See Also:

Walkthrough: Creating a custom UserControlTask
Walkthrough: Creating a custom server task