Developing a User Interface for a Custom Task
The Integration Services object model provides custom task developers the ability to easily create a custom user interface for a task that can then be integrated and displayed in Business Intelligence Development Studio. The user interface can provide helpful information to the user in SSIS Designer, and guide users to correctly configure the properties and settings of the custom task.
Developing a custom user interface for a task involves using two important classes. The following table describes those classes.
| Class | Description |
|---|---|
An attribute that identifies a managed task, and supplies design-time information through its properties to control how SSIS Designer displays and interacts with the object. |
|
An interface used by the task to associate the task with its custom user interface. |
This section describes the role of the DtsTaskAttribute attribute and the IDtsTaskUI interface when you are developing a user interface for a custom task, and provides details about how to create, integrate, deploy, and debug the task within SSIS Designer.
The SSIS Designer provides multiple entry points to the user interface for the task: the user can select Edit on the shortcut menu, double-click the task, or click the Show Editor link at the bottom of the property sheet. When the user accesses one of these entry points, SSIS Designer locates and loads the assembly that contains the user interface for the task. The user interface for the task is responsible for creating the properties dialog box that is displayed to the user in Business Intelligence Development Studio.
A task and its user interface are separate entities. They should be implemented in separate assemblies to reduce localization, deployment, and maintenance work. The task DLL does not load, call, or generally contain any knowledge of its user interface, except for the information that is contained in the DtsTaskAttribute attribute values coded in the task. This is the only way that a task and its user interface are associated.
The DtsTask Attribute
The DtsTaskAttribute attribute is included in the task class code to associate a task with its user interface. The SSIS Designer uses the properties of the attribute to determine how to display the task in the designer. These properties include the name to display and the icon, if any.
The following table describes the properties of the DtsTaskAttribute attribute.
| Property | Description |
|---|---|
Displays the task name in the Control Flow toolbox. |
|
The task description (inherited from DtsLocalizableAttribute). This property is shown in ToolTips. |
|
The icon displayed in SSIS Designer. |
|
If used, set it to one of the values in the DTSProductLevel enumeration. For example, |
|
Holds contact information for occasions when the task requires technical support. |
|
Assigns a type to the task. |
|
Attribute.TypeId |
When implemented in a derived class, gets a unique identifier for this Attribute. For more information, see Attribute.TypeID property in the .NET Framework Class Library. |
The type name of the assembly that is used by SSIS Designer to load the assembly. This property is used to find the user interface assembly for the task. |
The following code example shows the DtsTaskAttribute as it would look, coded above the class definition.
using System;
using Microsoft.SqlServer.Dts.Runtime;
namespace Microsoft.SSIS.Samples
{
[DtsTask
(
DisplayName = "MyTask",
IconResource = "MyTask.MyTaskIcon.ico",
UITypeName = "My Custom Task," +
"Version=1.0.0.0," +
"Culture = Neutral," +
"PublicKeyToken = 12345abc6789de01",
TaskType = "PackageMaintenance",
TaskContact = "MyTask; company name; any other information",
RequiredProductLevel = DTSProductLevel.None
)]
public class MyTask : Task
{
// Your code here.
}
}
Imports System
Imports Microsoft.SqlServer.Dts.Runtime
<DtsTask(DisplayName:="MyTask", _
IconResource:="MyTask.MyTaskIcon.ico", _
UITypeName:="My Custom Task," & _
"Version=1.0.0.0,Culture=Neutral," & _
"PublicKeyToken=12345abc6789de01", _
TaskType:="PackageMaintenance", _
TaskContact:="MyTask; company name; any other information", _
RequiredProductLevel:=DTSProductLevel.None)> _
Public Class MyTask
Inherits Task
' Your code here.
End Class 'MyTask
The SSIS Designer uses the UITypeName property of the attribute that includes the assembly name, type name, version, culture, and public key token, to locate the assembly in the Global Assembly Cache (GAC) and load it for use by the designer.
After the assembly has been located, SSIS Designer uses the other properties in the attribute to display additional information about the task in SSIS Designer, such as the name, icon, and description of the task.
The DisplayName, Description, and IconResource properties specify how the task is presented to the user. The IconResource property contains the resource ID of the icon embedded in the user interface assembly. The designer loads the icon resource by ID from the assembly, and displays it next to the task name in the toolbox and on the designer surface when the task is added to a package. If a task does not provide an icon resource, the designer uses a default icon for the task.
The IDTSTaskUI Interface
The IDtsTaskUI interface defines the collection of methods and properties called by SSIS Designer to initialize and display the user interface associated with the task. When the user interface for a task is invoked, the designer calls the Initialize method, implemented by the task user interface when you wrote it, and then provides the TaskHost and Connections collections of the task and package, respectively, as parameters. These collections are stored locally, and used subsequently in the GetView method.
The designer calls the GetView method to request the window that is displayed in SSIS Designer. The task creates an instance of the window that contains the user interface for the task, and returns the user interface to the designer for display. Typically, the TaskHost and Connections objects are provided to the window through an overloaded constructor so they can be used to configure the task.
The SSIS Designer calls the GetView method of the task UI to display the user interface for the task. The task user interface returns the Windows form from this method, and SSIS Designer shows this form as a modal dialog box. When the form is closed, SSIS Designer examines the value of the DialogResult property of the form to determine whether the task has been modified and if these modifications should be saved. If the value of the DialogResult property is OK, the SSIS Designer calls the persistence methods of the task to save the changes; otherwise, the changes are discarded.
The following code sample implements the IDtsTaskUI interface, and assumes the existence of a Windows form class named SampleTaskForm.
using System;
using System.Windows.Forms;
using Microsoft.SqlServer.Dts.Runtime;
using Microsoft.SqlServer.Dts.Runtime.Design;
namespace Sample
{
public class HelloWorldTaskUI : IDtsTaskUI
{
TaskHost taskHost;
Connections connections;
public void Initialize(TaskHost taskHost, IServiceProvider serviceProvider)
{
this.taskHost = taskHost;
IDtsConnectionService cs = serviceProvider.GetService
( typeof( IDtsConnectionService ) ) as IDtsConnectionService;
this.connections = cs.GetConnections();
}
public ContainerControl GetView()
{
return new HelloWorldTaskForm(this.taskHost, this.connections);
}
public void Delete(IWin32Window parentWindow)
{
}
public void New(IWin32Window parentWindow)
{
}
}
}
Imports System
Imports Microsoft.SqlServer.Dts.Runtime
Imports Microsoft.SqlServer.Dts.Runtime.Design
Imports System.Windows.Forms
Public Class HelloWorldTaskUI
Implements IDtsTaskUI
Dim taskHost As TaskHost
Dim connections As Connections
Public Sub Initialize(ByVal taskHost As TaskHost, ByVal serviceProvider As IServiceProvider) _
Implements IDtsTaskUI.Initialize
Dim cs As IDtsConnectionService
Me.taskHost = taskHost
cs = DirectCast(serviceProvider.GetService(GetType(IDtsConnectionService)), IDtsConnectionService)
Me.connections = cs.GetConnections()
End Sub
Public Function GetView() As ContainerControl _
Implements IDtsTaskUI.GetView
Return New HelloWorldTaskForm(Me.taskHost, Me.connections)
End Function
Public Sub Delete(ByVal parentWindow As IWin32Window) _
Implements IDtsTaskUI.Delete
End Sub
Public Sub [New](ByVal parentWindow As IWin32Window) _
Implements IDtsTaskUI.[New]
End Sub
End Class
See Also
Concepts
Creating a Custom Task
Coding a Custom Task
Developing a User Interface for a Custom Task
Help and Information
Getting SQL Server 2005 Assistance
Change History
| Release | History |
|---|---|
15 September 2007 |
|
17 July 2006 |
|
14 April 2006 |
|