Common Custom tasks

Purpose

This sample illustrates a range of techniques for developing custom tasks using the task framework included with the Web Application Developer Framework (ADF). The task framework is unique to the Web ADF and is not inherently dependent on a specific data source. Each task in this sample is placed in its own assembly (Visual Studio project) and has a companion Web page to demonstrate the task's functionality. This sample includes the following task examples:

• AsyncTask—Illustrates how to submit a job for asynchronous processing, return control to the client, check the job status, and return the job's results once it is complete.
• EmbeddedResourcesTask—Demonstrates how to register and use Web resources, such as images and JavaScript files.
• PostBackTask—Shows several techniques for invoking and handling asynchronous requests using callbacks and partial postbacks.
• ScriptTask—Includes a "super class" task implementation that enables subclasses to easily make server-side functionality scriptable. Allows server-side properties and methods to be invoked from the client with minimal code and is compatible with callbacks and partial postbacks. Especially useful for tasks that have several functions requiring requests to the server.
• QueryBuilderTask—Illustrates a fully fleshed out implementation of a ScriptTask that has several interdependent controls for input specification. Enables construction and execution of queries at run time.
• FindNearTask—Demonstrates a FloatingPanelTask implementation with a number of advanced features. Includes a toolbar that enables run time specification of a search area through interactions with buddied Map and TaskResults controls, and allows cumulative merging of search areas as new areas are specified. Shows how task results can be displayed in a table embedded in a floating panel.
• OptimizeTask—Demonstrates how to minimize the amount of overhead required to create a task and its child controls. By default, each Web request to a page reconstructs the page and its contents, including a task control and its child controls. If the Web request does not require the construction of a task (for example, the task or a subcomponent is not involved in processing the request), you can skip its construction. This saves valuable request processing time, especially if your task is notably complex. An optimizer class (AsyncOptimizer) is utilized in the task's CreateChildControls method to determine if child control creation is necessary.

How to use

If the sample has associated data, you will find that the sample's zip file includes a "data" folder alongside the language folders. However, you will need to update the sample to point to the location of the data once you have extracted all the files.

1. Verify that the Web ADF for the .NET Framework is installed and functioning properly. For information on installing and configuring the Web ADF, consult the installation guide.
2. In Windows Explorer, navigate to <ArcGIS Developer Kit install location>\Samples\ServerNET. This folder contains the Common_CustomTasks_CSharp and Common_CustomTasks_VBNet folders.
3. Open the folder of the language you are going to use (that is, CSharp or VBNet) and copy the Common_CustomTasks_<language> folder to c:\inetpub\wwwroot. The <language> variable can be CSharp or VBNet.
4. Open the IIS Manager from Control Panel, Administrative Tools, Internet Information Services (IIS) Manager, or Internet Information Services.
5. In the console tree view on the left, navigate to Local Computer, Web Sites, Default Web Site. Expand Default Web Site, open the Common_CustomTasks_<language> folder, right-click the CustomTasksWebSite folder, and click Properties. The Properties dialog box appears.
6. Click the Directory tab, click the Create button in the Application Settings section, then click OK to close the Properties dialog box.
7. Start Visual Studio 2010 and open solution file for the Common_CustomTasks_CSharp sample Common_CustomTasks_CSharp2010.sln located in the c:\inetpub\wwwroot\Common_CustomTasks_CSharp folder.
8. In the Solution Explorer, right-click the CustomTasksWebSite project, and select Set as StartUp Project.
9. Right-click the page you want to view and select Set As Start Page.
10. The pages in this sample are configured to use the USA and NorthAmerica map services, and it is assumed that USA service is running on the local machine (localhost) while NorthAmerica is accessed online. You can create these services by publishing the map documents located at <ArcGIS Developer Kit install location>\Samples\data. Usa.mxd is in the USA folder. For instructions on how to publish a map document to ArcGIS for Server, see "Publishing a GIS resource to the server" in the ArcGIS for Server Help. The sample also uses the following uniform resource locator (URL) for geometry tasks such as buffer (http://tasks.arcgisonline.com/arcgis/services/Geometry/GeometryServer).
11. If these services are running on a remote machine, specify the proper location by opening the page you want to view in Design view, open the properties window for the MapResourceManager control, and click the ellipsis next to the ResourceItems property. The ResourceItem Collection Editor dialog box appears.
12. Click the ellipsis next to the Definition property. The Map Resource Definition Editor dialog box appears.
13. In the Data Source field, replace localhost with the name of the machine hosting the service.
14. If necessary, set the run time identity of the Web application by following one of the next two steps. If not necessary, proceed to Step 17.
15. At design time, the identity of the user running Visual Studio is used to connect to an ArcGIS for Server local data source. At run time, that identity is established by the Web application. Only one identity can be used to define access to the ArcGIS for Server local data sources in a single Web application. This identity can be explicitly defined when building the Web ADF application in Visual Studio by right-clicking the Web project in the Solution Explorer and selecting the Add ArcGIS Identity option. Add the identity credentials that will be used to access ArcGIS for Server local resources at run time. This information is added to the web.config file in a standard ASP.NET identity tag. If the Encrypt identity in web.config check box is selected, the identity tag will be encrypted; otherwise, the username and password are stored as clear text.
16. Open the web.config file and add an <identity> element in <system.web>, set the impersonate attribute to true, add a username and password attribute, and set them to a valid user account. If you are working with ArcGIS for Server local data sources, ensure the account has access to the geographic information system (GIS) server resources referenced in the Map control.
17. Save the solution. This sample includes pre-built custom task assemblies, and the appropriate statements in each corresponding .aspx file to load and utilize these custom tasks. To rebuild a custom task control, see the following "Rebuild a custom task control" section.

1. Each task's source code is in the <task name>_<language> class library project, for example, EmbeddedResourcesTask_CSharp. Build the custom task control by right-clicking the project and selecting Build.
2. Open the corresponding Web page in Design view. The name of the corresponding Web page is in the form <task name>WebPage, for example, EmbeddedResourcesTaskWebPage.
3. Right-click the General tab on the Visual Studio toolbox, select Choose Items, and navigate to the location of the assembly (<task name>_<language>.dll) generated in the previous step (for example, c:\inetpub\wwwroot\Common_CustomTasks_<language>\CustomTasksWebSite\bin\Debug). A new control reference with the name <task name>_<language> is available in the Visual Studio toolbox.
4. If a custom task control has already been added to the TaskManager control in the page, delete it, drag the new task control into the TaskManager, then set its TaskResults container property to the TaskResults1 control on the page.
5. Click the Debug drop-down menu and click Start Debugging.

1. Open a browser and add the URL of the page you want to view. For example, http://localhost/Common_CustomTasks_CSharp/CustomTasksWebSite navigates to the root of the sample Web site.
2. Use the custom task Web pages as outlined in the following "Async task Web page" section.

1. Access AsyncTaskWebPage.aspx.
2. Click the Execute button several times. The task result nodes change from an executing message, to a submitted message, to a succeeded message.

1. Access EmbeddedResourcesTaskWebPage.aspx.
2. Click the Change Image button. The image changes. The images and the JavaScript that changes them were included in the task as embedded resources.

1. Access PostBackTaskWebPage.aspx.
2. The PostBackTask has three buttons that all have similar effects. The instructive part of this example is the different ways those effects are achieved. To see this, place breakpoints and step through the code for each button.
3. Add a ScriptManager to the page (enabling partial postbacks) and step through the code again.

1. Access ScriptTaskWebPage.aspx.
2. Type the name of a map service running locally into the text box and click Get Layers. The task result appears on the bottom of the task interface. The task execution and interface update are both done through server-side members that have been made scriptable.
3. Type something that is not the name of a map service and click Get Layers. An error message appears on the task interface.

1. Access QueryBuilderTaskWebPage.aspx.
2. Change the layer. Note the cascading changes to the Fields and Sample Values. This behavior is initiated via scriptable server-side members.
3. Change the field. The Sample Values are updated.
4. Click the Add to Query button. The selected values in the drop-down lists have been turned into a query expression and placed in the Query text box.
5. Click the Execute Query button. The results display.
6. Click Switch Maps in the upper right corner of the page. The task's drop-down lists are updated with information pertaining to the California service.

1. Access FindNearTaskWebPage.aspx.
2. Click the Define search area by point tool, and click a point on the map.
3. Change the units to miles. The search area is updated.
4. Change the search distance to 300. The search area is updated.
5. Click the Define search area by polyline tool, click several points on the map to draw a polyline, and double-click when finished. The search area is updated to include a buffer around the polyline.
6. Click the Define search area by polygon tool, draw the polygon on the map, and double-click when finished. The search area is updated to include a buffer around the polygon.
7. Click Find on the Query Counties task. The task executes and finds six counties.
8. In the TaskResults control, click the Query Counties node, then click the Counties child node. The feature nodes for the six counties that were found appear.
9. On FindNearTask, select the tool to specify the search area by task result.
10. Click one of the county task result nodes. The search area updates to include a buffer around the county corresponding to the node that was clicked.
11. Click the tool to define a search area by selecting features from the map.
12. In the drop-down list that appears, choose States as the selection layer.
13. On the map, click and drag a small box over a few states. The search area is updated with a buffer around the selected states.
14. From the Search Layer drop-down list, select States.
15. Click the Find button. The states intersecting the buffer are selected and the task results appear in a floating panel.
16. On FindNearTask, click the command to clear input features from the map. Input features and buffers are removed, but the task results remain.

1. Access FindNearUserControlTaskWebPage.aspx.
2. All the functionality is same as provided by the Find Near task Web page. The only difference is that the Find Near task on this page is a user control task that is plugged into the out-of-the box UserControlTask control.

1. Access OptimizerTaskWebPage.aspx.
2. Add a value in the text box in the task, and click the button to execute the task. The task iterates through the CreateChildControls method and generates output for the TaskResults control.
3. Click a tool in the toolbar to zoom in or out on the map.
4. Apply the tool in the map. The child controls for the task are not created (step through the code in debug mode to view this).
5. Click the callback or partial postback button in the task. The task iterates through the CreateChildControls method and processes the async request. The map zooms in by a factor of two (2). Even though the task did not process the async request, one of its child controls did, so iterating through CreateChildControls was necessary.

Download the files for all languages