Getting Started

This guide gives a brief overview of how to get started with the Google Ads API .NET library.

Installation

The client library binaries are distributed using NuGet. Add a Nuget reference to the Google.Ads.GoogleAds package in your project to use the client library.

Set up authorization

To authorize your API calls, you need to specify your client ID, client secret, refresh token, and developer token to the library.

If you already have credentials...

• Copy the GoogleAdsApi node and the GoogleAdsApi section under the configSections node from the App.config file in GitHub into your App.config / Web.config file. If you used NuGet to install the package, these nodes will be automatically inserted into your App.config / Web.config file.
• Include the developer token, the client ID, client secret, and refresh token in your app's App.config / Web.config. The App.config file included in GitHub is well-documented, but you can also refer to the Configuration guide to learn more as well as use alternate configuration settings.

If you need to generate credentials...

• Follow the Developer token guide to obtain your developer token, if you don't already have one.
• Follow the OAuth desktop app flow guide to generate a client ID, client secret, and refresh token.
• Copy the GoogleAdsApi node and the GoogleAdsApi section under the configSections node from the App.config file in GitHub into your App.config / Web.config file. If you used NuGet to install the package, these nodes will be automatically inserted into your App.config / Web.config file.
• Include the developer token, the client ID, client secret, and refresh token in your app's App.config / Web.config. The App.config file included in GitHub is well-documented, but you can also refer to the Configuration guide to learn more as well as use alternate configuration settings.

Make an API call

The basic usage of the client library is shown below:

// Create a Google Ads client.
GoogleAdsClient client = new GoogleAdsClient();

// Create the required service.
CampaignServiceClient campaignService =
    client.GetService(Services.V10.CampaignService);

// Make more calls to service class.

Create a GoogleAdsClient instance

The most important classes in the Google Ads API .NET library is the GoogleAdsClient class. It lets you create a pre-configured service class that can be used for making API calls. GoogleAdsClient provides a default constructor that creates a user object using the settings specified in your app's App.config / Web.config. Refer to the Configuration guide for various configuration options.

// Create a new GoogleAdsClient with the App.config settings.
GoogleAdsClient user = new GoogleAdsClient();

Create a service

GoogleAdsClient provides a GetService method that can be used to create an Ads service.

CampaignServiceClient campaignService = client.GetService(Services.V10.CampaignService);
// Now make calls to CampaignService.

We provide a Services class that enumerates all the supported API versions and services. The GetService method accepts these enumeration objects as argument when creating the service. For example, to create an instance of CampaignServiceClient for version V10 of the Google Ads API, you need to call GoogleAdsClient.GetService method with Services.V10.CampaignService as the argument, as shown above.

Thread safety

It is not safe to share a GoogleAdsClient instance between multiple threads, since the configuration changes you make on an instance in one thread might affect the services you create on other threads. Operations like obtaining new service instances from a GoogleAdsClient instance, making calls to multiple services in parallel, etc., are thread-safe.

A multithreaded application would look something like this:

GoogleAdsClient client1 = new GoogleAdsClient();
GoogleAdsClient client2 = new GoogleAdsClient();

Thread userThread1 = new Thread(addAdGroups);
Thread userThread2 = new Thread(addAdGroups);

userThread1.start(client1);
userThread2.start(client2);

userThread1.join();
userThread2.join();

public void addAdGroups(object data) {
  GoogleAdsClient client = (GoogleAdsClient) data;
  // Do more operations here.
  ...
}

Canceling async methods

For async programming, you can use the callSettings parameter to pass a CancellationToken:

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
cancellationTokenSource.CancelAfter(3000);
CallSettings callSettings = CallSettings.FromCancellationToken(cancellationTokenSource.Token);

string query = "SELECT campaign.name FROM campaign";
var request = new SearchGoogleAdsStreamRequest()
{
    CustomerId = customerId.ToString(),
    Query = query,
};

GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V10.GoogleAdsService);

googleAdsService.SearchStream(request,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        foreach (GoogleAdsRow googleAdsRow in resp.Results)
        {
            // Process the row.
        }
    }, callSettings
);

Error handling

Not every API call will succeed. The server can throw errors if your API calls fail for some reason. It is important to capture API errors and handle them appropriately.

A GoogleAdsException instance is thrown when an API error occurs. It has details to help you figure out what went wrong:

// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V10.CampaignService);

// Create a campaign for update.
Campaign campaignToUpdate = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    // More fields to update.
    // ...
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};

try
{
    // Update the campaign.
    MutateCampaignsResponse response = campaignService.MutateCampaigns(
        customerId.ToString(), new CampaignOperation[] { operation });

    // Display the results.
    // ...
}
catch (GoogleAdsException e)
{
    Console.WriteLine("Failure:");
    Console.WriteLine($"Message: {e.Message}");

    // Can examine to get more error details.
    Console.WriteLine($"Failure: {e.Failure}");

    // Can be shared with Google for further troubleshooting.
    Console.WriteLine($"Request ID: {e.RequestId}");
}