Developing a User Interface for a Custom Task

Applies to: SQL Server SSIS Integration Runtime in Azure Data Factory

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 SQL Server Data Tools (SSDT). 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.

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 SQL Server Data Tools (SSDT).

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.

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

Creating a Custom Task
Coding a Custom Task
Developing a User Interface for a Custom Task