2010年8月12日_周四_UserControlTask control

/**********************************************************************/

//UserControlTask control

//2010年8月14日

/**********************************************************************/
ADF tasks have traditionally been associated with server controls - redistributable bits of logic that can be integrated with Manager and leverage the ADF task framework.  The base class for tasks include with the ADF is FloatingPanelTask, a server control.  Server control development can be quite complex since the controls are designed to be application agnostic（不可知论的） and inherently distributable, thus more flexible. One major drawback is that the structure of the task's visual interface must be constructed programmatically.  In this area, page developers have the luxury of working within the context of a page, for which Visual Studio provides a rich, interactive visual design time experience.  For page developers, one technique for isolating related actions visually within the context of a single application is a User control. It offers the same visual experience and structure as a page.  The UserControlTask control enables you to integrate an ASP.NET User control as a task within an ADF application.   The Web ADF task framework includes a base class, ESRI.ArcGIS.ADF.Web.UI.WebControls.UserControlTaskPanel, you can subclass in an ASP.NET User control to gain access to task framework behavior and capabilities. 

ADF tasks一直以来都和server端控件联系在一起，重复着一个逻辑，ADF task可以和管理者之间进行交互和影响着ADF task框架。Task 的基础类是FloatingPanelTask，并且FloatingPanelTask 是一个server控件。 Server控件的发展会更加复杂，因为server控件被设计为应用程序不可知论的和内部分配的，因此也更加的灵活。对于task的可视化界面来说一个主要的缺点是它必须使用代码来创创建。在这个区域，页面开发者拥有可以在页面内容中工作的奢侈享受，这是因为VS提供了一个丰富的、互动的设计体验。对于页面开发者来说，可视化的区分一个单独应用程序中的相关动作的技术是一个用户控件。 她提供了一样的可视化开发经验和同页面类似的架构。UserControlTask控件能够让你将一个ASP.NET用户控件当成一个任务集成在一个ADF应用程序中。Web adf 任务框架包含一个基础类，ESRI.ArcGIS.ADF.Web.UI.WebControls.UserControlTaskPanel，你可能将这个类应用到一个ASP.NET用户控件中来获取task框架行为和功能的访问权限。
The UserControlTask only works with the ASP.NET AJAX  partial postback pattern for asynchronous communication in a Web application.  A ScriptManager must be in the page for the UserControlTask to function.   
UserControlTask 只和ASP.NET AJAX部分回发一起工作用于web 应用程序中的异步交流。 页面中必须有一个ScriptManager用于UserControlTask执行功能。
Assembly: ESRI.ArcGIS.ADF.Web.UI.WebControls.dll
Class: ESRI.ArcGIS.ADF.ADF.Web.UI.WebControls.UserControlTask

Using the UserControlTask control

Add supporting controls to the page
At the top of the page, add a ScriptManager control.  A ScriptManager control must be in the page for the UserControlTask to function. 
在页面的顶部添加一个ScripitManager控件。在页面中必须有一个ScriptManager控件用于UserControlTask执行功能。
In order to take full advantage of the UserControlTask control, a number of supporting controls must be available.  Setup a Web application with a MapResourceManager and Map control using their discussion topics as a guide. Add a TaskManager, Menu, and TaskResults control using their discussion topics as a guide. At runtime, the TaskResults control displays the results of you custom UserControlTask.  

Add the UserControlTask control to the page
为了充分利用UserControlTask 控件，一系列的支持控件必修是可以得到的。使用他们的讨论作为一个向导创建一个含有一个MapResourceManager控件和Map控件的web应用程序。 添加一个TaskManager控件，菜单控件，和taksResults控件。 运行状态下，TaskResults控件显示你自定义的UserControlTask控件的结果。

向页面中添加UserControlTask控件。
In Visual Studio, display the prepared Web form in design mode, select the Toolbox, and expand the ArcGIS Web Controls tab.  Drag and drop a UserControlTask control into the TaskManager control.  You should now see the following in Visual Studio:
在VS中，在设计模式下展开准备好的表格，选择toolbox展开ArcGIS Web 控件页签。 向taksManager控件中拖拽一个userControlTask控件。 此时你在VS中将看到如下的内容。

 

Create a custom ASP.NET Web User control
创建一个自定义的ASP.NET web 用户控件。
Create a new Web User control.  In Visual Studio right click on the Website and select "Add New Item".  Select the Web User Control option in the dialog (as displayed below).
创建一个新的web用户控件。 在VS中，在webside上单击右键并选择“Add New Item”。 在对话框中选择Web user Control控件(如下所示)。

 

Subclass the ADF UserControlTaskPanel class
继承ADF UserControlTaskPanel类
To expose a User control to the ADF task framework, open the code-behind for the User control and subclass the UserControlTaskPanel class.   Right-click the UserControlTaskPanel text in the code and select "Implement Abstract Class".  An override for the ExecuteTask method is added to the class definition.
为了暴漏一个用户控件到ADF任务框架，打开用户控件后台代码并继承UserControlTaskPanel类，在UserControlTaskPanel文本中单击右键并选择“implement Abstract 类”。 一个ExecuteTask 方法的重载函数被添加到类的定义当中
[C#]
 

Add controls to the User control
向用户控件中添加控件。
In traditional server control developer, controls are added and placed programmatically.  In the User control merely drag and drop server controls on the page (or add in markup) and place using the Visual Studio design view.   In this case, add an ASP.NET Panel and insert a Textbox and Button.  The unique id for each is, MyPanel, InputTextBox, and ExecuteButton, respectively(各自的，各个的).   The Panel will define the display surface of the User control at runtime.   The design view for the User control should appear similar to the following:
在传统的服务器端控件开发工具中，控件的开发以及位置的摆放都是通过代码实现的。 在VS可视化设计模式下，用户控件仅仅被拖到页面。 这种情况下，添加一个ASP.NET的面板，和一个文本输入框和一个按钮。为每一个控件设置一个唯一的ID，myPanet,inputTextBox,ExcuteButton。面板将会定义用户控件在运行状态现实的样式。用户控件在设计视图模式下将会和下面的类似。
 

Handle events on controls to execute task
处理控件中的事件执行任务。
Upon click of the Button in the User control, the task will execute.  Since the UserControlTask only supports partial postbacks you can handle events using the standard postback architecture.  Double-click on the Button to create the click event handler in the code-behind.  To start execution of a task, call the Start method on the base class (UserControlTaskPanel) and provide an object that contains parameter to process. In this case, pass the text in the TextBox. 
单击用户控件中的按钮，任务将会被执。因为UserControlTask控件仅仅支持部分的回发，你可以使用标准的回发架构来处理事件。在button上面双击，在后代定义单击事件的处理函数。为了执行一个任务，调用基类中的开始方法，并提供一个包含用于处理的参数的对象。在这里，发送文本框中的文本。

[C#]

Register controls non-AJAX enabled controls with ScriptManager
在scriptManager中注册非AJAX功能的控件。

All ADF controls are already AJAX enabled, so if an ADF control exists in a User control task, it will register itself with the ScriptManager.  Many ASP.NET server controls are not AJAX enabled.  As a result, they must be registered with the ScriptManager to generate a partial postback.  In this case, register the Button with the ScriptManager as an AJAX control.   Since the ScriptManager is in the page that contains the User control, use the static GetCurrent method and provide the Page container for the User control to get a reference to the ScriptManager.
所有的ADF控件都具有AJAX的能力， 因此如果一个ADF控件存在于一个用户控件任务，她将会将自己注册到ScriptManager。很多的ASP.NET服务器端控件没有AJAX功能。 结果，他们必须注册到ScriptManager来生成一个部分回发。。在这种情况下，将button控件当成一个AJAX控件注册到ScriptManager中。 因为scriptManager控件在包含用户控件的页面中，使用静态的GetCurrent方法并为用户控件提供页面容器来获取一个scriptManager控件的引用。

[C#]

Implement ExecuteTask method
实现Execute Task方法
The parameters provided with the Start method (previous step) are passed to the ExecuteTask method.   The ExecuteTask method should contain the business logic for processing task inputs and generating output.   A number of task result types can be returned from the ExecuteTask method.    See the TaskResults control discussion for more information.  In this case a simple task result containing server time is generated, returned to the client browser, and displayed in a TaskResults control.   The implementation code for the User control task is now complete.   
由start方法提供的参数被传递到ExecuteTask方法。ExecuteTask方法应该包含一个事件逻辑来处理输入的任务和生成输出。一系列的任务结果类型将会从ExecuteTask 方法中返回。更多的信息查看

TaskResults control discussion 。 在这个例子中一个简单的包含服务器事件的结果被生成并返回到客户端浏览器，然后显示在TaskResults控件中。用户控件任务的事件代码如下所示：

[C#]

Set the UserControlTask control properties
设置UserControlTask控件的属性

In design mode, click on the SearchAttributesTask control and display the verbs（动词） associated with the control.
在设计模式下，单击SearchAttributesTask控件，展示和控件相关的动词。

a. Buddy the task control with the TaskResults control.

将task 控件绑定到taskResults控件
To display the results of a task, you must buddy the task control with the TaskResults control.  Select the Choose Task Results Container verb to modify the TaskResultsContainers property.  In the buddy control dialog, add a new item and select the id of the TaskResults control you want to display in the task results. 
为来显示任务的结果，你必须将task控件绑定到TaskResults控件。 选择【 Choose Task Results Container】动词，来重新定义TaskResultsContainers属性。 在buddy control对话框中，添加一个新项，并选择你想在buddy control中展示的TaskResults控件的ID。

b.  References the User control task

In the property page for the UserControlTask, set the path to the User control task.  The path should be relative to the Web application.  
在UserControlTask控件的属性页面中，设置控件控件任务的路径。路径应该是web 应用程序的相对路路径。

Runtime use
运行状态下的使用。
Run the application.  Note, the Menu control lists the User control task and the User control task is displayed by default.  Enter a value in the TextBox in the User control task dialog.  The text entered and the time on the server is returned in the TaskResults control.   To access other Web ADF components, such as task result containers (e.g. Map) and callback results, see the UserControlTaskPanel discussion below.
运行应用程序。注意：菜单控件列出用户控件任务并且用户控件任务以默认的方式展示。在用户控件任务对话框中的文本输入框中输入一个值。文本输入，服务器端的事件在taskresults控件中返回。 为了访问其他的web ADF 组件，比如：任务结果容器和回调结果，查看下面的UserControlTaskPanel的讨论。

Members

Properties

The following table provides a list of properties of interest.  For complete reference information, see the SearchAttributesTask control in the library reference section.

Property Name	Type	Description
FeatureSelectionColor	Color	The Color of selected features.
GroupResultsByTable	bool	Whether the results of this task will have the results grouped by layers.
HideOnSubmit	bool	Whether to hide the panel when the task executes.
LabelText	string	Text to display next to the input box, to indicate the nature of the value to enter.
NavigationPath	string	The path to the task as it would appear in a hierarchical data control buddied to the task's TaskManager.
SearchFields	string	A list of map resource - layer - fields on which a search for a value will be made.
ShowFieldAttributes	bool	Whether the results of this task will have the field attributes.
ShowLegend	bool	Whether the results of this task will have a legend. Legend is only available if GroupResultsByTable is true.
TaskResultsContainers	BuddyControl Collection	The controls in which results from this task are displayed.
TaskControl	string	Path to the User control task (.ascx) that implements UserControlTaskPanel.
Title	string	The text displayed in the title bar of the panel.

Discussion

Accessing ADF and task framework properties from a User control task
讨论：从一个用户控件任务中访问ADF和任务框架属性。
For an ASP.NET Web User control to plug into the ADF task framework, it must implement the UserControlTaskPanel base class.  The UserControlTaskPanel base class provides a simple Start method to pass parameters to the ExecuteTask method.  The ExecuteTask method should contain the bulk（大块、主题） of the business logic for executing the task to generate results based on inputs.  To access the UserControlTask server control, a FloatingPanelTask which contains the framework that supports a User control, use the UserControlTask property.  The UserControlTask will provide access to traditional task server control properties such as callback results (CallbackResults) and task results containers such as a Map (TaskResultsContainers).  At this point, standard task framework development is in play. 

对于嵌入到ADF任务框架中的一个ASP.NET 网络用户控件，她必须继承（实现）UserControlTaskPanel基类。UserControlTaskPanel基类提供来一个简单的方法来向ExecuteTask方法传递参数。ExecuteTask方法必须包含事件逻辑的主题用户处理任务和生成基于输入的结果，为来访问UserControlTask服务器端控件，一个包含支持用户控件的框架的FloatingPanelTask，使用UserControlTask属性。UserControlTask控件提供了传统任务服务器端控件属性的接口，比如：callback results（CallbackResults）和任务结果容器，比如：一个Ｍａｐ控件。到此，标准任务控件的开发已经能够使用。