commercetools-dotnet-sdk

⚠️ This commercetools .NET SDK is deprecated and will be decommissioned within 2020. We provide for this repository maintenance support only, which means that new features are not actively developed. Pull requests will be reviewed and added. Issues with the SDK in using the API like serializing/deserializing will be fixed. For new projects we recommend to use our .NET Core SDK.

The commercetools.NET SDK allows developers to work effectively with the commercetools platform in their .NET applications by providing typesafe access to the commercetools HTTP API.

For more documentation please see the wiki

Supported Platforms

.NET Standard 2.0

Using the SDK

You will need a commercetools project to use the SDK. If you don't already have one, you can create a free trial project on the commercetools platform and configure the API credentials.

The namespaces in the SDK mirror the sections of the commercetools HTTP API. Access to these namespaces is provided by a fluent interface on the Client class.

Responses from the client are wrapped in a Reponse object so you can determine if the request was successful and view the error(s) returned from the API if it was not.

using System;
using System.Threading.Tasks;

using commercetools.Common;
using commercetools.Products;

class Program
{
    static void Main(string[] args)
    {
        new Program().Run().Wait();

        Console.WriteLine("Press any key to exit.");
        Console.ReadKey();
    }

    private async Task Run()
    {
        Configuration config = new Configuration(
            "https://auth.europe-west1.gcp.commercetools.com/oauth/token",
            "https://api.europe-west1.gcp.commercetools.com",
            "[your project key]",
            "[your client ID]",
            "[your client secret]",
            ProjectScope.ManageProject);

        Client client = new Client(config);

        Response<ProductQueryResult> response = await client.Products().QueryProductsAsync();

        if (response.Success)
        {
            ProductQueryResult productQueryResult = response.Result;

            foreach (Product product in productQueryResult.Results)
            {
                Console.WriteLine(product.Id);
            }
        }
        else
        {
            Console.WriteLine("{0}: {1}", response.StatusCode, response.ReasonPhrase);

            foreach (ErrorMessage errorMessage in response.Errors)
            {
                Console.WriteLine("{0}: {1}", errorMessage.Code, errorMessage.Message);
            }
        }
    }
}

Not all API sections and representations have been implemented in the SDK. If you need to work with areas of the API that have not yet been covered, you can use the Client to make JSON requests directly. Ask the client for a JObject and you will get the entire JSON response that is returned from the API.

This code snippet will have the same output as the code snippet above:

Response<JObject> response = await client.GetAsync<JObject>("/products");

if (response.Success)
{
    dynamic responseObj = response.Result;

    foreach (dynamic product in responseObj.results)
    {
        Console.WriteLine(product.id);
    }
}
else
{
    Console.WriteLine("{0}: {1}", response.StatusCode, response.ReasonPhrase);

    foreach (ErrorMessage errorMessage in response.Errors)
    {
        Console.WriteLine("{0}: {1}", errorMessage.Code, errorMessage.Message);
    }
}

License, Contributing

This software is licenses under the MIT License, which allows commercial use and modification as well as open source collaboration.

We are warmly welcoming contributors and are happy to help out. To contribute changes or improvements, please fork the repository into your account on GitHub and create a pull request.

Contribution Guidelines

The namespaces and directory names in the SDK should match up exactly with the project name in the documentation. For your contributions.

For Example: The namespace should be commercetools.CartDiscounts (plural) should be used rather than commercetools.CartDiscount (singular).
Only the required properties for an API entity should be used as constructor parameters in the corresponding SDK class. Parameters marked as optional in the documentation should not be required for creating a new instance of the class.

For Example: In the commercetools.CartDiscounts.CartDiscountDraft class, description, target, isActive, validFrom and validUntil should not be used as constructor parameters as they are not required.
Wherever applicable, try to treat objects as groups of entities and use a factory to create these groups of entities when response is being parsed.

For Example: The CartDiscountValue entities (AbsoluteCartDiscountValue/RelativeCartDiscountValue/GiftLineItemCartDiscountValue) are treated as a group of entities that share a common type property, Type (Relative/Absolute/GiftLineItem). These entities are created by a CartDiscountValueFactory when we parse the response from the CommerceTools API.

Mac Users

The Visual Studio IDE is available for Mac OS (preview version as of 2016)