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). 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 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 as "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 custom task with the Task configuration framework in Manager, the IWebConfigurator and IBuddyControlSupport interfaces are implemented. Following are 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:
[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:
[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. 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 titlebar 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, we 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 new 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 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—you need to reload the current control settings. Both loadProperties and Refresh enable retrieval of existing custom task control properties as shown in the following code:
[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, a basic implementation of the event handlers is provided. The ControlToConfigure property returns a reference to an instance of the custom task created 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. 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 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 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, 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 (e.g. 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 SDK, open 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 in the context menu. Click the Signing tab and check the Sign the assembly check box. Enter the correct path to the key.
  2. Rebuild the custom task assembly.
Deploy the custom task in Manager
Perform 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 Global Assembly Cache (GAC), navigate to the location of the SimpleServerTask_CSharp.dll file. Use the gacutil.exe utility included with the .NET software development kit (SDK), open 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 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 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, is listed.

    The following table shows the task attribute definitions:
Task attribute
Description
Name
Task class name
DisplayName
Name of the custom task displayed in 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"/>
It is important to note the type tags in two <Task> tags above. CSharp task has only one namespace and VBNet task has two namespaces. Bydefault VBNet creates a rootnamespace and all other namespaces are contained by this rootnamespace. Proper Namespace hierarchy must be used in the "Fully qualified task class name" parameter for Type attribute in Task tag.
    1. Confirm that the Version, Culture, and PublicKeyToken attributes are correct by opening 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's 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 opening 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 manger and login 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 hit "Next".
  4. Add the required layers (services) and click "Next" to go to next step which is configuring task.
  5. Click on "Add Task" option which will display Tasks panel with all the available task. Select Simple Server Task CSharp and add it to the current list of tasks to be included in the Web application.( Refer to the screen shots below)
  1. Highlight the custom task in the Current Tasks window and click the Configure button. The window displayed would appear as seen below:
  1. Set the name of the custom task window, the button text, and the background color of the control.
  1. Upon completion, initialize the custom task in the Web application by expanding the Tasks panel and clicking the custom task in the menu.

    The following screen shot illustrates what you'll see:



See Also:

Introduction to the Task Framework
Creating a custom server task
Creating a custom UserControl task