public class ConnectionStringManager : UserControl

public class ConnectionStringManager : UserControl

Public Class ConnectionStringManager _
	Inherits UserControl

Public Class ConnectionStringManager _
	Inherits UserControl

public ref class ConnectionStringManager : public UserControl

public ref class ConnectionStringManager : public UserControl

This control provides a plug-in credential form, whereby you specify which of several fields the user should be able to modify or only to view. It includes a facility for testing the credentials with a color-coded status indicator and/or a status message display.

Besides the description here, I have also published an article discussing the practical uses of this tool -- .NET Building Blocks: Build a Configurable Database Credential Selector -- available on the DevX online magazine.

Typical use of this control requires instantiating it along with Accept and Cancel buttons on a separate form for handling credentials, which you open as needed from your main application. As shown in the sample, the code for the credential form is quite brief. You need to connect the Cancel and Accept buttons as shown for the control to work. So if the Accept button is activated, let the control know via the Accept  method, at which time it will take whatever changes have been made, if any, and make them accessible through the ConnectionString property. Without that, the original string will be returned through the ConnString property. Notice that the handler for the Cancel button does not call Accept so the ConnString property would then just return the original unchanged.

public partial class CredentialForm : Form
{
    public CredentialForm()
    {
        InitializeComponent();
        connStrMgr.DbType = ...; // set to Oracle, SqlServer, etc.
    }

    private void acceptButton_Click(object sender, EventArgs e)
    { connStrMgr.Accept(); Close(); }

    private void cancelButton_Click(object sender, EventArgs e)
    { Close(); }


    // To interface to a main form. 
    public string ConnString
    {
        get { return connStrMgr.ConnectionString; }
        set { connStrMgr.ConnectionString = value; }
    }

    public ConnectionStringManager.DBTypes DbType
    {
        get { return connStrMgr.DbType; }
        set { connStrMgr.DbType = value; }
    }
}

public partial class CredentialForm : Form
{
    public CredentialForm()
    {
        InitializeComponent();
        connStrMgr.DbType = ...; // set to Oracle, SqlServer, etc.
    }

    private void acceptButton_Click(object sender, EventArgs e)
    { connStrMgr.Accept(); Close(); }

    private void cancelButton_Click(object sender, EventArgs e)
    { Close(); }


    // To interface to a main form. 
    public string ConnString
    {
        get { return connStrMgr.ConnectionString; }
        set { connStrMgr.ConnectionString = value; }
    }

    public ConnectionStringManager.DBTypes DbType
    {
        get { return connStrMgr.DbType; }
        set { connStrMgr.DbType = value; }
    }
}

Before you open your CredentialForm, at a minimum you must set the ConnString and the DbType properties shown above. There are other properties you may want to use as well to customize the control. Activate the dialog modally, then use the ConnString property once you return from that dialog.

using (CredentialForm credForm = new CredentialForm())
{
  credForm.ConnString = ...; // typically from your config file
  credForm.DbType = ConnectionStringManager.DBTypes.SqlServer;
  credForm.ShowDialog();
  ... = credForm.ConnString;
}

using (CredentialForm credForm = new CredentialForm())
{
  credForm.ConnString = ...; // typically from your config file
  credForm.DbType = ConnectionStringManager.DBTypes.SqlServer;
  credForm.ShowDialog();
  ... = credForm.ConnString;
}

The ConnectionStringManager control includes the input fields listed below. By default, the user may both view and edit these fields. You may adjust what is editable and what is displayed either at design time or dynamically at run time, via properties of the control. Each may be set to Edit (displays the field and allows the use to edit it), Display (displays the field but prohibits editing), or Hide (does not display the field at all). These are the relevant properties:

• ExposeUsername
  Controls exposure of the Username field.
• ExposePassword
  Controls exposure of the Password field.
• ExposeServer
  Controls exposure of the Server field.
• ExposeDbType
  Controls exposure of the DbType field.
• ExposeDB
  Controls exposure of the DB field.
• ExposeAuthenticationType
  Controls exposure of the AuthenticationType field.

All of these parameters are visible and editable by default. But if, for example, you want the user to specify only a username and password (as all users will log in to the same database) then set each of the others to ConnectionStringManager.AccessLevel.Hide. Finally, besides the input fields, there are a few other controls that you may expose or hide at your discretion: the test results box and the "remember password" checkbox.

The control includes a combination button and status indicator that provides a convenient way to check the entered credentials. The button will appear grey (due to being disabled) until the user fills out the fields needed to attempt a connection. At that time, the button will switch to orange, indicating the validity of the credentials is unknown. Pressing the button will attempt to connect to the database the user has specified. If successful, the indicator will change to green. If unsuccessful, it will change to red and an ErrorProvider token will appear (hovering over it will show the error message from the database). The status indicator will remain green or red until any field is changed, at which time it will revert to orange since the validity then becomes open to question again.

The username and password fields are TextBox controls. The database type and database fields are non-editable ComboBox controls. The database field will only be enabled for those databases that support the notion of multiple databases (e.g. SQL Server or MySql). By default, the list will include only non-system databases (e.g. omitting master and others in SQL Server). You may optionally include the system databases in the list, though, by depressing Shift as you open the drop-down. The authentication type choices are radio buttons. The server field, however deserves special note. By default it is also an ordinary TextBox. However, if you set the ServerChoices property to a list of names, the server field changes into a non-editable ComboBox with the choices you have provided.

Since the control may have a variable number of components visible, it will automatically resize itself based on the components you have enabled. With appropriate property settings on the form in which you embed this control, you could then make the form itself resize automatically to give a tidy look to it.

This control knows how to configure SQL Server, Oracle, and MySql connections (subclasses of DbConnection). It also works with any ODBC data source that you set up with the Window ODBC Data Source Administrator tool. That allows you to connect directly to Excel files or CSV files, Access databases, or even SQL Server or Oracle through ODBC connections. You can use MySql as well but you will have to load the MySql ODBC driver from MySQL's ODBC Connectors page.

This class is instrumented with a StructuredTraceSource for diagnostic output. Its key name is ConnectionStringManager.

This control is instrumented with a ContainerTest property that provides additional functionality when run in the User Container of Visual Studio and set to true. See the property description for details of the added diagnostic functionality.

Since CleanCode 0.9.15.