dotConnect for Salesforce Documentation
In This Topic
    Connecting to
    In This Topic

    This tutorial describes how to connect to

    In this walkthrough:


    In order to connect to or you need to have the corresponding account, dotConnect for Salesforce installed and IDE running. You have to know your account login, password, and security token.

    Note that if you do not use design-time (specifically, if you do not place the SalesforceConnection component from toolbox on a form designer), you have to embed licensing information manually. This is described in the Licensing topic.

    General information

    To establish a connection to server you have to provide some connection parameters to dotConnect for Salesforce. This information is used by the SalesforceConnection component to login with credentials of your account. The parameters are represented as connection string. You can compose the connection string manually or have dotConnect for Salesforce construct it for you.

    You will need the following connection string parameters:

    Host specifies the login URL, which determines the service to connect to - or For example, login URL can be the following: "".

    Security Token is an automatically generated key that is used for logging in to Salesforce from an untrusted network. To get your security token, login to, go to Setup, and under "My Personal Information" click on Reset My Security Token. The security token will be delivered to the email address associated with your account.

    Creating SalesforceConnection

    Design time creation

    The following assumes that you have IDE running, and you are currently focused on a form designer.

    1. Open Toolbox and find SalesforceConnection component in dotConnect for Salesforce category.
    2. Double-click the component. Note that new object appears on the designer underneath the form. If this is first time you create SalesforceConnection in this application, it is named salesforceConnection1.
    3. Click on the salesforceConnection1 object and press F4 to focus on object's properties.
    4. In the Host property provide the or login URL.
    5. In the UserId property specify your login. For example, [email protected].
    6. In the Password property specify your password. For example, mypassword.
    7. In the SecurityToken property specify your security token. Security token is an automatically generated key that is used for logging in to Salesforce from an untrusted network. For example, qweASDzcx1234567890rtyui.
    8. Note that as you assign values to these properties the ConnectionString property is automatically updated to reflect your settings. Now it contains something like;User Id= [email protected];Password=mypassword;Security Token=qweASDzcx1234567890rtyui;.

    Run time creation

    Same operations performed in runtime look as follows (note that you have to add references to Devart.Data.Salesforce.dll and Devart.Data.dll assemblies):

    using Devart.Data.Salesforce;
    SalesforceConnection salesforceConnection1 = new SalesforceConnection();
    salesforceConnection1.Host = "";
    salesforceConnection1.UserId = "[email protected]";
    salesforceConnection1.Password = "mypassword";
    Imports Devart.Data.Salesforce
    Dim SalesforceConnection1 As SalesforceConnection = New SalesforceConnection()
    salesforceConnection1.Host = ""
    salesforceConnection1.UserId = "[email protected]"
    salesforceConnection1.Password = "mypassword"

    You can do this all in single assignment. It actually does not matter whether connection string is assigned directly or composed with particular properties. After you assign a value to ConnectionString property all other properties are populated with parsed values. So you can choose what is more convenient for you.

    salesforceConnection1.ConnectionString = ";" +
          "User Id= [email protected];Password=mypassword;Security Token=qweASDzcx1234567890rtyui;";
    SalesforceConnection1.ConnectionString = "; & _
          User Id= [email protected];Password=mypassword;Security Token=qweASDzcx1234567890rtyui;"

    Using connection string builder

    If you decide to setup a connection by assigning values to several properties, consider using the SalesforceConnectionStringBuilder class. It has all of the possible connection settings exposed as properties, thus allowing you to customize the connection at full extent. The following example demonstrates how to compose a more complex connection string:

    SalesforceConnectionStringBuilder sfCSB = new SalesforceConnectionStringBuilder();
    sfCSB.Host = "";
    sfCSB.UserId = "[email protected]";
    sfCSB.Password = "mypassword";
    sfCSB.SecurityToken = "qweASDzcx1234567890rtyui";
    sfCSB.MaxPoolSize = 150;
    sfCSB.ConnectionTimeout = 30;
    SalesforceConnection myConnection = new SalesforceConnection(sfCSB.ConnectionString);
    Dim sfCSB As SalesforceConnectionStringBuilder = New SalesforceConnectionStringBuilder
    sfCSB.Host = ""
    sfCSB.UserId = "[email protected]"
    sfCSB.Password = "mypassword"
    sfCSB.SecurityToken = "qweASDzcx1234567890rtyui"
    sfCSB.MaxPoolSize = 150
    sfCSB.ConnectionTimeout = 30
    Dim myConnection As SalesforceConnection = New SalesforceConnection(sfCSB.ConnectionString)

    Note that in this example we used SalesforceConnection constructor that accepts connection string as argument.

    For the information on arguments allowed in the connection string, refer to the description of the SalesforceConnection.ConnectionString property.

    Opening connection

    Opening a connection is as simple as that:


    Of course, SalesforceConnection1 must have a valid connection string assigned earlier. When you call Open, dotConnect for Salesforce tries to find the host and connect to server. If any problem occurs it raises an exception with brief explanation on what is wrong. If no problem is encountered dotConnect for Salesforce tries to establish the connection during ConnectionTimeout interval. Finally, when connection is established, the Open method returns and State property is changed to Open.

    In design time you can connect to server in few steps:

    1. Right-click on salesforceConnection1 object in designer.
    2. Select Connect from the popup menu.
    3. In the dialog window provide necessary logon information.
    4. Click the Connect button to establish connection.

    Or you can simply change the State property to Open in the Properties window to establish a connection using the current connection string.

    Closing connection

    To close a connection call its Close method, or set its State property to Closed.

    The following example summarizes aforementioned information and shows how to create, setup, open, use and then close the connection.

    SalesforceConnection myConn = new SalesforceConnection();
    myConn.ConnectionString = ";" +
            User Id= [email protected];Password=mypassword;Security Token=qweASDzcx1234567890rtyui;";
    Dim myConn As SalesforceConnection = New SalesforceConnection()
    myConn.ConnectionString = "; & _
           User Id= [email protected];Password=mypassword;Security Token=qweASDzcx1234567890rtyui;"

    The sample code connects to a server, shows its version and then closes the connection. This actually is rare usage, because in real applications connections are used by other objects like SalesforceCommand and others. For more information on this, please see the corresponding tutorials or the reference information.

    Modifying connection

    You can modify connection by changing properties of SalesforceConnection object. Keep in mind that while some of the properties can be altered freely, most of them close connection when new value is assigned. For example, if you change the DataSource property, it gets closed immediately, and you have to reopen it manually.

    Additional information

    SalesforceConnection supports various kinds of authentication, not just authentication with username, password, and security token. It supports OAuth 2.0 authentication via access refresh token and the session ID authentication. See AuthenticationType for more information about the supported authentication kinds. You can choose the authentication kind to use by setting the Authentication parameter of the connection string.

    If you target .NET Framework 4.5 or lower and get the following exception: UNSUPPORTED_CLIENT: TLS 1.0 has been disabled in this organization. Please use TLS 1.1 or higher when connecting to Salesforce using https", you need to set ServicePointManager.SecurityProtocol to SecurityProtocolType.Tls11 or to SecurityProtocolType.Tls12 in your code.