Skip to main content

Client Initialization from Environment Variables

APIMatic's SDKs support initializing clients directly from environment variables, allowing you to configure SDK settings automatically without hardcoded values. This enables seamless environment-specific deployments, secure credential management, and runtime configuration changes without modifying your code.

The .NET SDK supports client initialization directly from IConfigurationSection, leveraging .NET's built-in configuration system. This allows developers to define SDK settings through multiple configuration sources such as configuration files, environment variables, user secrets, and command-line arguments.

The SDK integrates seamlessly with your existing .NET configuration setup (for example, appsettings.json or any other provider). If you don't have configuration set up yet, you can use ConfigurationBuilder as shown in the examples below to easily configure and utilize the configuration system.

The FromConfiguration Method

The FromConfiguration method has been added to both Client and Client.Builder classes. It accepts an IConfigurationSection and returns a configured client instance or a client builder instance.

Basic Client Initialization 

using Sdk.Standard;
using Microsoft.Extensions.Configuration;

namespace ConsoleApp;

// Build the IConfiguration using .NET conventions (JSON, environment, etc.)
var configuration = new ConfigurationBuilder()
    .AddJsonFile("config.json")
    .AddEnvironmentVariables() // [optional] read environment variables
    .Build();

// Instantiate your SDK and configure it from IConfiguration
var client = SdkClient
    .FromConfiguration(configuration.GetSection("SdkConfig"));

Advanced Client Initialization with Builder Pattern 

using Sdk.Standard;
using Microsoft.Extensions.Configuration;
using Environment = Tester.Standard.Environment;

namespace ConsoleApp;

// Build the IConfiguration using .NET conventions (JSON, environment, etc.)
var configuration = new ConfigurationBuilder()
    .AddJsonFile("config.json")
    .AddEnvironmentVariables() // [optional] read environment variables
    .Build();

// Instantiate your SDK builder and configure it from IConfiguration with overrides
var client = Sdk.Builder
    .FromConfiguration(configuration.GetSection("SdkConfig"))
    .Environment(Environment.Testing)
    .HttpClientConfig(c => c.Timeout(TimeSpan.FromSeconds(60)))
    .Build();

Note: You can also override configurations loaded from the IConfigurationSection if needed by using the builder methods on Client.Builder.

JSON Configuration Structure

Here's an example of how your config.json file should be structured to work with the above code samples:

{
  "SdkConfig": {
    "Environment": "testing",
    "Port": "port",
    "HttpClientConfig": {
      "Timeout": "00:01:00",
      "NumberOfRetries": 3,
      "BackoffFactor": 2,
      "RetryInterval": 1,
      "MaximumRetryWaitTime": "00:02:00",
      "StatusCodesToRetry": [408, 413],
      "RequestMethodsToRetry": ["GET", "PUT", "DELETE"],
      "ProxyConfiguration": {
        "Address": "http://localhost:3000",
        "Port": 8080,
        "Tunnel": false,
        "User": "username",
        "Pass": "password"
      }
    }
  }
}

Environment Variables Configuration

You can also configure individual settings using environment variables. .NET's configuration system uses double underscores (__) to represent nested configuration sections. Here are some examples:

# Set the environment
SdkConfig__Environment=production

# Set number of retries
SdkConfig__HttpClientConfig__NumberOfRetries=5

# Configure proxy settings
SdkConfig__HttpClientConfig__ProxyConfiguration__Port=8080

Configuration Precedence

When using environment variables, their precedence depends on the order in which you add configuration providers to the ConfigurationBuilder. Providers added later override values from earlier providers.