Introducing the UserControlTask

With version 9.3.1 of the .NET Web ADF you can use the new UserControlTask to streamline the creation of your own custom tasks. Previously, you would need to create your own class that derived from FloatingPanelTask and take care of the creation and placement of your user interface controls, while paying particular attention to the page lifecycle events as they were raised. With the new UserControlTask, you can create your user interface interactively, in the design view of Visual Studio, and then simply assign a link to it using a property of the UserControlTask called TaskControl.

In Visual Studio, the first thing you'll want to do is right-click your project and choose "Add New Item..." from the menu. When the dialog appears, choose "Web User Control". This will create an empty template for your user control so that you can add whatever controls are necessary to your user interface. You will want to wire up any event handlers for the various user interface controls you added, and be sure to add a mechanism to start the execution of your task (typically a button).

In the code behind page for your control, you will need to make sure your class derives from the new ADF class called UserControlTaskPanel.

public partial class MyCustomTask : UserControlTaskPanel
{
    protected void btnExecute_Click(object sender, EventArgs e)
    {
        object[] input = new object[] { TextBox1.Text, DropDownList1.SelectedValue };
        this.Start(input);
    }

    public override object ExecuteTask(object input)
    {
        // Extract packaged parameters
        object[] parameters = (object[])input;

        string textBoxValue = (string)parameters[0];
        string selectedValue = (string)parameters[1];

        // Perform your task processing
        DateTime now = DateTime.Now;
        string heading = string.Format("The time on the server is {0}:{1:d2}:{2:d2}", 
            now.Hour, now.Minute, now.Second);
        string detail = string.Format("The value in the text box is {0} and the drop down list is {1}.", 
            textBoxValue, selectedValue);

        // Generate result packaged for task results control
        ESRI.ArcGIS.ADF.Web.UI.WebControls.SimpleTaskResult result = 
            new ESRI.ArcGIS.ADF.Web.UI.WebControls.SimpleTaskResult(heading, detail);
        return result;
    }
}

This will allow your code to access the Start method of the base class to begin execution of your task and supply input parameters to your task execution logic. You will need to extract applicable values from your user interface controls and package them as a single object to be used by your execution code. The final step is to implement the abstract ExecuteTask method. Here you will need to make use of the single input parameter object (which contains your packaged input values you passed into the Start method), execute your particular logic, and return a task result so that it can be displayed in a TaskResults control.

To test your task, you simply add a UserControlTask to your page (typically in a TaskManager control) and configure it appropriately. This includes assigning the TaskControl property to point to the location where your .ascx file is located, and likely assigning a value to the TaskResultsContainers property. When your application runs, your user interface should appear, collect user input, execute, and cause the task results to appear in the task results control.

For further reading, see the UserControlTask control overview in the .NET Web ADF Help.

Contributed by John Donahue of the ArcGIS Server .NET Web ADF development team.