Composable Commerce .NET SDK

Introduction

This repository contains the .NET SDKs generated from the Composable Commerce API reference.

Packages

Package	Version
HTTP API
Import API
Change History API

Example and Training material

Feel free to explore these examples using this SDK for calling the Composable Commerce HTTP API, and Import API. .NET Core SDK Training for V2 SDK

Installation

Download from Nuget

Package	Installation
HTTP API	dotnet add package commercetools.Sdk.Api
Import API	dotnet add package commercetools.Sdk.ImportApi
Change History API	dotnet add package commercetools.Sdk.HistoryApi

Technical Overview

The SDK consists of the following projects:

• commercetools.Base.Abstractions: Contains common classes and interfaces that can be used in other SDK projects like IClient and ISerializerService.
• commercetools.Base.Client: Contains CtpClient which communicate with Composable Commerce to execute requests, it contains also the classes related to the client like tokens,middlewares and handlers.
• commercetools.Base.Registration: Helper classes for things like types retriever.
• commercetools.Base.Serialization: Serialization and deserialization services for responses and requests to the HTTP API using System.Text.Json.
• commercetools.Sdk.Api: Contains all generated models and request builders to communicate with Composable Commerce HTTP API.
• commercetools.Sdk.ImportApi: Contains all generated models and request builders to communicate with the Import API.
• commercetools.Sdk.HistoryApi: Contains all generated models and request builders to communicate with the Change History API.
• commercetools.Sdk.GraphQL.Api: Contains a type safe GraphQL client to communicate with Composable Commerce HTTP API.

In addition, the SDK has the following directories:

• /IntegrationTests: Integration tests for the SDK. A good way for anyone using the .NET SDK to understand it further.
• /Tests: Unit Tests for serialization and request builders.
• /Examples:
  1. commercetools.Api.ConsoleApp as an example of how to use the SDK in a console app and create a client using ClientFactory.
  2. commercetools.Api.CheckoutApp, the example is developed to illustrate how to deal with the me endpoints, like listing and adding products to cart as anonymous user, user can login and switch to password token flow, it's storing the token in the cookie right now, cookies only used as POC, it maybe not the best option for production purposes.

Getting Started with the .NET SDK

All operations (get, query, create, update, delete and others) are available in the generated request builders, so you can build the request and use the client to execute it and all the request builders accessible through ApiRoot. In order to use the client object, it needs to be setup first through dependency injection setup.

Basic Workflow

At a high level, to make a basic call to the API, do the following:

1. Use the dependency injection class to set things up.
2. get a client object from the services responsible for calling requests to the API
3. use the ApiRoot instance inside the client and identify the project-key.
4. If needed - Create a draft object as a required for the request based on the documentation.
5. Build your request and execute it using ExecuteAsync.
6. Receive the response as a model.

Dependency Injection Setup

In the ConfigureServices method of Startup.cs add the following:

• Composable Commerce HTTP API:

services.UseCommercetoolsApi(this.configuration, "Client"); // replace with your instance of IConfiguration

• Import API:

services.UseCommercetoolsImportApi(this.configuration, "ImportClient");

• Change History API:

services.UseCommercetoolsHistoryApi(this.configuration, "HistoryClient");

Configuration

The client configuration needs to be added to appsettings.json in order for the client to work. The structure is as follows:

{
    "Client": {
        "ClientId": "", // replace with your client ID
        "ClientSecret": "", // replace with your client secret
        "AuthorizationBaseAddress": "https://auth.europe-west1.gcp.commercetools.com/", // replace if needed
        "Scope": "", // replace with your scope
        "ProjectKey": "", // replace with your project key
        "ApiBaseAddress": "https://api.europe-west1.gcp.commercetools.com/"  // replace if needed
    }
}

Getting instance of ApiRoot

you can use the instance inside the injected client or use ApiFactory to create a new instance.

• Composable Commerce HTTP API:

var root1 = client.WithApi();
var root2 = ApiFactory.Create(client);

• Import API:

var root1 = client.WithImportApi();
var root2 = ImportApiFactory.Create(client);

• Change History API:

var root1 = client.WithHistoryApi();
var root2 = HistoryApiFactory.Create(client);

Getting instance of ProjectApiRoot

The ProjectApiRoot is scoped to the projectKey in order to not have to provide the project for building requests. You can use the instance inside the injected client or use ApiFactory to create a new instance.

• Composable Commerce HTTP API:

ProjectApiRoot root1 = client.WithProject(projectKey);
ProjectApiRoot root2 = ApiFactory.Create(client, projectKey);

• Import API:

ProjectApiRoot root1 = client.WithImportApi(projectKey);
ProjectApiRoot root2 = ImportApiFactory.Create(client, projectKey);

• Change History API:

ProjectApiRoot root1 = client.WithHistoryApi(projectKey);
ProjectApiRoot root2 = HistoryApiFactory.Create(client, projectKey);

When using the UseCommercetools methods a ProjectApiRoot will be registered to the ServiceProvider using the project key given in the configuration

Multiple Clients

It is possible to use more than one client in the same application with different token providers. The following code can be used to set it up 2 clients with the default ClientCredentials token provider:

services.UseCommercetoolsApi(configuration,
                new List<string>{"AdminClient", "StoreClient"},
                CreateTokenProvider);

public static ITokenProvider CreateTokenProvider(string clientName, IConfiguration configuration, IServiceProvider serviceProvider)
        {
            var httpClientFactory = serviceProvider.GetService<IHttpClientFactory>();
            var clientConfiguration = configuration.GetSection(clientName).Get<ClientConfiguration>();
            return TokenProviderFactory.CreateClientCredentialsTokenProvider(clientConfiguration, httpClientFactory);
        }

you can choose different token provider based on the clientName, Also The appsettings.json then needs to contain the configuration sections named the same. The clients can then be injected by using IEnumerable and specific client can be selected by name.

    public MyController(IEnumerable<IClient> clients)
    {
        var storeClient = clients.FirstOrDefault(c => c.Name.Equals("StoreClient"));
    }

Using SDK

SDK follows a builder pattern when creating requests. Category resource will be used to demonstrate how to use the SDK. This behaviour is the same for all resources. The IClient interface can be used by injecting it and calling its ExecuteAsync method for different requests.

private readonly IClient client;
public CategoryController(IClient client)
{
    this.client = client;
}
public async Task CreatingRequests()
{
    var projectApiRoot = client.WithProject("project-key")
    // Create CategoryDraft
    var categoryDraft = new CategoryDraft
                {
                    Name = new LocalizedString {{"en", "Name"}},
                    Slug = new LocalizedString {{"en", "Slug"}},
                    Key = "Key"
                };

    // Use in the previous step configured client instance to send and receive a newly created Category
     var category = await projectApiRoot
                .Categories()
                .Post(categoryDraft)
                .ExecuteAsync();

    // Get Category by id
    var queriedCategory = await projectApiRoot
                .Categories()
                .WithId(category.Id)
                .Get()
                .ExecuteAsync();

    // Get Category by key
    var queriedCategory = await projectApiRoot
                .Categories()
                .WithKey(category.Key)
                .Get()
                .ExecuteAsync();

    // Query Categories
    var response = await projectApiRoot
            .Categories()
            .Get()
            .WithWhere($"key = \"{category.Key}\"")
            .ExecuteAsync();

    // Delete Category by id
    var deletedCategory = await projectApiRoot
            .Categories()
            .WithId(category.Id)
            .Delete()
            .WithVersion(category.version)
            .ExecuteAsync();

    // Update Category
    var newName = "newName";
    var action = new CategoryChangeNameAction
                    {
                        Name = new LocalizedString {{"en", newName}}
                    };
    var update = new CategoryUpdate
                    {
                        Version = category.Version,
                        Actions = new List<ICategoryUpdateAction> {action}
                    };

    var updatedCategory = await projectApiRoot
            .Categories()
            .WithId(category.Id)
            .Post(categoryUpdate)
            .ExecuteAsync();

    // Delete Category by key
    var deletedCategory = await projectApiRoot
            .Categories()
            .WithKey(category.Key)
            .Delete()
            .WithVersion(category.Version)
            .ExecuteAsync();
    }

Creating a client using ClientFactory

You can get a client from injected services or you can create client on the fly using ClientFactory, the example below illustrate how to create a client with password TokenFlow to get customer's orders:

private readonly IServiceProvider serviceProvider;

public CustomerController(IServiceProvider serviceProvider)
{
    this.serviceProvider = serviceProvider;
}
public async Task ExecuteAsync()
{
    var email = "customerEmail";
    var password = "customerPassword";

    var configuration = serviceProvider.GetService<IConfiguration>();
    var httpClientFactory = serviceProvider.GetService<IHttpClientFactory>();
    var serializerService = serviceProvider.GetService<SerializerService>();

    var clientConfiguration = configuration.GetSection("MeClient").Get<ClientConfiguration>();

    //Create passwordFlow TokenProvider
    var passwordTokenProvider = TokenProviderFactory
        .CreatePasswordTokenProvider(clientConfiguration,
            httpClientFactory,
            new InMemoryUserCredentialsStoreManager(email, password));

    //Create MeClient
    var meClient = ClientFactory.Create(
        "MeClient",
        clientConfiguration,
        httpClientFactory,
        serializerService,
        passwordTokenProvider);

    //Get Customer Profile
    var myProfile = await meClient.WithApi().WithProjectKey("project-key")
        .Me()
        .Get()
        .ExecuteAsync();

    //Get Customer Orders
    var myOrders = await
        meClient.WithApi()
            .WithProjectKey("project-key")
            .Me()
            .Orders()
            .Get()
            .ExecuteAsync();
}

If you are going to create the client using the ClientFactory, don't forget to call SetupClient extension method here while building the services container. This will attach the Default Handlers like ErrorHandler and LoggerHandler to the Client like below:

services.SetupClient(
                "MeClient",
                errorTypeMapper => typeof(ErrorResponse),
                s => s.GetService<SerializerService>()
            );

Predicates

• Query Predicate Builders

GraphQL

• GraphQL package

Migration Guidelines

To migrate from the 1.x to the 2.x, there is a guideline below:

• Migration guidelines from v1 to v2

Documentation

• Documentation