This tutorial describes how to connect to QuickBooks Online.

In this walkthrough:

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

Requirements

In order to connect to QuickBooks Online you need to have the corresponding account, dotConnect for QuickBooks Online installed and IDE running. You also have to know the required connection parameters described below.

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

Required Connection Parameters

To establish a connection to server you have to provide the required connection parameters to dotConnect for QuickBooks Online. This information is used by QuickBooksConnection component to connect to QuickBooks Online. The parameters are represented as a connection string. You can compose the connection string manually or have dotConnect for QuickBooks Online construct it for you.

The following connection string parameters are required:

• CompanyID - The string that uniquely identifies a QuickBooks company, for example, "Company Id=1440905870".
• Refresh Token - the OAuth 2.0 refresh token for QuickBooks.
• Token Server - a file or registry key to store refresh tokens between sessions. For example, "Token Server=file://D:\\temp\\QuickBooks_oauth_token_1234.txt" or "Token Server=reg://HKEY_CURRENT_USER\\Software\\Devart\\QuickBooks\\OAuth_12345"
• Client ID - one of the pair of OAuth 2.0 credentials, that you can obtain when you register a client application at developer.intuit.com/myapps with your developer account.
• Client Secret - the second one of the pair of OAuth 2.0 credentials, that you can obtain when you register a client application at developer.intuit.com/myapps with your developer account.

The easiest way to get the required parameters is to create a connection at design-time or in the Server Explorer, by performing the procedure described below. Actually, in this case the Client Id and Client Secret are not required, because dotConnect for QuickBooks Online implicitly uses its own values for them. These values are obtained from an embedded OAuth app, registered by Devart. However, it's still recommended to register your own application and using your own values.

If you cannot obtain the refresh token using design time or Server Explorer, registering your own OAuth application is required. Then, at QuickBooks OAuth 2.0 playground, you may get the Refresh Token. You can find more information in the QuickBooks documentation.

Creating a Connection to QuickBooks Online

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 QuickBooksConnection component in dotConnect for QuickBooks Online category.
2. Double-click the component. Notice that new object appears on the designer underneath the form. If this is first time you create the QuickBooksConnection in this application it is named quickBooksConnection1.
3. Click on the quickBooksConnection1 object and press F4 to focus on object's properties.
4. Click Web Login.
5. In the opened Web Login dialog box sign in to your QuickBooks Online account.
6. Select a company to query data from (click the link with the corresponding company name).
7. Click Authorize.
8. If necessary, click the Advanced button and configure other connection string parameters. You can find the description of these connection string parameters in the QuickBooksConnection.ConnectionString topic.

Run time creation

You can also configure a connection at run-time by setting its ConnectionString property (note that you have to add references to Devart.Data.QuickBooks.dll, Devart.Data.SqlShim.dll, and Devart.Data.dll assemblies):

quickBooksConnection1.ConnectionString = "Company Id=1440905870;Refresh Token=AB11590759756UCO8O6CpRQcAMP00sIANafgS8Y4RN10rpLJNM;Token Server=file://D:\\temp\\QuickBooksToken.txt";

quickBooksConnection1.ConnectionString = "Company Id=1440905870;Refresh Token=AB11590759756UCO8O6CpRQcAMP00sIANafgS8Y4RN10rpLJNM;Token Server=file://D:\\temp\\QuickBooksToken.txt"

Using connection string builder

If you decide to setup connection by assigning values to several properties, consider using QuickBooksConnectionStringBuilder class. It has all of the possible connection settings exposed as properties, thus allowing to customize the connection at full extent.

QuickBooksConnectionStringBuilder connectionStringBuilder = new QuickBooksConnectionStringBuilder();


QuickBooksConnection myConnection = new QuickBooksConnection(connectionStringBuilder.ConnectionString);

Dim connectionStringBuilder As QuickBooksConnectionStringBuilder = New QuickBooksConnectionStringBuilder


Dim myConnection As QuickBooksConnection = New QuickBooksConnection(connectionStringBuilder.ConnectionString)

Notice that in this example we used QuickBooksConnection constructor that accepts connection string as argument.

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

Creating Connection in Server Explorer

To create a Server Explorer connection, you just need to:

1. Click Connect to Database on the Server Explorer toolbar
   
   
2. If the QuickBooks Online Data Source is not selected by default, click the Change button.
3. Select QuickBooks Online Data Source (dotConnect for QuickBooks Online) and click OK.
4. Click Web Login.
5. In the opened Web Login dialog box sign in to your QuickBooks Online account.
6. Select a company to query data from (click the link with the corresponding company name).
7. Select the Sandbox check box if you want to connect to a sandbox.
8. Click Authorize.

Optionally, if you have registered your client application at developer.intuit.com/myapps with your developer account, you can select select the Use custom OAuth App check box and specify the Client ID and Client Secret parameters and redirect URL.

After this you can browse QuickBooks Online objects in Server Explorer.

Opening connection

Opening a connection is as simple as that:

myConnection1.Open();

myConnection1.Open()

Of course, the myConnection1 object must have a valid connection string assigned earlier. When you call Open, dotConnect for QuickBooks Online tries to find the host and connect to QuickBooks Online. If any problem occurs it raises an exception with brief explanation on what is wrong. If no problem is encountered dotConnect for QuickBooks Online 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 the connection object in designer and then click Connect.
2. In the dialog window provide the required connection parameters.
3. Click Web Login.
4. In the opened Web Login dialog box sign in to your QuickBooks Online account.
5. Select a company to query data from (click the link with the corresponding company name).
6. Click Authorize.
7. If necessary, click the Advanced button and configure other connection string parameters. You can find the description of these connection string parameters in the QuickBooksConnection.ConnectionString topic.
8. Click Connect 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.

QuickBooksConnection myConn = new QuickBooksConnection();
myConn.ConnectionString = "Company Id=1440905870;Refresh Token=AB11590759756UCO8O6CpRQcAMP00sIANafgS8Y4RN10rpLJNM;Token Server=file://D:\\temp\\QuickBooksToken.txt";
myConn.Open();
MessageBox.Show(myConn.ServerVersion);
myConn.Close();

Dim myConn As QuickBooksConnection = New QuickBooksConnection()
myConn.ConnectionString = "Company Id=1440905870;Refresh Token=AB11590759756UCO8O6CpRQcAMP00sIANafgS8Y4RN10rpLJNM;Token Server=file://D:\\temp\\QuickBooksToken.txt"
myConn.Open()
MessageBox.Show(myConn.ServerVersion)
myConn.Close()

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

Modifying Connection

You can modify connection by changing properties of QuickBooksConnection object. Keep in mind that while some of the properties can be altered freely, most of them close connection when new value is assigned.