Learning PathModule

Set up the .NET SDK

Learn how to configure your environment for the .NET SDK.

Ask about this Page
Copy for LLM
View as Markdown

After completing this module, you should be able to:

  • Use the .NET SDK to work on a commercetools Project.

The following instructions help you set up your environment to develop applications with commercetools using the .NET SDK.

This exercise walks you through a hands-on setup. For the full SDK reference, including .NET integration and multi-API support, see Get started with the .NET SDK.

To follow along, you'll need:

  • Your preferred .NET IDE or text editor
  • The .NET runtime

Pay special attention to version requirements.

Install an IDE

In this tutorial, we use Visual Studio Code (VS Code) with the C# Dev Kit extension. If you prefer a full-featured IDE, Visual Studio Community is a free alternative.
If you don't have VS Code installed, follow the instructions here.

Check .NET runtime version

The .NET SDK requires .NET Standard 2.1 or later. We recommend .NET 8 or later for new projects.

To check the version of .NET installed on your machine, run the following command in your terminal:

Check .NET versionbash
dotnet --version
If .NET is not installed or the version is too old, download the latest release from dotnet.microsoft.com.

Install the SDK

Let's now set up a new project and install the commercetools .NET SDK.

Step 1: Create a new project

Create a new console application in your terminal. We named ours commercetools-environment.
Create a new console applicationbash
dotnet new console -n commercetools-environment
cd commercetools-environment

Open the project folder in VS Code:

Open the project in VS Codebash
code .
Once the project is open, you should see a Program.cs file and a .csproj file in the Explorer panel.

Step 2: Install the SDK packages

Add the core commercetools SDK package and the Import API package. This learning path uses both:

Install SDK packagesbash
dotnet add package commercetools.Sdk.Api
dotnet add package commercetools.Sdk.ImportApi
dotnet add package Microsoft.Extensions.Logging.Console
The commercetools.Sdk.Api package provides access to the HTTP API. The commercetools.Sdk.ImportApi package is required for the Import API module later in this learning path.

Step 3: Finish project setup

Verify the packages installed successfully by running:

Restore packagesbash
dotnet restore
Open your .csproj file and confirm that the three packages appear as PackageReference entries, similar to the following:
commercetools-environment.csprojxml
<ItemGroup>
  <PackageReference Include="commercetools.Sdk.Api" Version="*" />
  <PackageReference Include="commercetools.Sdk.ImportApi" Version="*" />
  <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="*" />
</ItemGroup>

Do you see all the packages listed? Great, you are ready to create a commercetools application!

Test your setup

Let's now check if the SDK is set up correctly. Make sure that you have created an API Client as mentioned previously before continuing.

Step 4: Set up an API Client in your SDK

Create a new folder called impl inside your project directory. Inside that folder, create a file called ClientService.cs and copy the following code into it.
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using commercetools.Sdk.Api;
using commercetools.Sdk.Api.Client;

public static class ClientService
{
    public static ProjectApiRoot CreateApiClient()
    {
        var services = new ServiceCollection();
        var configuration = new ConfigurationBuilder()
            .AddInMemoryCollection(new List<KeyValuePair<string, string>>
            {
                new("Client:ApiBaseAddress", "https://api.{region}.commercetools.com/"),
                new("Client:AuthorizationBaseAddress", "https://auth.{region}.commercetools.com/"),
                new("Client:ClientId", "{clientID}"),
                new("Client:ClientSecret", "{clientSecret}"),
                new("Client:ProjectKey", "{projectKey}")
            })
            .Build();

        services.UseCommercetoolsApi(configuration, "Client");
        services.AddLogging();

        return services.BuildServiceProvider()
            .GetRequiredService<ProjectApiRoot>();
    }
}

Then update the following placeholder values to match your API Client:

  • {clientID}
  • {clientSecret}
  • {projectKey}
  • {region} (for both ApiBaseAddress and AuthorizationBaseAddress)
For the region values, see Hosts to find the correct region for your Project.

Step 5: Fetch the Customer data

Now let's use the API Client to make the first call to the commercetools API. Create a file called CustomerFetch.cs in the root of your project and copy the following code. Remember to update the Customer ID.
using commercetools.Sdk.Api.Client;
using Microsoft.Extensions.Logging;

public class CustomerFetch
{
    public static async Task Main(string[] args)
    {
        ProjectApiRoot projectApiRoot = ClientService.CreateApiClient();

        ILoggerFactory loggerFactory = LoggerFactory.Create(b => b.AddConsole());
        ILogger logger = loggerFactory.CreateLogger<CustomerFetch>();

        string customerId = "{customerID}";

        var customer = await projectApiRoot
            .Customers()
            .WithId(customerId)
            .Get()
            .ExecuteAsync();

        logger.LogInformation("Customer last name: " + customer.LastName);
    }
}

Step 6: Execute the code

Run the application with the following command in your terminal:

Run the applicationbash
dotnet run

If the Customer is fetched successfully, you should see the Customer's last name in the console output.

If you receive a 401 Unauthorized error, double-check that your clientID, clientSecret, and projectKey are correct in ClientService.cs.