Getting Started with the Microsoft adCenter API

Getting Started with the Microsoft ...

Collapse All

Microsoft Advertising APIs

Before you can get started with the Microsoft adCenter API, you must obtain the appropriate Web Services Description Language (WSDL) document. The formal WSDL is an XML document that defines the format of messages in use by Microsoft adCenter. The service description serves as an agreement that defines the behavior of adCenter and instructs potential clients how to interact with it. Your development project must reference the appropriate WSDL to access the adCenter API.

Using Visual Studio 2008 with adCenter API

Using the adCenter API with Microsoft Visual Studio 2008 requires that you use the Microsoft .NET Framework version 3.0 or the .NET Framework version 3.5, and then add a service reference to your project.

Create a project that uses the adCenter API in Visual Studio 2008 by using the following steps.

Open Visual Studio 2008.
Create a new Visual C# or Visual Basic project. In the New Project combo box, make sure that .NET Framework 3.0 or .NET Framework 3.5 is selected.
After the project has been created, select Project, and then select the Add Service Reference command.
We recommend that you use message contracts when you create your client proxy, although it isn't required. Create a client proxy that uses message contracts by using the following steps:
1. In the Add Service Reference dialog box, click Advanced.
2. In the Service Reference Settings dialog box, select the Always generate message contracts check box as shown in the following figure.
  
  Always generate message contracts check box
3. Click the OK button.
For more information about message contracts, see Message Contracts.
In the Address field, type the URL of the Web service to create a service reference for. For example, to create a service reference for the sandbox reporting Web service, type "https://sandboxapi.adcenter.microsoft.com/Api/Advertiser/V6/Reporting/ReportingService.svc" in the Address field.
Click Go. Visual Studio then contacts the given URL and downloads the necessary information.
In the Namespace field, type a descriptive name for the namespace. This can be any name you want as long as it’s unique within your project; for example, "adCenter_ReportingService".
Click OK. Visual Studio then creates the necessary files and adds them to your project.
Repeat these steps for any other service references you may need.

To use the Web service, add a using or Imports statement to your code to include the service reference. The following is what a using statement would look like for the reporting service reference that was previously created.

using <project name>.adCenter_ReportingService;

The following is what an Imports statement would look like for the reporting service reference that was previously created.

Imports <project name>.adCenter_ReportingService

Replace <project name> with the name of your project.

You are now ready to begin writing code that uses the adCenter Web services you have added references to.

Using Visual Studio 2005 with adCenter API

Using the adCenter API with Microsoft Visual Studio 2005 requires that you complete a process that includes four steps. Each one of the following steps represents a procedure; each is covered in this topic in the order shown:

Install the Microsoft.NET Framework version 3.0.
Create the required client proxy files by using svcutil.exe.
Add the newly created client proxy files to your project.
Add the required references to System.Runtime.Serialization.dll and System.ServiceModel.dll.

For more information and a step-by-step example of how to create a program that uses the adCenter API, see Hello Microsoft adCenter Sample in C#.

Install the .NET Framework 3.0

The adCenter API uses Windows Communication Foundation (WCF) as the basis for implementing the Reporting and Campaign Management Web services. Previous versions of the adCenter API were based on ASP.NET Web Services (ASMX). When you use Visual Studio 2005 to create a WCF client, you must have the Microsoft .NET Framework 3.0 Service Pack 1 installed on all computers that your application is run on.

The .NET Framework version 3.0 amends rather than replaces the .NET Framework version 2.0. Starting with .NET Framework 3.0, WCF components are available. They must be used with the adCenter API and the languages that are compatible with the .NET Framework.

The .NET Framework 3.0 also contains the System.ServiceModel namespace, which contains the FaultException class. You're not required to use the FaultException class; however, it's the only way to take advantage of the error-reporting functionality in the adCenter API. You'll still use the .NET Framework 2.0 for the majority of your application.

Create the Client Proxy Files

You can no longer use either the Visual Studio 2005 Web Reference tool or the WSDL tool (wsdl.exe) to create your Web service client proxy. You must use the svcutil.exe utility to create your client proxy code when using one of the languages that is compatible with the .NET Framework. When the client proxy code is generated, you then manually add the generated files to your client project.

For more information about how to use the svcutil.exe utility, see the following topics:

The svcutil.exe utility is installed with the Windows SDK for Windows Server 2008 and .NET Framework 3.5. To install svcutil.exe, you need only to select the .NET Development Tools option.

The following is an example of an svcutil.exe command that creates a client proxy for the Campaign Management Web service.

svcutil https://sandboxapi.adcenter.microsoft.com/Api/Advertiser/V6/CampaignManagement/CampaignManagementService.svc /config:app.config /messageContract /n:*,adCenter.CampaignManagementService /language:csharp /out:CampaignManagementService.cs

This command creates two files—app.config and CampaignManagementService.cs. Described as follows, they are the client proxy files that must be added to your project:

app.config – Contains binding and endpoint information for the Web services
CampaignManagementService.cs – Contains the client proxy definitions

The previously mentioned svcutil.exe command creates a client proxy whose namespace is adCenter.CampaignManagementService. The namespace name is specified by the /n option. You can change this namespace to anything you choose. If you are using more than one adCenter service in your application, you must use different names for each namespace. Otherwise, the compiler cannot distinguish between the various services.

We recommend that you use message contracts when creating your client proxy, although it isn't required. To create a client proxy that uses message contracts, use the /messageContract (/mc) option with svcutil.exe to generate message contract types. For more information about message contracts, see Message Contracts.

Add the Client Proxy Files

You must manually add the client proxy files created by the svcutil.exe utility to your Visual Studio project.

Add the Required References

You must add references to System.Runtime.Serialization.dll and System.ServiceModel.dll to your project. These two DLLs are installed with the Microsoft .NET Framework 3.0 and are in the following directory:

%WINDIR%\Microsoft.NET\Framework\v3.0\Windows Communication Foundation

Message Contracts

Using message contracts creates client proxy code that uses the Request and Response sets of classes for the service operations. For example, the AddCampaigns service operation uses an AddCampaignsRequest object, and then returns an AddCampaignsResponse object. The set of Request classes contains all the header and parameter information that is passed to the service operation. The Response set of classes contains all the information that has been returned from the service operation.

If you don’t use message contracts, the signature of the service operations is significantly different. Without message contracts, each service operation uses all the header and parameter information as parameters to the service operation rather than wrapping them in a data class. For example, the signature of the AddCampaigns service operation with message contracts is as follows.

public AddCampaignsResponse AddCampaigns 
(
  AddCampaignsRequest request
);

By comparison, the signature of the CampaignManagementServiceClient.AddCampaigns service operation without message contracts is as follows.

public ApiCallTrackingData AddCampaigns 
(
  ApplicationToken applicationToken,
  System.Nullable<int> customerAccountId,
  DeveloperToken developerToken,
  UserCredentials userCredentials,
  int accountId,
  Campaign[] campaigns,
  out int[] campaignIds
);

For more information about message contracts, see Using Message Contracts.

Concepts

Developing with the Microsoft adCenter API