This tutorial describes how to connect to Salesforce.com.

In this walkthrough:

• Requirements
• General information
• Creating SalesforceConnection
• Opening connection
• Closing connection
• Modifying connection

Requirements

In order to connect to Salesforce.com or Database.com 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:

• User Id
• Password
• Host
• Security Token

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

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 SalesForce.com, 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 Salesforce.com or Database.com 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 Host=login.salesforce.com;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 = "login.salesforce.com";
salesforceConnection1.UserId = "[email protected]";
salesforceConnection1.Password = "mypassword";

Imports Devart.Data.Salesforce
...
Dim SalesforceConnection1 As SalesforceConnection = New SalesforceConnection()
salesforceConnection1.Host = "login.salesforce.com"
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 = "Host=login.salesforce.com;" +
      "User Id= [email protected];Password=mypassword;Security Token=qweASDzcx1234567890rtyui;";

SalesforceConnection1.ConnectionString = "Host=login.salesforce.com; & _
      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 = "login.salesforce.com";
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 = "login.salesforce.com"
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:

salesforceConnection1.Open();

SalesforceConnection1.Open()

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 = "Host=login.salesforce.com;" +
        User Id= [email protected];Password=mypassword;Security Token=qweASDzcx1234567890rtyui;";
myConn.Open();
MessageBox.Show(myConn.ServerVersion);
myConn.Close();

Dim myConn As SalesforceConnection = New SalesforceConnection()
myConn.ConnectionString = "Host=login.salesforce.com; & _
       User Id= [email protected];Password=mypassword;Security Token=qweASDzcx1234567890rtyui;"
myConn.Open()
MessageBox.Show(myConn.ServerVersion)
myConn.Close()

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.