This Getting Started Guide provides the following information to help you get started using the eBay .NET SDK:

Introduction

The eBay .NET SDK is a set of libraries and tools intended to simplify and speed up application development for .NET developers who want to create applications that access eBay through the eBay Trading API. The libraries provide convenience classes that do the heavy lifting for you in handling communication with the eBay platform, handling errors, logging, and so forth. The libraries also provide a wrapper layer for the Trading API calls, providing simplified access to request and response fields and eliminating the need to handle XML.

The eBay Trading API is an extensive API enabling an application to do these and other types of activities on eBay:

The Trading API is documented thoroughly in the Trading API Guide and Call Reference , which you refer to when you write code that constructs and processes data from the API objects in the SDK. (The SDK documentation set does not provide any details on the Trading API.)

What is in the SDK?

The following screen capture shows the typical directory structure of the SDK after installation:

directory structure

The following table provides a brief description for the main items of interest in the SDK distribution:

Directory/File Description
Doc Directory containing this guide, tutorials, the SDK library reference, and release notes.
Misc Directory containing the EULA, application icon, links to the eBay Windows Development Center, etc.
Samples Directory containing C# and VB.Net samples.
Source Directory containing source for the SDK lib, the attributes, lib, the samples helper lib, and the sanity test lib. You do not need to customize any source code unless you want to upgrade to a newer Trading API WSDL that is supported by the current version of the SDK lib. If you wish to do such an upgrade, you need to generate the new proxy class (code stubs) from the new WSDL first using the Code Generator and then write wrapper code for the new or changed elements from the new WSDL, prior to rebuilding the SDK lib from the source.
Tools Directory containing the code generator source and batch files. These are not needed unless you want to upgrade to a newer Trading API WSDL than is supported by the current SDK lib. These tools generate the proxy class (code stubs) from the new WSDL and also add certain customizations, such as using collection instead of array for container type, adding SOAP extension for logging purpose, and other eBay specific fixes.
wsdl Directory containing the WSDL used in this version of the SDK.
eBay.build A NAnt build script supporting .NET 2.0 and VS2005 builds.
eBay.Service.dll The redistributable SDK lib. Must be distributed with every eBay .NET SDK program. If you customize the source, you would replace this with the customized lib, but retaining the same name.
eBay.Service.SDK.Attribute.dll An optional redistributable attributes lib. This is only required if your program uses the eBay Attributes API.
SamplesHelper.dll Used only for the samples.
eBaySDKLicense The common development and distribution license you are subject to.

Requirements

Before Using the the SDK you will need the following:

When you deploy your program, the target computer requires:

Download Locations

The eBay SDKs can be downloaded from the eBay Windows developer center. The SDK is released at regular intervals to support the newer Trading API WSDL versions, although the WSDL version supported by SDK lags the latest version that is available.

The WSDLs can be downloaded from http://developer.ebay.com/webservices/Version/ebaySvc.wsdl, where Version is replaced by the version number of the WSDL release to be downloaded, for example, http://developer.ebay.com/webservices/687/ebaySvc.wsdl.

The latest released WSDL version can always be found at http://developer.ebay.com/webservices/latest/ebaySvc.wsdl.

Installing the SDK

To install the eBay .NET SDK,

  1. If you have another version of the eBay .NET SDK already installed on your system, save any modified code safely away at a location outside of the SDK install directory, then deinstall that older SDK version.
  2. Locate and download the desired SDK version from the eBay Windows developer center. Normally, it is best to download the latest available Full version with the installer (msi).

    download page
  3. Double-click the downloaded file to start the installation.
  4. Follow the prompts to install the SDK. Accepting the defaults is a good idea, but not required.

SDK Architecture

The following diagram illustrates the overall architecture of the eBay .NET SDK:

logical diagram

As shown in the illustration, the SDK kernel handles the SOAP communication with eBay for the application, using ApiCall properties. The application uses Api call wrappers to build the Trading API requests and the SDK kernel sends the corresponding SOAP request to the eBay Trading API. The response from the Trading API is handled by the SDK kernel, which wraps the response into the appropriate call wrapper response. The application can then extract data as needed from the response object.

Notice that the illustration shows two paths from the ApiCall layer to the Request and Response objects that are accessed by the application. This indicates that although the call wrappers may be used, you may optionally bypass the call wrappers in order to allow the application to access the underlying SOAP requests and responses if necessary.

A Closer Look at SDK Kernel-to-Trading API Communication

The following diagram shows a bit more of the underlying classes used in the SDK kernel-to-Trading API communication:

closeup diagram

As shown, the ApiCall base class has an ApiContext property that contains the key information required for accessing the eBay Trading API. The ApiContext class is a singleton that is shared by all call wrapper instances in the same session (each call wrapper is an extension of ApiCall.) The critical properties of ApiContext are shown above:

A Closer Look at Api Call Wrappers (extensions of ApiCall)

The following diagram shows a bit more of the underlying classes used in the SDK kernel-to-Trading API communication:

closeup diagram

As shown, the ApiCall base class is extended by each of the Api call wrapper classes, each of which corresponds to an equivalent call in the Trading API. Notice that each wrapper class instance in your code shares the same ApiContext object, which is set with valid URL, token, and site values.

In order to build the call request, refer to the Trading API call that the SDK call is based on. The SDK call is identical to its Trading API equivalent, except that the SDK version of the call has Call appended to it. For example, AddItem in the Trading API becomes AddItemCall in the SDK.

Some of the properties of the call wrapper object are used for input, some for output. To determine this for a particular call and to learn more about constructing any input objects required by a call wrapper, refer to the Trading API Call Reference section on input fields for detailed information.

What to Expect in the Call Response

The actual data returned in each call response can vary depending on the data supplied in the call request. Refer to the Trading API Call Reference sections on output fields for details on the possible data that could be returned for each call.

The Core SDK Classes

The following diagram shows the two main core SDK classes ApiCall and ApiContext, along with some API call wrapper classes that extend ApiCall:

sdk core

The ApiCall base class is not used directly, but is shown here because all the call wrapper classes extend it. Some of the more commonly used properties of the ApiCall base class are also shown. These are properties you would set on a per-call basis.

The ApiContext class is a singleton containing properties you set to be in effect for all calls in the current session. The ApiCredential and SoapApiServerUrl properties are required, the others are available should you want to use them.

Classes Used in ApiCall Properties

Class/Property Name Description
ApiContext Provides data required by the call wrapper classes (which are based on ApiCall) in order to communicate with eBay, such as tokens, URLs, and so forth. It also provides properties needed for logging, call retries, call metrics. See ApiContext for more information.
ApiException Contains any exceptions that resulted from the API call.
CallMetricsEntry Holds the optional call metrics object used to track performance of this call.
CallRetry Specifies the call retry that is to occur for this call if the exception specified in the CallRetry object is encountered.
EnableCompression Boolean for specifying whether the response data from this call should be compressed at the server to reduce transfer size.
HasError Boolean indicating whether the call response contains an error.
HasWarning Boolean indicating whether the call response contains a warning.

Classes Used in ApiContext Properties

Class/Property Name Description
ApiCredential Used to hold the token that authorizes the application to access eBay on behalf of the user.
ApiLogManager Used to contain the various logger objects used to implement logging in your application.
CallMetricsTable Table used to hold metrics logging information during the application calls to eBay.
EnableMetrics Boolean turning on or off the logging of performance data during calls to the eBay platform.
EPSServerUrl Used to hold the URL to use for uploading pictures to eBay Picture Service
ErrorLanguage Used to specify the use of a language other than the one used on the site you are accessing in any returned error messages.
LastCallTime Holds the time of the last API call.
Site Used to specify the eBay site that the application is accessing.
SoapApiServerUrl Specifies the URL indicating the eBay server and endpoint used by the Trading API: the call requests are sent to this URL.

Handling Authorization in Your Application

Most Trading API calls you make from the .NET SDK require an authorization token, which represents the user's authorization of your application to access eBay on behalf of that user. If eBay authorization tokens are new to you, review the short and focused topic Getting Tokens in the Trading API Guide. Be especially attentive to the different requirements of single-user and multi-user applications. There is also a very handy Getting Tokens tutorial.

Be aware that the methodology used in the .NET SDK sample applications to get and store the token is for a single-user application, for example, an in-house application that you use to do your own batch listings, where you can get the token in advance. In this scenario, you provide a token at design time within the App.config file; at runtime the sample programs load that stored value into the ApiCredential property of the ApiContext class instance.

However, multi-user applications (ones that you make available to other users not known in advance) would use a different method of obtaining and storing the token. Such applications would subsequently retrieve that token at runtime and load it into the ApiCredential property of the ApiContext class. For multi-user applications, you need to follow the instructions provided in Configuring the Consent Flow for Applications with Multiple Users . You also need to follow the process described in Getting Tokens for Applications with Multiple Users.

Sample Code for Getting Tokens

The follow .NET sample programs may be useful to you:

Building the Samples

The samples will not run unless you add a valid auth token(user token) to the samples and rebuild them.

To build the samples,

  1. All of the .NET samples are configured to refer the SDK kernel libraries under the SDK home directory. If you have rebuilt the SDK kernel using Source\DOTNET.SOAP.sln, run \Source\CopyDebug.bat to copy all needed files from bin\debug to the SDK home directory. (Or, if you rebuilt the SDK kernel as Release, run \Source\CopyRelease.bat to do the same thing.) Then run \Samples\C#\SwitchSDKRefConfig.bat to clean all the existing references for all samples before rebuilding the samples. Otherwise you may get a reference warning during the build attempt.
  2. Path to the SDK installation subdirectory \Samples\C# or \Samples\VB.NET.
  3. Double-click on the file CSharp Samples.sln or the file VB.Net Samples.sln if you are building VB.Net samples. If prompted to convert the solution to the newer version of Visual Studio, follow the prompts to do so.
  4. In the solution explorer,

    locate the App.config file for each project in the solution:

    solution explorer
  5. Open the App.config file in each project within the solution. Notice that the samples are set up to work with the Sandbox by default.

    Locate the line adding a key containing ApiToken in the name, and for the value, insert the Auth token (user token) for a user that you created in the sandbox as described earlier under Requirements.

    As shown here:

    app config
  6. In Visual Studio, rebuild the solution.
  7. To test your installation, run the simplest sample Hello World located in the SDK subdirectory /Samples/C#/HelloWorld.
  8. Run the other individual sample programs as desired.

Communicating with eBay

All .NET SDK applications communicate with an eBay site following the same basic procedure.

  1. Every application must instantiate ApiContext (a singleton)
  2. The user token (authorization token), eBay SOAP server and endpoint URL, and the site ID are loaded into ApiContext
  3. Any desired API call wrapper object (for example, AddItemCall) is instantiated using that ApiContext instance
  4. The call wrapper object is fully constructed
  5. The call wrapper object is invoked to send the request to eBay.
  6. The call response data is handled as desired

For details, see Making an SDK Call.

Advanced Topics

The following are advanced topics on commonly used SDK features:

Caching MetaData

The eBay API architecture uses metadata to describe rules for listing items and managing them through the life cycle of a sale. An example of metadata are the item categories for a given site, which is obtained by a call to GetCategory. This metadata typically is too large to retrieve every time you need it. Instead, you should cache that data locally and update it incrementally as needed. Your application can update the cached metadata periodically, either on a regular schedule or when the API reports that metadata has changed.

For example, the GetCategory call returns a version number for the current category hierarchy, and can be used to detect when this version number has changed. For more information about the category hierarchy version number see Maintaining Category Data in the eBay Trading API Guide.

Logging

The SDK provides the ability to log your application's SDK activities (It doesn't support special logging that you want to emit from your application's own, non-SDK related operations.) The type of information logged depends on how you initialize the logger object. For example, you can set the logger to log informational messages, exceptions, and/or the payload of the API call requests and responses. For debugging purposes, you would log all three of those message types. For a deployed application you might want to log only exceptions.

To add logging to your application, you instantiate an instance of the ApiLogManager class in your ApiContext object. You then add a FileLogger instance to the ApiLogManager, specifying the name of the log file and setting the logging booleans to the type of logging you want in the FileLogger constructor. The following snippet from the sample program ConsoleAddFixedPriceItem (located in /Samples/C#/ConsoleAddFixedPriceItem) shows how logging is added:

apiContext = new ApiContext();
//set Api logging
apiContext.ApiLogManager = new ApiLogManager();
apiContext.ApiLogManager.ApiLoggerList.Add(new FileLogger("listing_log.txt", true, true, true)
apiContext.ApiLogManager.EnableLogging = true;
// set other api context properties...

where the name of the log file is specified as listing_log.txt, and the logger is set to log everying. In the FileLogger constructor, the first boolean controls information logging, the second boolean controls the ApiMessage payload logging, and the third boolean controls exception logging. You can turn these on or off in any combination you wish. You can also change these properties at runtime if you wish.

For more information and useful tips on logging, see Logging Best Practices.

Call Metrics Logging

During development, you may wish to log performance data for specific calls, in order to determine application performance before you deploy your application. The call metrics feature allows you to do this. This feature is intended for development, not for deployed applications.

For more information and code samples on using call metrics logging, see Enabling Call Metrics Logging.

Exceptions

The SDK provides three classes for exceptions:

You can catch these exceptions and handle them as desired. One way to make use of these exceptions is to use a CallRetry object to retry the call for exceptions resulting from network problems or a busy server.

Call Retries

When your application accesses the eBay platform using the SDK, errors can occur, such as network connection errors, an eBay server that is busy and fails to respond to the call request quickly enough, or some failure in the SDK layer itself. For many types of these failures, your application should retry the call. For example, for most calls that fail due to HTTP problems, such as error 502 bad gateway, error 404, and so forth, you should retry two or three times. Similarly, API call failures, notably AddItem, can occur even though the request is validly constructed due to server traffic; so you should retry the call for those failures also.

The SDK provides an easy way to make call retries using the ApiCall class property named CallRetry. All that you need to do is to instantiate an object of the CallRetry class and set the number of retries, the errors for which you want to retry and the interval at which you want to retry.

Retry only for errors caused on the eBay server side and not because of an error in your application, because retries will not help resolve application errors. You should normally try no more than 2 times. You should check the Error result set returned by the API call and set valid input arguments before you retry. (An easy way to figure out what is causing the error is to open the log and inspect the call request and response.)

You can retry on any of following errors:

For details and a complete code sample, see the knowledgebase article How can I retry a call with the .NET SDK?

Multithreading in the SDK

The SDK is thread-safe and supports multithreading. However, your application is limited in the number of simultaneous call threads it can use to access the eBay platform through the API. For details on these and other limits, see the application compatiblity check page.

By default, the HTTP client of .Net framework does not allow more than 2 HTTP connections with any server. If your applcation uses multi-threads to call eBay servers, you may want to change the HTTP connection limit for better performance.

You can do this in either of the following two ways:

<system.net>
   <connectionManagement>
   <add address="*" maxconnection="5"/>
   </connectionManagement>
</system.net>
ServicePointManager.DefaultConnectionLimit = 5;

Either of the above methods can be used to change the allowed connections to 5.

For sample code, see the Multithreading sample located in the SDK subdirectory /Samples/C#/MultiThread.

Time Values in the SDK

You might notice that date-time values returned from eBay may appear to be different from the time stamps you see on the eBay.com Web site and the Sandbox Web site. The reasons for this is that times are displayed in the local timezone for that site (with the US site using Pacific Time) while the time stamps returned by the API are in GMT (UTC). For more details, refer to Time Valuesin the API documentation.

For example, the following scenario can occur with an application based on the SDK: suppose that your application makes a request using the local time (for example, 10 AM Pacific Time). That time in the request is changed by the Trading API to GMT (for example, to 5 PM GMT). And a GMT time returned from the Trading API (for example, 1 PM) received by an application is converted by the SDK to local time (for example, to 6 AM).

Some classes provide the ability to specify whether to use local or GMT time. For example, if are using the TimeFilter class, it has properties that allow you to set the time specifically in GMT: TimeFilter.TimeFromUTC and TimeFilter.TimeToUTC. For more information, see the topic for this class in the Library Reference located at the SDK install subdirectory \docs\LibRef. (The TimeFilter class properties TimeFilter.TimeFrom and TimeFilter.TimeTo specify local computer time.)

Additional information is available in the following two MSDN Library topics:

Executing API Calls Without using SDK Call Wrappers

In some cases you might want to access new or changed fields (in an existing API call) that are available in a more recent WSDL version than is supported by the current SDK's API call wrapper classes. To do this, you need to "bypass" the call wrapper class and write your own code that writes data to the new fields and processes the new data returned in the call response. You do this by calling ExecuteRequest instead of Execute, which uses the underlying SOAP request object that you populate using your own code. The response is returned to the underlying SOAP response object, from which you can extract the data using your own code rather than the call wrapper convenience layer.

Notice that if you do use ExecuteRequest directly to call the eBay API, then you need to explicitly cast the response to the proper type, as shown in this code snippet:

GetSellerTransactionsCall gst = new GetSellerTransactionsCall(this.apiContext);
GetSellerTransactionsRequestType req = new GetSellerTransactionsRequestType();
GetSellerTransactionsResponseType resp = (GetSellerTransactionsResponseType)gst.ExecuteRequest(req);

For more details, see How to "Bypass" the Call Wrappers to Execute API Calls.

Http Compression

The ApiCall class used to execute requests to the eBay API has HTTP compression turned on by default. This greatly reduces the size of response data from the API. HTTP compression is especially advantageous for calls such as GetCategories that return large amounts of data. If you need to turn HTTP compression off (or back on), use the EnableCompression property of the ApiCall class.

How to Update the SDK to a Newer Trading API Version

The SDK is compiled to support a specific version of the Trading API WSDL. In most cases, you do not need to update the SDK to a newer Trading API version, because the SDK is released at regular intervals to provide support for newer API versions. (Typically, the SDK lags the current Trading API by a few versions.) However, if you need you need access to some new features supported by a newer WSDL, you can update the SDK to a newer WSDL yourself. Updating the SDK to a new WSDL requires you to rebuild the SDK Kernel and generate code stubs.

Updating and Rebuilding the SDK Kernel

Note: The SDK update and rebuild process described here is not recommended for most SDK users. Only advanced developers with significant experience using the eBay trading API should undertake this.

The SDK kernel (eBay.Service.dll)is already built in each SDK release: it is ready for use and redistribution as needed. You only need to rebuild it if you wish to update the kernel to a newer WSDL version.

Each version of the eBay .NET SDK is based on a specific version of the Trading API WSDL. This WSDL is updated by eBay on a regular basis to provide new or enhanced features. However, because the SDK is updated less frequently than the Trading API WSDL, the SDK tends to lag the latest WSDL. This means that new features available only in the latest WSDL might not be available in the latest SDK.

To get around this, you can update the SDK kernel to the latest WSDL using this general process:

  1. Make a copy of the eBay.Service.SDK source and do your work using the copy, and save the existing binaries and source so you'll have a known good environment to revert back to.
  2. Use the eBay Code Generation tool to generate the new web proxy (code stubs) from the latest WSDL, as described in Generating Code Using the eBay Code Generation Tool. This tool provides customizations for the SDK, such as using collection instead of array as container type, adding a SOAP extension for logging purpose, and other eBay specific features.
  3. If the new WSDL contains a new API call you will need to create a new empty wrapper class for that call and write code in the new wrapper class, using existing wrapper class code as a guide. For example, if a new API call named GetFoo was added to the WSDL, create a new empty wrapper class named GetFooCall.cs in the SDK install subdirectory \Source\eBay.Service.SDK\Call, and add code, using code from the existing wrapper classes as your guide.
  4. If the new WSDL contains new or changed fields in an existing call, you modify the existing related wrapper class to provide code to handle the new fields, if required, again using existing wrapper code as your guide.
  5. When you finish adding the updates to the wrapper classes, rebuild the SDK kernel following the SDK build directions.

In most cases, you should not use the Sanity Test suite to test your work. However, if you do need to use Sanity Test, you need to first install NUnit (version 2.4.7, "net-2.0"), which can be obtained from theNUnit download site. Then test your changes using the Sanity Test suite located in the SDK subdirectory /Source/SanityTest Note also that if the server-side prerequisites for a call are not present, a call from the Sanity Test suite will show a call failure. Additionally, some tests may fail or may show success even when there has been a failure. To handle these cases, do the following:

  1. If necessary, update the Sanity Test project based on your NUnit installation.
  2. Build that project
  3. Start NUnit and run the UnitTests.exe file.

Other Links and Resources

You can find tutorials, code samples, and knowledgebase article links at the Samples/Tutorials page.

Back to top





This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.


© 2009–2010 eBay Inc. All rights reserved.
eBay and the eBay logo are registered trademarks of eBay Inc.
All other brands are the property of their respective owners.