Server task Manager integration

In this topic

About task framework integration with Manager

The Web application developer framework (ADF) task framework enables a custom task to be integrated into the ArcGIS Manager (Manager) Web application building framework. 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). 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 server task 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 "configurator."  Both the custom task and configurator must be deployed in Manager to use and configure the custom task. 

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

To integrate a custom task with the Task configuration framework in Manager, the IWebConfigurator and IBuddyControlSupport interfaces are implemented. Do the following steps to accomplish the integration:
  1. Create a class called SimpleServerTaskWebConfigurator_CSharp and add a reference to System.Web.dll, System.Drawing.dll, and ESRI.ArcGIS.ADF.Web.UI.WebControls.dll. The namespace is SimpleServerTask_CSharp. See the following code example:
[C#] 
using System;
using System.Collections.Generic;
using System.Text;
using System.Web.UI;
using System.Collections.Specialized;
using System.Web.UI.WebControls;
using System.Drawing.Design;
using System.ComponentModel;
using System.Collections;
using System.Web.UI.HtmlControls;
using ESRI.ArcGIS.ADF.Web.UI.WebControls;
namespace SimpleServerTask_CSharp
{
    public class SimpleServerTaskWebConfigurator_CSharp:
        ESRI.ArcGIS.ADF.Web.UI.WebControls.CompositeControl, IWebConfigurator,
        IBuddyControlSupport
    {
  1. Add member variables to store references to the controls in the Web configurator interface as shown in the following code example:
[C#] 
private Button m_okButton = null;
private Button m_cancelButton = null;
private TextBox m_buttonTextBox = null;
private TextBox m_titleTextBox = null;
private ColorPicker m_backgroundColorPicker = null;
private ColorPicker m_titleColorPicker = null;
private SimpleServerTask_CSharp m_simpleTaskInstance = null;
  1. Override the CreateChildControls() method to create the run time interface of the Web configurator control as shown in the following code example. This process is similar to creating the interface for the custom task. However, there is no visual designer for this process, so manually formatting the control programmatically is required. The Web configurator contains two text boxes to change the title of the custom task floating panel and the button text, two buttons to approve or cancel the changes, and two ColorPicker controls to interactively select the background color and title bar color of the control in the Web application at run time.
[C#] 
protected override void CreateChildControls()
{
    Controls.Clear();
    // Create a table to hold the controls that will appear on the interface.
    Table taskConfiguratorTable = new Table();
    taskConfiguratorTable.Style[System.Web.UI.HtmlTextWriterStyle.Position] = 
        "relative";
    Controls.Add(taskConfiguratorTable);

    // Initialize the title label.
    Label titleTextLabel = new Label();
    titleTextLabel.ID = "lblTitle";
    titleTextLabel.Text = "Title:";

    // Add the title label to a table cell.
    TableCell taskConfiguratorCell = new TableCell();
    taskConfiguratorCell.Controls.Add(titleTextLabel);

    // Add the table cell to a table row.
    TableRow taskConfiguratorRow = new TableRow();
    taskConfiguratorRow.Controls.Add(taskConfiguratorCell);

    // Initialize the title textbox.
    m_titleTextBox = new TextBox();
    m_titleTextBox.ID = "txtTitle";

    // Add the title textbox to a table cell and the table cell to a table row.
    taskConfiguratorCell = new TableCell();
    taskConfiguratorCell.Controls.Add(m_titleTextBox);
    taskConfiguratorRow.Controls.Add(taskConfiguratorCell);

    // Add the row containing the title label and textbox to the table.
    taskConfiguratorTable.Controls.Add(taskConfiguratorRow);

    // Initialize the button text label.
    Label buttonTextLabel = new Label();
    buttonTextLabel.ID = "lblButtonText";
    buttonTextLabel.Text = "Button Text:";
    buttonTextLabel.Style[System.Web.UI.HtmlTextWriterStyle.WhiteSpace] = "nowrap";

    // Add the button text label to a table cell and the table cell to a table row.
    taskConfiguratorCell = new TableCell();
    taskConfiguratorCell.Controls.Add(buttonTextLabel);
    taskConfiguratorRow = new TableRow();
    taskConfiguratorRow.Controls.Add(taskConfiguratorCell);

    // Initialize the button text textbox.
    m_buttonTextBox = new TextBox();
    m_buttonTextBox.Text = "Execute";
    m_buttonTextBox.ID = "txtButton";

    // Add the button text textbox to a table cell and the cell to a table row.
    taskConfiguratorCell = new TableCell();
    taskConfiguratorCell.Controls.Add(m_buttonTextBox);
    taskConfiguratorRow.Controls.Add(taskConfiguratorCell);

    // Add the row containing the button text label and textbox to the table.
    taskConfiguratorTable.Controls.Add(taskConfiguratorRow);
    // Initialize the title bar color picker.
    m_titleColorPicker = new ESRI.ArcGIS.ADF.Web.UI.WebControls.ColorPicker();
    m_titleColorPicker.ID = "clrPkrTitle";
    m_titleColorPicker.Font.Name = "Verdana";
    m_titleColorPicker.Font.Size = new FontUnit(new Unit(8, UnitType.Point));
    m_titleColorPicker.BackColor = System.Drawing.Color.White;
    m_titleColorPicker.DropDownBorderColor = System.Drawing.Color.Silver;
    m_titleColorPicker.DropDownBorderStyle = BorderStyle.Solid;
    m_titleColorPicker.DropDownBorderWidth = new Unit(1, UnitType.Pixel);
    m_titleColorPicker.ChosenColor = System.Drawing.Color.White;
    m_titleColorPicker.ShowColorNames = false;
    m_titleColorPicker.DisplayText = "Title Bar Color:";

    // Add the title color picker to the Web configurator's control's collection. Note that,
    // for formatting purposes, do not add the color picker to the table.
    Controls.Add(m_titleColorPicker);

    // Initialize the background color picker and add it to the Web configurator's controls.
    m_backgroundColorPicker = new ESRI.ArcGIS.ADF.Web.UI.WebControls.ColorPicker();
    m_backgroundColorPicker.ID = "clrPkrBackground";
    m_backgroundColorPicker.Font.Name = "Verdana";
    m_backgroundColorPicker.Font.Size = new FontUnit(new Unit(8, UnitType.Point));
    m_backgroundColorPicker.BackColor = System.Drawing.Color.White;
    m_backgroundColorPicker.DropDownBorderColor = System.Drawing.Color.Silver;
    m_backgroundColorPicker.DropDownBorderStyle = BorderStyle.Solid;
    m_backgroundColorPicker.DropDownBorderWidth = new Unit(1, UnitType.Pixel);
    m_backgroundColorPicker.ChosenColor = System.Drawing.Color.White;
    m_backgroundColorPicker.ShowColorNames = false;
    m_backgroundColorPicker.DisplayText = "Background Color:";
    Controls.Add(m_backgroundColorPicker);

    // Initialize the OK button.
    m_okButton = new Button();
    m_okButton.ID = "btnOK";
    m_okButton.Text = "OK";
    m_okButton.Click += new System.EventHandler(okButton_Click);

    // Add the OK button to a table cell and the cell to a table row.
    taskConfiguratorCell = new TableCell();
    taskConfiguratorCell.Controls.Add(m_okButton);
    taskConfiguratorCell.Style[System.Web.UI.HtmlTextWriterStyle.Width] = "50%";
    taskConfiguratorRow = new TableRow();
    taskConfiguratorRow.Controls.Add(taskConfiguratorCell);

    // Initialize the Cancel button.
    m_cancelButton = new Button();
    m_cancelButton.ID = "btnCancel";
    m_cancelButton.Text = "Cancel";
    m_cancelButton.Click += new System.EventHandler(cancelButton_Click);

    // Add the Cancel button to a table cell and the cell to a table row.
    taskConfiguratorCell = new TableCell();
    taskConfiguratorCell.Controls.Add(m_cancelButton);
    taskConfiguratorCell.Style[System.Web.UI.HtmlTextWriterStyle.Width] = "50%";
    taskConfiguratorRow.Controls.Add(taskConfiguratorCell);

    // Create a table to hold the OK and Cancel buttons.
    taskConfiguratorTable = new Table();
    taskConfiguratorTable.Style[System.Web.UI.HtmlTextWriterStyle.Width] = "100%";
    taskConfiguratorTable.Style[System.Web.UI.HtmlTextWriterStyle.TextAlign] = 
        "center";

    // Add the row containing the OK and Cancel buttons to the new table.
    taskConfiguratorTable.Controls.Add(taskConfiguratorRow);

    // Add the table to the Web configurator's controls.
    Controls.Add(taskConfiguratorTable);
}
  1. The following code example shows methods that enable the Web configurator to work within events in the Manager Web application. The OK and Cancel buttons in the Web configurator control call events that hook into implementation methods for the IWebConfigurator interface, namely the OnWebConfiguration* event handlers. Since the control operates with a Web application, it can override page events to initialize and update Web configurator properties.
[C#] 
void cancelButton_Click(object sender, EventArgs e)
{
    OnWebConfigurationCancel(new EventArgs());
}

private void okButton_Click(object sender, EventArgs e)
{

    if (m_simpleTaskInstance == null)
        return ;
    m_simpleTaskInstance.Title = m_titleTextBox.Text;
    m_simpleTaskInstance.ButtonText = m_buttonTextBox.Text;
    m_simpleTaskInstance.BackColor = m_backgroundColorPicker.ChosenColor;
    m_simpleTaskInstance.TitleBarColor = m_titleColorPicker.ChosenColor;
    OnWebConfigurationComplete(new
        ESRI.ArcGIS.ADF.Web.UI.WebControls.WebConfigurationCompleteEventArgs
        (m_simpleTaskInstance, getDesignTimeTag()));
}

protected override HtmlTextWriterTag TagKey
{
    get
    {
        return HtmlTextWriterTag.Div;
    }
}

protected override void OnLoad(EventArgs e)
{
    base.OnLoad(e);
}

protected override void OnPreRender(EventArgs e)
{
    base.OnPreRender(e);
    if (!base.IsAsync)
    {
        loadProperties();
    }
}
  1. If the custom task has already been configured—for example, you attempt to edit an existing Web application that contains the custom task—reload the current control settings. Both loadProperties and Refresh enable retrieval of existing custom task control properties as shown in the following code example:
[C#] 
private void loadProperties()
{

    if (m_simpleTaskInstance == null)
        return ;
    m_titleTextBox.Text = m_simpleTaskInstance.Title;
    m_buttonTextBox.Text = m_simpleTaskInstance.ButtonText;
    m_backgroundColorPicker.ChosenColor = m_simpleTaskInstance.BackColor;
    m_titleColorPicker.ChosenColor = m_simpleTaskInstance.TitleBarColor;
}

public override void Refresh()
{
    loadProperties();
    base.Refresh();
}
  1. Implement a set of IWebConfiguratior properties and methods. In the following code example, a basic implementation of the event handlers is provided. The ControlToConfigure property returns a reference to an instance of the created custom task when the custom task was added to the Current Tasks panel in Manager.
[C#] 
private ControlCollection controls = null;

public ControlCollection AdditionalControls
{
    get
    {
        return controls;
    }
    set
    {
        controls = value;
    }
}

public Control ControlToConfigure
{
    get
    {
        return m_simpleTaskInstance;
    }
    set
    {
        if (!(value is SimpleServerTask_CSharp))
        {
            throw new ArgumentException();
        }
        m_simpleTaskInstance = value as SimpleServerTask_CSharp;
    }
}

public bool ValidateResources(out string message)
{
    message = null;
    return true;
}

private WebConfigurationCompleteEventHandler onWebConfigurationComplete;
public event WebConfigurationCompleteEventHandler WebConfigurationCompleted
{
    add
    {
        onWebConfigurationComplete += value;
    }
    remove
    {
        onWebConfigurationComplete -= value;
    }
}

protected virtual void OnWebConfigurationComplete(WebConfigurationCompleteEventArgs
    args)
{
    if (onWebConfigurationComplete != null)
        onWebConfigurationComplete(this, args);
}

private WebConfigurationCanceledEventHandler onWebConfigurationCancel;
public event WebConfigurationCanceledEventHandler WebConfigurationCanceled
{
    add
    {
        onWebConfigurationCancel += value;
    }
    remove
    {
        onWebConfigurationCancel -= value;
    }
}

protected virtual void OnWebConfigurationCancel(EventArgs args)
{
    if (onWebConfigurationCancel != null)
        onWebConfigurationCancel(this, args);
}
  1. Implementing the IBuddyControlSupport interface involves implementing the GetSupportedBuddyControlTypes() method as shown in the following code example. This method returns the types of controls that another control can buddy with. In this case, the Web configurator control can buddy with the custom task control, enabling the Web configurator to get a reference to the custom task instance.
[C#] 
public Type[] GetSupportedBuddyControlTypes()
{
    Type[] types = new Type[1];
    types[0] = typeof(SimpleTask_CSharp);
    return types;
}
  1. Define the custom tags that are added to the page when the custom task 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 getDesignTimeTag()
{

    string simpleTaskOpenTag = string.Format(
        "<simpleServerTaskCS:SimpleServerTask_CSharp ID=\"{0}\" " + 
        "runat=\"server\" Style=\"z-index: 10000; left: 100px; position: absolute; "
        + 
        "top: 100px\" Width=\"200px\" Visible=\"False\" ButtonText=\"{1}\" Title=\"{2}\" " + "ToolTip=\"{3}\" NavigationPath=\"{4}\" BackColor=\"{5}\" TitleBarColor=\"{6}\" " + "BorderStyle=\"Solid\" BorderWidth=\"1px\" BorderColor=\"Black\">", m_simpleTaskInstance.ID, m_simpleTaskInstance.ButtonText, m_simpleTaskInstance.Title, m_simpleTaskInstance.ToolTip, m_simpleTaskInstance.NavigationPath, System.Drawing.ColorTranslator.ToHtml(m_simpleTaskInstance.BackColor), System.Drawing.ColorTranslator.ToHtml(m_simpleTaskInstance.TitleBarColor));


    System.Text.StringBuilder taskResultsContainerTagStringBuilder = new
        System.Text.StringBuilder();
    taskResultsContainerTagStringBuilder.Append("<TaskResultsContainers>");
    taskResultsContainerTagStringBuilder.Append(
        "<esri:BuddyControl Name=\"TaskResults1\" />");
    taskResultsContainerTagStringBuilder.Append("</TaskResultsContainers>");

    string simpleTaskCloseTag = "</simpleServerTaskCS:SimpleServerTask_CSharp>";

    System.Text.StringBuilder completeTagStringBuilder = new
        System.Text.StringBuilder();
    completeTagStringBuilder.Append(simpleTaskOpenTag);
    completeTagStringBuilder.Append(taskResultsContainerTagStringBuilder.ToString());
    completeTagStringBuilder.Append(simpleTaskCloseTag);
    return completeTagStringBuilder.ToString();

}
  1. The custom Web configurator class is complete. Associate the Web configurator with the task class by using the WebConfigurator attribute to specify the name of the Web configurator class (SimpleServerTaskWebConfigurator_CSharp). In the following code example, only one new line referencing the WebConfigurator attribute has been added to the existing content:
[C#] 
namespace SimpleServerTask_CSharp
{
    [System.Web.UI.ToolboxData(
        "<{0}:SimpleServerTask_CSharp runat=\"server\" Width=\"100px\" BorderWidth=\"1px\"><TaskResultsContainers><esri:BuddyControl Name=\"TaskResults1\" /></TaskResultsContainers> </{0}:SimpleServerTask_CSharp>")][Designer(typeof(SimpleServerTaskDesigner_CSharp))]
    // Specifies the class used to configure the task in ArcGIS Manager.
    [ESRI.ArcGIS.ADF.Web.UI.WebControls.WebConfigurator(typeof
        (SimpleServerTaskWebConfigurator_CSharp))]
    // Specifies the image used to represent the task in a container (for example, the Visual Studio toolbox).
    [System.Drawing.ToolboxBitmap(typeof(SimpleServerTask_CSharp))]
    public class SimpleServerTask_CSharp: FloatingPanelTask
    {
  1. Sign the custom task assembly so it can be added to the global assembly cache (GAC). Signing the assembly makes it easier to distribute and register with Manager. To sign the assembly, generate a signed key. Using the sn.exe utility included with the .NET software development kit (SDK), start a Visual Studio 2008 command prompt and type the following:
[C#] 
sn - k MyKeyPair.snk
  1. In Visual Studio, right-click the custom task class library project in the Solution Explorer window and select Properties. Click the Signing tab and select the Sign the assembly check box. Add the correct path to the key.
  2. Rebuild the custom task assembly.

Deploy the custom task in Manager

Do the following steps to deploy a custom task for use in Manager. The steps are the same whether you created the custom task and have the source code or you were provided the custom task assembly from another party.
  1. To add the custom task assembly to the GAC, navigate to the location of the SimpleServerTask_CSharp.dll file. Use the gacutil.exe utility included with the .NET SDK, start a Visual Studio 2008 command prompt, and type the following:
[C#] 
gacutil - i SimpleServerTask_CSharp.dll
  1. If you change the custom task, update the GAC using the -if option with gacutil.exe. Optionally, automate reinstalling the custom task assembly to the GAC by modifying the pre-build and post-build events in Visual Studio. Use the following steps to configure this option:
    1. In Visual Studio, open the property page for the custom task project.
    2. Add the following code example to the pre-build event command line text box:
[C#] 
call "%VS90COMNTOOLS%vsvars32.bat"

gacutil - u $(TargetName)
The first line initializes the command line environment for the .NET Framework tools. The second line uninstalls the existing custom task assembly from the GAC.
    1. Add the following code example to the post-build event command line text box:
[C#] 
call "%VS90COMNTOOLS%vsvars32.bat"

gacutil - if "$(TargetPath)"

iisreset
Again, the first line initializes the command line environment for the .NET Framework tools. The second line installs the existing custom task assembly into the GAC. The last line restarts Microsoft Internet Information Services (IIS) and is optional. It assumes that task development and run time testing occur on the same machine.
    1. Restart IIS because ASP.NET Web applications can work with a cached copy of an assembly in the GAC (for example, a custom task control); otherwise, the most recent task modifications might not be accessible during run time testing.
  1. Add the custom task information to the Tasks.xml used by Manager. A series of task elements, one for each task control available in Manager shows.

    The following table shows the task attribute definitions:
Task attribute
Description
Name
Task class name
DisplayName
Name of the custom task shown on the Manager dialog box to add and configure a task
Type
Contains the following five comma-delimited parameters (listed in order):
  • Fully qualified task class name
  • Name of the assembly that contains the task classes and resources
  • Version number of the assembly
  • Culture of the assembly
  • PublicKeyToken of the assembly. Defined by the key used to sign the assembly.
TagPrefix
The tag prefix name assigned to the task control. Defined by the TagPrefix attribute of the assembly.
    1. In the App_Data folder for the Manager Web application (for example, C:\Inetpub\wwwroot\ArcGIS\Manager\App_Data), open the Tasks.xml file in a text editor and add the following line within the <Tasks> tags (confirm that the assembly version is correct):
[XML] 
<Task
  Name="SimpleServerTask_CSharp"
  DisplayName="Simple ServerTask CSharp"
  Type="SimpleServerTask_CSharp.SimpleServerTask_CSharp, SimpleServerTask_CSharp, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8ae5220d89bb5443"
  TagPrefix="simpleServerTaskCS"/>
<Task
  Name="SimpleServerTask_VBNet"
  DisplayName="Simple ServerTask VB Net"
  Type="Commom_SimpleServerTask_VBNet.Commom_SimpleServerTask_VBNet.SimpleServerTask_VBNet, SimpleServerTask_VBNet, Version=1.0.0.0, Culture=neutral, PublicKeyToken=195c10c6b8411b40"
  TagPrefix="simpleServerTaskVB"/>
In the preceding XML code example, it is important to note the Type tags in the two <Task> tags. The CSharp task has only one namespace and the VBNet task has two namespaces. By default, the VBNet task creates a root namespace and all other namespaces are contained by this root namespace. Proper namespace hierarchy must be used in the "Fully qualified task class name" parameter for the Type attribute in the Task tag.
    1. Confirm that the Version, Culture, and PublicKeyToken attributes are correct by starting a Visual Studio 2008 command prompt and typing the following:
[C#] 
gacutil - l SimpleServerTask_CSharp
Custom entries in the Tasks.xml file are overwritten when the Web application developer framework (ADF) is uninstalled or reinstalled. Consequently, you must retain or re-add the entries using one of the following options:
    • Manual reentry—Manually reentering the custom task items works, but it is a labor intensive and potentially error-prone option. This is an option for custom task developers.
    • Retain Tasks.xml with custom task entries—Store the custom Tasks.xml in another location (other than the install location), reinstall, and copy it to the appropriate Manager location. This option is also error prone since it relies on manually copying a file from one location to another. In addition, it is only successful if the Web ADF version remains the same. Again, this is only a reliable option for custom task developers.
    • Create a custom task deployment setup—Create a setup application to configure your custom task. This is the best option for distribution since an end user only needs to run a custom task setup program included with the custom task. The installation and setup of the custom task manages the addition of the custom task item in Tasks.xml. This option requires additional work for the custom task developer (for example, creating a setup application) but provides a more familiar end user experience.
  1. Restart IIS (for Manager to recognize the changes) by starting a Visual Studio 2008 command prompt and typing the following:
[C#] 
iisreset
ArcGIS Server Manager provides you with the ability to configure the custom task while designing a new Web application.
  1. Open ArcGIS Server Manager and log in using valid credentials.
  2. From the Applications tab, select Web Applications and choose  Create Web Application.
  3. Specify the name of the application you want to create and click Next.
  4. Add the required layers (services) and click Next to go to the next step, which is configuring the task.
  5. Click the Add Task option. The Available Task panel shows with all of the available tasks.
  6. Select Simple Server Task CSharp and add it to the current list of tasks to be included in the Web application. See the following screen shots:


  7. Highlight the custom task in the current Tasks window and click Configure. The following appears:


  8. In the Title text box, add the name of the custom task window. In the Button Text area, add the name for the button text. Set the title bar and background color for the control. See the following screen shot:


  9. Upon completion, initialize the custom task in the Web application by expanding the Tasks panel and clicking the custom task in the menu. See the following screen shot:



See Also:

Working with the Task Framework
Walkthrough: Creating a custom server task
Walkthrough: Creating a custom UserControl task