The QuickBooks Online .NET SDK has generic APIs to call Data Services using both synchronous and asynchronous methods. Asynchronous methods are potentially used to call object methods that require a long time to complete. Asynchronous calling enhances long running methods with an asynchronous variant that returns immediately while the original thread continues calling uninterrupted. It is also possible to subscribe and obtain return value when such long methods are complete. An example scenario where asynchronous method of calling can be used would be, calling thread is blocked until the method of loading data is complete. The following sections describe how to call the APIs asynchronously.
The .NET SDK provides asynchronous methods for accessing QuickBooks Online Data Services.
Note
Note
The .NET SDK supports globalization. Your app users can input data in languages such as Chinese or Japanese to obtain output in the same languages.
To asynchronously access a single data object, such as an account or customer, perform the following steps:
1. Reference the SDK Assemblies
Make sure the following assemblies have been referenced:
Include the following using statements:
1 2 3 4 | using Intuit.Ipp.Core; using Intuit.Ipp.DataService; using Intuit.Ipp.Data; using Intuit.Ipp.Security; |
2. Set up Configuration
The SDK allows you to set configurations for features such as Logging in the application settings (Appsettings.json) file. If you have already defined custom settings or do not need to configure custom settings for your app, go to step 3.
a. Configure the request and response message formats. Configure the serialization and compression format of requests and responses. For more information, see Making calls with the REST API. Include the following script to set the Serialization format of requests and responses to net and their compression format to GZip:
1 2 3 4 5 6 7 8 9 10 | "Message":{ "Request": { "CompressionFormat": "Gzip", "SerializationFormat": "Json" }, "Response": { "CompressionFormat": "Gzip", "SerializationFormat": "Json" } } |
Note
Note
You can define additional features in the config file. For information, see Configuration. If custom settings are not defined in the config file, the SDK will use the default values.
3. Build the ServiceContext
The ServiceContext
object is a parameter for all calls to QuickBooks OnlineData Services, Platform Services, and Reporting Services. When you call a data service API to access QuickBooks data, the SDK first retrieves the available custom configuration settings to build the ServiceContext
object. In the absences of custom settings, it uses the default values available within the SDK.
a. Create the OAuth2RequestValidator
object: A valid OAuth2RequestValidator
object ensures that the end-user has authorized your app to access QuickBooks Onlinedata. For details on how to create an OAuth2RequestValidator
object, see
Authorization.
1 | OAuth2RequestValidator reqValidator = new OAuth2RequestValidator(accessToken); |
ServiceContext
class. The following code creates a ServiceContext
object:
1 | ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator); |
4. Create the DataService
Create an instance of DataService
by passing the ServiceContext
created in Step 3 as the argument.
1 | DataService service = new DataService(context); |
5. Create the Data Object
Data objects (entities) represent QuickBookscompany data, such as invoices and customers. The following code shows how to create a customer object:
1 2 3 4 5 6 | Customer customer = new Customer(); //Mandatory Fields customer.GivenName = "Mary"; customer.Title = "Ms."; customer.MiddleName = "Jayne"; customer.FamilyName = "Cooper"; |
6. Subscribe to Events
Setup the callback event for the asynchronous service:
1 2 3 4 5 6 7 8 9 10 11 12 | service.OnAddAsyncCompleted += (sender, e) => { if (e.Error != null) { // Error handling code // User e.Error to get Error object } else if(e.Entity!=null) { Customer addedCustomer = e.Entity as Customer; } }; |
1 2 3 4 5 6 7 8 9 10 11 12 | service.OnUpdateAsyncCompleted += (sender, e) => { if (e.Error != null) { // Error handling code // User e.Error to get Error object } else if(e.Entity!=null) { Customer updatedCustomer = e.Entity as Customer; } }; |
1 2 3 4 5 6 7 8 9 10 11 12 | service.OnFindAllAsyncCompleted += (sender, e) => { if (e.Error != null) { // Error handling code // User e.Error to get Error object } else if(e.Entities!=null) { List<IEntity> customers = e.Entities; } }; |
1 2 3 4 5 6 7 8 9 10 11 12 | service.OnFindByIdAsyncCompleted += (sender, e) => { if (e.Error != null) { // Error handling code // User e.Error to get Error object } else if(e.Entity!=null) { Customer customer = e.Entity as Customer; } }; |
6. Call the Service
To perform a CRUD operation on QuickBooks Onlinedata, call the appropriate method on the service.
The following code snippets show how to call CRUD methods asynchronously:
1 | service.AddAsync<Customer>(customer); |
This operation updates all writable properties of an existing entity. If a writable property is omitted in the request, that property’s value is set to NULL.
1 | service.UpdateAsync<Customer>(customer); |
Note
Note
To update only the property values specified in the request and leave the rest of writable properties unchanged, set the sparse property to true.
To paginate through all of the objects of a specific type in a given company, call the FindAll()
method. Increment the startPosition
parameter with each successive call. The maxResult
parameter is the number of objects to fetch in each call. For example, the following code snippet gets
the first ten accounts:
1 2 3 | int startPosition = 1; int maxResult = 10; service.FindAllAsync<Customer>(customer, startPosition, maxResult); |
1 | service.FindByIdAsync<Customer>(customer); |
To asynchronously access multiple data objects in a single request, perform the steps as shown in the following example. For more information, see Calling synchronous methods asynchronously.
1. Build the ServiceContext object
The ServiceContext
object is a parameter for all calls to QuickBooks OnlineData Services, Platform Services, and Reporting Services. When you call a Data service API to access a QuickBooks company, the SDK first retrieves the available custom configuration settings to build the
ServiceContext
object.
OAuth2RequestValidator
object. A valid OAuth2RequestValidator
object ensures that the end user has authorized your app to access their QuickBooks company. The following code creates an OAuth2RequestValidator
object:
1 | OAuth2RequestValidator oauthValidator = new OAuth2RequestValidator(accessToken); |
b.Create a ServiceContext
object. The following code creates a ServiceContext
object:
1 | ServiceContext context = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator); |
2. Create the Data Service
Create an instance of DataServices
by passing the ServiceContext
as the argument:
1 | DataServices dataServices = new DataServices(context); |
3. Create the Batch object
The following code snippet shows how to create a Batch object:
1 | Batch batch = service.CreateNewBatch(); |
4. Create the Data object
Data objects (entities) represent QuickBooks company data, such as invoices and customers. The following code shows how to create a Customer
object:
1 2 3 4 5 6 | Customer customer = new Customer(); //Mandatory fields customer.GivenName = "Mary"; customer.Title = "Ms."; customer.MiddleName = "Jayne"; customer.FamilyName = "Cooper"; |
5. Add Request to the batch
Each operation element in the batch is called a batch item and is represented by a unique batch ID. The ID is referenced in the IntuitBatchResponse
objects that are returned by the call to the service. The following code snippets show how to add the operation element to the batch object created
in step 3:
1 2 3 4 5 | //This code adds the Create request to the batch batch.Add(customer, "bID1", OperationEnum.create); //This code adds the Query request to the batch batch.Add("Select * from Customer", "bID2"); |
6. Subscribe to the Event and execute the batch
To receive responses when batch processing completes, subscribe to the event and then execute the batch:
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 | try { batch.OnBatchExecuteAsyncCompleted += new BatchProcessingCallback.BatchExecutionCompletedEventHandler (this.BatchExecutionCompleted); batch.ExecuteAsync(); } catch (Ipp.Exception.IdsException ex) { } private void BatchExecutionCompleted(object sender, BatchExecutionCompletedEventArgs eventArgs) { if (eventArgs.Error != null) { Batch batch = eventArgs.Batch; IntuitBatchResponse addCustomerResponse = batch["addCustomer"]; if (addCustomerResponse.ResponseType == ResponseType.Entity) { Customer addedcustomer = addCustomerResponse.Entity as Customer; } IntuitBatchResponse queryCustomerResponse = batch["queryCustomer"]; if (queryCustomerResponse.ResponseType == ResponseType.Query) { List< Customer> customers = queryCustomerResponse.Entities.ToList().ConvertAll(item => item as Customer); } } } |