Introducing the Bing Ads .NET SDK

  • Article

Today we are happy to announce the availability of the Bing Ads SDK beta for .NET on NuGet. This library will improve your Bing Ads developer experience by providing high-level access to features such as:

We are currently working on the Java version of the SDK, which will be available soon, followed by the Python SDK.

This post is an overview of the main features available within the Bing Ads SDK. You can find more details about these and other features on our MSDN page.

Bulk API

Since its first announcement, the Bulk API has offered an efficient way to manage your campaigns, keywords and other entities, transferring large amounts of data up to ten times faster than traditional SOAP APIs. However, as a text-based API, the Bulk API requires a lot of work on the client side to parse the files storing the Bing Ads entities. On the other hand, traditional SOAP APIs can be easily accessed using an automatically generated object model.

The Bing Ads SDK closes this gap by providing an infrastructure for accessing the Bulk API using the same object model as our SOAP APIs. It’s very easy now to migrate your existing code working with the SOAP API objects to take advantage of the Bulk API.

For example, one of the most popular requests from advertisers is the ability to quickly update keyword bids under their account based on their performance. Here’s how it can be done using the Bing Ads SDK:

First we instantiate a BulkServiceManager object:

      var bulkServiceManager = new BulkServiceManager(authorizationData);

Then download the keywords including their performance data during the last month:

 var keywords = (await bulkServiceManager.DownloadEntitiesAsync(new DownloadParameters {
     Entities = BulkDownloadEntity.Keywords,
     DataScope = DataScope.EntityData | DataScope.EntityPerformanceData,
     PerformanceStatsDateRange = new PerformanceStatsDateRange { PredefinedTime = ReportTimePeriod.LastMonth }
 })).OfType<BulkKeyword>();

And finally upload the keywords back, while increasing the bids by 10 for the keywords that had received more than 100 clicks:

      var uploadErrors = (await BulkServiceManager.UploadEntitiesAsync(new EntityUploadParameters {
      Entities = keywords.Where(keyword => keyword.PerformanceData.Clicks > 100).Select(keyword => {
           keyword.Keyword.Bid.Amount += 10;

            return keyword;

       }),
      ResponseMode = ResponseMode.ErrorsOnly
 })).OfType<BulkKeyword>();

The SDK also provides an easy way to write your objects to the bulk files or parse existing bulk files. Please check out the MSDN documentation for the BulkFileReader and BulkFileWriter.

OAuth Authorization

As you may already know, Bing Ads is now actively transitioning to the OAuth Authorization model, a better and more secure way to handle user authentication than the traditional username/password authentication.

To make this transition easier for our customers, the Bing Ads SDK includes high-level implementations of standard OAuth 2.0 grant flows, including the authorization code grant flow for both web and desktop applications and the implicit grant flow for desktop applications.

For example, to start using the OAuth authorization code grant flow, you have to first instantiate the corresponding OAuth object. If you are building a web app:

 var auth = new OAuthWebAuthCodeGrant(clientId, clientSecret, new Uri(redirectionUri));

Or if you are working on a desktop app:

 var auth = new OAuthDesktopMobileAuthCodeGrant(clientId);

Then you can get the url to direct the user to the Microsoft Account authorization page:

 var autorizationUrl = auth.GetAuthorizationEndpoint();

And once you are called back by the Microsoft Account authorization server, you can request the OAuth tokens by using the received authorization response uri:

 OAuthTokens tokens = await auth.RequestAccessAndRefreshTokensAsync(responseUri);

When using the OAuth objects with the ServiceClient class (described in the next section), your access and refresh tokens will be automatically refreshed upon the access token expiration. You can use the NewOAuthTokensReceived event to get notified whenever new tokens are received, to make sure you always have the latest refresh token.

Please check our Getting Started Guides on MSDN for complete examples of using the OAuth classes in your web or desktop application.

SOAP APIs

One of our goals in the Bing Ads SDK is to make sure it’s easy to access the SOAP APIs without doing any additional work. We have included generated proxy classes for all of our SOAP APIs, so there is no need for API users to manually run “svcutil” or another tool of choice.

We have also included the ServiceClient class that provides uniform access to all of our SOAP services. It also handles common request header fields for you, allowing to specify the values for fields such as CustomerId, AccountId, DeveloperToken etc. in the AuthorizationData object only once.

Here is an example of initializing the AuthorizationData object:

  var authorizationData = new AuthorizationData{
           AccountId = accountId,
           CustomerId = customerId,
           DeveloperToken = developerToken,
           Authentication = auth
 };

The Authentication property can hold one of the OAuth Authorization objects (for authorization code grants or implicit grants, also described in the previous section) or the PasswordAuthentication object (if you want to use the user name/password authentication).

Now that we have the AuthorizationData object, we can create the ServiceClient and call API operations without passing the same information with every request:

 var client = new ServiceClient<ICampaignManagementService>(authorizationData);
 var request = new GetAdGroupsByCampaignIdRequest { CampaignId = campaignId };
 GetAdGroupsByCampaignIdResponse response = 
      await client.CallAsync((s, r) => s.GetAdGroupsByCampaignIdAsync(r), request);

Note that we only set the CampaignId field on the GetAdGroupsByCampaignIdRequest. All other fields will be taken from the AuthorizationData object that we provided earlier.

Another great feature of the ServiceClient is automatic token refresh when using the OAuth Authorization objects (described in the previous section). Whenever your current access token expires, ServiceClient will detect it for you (by examining the error code returned from the Bing Ads API) and request a new pair of access and refresh tokens from the Microsoft Account authorization server. It will happen seamlessly without any action from your side. You can also subscribe to the NewOAuthTokensReceived event to always have the latest refresh token.

Please check our Getting Started Guides on MSDN for complete examples of using the ServiceClient with the AuthorizationData and OAuth classes in your web or desktop application.

Additional Resources

Please check our MSDN pages for more information about working with the Bing Ads SDK:

Coming soon

We be releasing the SDK source code under the MS-Public license on GitHub, where you will be able to browse and download the code or send pull requests if you want to make a contribution.

Feedback

Please let us know what you think about the Bing Ads SDK by sending an email to bing_ads_sdk@microsoft.com or leaving a comment below. We want to know about your experience coding with the Bing Ads SDK and what we can do to help you minimize your coding time and maximize conversions.