UserControl task Manager integration

Click here to get the sample associated with this walkthrough.

In this topic

About UserControlTask control integration with Manager

Beginning 9.3.1, we enhanced Manager Support for configuring tasks by allowing the use of usercontrols to configure web tasks which can be configured and deployed in 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 Items list for the task to be available in Manager.
When uninstalling or reinstalling the Web 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 termed as "configurator".   Both 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 custom UserControlTask with the Task configuration framework in Manager, the IWebConfigurator interface is implemented.
IWebConfiguratorValidation and IDefaultWebConfiguration may also be implemented(optionally).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.
Following are steps to accomplish the integration:
  1. Add a new item of type Web User Control in your project and Implement
    IWebConfigurator, IWebConfiguratorValidation, IDefaultWebConfiguration
[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 UserControlTask configuration. A textbox to set the default text and color picker to change the control's background color has been added. Add OK and cancel buttons to accept or cancel the changes. See screen shot below:
  1. Add member variables to store the values read from the usercontroltask's configuration. See code below:
[C#] 
private string defaultText = string.Empty;
private Color backColor;
  1. Register the OK and Cancel button to handle the AJAX partial postback. We can get the reference of the scriptmanager using GetCurrent(page) and register the buttons.
[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 which returns a reference to an instance of the usercontroltask being configured.
[C#] 
UserControlTask _controlToConfigure;
public Control ControlToConfigure
{
    get
    {
        return _controlToConfigure;
    }
    set
    {
        if (!(value is UserControlTask))
        {
            throw new ArgumentException();
        }
        _controlToConfigure = value as UserControlTask;
    }
}
  1. The next step is to enable OK and Cancel buttons in the webconfigurator control to hook into implementation methods for the IWebConfigurator Interface , namely OnWebConfiguration* event handlers.
[C#] 
protected void cancel_Clicked(object sender, EventArgs args)
{
    //Fire WebConfigurationCanceled event
    if (WebConfigurationCanceled != null)
        WebConfigurationCanceled(sender, EventArgs.Empty);
}

protected void ok_Clicked(object sender, EventArgs args)
{
    //Fire 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—for example, you attempt to edit an existing Web application that contains the custom usercontroltask—you need to reload the current control settings. The current settings are stored in configuration attribute in the usercontrolask tag and should be retrieved on page_load.
[C#] 
//Populate UI from 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 out to the Web application created by Manager as shown in the following code. 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 would allow users to add a task without configuring it.
[C#] 
public string GetDefaultTag(ControlCollection AdditionalControls)
{
    return getMarkup(AdditionalControls);
}
  1. If there is a need to perform validations then you may need to implement IConfigurationvalidation. In this case we are not doing any validation so implementation is simple.
[C#] 
public bool IsConfigurationValid(out string message)
{
    message = string.Empty;
    return true;
}
Deploying UserControlTask in Manager
This section would step through the process of adding custom usercontrol task via ArcGIS Server manager Application.
  1. Create a TemplateExtensions folder under ${ArcGIS-Instance}\Manager\Modules\Applications Applications (If one doesn’t already exist).

  2. Create a UserControlTasks folder under ${ArcGIS-Instance}\Manager\Modules\Applications\TemplateExtensions Applications (If one doesn’t already exist).

  3. Create a folder under UserControlsTasks 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 etc) under this folder.
 
  1. Add the following entry to Tasks.xml under ${ArcGIS-Instance}\Manager\App_Data. Task should now show up in the 'Tasks' step of the publishing wizard and can be added to web applications.
[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
This section would step through the process of configuring UserControlTask from a Server manager Application using a user-control configurator. For reference of how to create a configurator control refer to Creating a Web control to configure a custom server task in Manager section.
  1. Create a TemplateExtensions folder under ${ArcGIS-Instance}\Manager\Modules\Applications (If one doesn’t already exist) .
  2. Create a UserControlConfigurators folder under ${ArcGIS-Instance}\Manager\Modules\Applications\TemplateExtensions Applications (If one doesn’t already exist).

  3. Create a nested Folder which will contain all the elements of your configurator. Recommended naming convention for this folder is <Task-Name>Webconfig.

 

 

 
  1. Add all the content files (.ascx) and supporting media (javascript files, css files, image files etc) under this folder.
 
 
  1. Add the following entry to Tasks.xml under ${ArcGIS-Instance}\Manager\App_Data.
If you have already added this entry while adding the task then only update 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"/>
Your task can now be configured within Manager.
 
When the application is run and task is selected it will show up with default text and color set in the configurator.


See Also:

Creating a custom UserControl task
Creating a custom server task