Configuration

The QuickBooks Online .NET SDK allows you to configure app settings such as minor version, number of retries, and logging. As installed, the SDK is configured with default values as listed in the table below.Override default settings as follows:

• At the configuration file level—values set in a configuration file take precedence over their default values for the life of the SDK.
• At the code level—values set with the IppConfiguration property take precedence over both their default values and their configuration file (if present) values at run time.

Features you can configure:

• Base URL
• Minor version
• Logging
• Serialization and compression
• Retries
• OAuth Authorization

General configuration file structure can be found here.

The following table lists the default values configured in the .NET SDK:

The SDK allows you to define custom, local app settings in the AppSettings.json file. Then, when your app makes QuickBooks OnlineAPI calls to access QuickBooks Onlinedata, the SDK by default checks for configuration settings in the configuration file before using its defaults. To see the configuration file, click here.

To configure app settings at the code level, first build the service context and then override the feature setting as described on this page.

A base URL defines the work environment accessed for REST API services. Supported work environments include:

The default configuration accesses the QuickBooks Onlineproduction environment for REST API services. To test your code in the development environment using your QuickBooks Online sandbox, you can either create a configuration file setting or explicitly set the Base URL in ServiceContext objects. For more information about sandboxes, click here.

Include the following code in the configuration file to override the default production work environment:

1
2
3
4
5
6
7
8

"Service": {
   "BaseUrl": {
      "Qbo": "https://quickbooks.api.intuit.com",
      "Ips": "",
      "OAuthAccessTokenUrl": "",
      "UserNameAuthentication": ""
  }
}

Use the steps in this section to override the default value or, if set, the value defined in the configuration file.

Once the tokens are received, you can then make QuickBooks Online API calls using the .NET SDK. You can download the latest version using NuGet Package Manager. For example:

1
2
3
4
5

OAuth2RequestValidator oauthValidator = new OAuth2RequestValidator(access_token);
ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);
DataService commonServiceQBO = new DataService(serviceContext);
QueryService<Invoice> inService = new QueryService<Invoice>(serviceContext);
Invoice In = inService.ExecuteIdsQuery("SELECT * FROM Invoice").FirstOrDefault();

You must make a RefreshToken call after a 401 error (Invalid Token error) to get a new access token, or call RefreshToken every every hour since the Access Token expires in one hour.

Then, override the base URL setting as follows:

1

context.IppConfiguration.BaseUrl.Qbo = "https://sandbox-quickbooks.api.intuit.com/";

QuickBooks Onlinedata services support minor versions in order to provide a way for you to access incremental changes without breaking existing apps. Check release notes for current default value. Click here for more details about minor versions.

Override the default QuickBooks OnlineAPI minor version setting by replacing the <minorVersion> value with the desired value.

1
2
3
4
5

 "Service":{
      "MinorVersion":{
           "Qbo": "37"
       }
  }

Use the steps in this section to override the default value or, if set, the value defined in the configuration file.

Once the tokens are received, you can then make QuickBooks Online API calls using the .NET SDK. You can download the latest version using NuGet Package Manager. For example:

1
2
3
4
5

OAuth2RequestValidator oauthValidator = new OAuth2RequestValidator(access_token);
ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);
DataService commonServiceQBO = new DataService(serviceContext);
QueryService<Invoice> inService = new QueryService<Invoice>(serviceContext);
Invoice In = inService.ExecuteIdsQuery("SELECT * FROM Invoice").FirstOrDefault();

You must make a RefreshToken call after a 401 error (Invalid Token error) to get a new access token, or call RefreshToken every every hour since the Access Token expires in one hour.

Then, override the request and response formats, as follows:

1

serviceContext.IppConfiguration.MinorVersion.Qbo = "5";

Logging diagnostic information plays a key part for any application. The SDK provides several ways to log messages:

• Trace logging
• Request and Response logging

For detailed information on how to configure logging, click here.

The SDK uses System.Trace as the default logger. For detailed information on how to configure the default logger settings, such as whether to automatically flush the buffer, see Trace Logging.

Include the following code in the configuration file to enable request and response logging. Define the local file system (folder) path to store the logs:

1
2
3
4
5
6

"Logger": {
  "RequestLog": {
     "EnableLogs": "true",
     "LogDirectory": "C:\\IdsLogs"
  }
}

Use the steps in this section to override the default value or, if set, the value defined in the configuration file. For more information on message logging, see Logging.

Once the tokens are received, you can then make QuickBooks Online API calls using the .NET SDK. You can download the latest version using NuGet Package Manager. For example:

1
2
3
4
5

OAuth2RequestValidator oauthValidator = new OAuth2RequestValidator(access_token);
ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);
DataService commonServiceQBO = new DataService(serviceContext);
QueryService<Invoice> inService = new QueryService<Invoice>(serviceContext);
Invoice In = inService.ExecuteIdsQuery("SELECT * FROM Invoice").FirstOrDefault();

You must make a RefreshToken call after a 401 error (Invalid Token error) to get a new access token, or call RefreshToken every every hour since the Access Token expires in one hour.

Then, override the desired logging feature, as described in the following sections.

Enable Request and Response logging. If you have already enabled Request and Response logging in the configuration file, go to the next step.

1

context.IppConfiguration.Logger.RequestLog.EnableRequestResponsLogging = true;

Set a local path for the log file:

1

context.IppConfiguration.Logger.RequestLog.ServiceRequestLoggingLocation = @"C:\IdsLogs";

The SDK supports XML and JSON serialization for QuickBooks OnlineAPI request and response payloads. It also supports compression of request and response data to GZip and Deflate formats. You must use the same serialization format for both request and response payloads.

Include the following code to set the serialization and compression formats of requests and responses:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

"Message": {
  "Request": {
     "CompressionFormat": "GZip",
     "SerializationFormat": "Json"
  },
  "Response": {
     "CompressionFormat": "GZip",
     "SerializationFormat": "Json"
  }
}

Use the steps in this section to override the default value or, if set, the value defined in the configuration file.

Once the tokens are received, you can then make QuickBooks Online API calls using the .NET SDK. You can download the latest version using NuGet Package Manager. For example:

1
2
3
4
5

OAuth2RequestValidator oauthValidator = new OAuth2RequestValidator(access_token);
ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);
DataService commonServiceQBO = new DataService(serviceContext);
QueryService<Invoice> inService = new QueryService<Invoice>(serviceContext);
Invoice In = inService.ExecuteIdsQuery("SELECT * FROM Invoice").FirstOrDefault();

You must make a RefreshToken call after a 401 error (Invalid Token error) to get a new access token, or call RefreshToken every every hour since the Access Token expires in one hour.

Then, override the request and response formats, as follows.

1
2

context.IppConfiguration.Message.Request.SerializationFormat = SerializationFormat.Json;
context.IppConfiguration.Message.Response.SerializationFormat = SerializationFormat.Json;

Similarly, you can set the serialization to XML.​

Include the following code to compress request and response code, respectively, data using GZip format:

1
2

context.IppConfiguration.Message.Request.CompressionFormat = CompressionFormat.GZip;
context.IppConfiguration.Message.Response.CompressionFormat = CompressionFormat.GZip;

Similarly, you can set data compression of requests to Deflateor none. When compression is set to none, the SDK leaves the data uncompressed.​

Retry policies enable your app to handle transient errors. For detailed information on retry policies, click here.

Include the following code to set linear retry attempts:

1
2
3
4
5

"LinearRetry":{
    "Enable": "false",
    "RetryCount": "",
    "RetryInterval": ""
 }

Include the following code to set incremental retry attempts for a specified number of times:

1
2
3
4
5
6

"IncrementatlRetry": {
  "Enable": "false",
  "RetryCount": "",
  "InitialInterval": "",
  "Increment": ""
}

Include the following code to set randomized exponential retry attempts for a specified number of times:

1
2
3
4
5
6
7

"ExponentialRetry": {
  "Enable": "false",
  "RetryCount": "",
  "MinBackoff": "",
  "MaxBackoff": "",
  "DeltaBackoff": ""
}

Use the steps in this section to override the default value or, if set, the value defined in the configuration file.

Once the tokens are received, you can then make QuickBooks Online API calls using the .NET SDK. You can download the latest version using NuGet Package Manager. For example:

1
2
3
4
5

OAuth2RequestValidator oauthValidator = new OAuth2RequestValidator(access_token);
ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);
DataService commonServiceQBO = new DataService(serviceContext);
QueryService<Invoice> inService = new QueryService<Invoice>(serviceContext);
Invoice In = inService.ExecuteIdsQuery("SELECT * FROM Invoice").FirstOrDefault();

You must make a RefreshToken call after a 401 error (Invalid Token error) to get a new access token, or call RefreshToken every every hour since the Access Token expires in one hour.

Then, override the request and response formats, as follows. The IppConfiguration class has the IntuitRetryPolicy constructors required to override the configuration file settings. The parameters of the IntuitRetryPolicy constructor determine the number and frequency of retries.

Include the following code to set a linear retry:

1

context.IppConfiguration.RetryPolicy = new IntuitRetryPolicy(int retryCount, TimeSpan retryInterval);

Include the following code to set an incremental retry:

1

context.IppConfiguration.RetryPolicy = new IntuitRetryPolicy(int retryCount, TimeSpan initialInterval, TimeSpan increment);

Include the following code to set an exponential retry:

1

context.IppConfiguration.RetryPolicy = new IntuitRetryPolicy(int retryCount, TimeSpan minBackoff, TimeSpan maxBackoff, TimeSpan deltaBackoff);

The following table lists the parameters of the preceding IntuitRetryPolicy() constructors:

For an app to access a QuickBooks company, you must use OAuth to authorize the app. In this type of authorization, an OAuth token is used to authorize and connect an app to the company. For more information, see Authorization.

The basic structure of the configuration information are declared in Appsettings.json file, is as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

 {
  "Logger": {
   "RequestLog": {
       "EnableLogs": "true",
       "LogDirectory": ""
    }
},
 "Security": {
     "Mode": {
         "Oauth": {
             "Enable": "false",
             "AccessToken": ""
           }
  },
  "Message": {
       "Request": {
            "CompressionFormat": "GZip",
            "SerializationFormat": "Json"
         },
       "Response": {
            "CompressionFormat": "GZip",
            "SerializationFormat": "Json"
        }
  },
  "Service": {
      "BaseUrl": {
          "Qbo": "https://quickbooks.api.intuit.com",
          "Ips": "",
          "OAuthAccessTokenUrl": "",
          "UserNameAuthentication": ""
       },
       "MinorVersion": {
         "Qbo": "37"
       }
   },
  "WebhooksService": {
        "VerifierToken": {
              "Value": ""
        }
  },
 "Retry": {
     "Mode": {
         "LinearRetry": {
            "Enable": "false",
            "RetryCount": "",
            "RetryInterval": ""
          },
        "IncrementatlRetry": {
           "Enable": "false",
           "RetryCount": "",
           "InitialInterval": "",
           "Increment": ""
        },
       "ExponentialRetry": {
           "RetryCount": "",
           "MinBackoff": "",
           "MaxBackoff": "",
           "DeltaBackoff": ""
        }
     }
  }
}