Developing a User Interface for a Custom Connection Manager
After you have overridden the implementation of the properties and methods of the base class to provide your custom functionality, you may want to create a custom user interface for your connection manager. If you do not create a custom user interface, users can configure your connection manager only by using the Properties window.
In a custom user interface project or assembly, you normally have two classes—a class that implements IDtsConnectionManagerUI, and the Windows form that it displays to gather information from the user.
Important
After signing and building your custom user interface and installing it in the global assembly cache as described in Building, Deploying, and Debugging Custom Objects, remember to provide the fully qualified name of this class in the UITypeName property of the DtsConnectionAttribute.
Note
For working samples of custom connection managers, see Sql Server Custom Connection Manager Sample and Excel2 Custom Connection Manager Sample. Also, the code examples in this topic come from the Sql Server Custom Connection Manager sample.
Coding the User Interface Class
The IDtsConnectionManagerUI interface has four methods, which are described in the following sections. You may not need to write any code for the Delete method if no cleanup is required when the user deletes an instance of the connection manager.
Initializing the User Interface
In the Initialize method, the designer provides a reference to the connection manager that is being configured so that the user interface can modify its properties. Your code needs to cache this reference for later use.
Public Sub Initialize(ByVal connectionManager As Microsoft.SqlServer.Dts.Runtime.ConnectionManager, ByVal serviceProvider As System.IServiceProvider) Implements Microsoft.SqlServer.Dts.Runtime.Design.IDtsConnectionManagerUI.Initialize
_connectionManager = connectionManager
_serviceProvider = serviceProvider
End Sub
public void Initialize(Microsoft.SqlServer.Dts.Runtime.ConnectionManager connectionManager, System.IServiceProvider serviceProvider)
{
_connectionManager = connectionManager;
_serviceProvider = serviceProvider;
}
Creating a New Instance of the User Interface
The New method, which is not a constructor, is called after the Initialize method when the user creates a new instance of the connection manager. In this method, you usually want to display the form for editing, unless the user has copied and pasted an existing connection manager.
Public Function [New](ByVal parentWindow As System.Windows.Forms.IWin32Window, ByVal connections As Microsoft.SqlServer.Dts.Runtime.Connections, ByVal connectionUIArgs As Microsoft.SqlServer.Dts.Runtime.Design.ConnectionManagerUIArgs) As Boolean Implements Microsoft.SqlServer.Dts.Runtime.Design.IDtsConnectionManagerUI.New
Dim clipboardService As IDtsClipboardService
clipboardService = _
DirectCast(_serviceProvider.GetService(GetType(IDtsClipboardService)), IDtsClipboardService)
If Not clipboardService Is Nothing Then
' If connection manager has been copied and pasted, take no action.
If clipboardService.IsPasteActive Then
Return True
End If
End If
Return EditSqlConnection(parentWindow)
End Function
public bool New(System.Windows.Forms.IWin32Window parentWindow, Microsoft.SqlServer.Dts.Runtime.Connections connections, Microsoft.SqlServer.Dts.Runtime.Design.ConnectionManagerUIArgs connectionUIArgs)
{
IDtsClipboardService clipboardService;
clipboardService = (IDtsClipboardService)_serviceProvider.GetService(typeof(IDtsClipboardService));
if (clipboardService != null)
// If connection manager has been copied and pasted, take no action.
{
if (clipboardService.IsPasteActive)
{
return true;
}
}
return EditSqlConnection(parentWindow);
}
Editing the Connection Manager
Since the form for editing is called from both the New and the Edit methods, it is convenient to use a helper function to encapsulate the code that displays the form.
Private Function EditSqlConnection(ByVal parentWindow As IWin32Window) As Boolean
Dim sqlCMUIForm As New SqlConnMgrUIFormVB
sqlCMUIForm.Initialize(_connectionManager, _serviceProvider)
If sqlCMUIForm.ShowDialog(parentWindow) = DialogResult.OK Then
Return True
Else
Return False
End If
End Function
private bool EditSqlConnection(IWin32Window parentWindow)
{
SqlConnMgrUIFormCS sqlCMUIForm = new SqlConnMgrUIFormCS();
sqlCMUIForm.Initialize(_connectionManager, _serviceProvider);
if (sqlCMUIForm.ShowDialog(parentWindow) == DialogResult.OK)
{
return true;
}
else
{
return false;
}
}
In the Edit method, you simply have to display the form for editing.
Public Function Edit(ByVal parentWindow As System.Windows.Forms.IWin32Window, ByVal connections As Microsoft.SqlServer.Dts.Runtime.Connections, ByVal connectionUIArg As Microsoft.SqlServer.Dts.Runtime.Design.ConnectionManagerUIArgs) As Boolean Implements Microsoft.SqlServer.Dts.Runtime.Design.IDtsConnectionManagerUI.Edit
Return EditSqlConnection(parentWindow)
End Function
public bool Edit(System.Windows.Forms.IWin32Window parentWindow, Microsoft.SqlServer.Dts.Runtime.Connections connections, Microsoft.SqlServer.Dts.Runtime.Design.ConnectionManagerUIArgs connectionUIArg)
{
return EditSqlConnection(parentWindow);
}
Coding the User Interface Form
After creating the user interface class that implements the methods of the IDtsConnectionManagerUI interface, you must create a Windows form where the user can configure the properties of your connection manager.
Initializing the User Interface Form
When you display your custom form for editing, you can pass a reference to the connection manager that is being edited, either by using a custom constructor for the form class, or by creating your own Initialize method as shown here.
Public Sub Initialize(ByVal connectionManager As ConnectionManager, ByVal serviceProvider As IServiceProvider)
_connectionManager = connectionManager
_serviceProvider = serviceProvider
ConfigureControlsFromConnectionManager()
EnableControls()
End Sub
public void Initialize(ConnectionManager connectionManager, IServiceProvider serviceProvider)
{
_connectionManager = connectionManager;
_serviceProvider = serviceProvider;
ConfigureControlsFromConnectionManager();
EnableControls();
}
Setting Properties on the User Interface Form
Finally, your form class needs a helper function that populates the controls on the form when it is first loaded with the existing or the default values of the properties of the connection manager. Your form class also needs a similar function that sets the values of the properties to the values entered by the user when the user clicks OK and closes the form.
Private Const CONNECTIONNAME_BASE As String = "SqlConnectionManager"
Private Sub ConfigureControlsFromConnectionManager()
Dim tempName As String
Dim tempServerName As String
Dim tempDatabaseName As String
With _connectionManager
tempName = .Properties("Name").GetValue(_connectionManager).ToString
If Not String.IsNullOrEmpty(tempName) Then
_connectionName = tempName
Else
_connectionName = CONNECTIONNAME_BASE
End If
tempServerName = .Properties("ServerName").GetValue(_connectionManager).ToString
If Not String.IsNullOrEmpty(tempServerName) Then
_serverName = tempServerName
txtServerName.Text = _serverName
End If
tempDatabaseName = .Properties("DatabaseName").GetValue(_connectionManager).ToString
If Not String.IsNullOrEmpty(tempDatabaseName) Then
_databaseName = tempDatabaseName
txtDatabaseName.Text = _databaseName
End If
End With
End Sub
Private Sub ConfigureConnectionManagerFromControls()
With _connectionManager
.Properties("Name").SetValue(_connectionManager, _connectionName)
.Properties("ServerName").SetValue(_connectionManager, _serverName)
.Properties("DatabaseName").SetValue(_connectionManager, _databaseName)
End With
End Sub
private const string CONNECTIONNAME_BASE = "SqlConnectionManager";
private void ConfigureControlsFromConnectionManager()
{
string tempName;
string tempServerName;
string tempDatabaseName;
{
tempName = _connectionManager.Properties["Name"].GetValue(_connectionManager).ToString();
if (!String.IsNullOrEmpty(tempName))
{
_connectionName = tempName;
}
else
{
_connectionName = CONNECTIONNAME_BASE;
}
tempServerName = _connectionManager.Properties["ServerName"].GetValue(_connectionManager).ToString();
if (!String.IsNullOrEmpty(tempServerName))
{
_serverName = tempServerName;
txtServerName.Text = _serverName;
}
tempDatabaseName = _connectionManager.Properties["DatabaseName"].GetValue(_connectionManager).ToString();
if (!String.IsNullOrEmpty(tempDatabaseName))
{
_databaseName = tempDatabaseName;
txtDatabaseName.Text = _databaseName;
}
}
}
private void ConfigureConnectionManagerFromControls()
{
{
_connectionManager.Properties["Name"].SetValue(_connectionManager, _connectionName);
_connectionManager.Properties["ServerName"].SetValue(_connectionManager, _serverName);
_connectionManager.Properties["DatabaseName"].SetValue(_connectionManager, _databaseName);
}
}
See Also
Tasks
Creating a Custom Connection Manager
Coding a Custom Connection Manager