Configuration

This section covers all configuration options available in the AVEVA Integration Service Data API SDK.

Basic Configuration

The SDK requires minimal configuration. At minimum, you need:

• DataAPI Host URL: Location of the AVEVA Integration Service Data API

• Authentication Type: NTLM or Connect

• Authentication Credentials: Windows credentials (NTLM) or access token (Connect)

  string host = "https://your-ais-server/api/v1/datasources";

  var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(host);

App.config Configuration

For .NET Framework or Console applications using App.config:

Basic Configuration

<?xml version="1.0" encoding="utf-8" ?>

<configuration>

<startup version="v4.0" sku=".NETFramework,Version=v4.7.2" />

<appSettings>

<!-- DataAPI endpoint URL -->

<add key="host" value="https://your-ais-server/api/v1/datasources"/>

<!-- Authentication type: NTLM or Connect -->

<add key="AuthenticationType" value="NTLM"/>

<!-- Timeout for live data acknowledgement (minutes) -->

<add key="waitingTimeInMinutesForLiveData" value="60"/>

</appSettings>

</configuration>

Reading from App.config

using System.Configuration;

var host = ConfigurationManager.AppSettings["host"];

var authTypeString = ConfigurationManager.AppSettings["AuthenticationType"];

var authType = authTypeString == "Connect"

? AuthenticationType.Connect

: AuthenticationType.NTLM;

var timeoutMinutes = int.Parse(

ConfigurationManager.AppSettings["waitingTimeInMinutesForLiveData"] ?? "60"

);

var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: host,

authType: authType,

waitingTimeInMinutesForLiveData: timeoutMinutes

);

appsettings.json Configuration

For .NET 5+ projects, use appsettings.json:

Basic Configuration

{

"Logging": {

"LogLevel": {

"Default": "Information"

}

},

"DataApi": {

"Host": "https://your-ais-server/api/v1/datasources",

"AuthenticationType": "NTLM",

"TimeoutMinutes": 60,

"RetryAttempts": 3,

"RetryDelayMs": 1000

}

}

Using IConfiguration in ASP.NET Core

using Microsoft.Extensions.Configuration;

public class DataApiService

{

private readonly IConfiguration _configuration;

public DataApiService(IConfiguration configuration)

{

_configuration = configuration;

}

public async Task<IEnumerable<DatasourceDto>> GetDataSources()

{

var host = _configuration["DataApi:Host"];

var authTypeString = _configuration["DataApi:AuthenticationType"];

var authType = authTypeString == "Connect"

? AuthenticationType.Connect

: AuthenticationType.NTLM;

var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: host,

authType: authType

);

return await client.GetDataSources("");

}

}

Configuration with Strongly-Typed Options

public class DataApiOptions

{

public string Host { get; set; }

public string AuthenticationType { get; set; }

public int TimeoutMinutes { get; set; }

public int RetryAttempts { get; set; }

public int RetryDelayMs { get; set; }

}

// Program.cs or Startup.cs

services.Configure<DataApiOptions>(

configuration.GetSection("DataApi")

);

// In your service

public class DataApiService

{

private readonly DataApiOptions _options;

public DataApiService(IOptionsMonitor<DataApiOptions> optionsMonitor)

{

_options = optionsMonitor.CurrentValue;

}

public async Task Initialize()

{

var authType = _options.AuthenticationType == "Connect"

? AuthenticationType.Connect

: AuthenticationType.NTLM;

var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: _options.Host,

authType: authType,

waitingTimeInMinutesForLiveData: _options.TimeoutMinutes

);

}

}

Environment Variables

Configuration via environment variables:

Windows Command Prompt

set AIS_HOST=https://your-ais-server/api/v1/datasources

set AIS_AUTH_TYPE=NTLM

set AIS_TIMEOUT=60

PowerShell

$env:AIS_HOST = "https://your-ais-server/api/v1/datasources"

$env:AIS_AUTH_TYPE = "NTLM"

$env:AIS_TIMEOUT = "60"

Linux/macOS

export AIS_HOST=https://your-ais-server/api/v1/datasources

export AIS_AUTH_TYPE=NTLM

export AIS_TIMEOUT=60

Reading Environment Variables

var host = Environment.GetEnvironmentVariable("AIS_HOST")

?? "https://localhost/api/v1/datasources";

var authTypeString = Environment.GetEnvironmentVariable("AIS_AUTH_TYPE") ?? "NTLM";

var timeoutString = Environment.GetEnvironmentVariable("AIS_TIMEOUT") ?? "60";

var authType = authTypeString == "Connect"

? AuthenticationType.Connect

: AuthenticationType.NTLM;

var timeout = int.Parse(timeoutString);

var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: host,

authType: authType,

waitingTimeInMinutesForLiveData: timeout

);

HttpClient Configuration

Configure Proxy

var handler = new HttpClientHandler

{

UseDefaultCredentials = true,

Proxy = new WebProxy("http://proxy-server:8080")

};

using (var httpClient = new HttpClient(handler))

{

var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(host);

}

SSL/TLS Certificate Validation

// WARNING: Only for development/testing with self-signed certificates.

// Never disable certificate validation in production.

var handler = new HttpClientHandler();

if (isDevelopment)

{

handler.ServerCertificateCustomValidationCallback =

HttpClientHandler.DangerousAcceptAnyServerCertificateValidator;

}

Timeout Configuration

Live Data Acknowledgement Timeout

// Timeout (minutes) waiting for asynchronous live data to become available

var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: host,

authType: AuthenticationType.NTLM,

waitingTimeInMinutesForLiveData: 120 // 2 hours

);

Handling Timeouts

try

{

var data = await client.GetDataSources("");

}

catch (TimeoutException ex)

{

Console.WriteLine("Request timed out. Try increasing timeout value.");

}

catch (TaskCanceledException ex)

{

Console.WriteLine("Request was cancelled due to timeout.");

}

Authentication Configuration

NTLM Authentication

// Uses current Windows user credentials automatically

var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: host,

authType: AuthenticationType.NTLM

);

Connect Authentication with Token

var token = "your-access-token"; // Obtain from AVEVA Connect service

var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: host,

authType: AuthenticationType.Connect,

token: token

);

Token Caching and Refresh

public class TokenManager

{

private string _cachedToken;

private DateTime _tokenExpiry;

public async Task<string> GetValidToken()

{

if (_cachedToken != null && DateTime.UtcNow < _tokenExpiry.AddMinutes(-5))

{

return _cachedToken;

}

_cachedToken = await RetrieveNewToken();

_tokenExpiry = DateTime.UtcNow.AddHours(1); // Adjust based on actual expiry

return _cachedToken;

}

private async Task<string> RetrieveNewToken()

{

// Implementation to get token from AVEVA Connect

throw new NotImplementedException();

}

}

Logging Configuration

Serilog Configuration

// Program.cs

Log.Logger = new LoggerConfiguration()

.MinimumLevel.Information()

.WriteTo.File(

"logs/application-.txt",

rollingInterval: RollingInterval.Day

)

.CreateLogger();

try

{

// Your application code

}

finally

{

Log.CloseAndFlush();

}

NLog Configuration

<!-- nlog.config -->

<nlog>

<targets>

<target name="logfile" xsi:type="File"

fileName="logs/${shortdate}.log"

layout="${longdate} ${level:uppercase=true} ${logger} ${message}"/>

</targets>

<rules>

<logger name="*" minlevel="Info" writeTo="logfile" />

</rules>

</nlog>

Application Insights

// appsettings.json

{

"ApplicationInsights": {

"InstrumentationKey": "your-key"

}

}

// In startup

services.AddApplicationInsightsTelemetry(

configuration["ApplicationInsights:InstrumentationKey"]);

Best Practices

Secure Credential Storage

Never hardcode credentials:

// BAD

var token = "hardcoded-token-value";

// GOOD

var token = configuration["DataApi:Token"];

// or from secure storage

var token = await secretManager.GetSecretAsync("ais-token");

Configuration Isolation

Keep development, staging, and production configurations separate:

appsettings.json (common)

appsettings.Development.json (development)

appsettings.Staging.json (staging)

appsettings.Production.json (production)

Validation on Startup

public IServiceCollection AddDataApiServices(IServiceCollection services, IConfiguration config)

{

var options = new DataApiOptions();

config.GetSection("DataApi").Bind(options);

if (string.IsNullOrEmpty(options.Host))

throw new InvalidOperationException("DataApi:Host is required");

if (options.AuthenticationType != "NTLM" && options.AuthenticationType != "Connect")

throw new InvalidOperationException("Invalid AuthenticationType");

services.Configure<DataApiOptions>(config.GetSection("DataApi"));

return services;

}

Use Dependency Injection

public interface IDataApiClient

{

Task<IEnumerable<DatasourceDto>> GetDataSources();

}

public class DataApiClientService : IDataApiClient

{

private readonly DataApiOptions _options;

private readonly ILogger<DataApiClientService> _logger;

public DataApiClientService(

IOptions<DataApiOptions> options,

ILogger<DataApiClientService> logger)

{

_options = options.Value;

_logger = logger;

}

public async Task<IEnumerable<DatasourceDto>> GetDataSources()

{

var authType = _options.AuthenticationType == "Connect"

? AuthenticationType.Connect

: AuthenticationType.NTLM;

var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: _options.Host,

authType: authType

);

return await client.GetDataSources("");

}

}

// Register in DI

services.AddScoped<IDataApiClient, DataApiClientService>();

Environment-Specific Configuration

public void ConfigureDataApi(IServiceCollection services, IConfiguration config, IHostEnvironment env)

{

if (env.IsDevelopment())

{

config["DataApi:Host"] = "http://localhost:44301";

}

else if (env.IsProduction())

{

config["DataApi:Host"] = "https://ais-prod.empresa.com";

}

services.Configure<DataApiOptions>(config.GetSection("DataApi"));

}