Client creation and initialization

Before using any of the clients, you need to properly initialize them using the factory pattern provided by the SDK.

Namespaces Required

using AVEVA.IntegrationService.DataAPI.SDK;

using AVEVA.IntegrationService.DataAPI.SDK.ApiClient;

using System.Net.Http;

DataApiClientFactory

The DataApiClientFactory is the primary way to create client instances. It manages HTTP clients, hub connections, and authentication.

Factory Class Location

• Namespace: AVEVA.IntegrationService.DataAPI.SDK

• Interface: IDataApiClientFactory

Authentication Types

The SDK supports two authentication types:

public enum AuthenticationType

{

NTLM = 0, // Windows Authentication

Connect = 1 // Bearer Token Authentication

}

Creating Clients - Basic Example

The SDK uses a static factory method pattern for creating clients directly. Each client is created independently using the DataApiClientFactory.CreateDataApiClient<T>() method.

Option 1: Using Bearer Token Authentication (Connect)

using AVEVA.IntegrationService.DataAPI.SDK;

using System;

using System.Threading.Tasks;

namespace MyApplication

{

class Program

{

static async Task Main(string[] args)

{

// Configuration

string host = "https://your-server/integration/v1";

string bearerToken = "your-access-token-here";

int waitingTimeInMinutes = 60; // Timeout for live data requests

// Create Engineering Client

var engineeringClient = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: host,

authType: AuthenticationType.Connect,

waitingTimeInMinutesForLiveData: waitingTimeInMinutes,

token: bearerToken,

hubCancellationToken: null

);

// Create Excel Client

var excelClient = DataApiClientFactory.CreateDataApiClient<ExcelClient>(

host: host,

authType: AuthenticationType.Connect,

waitingTimeInMinutesForLiveData: waitingTimeInMinutes,

token: bearerToken,

hubCancellationToken: null

);

// Create SQL Client

var sqlClient = DataApiClientFactory.CreateDataApiClient<SqlClient>(

host: host,

authType: AuthenticationType.Connect,

waitingTimeInMinutesForLiveData: waitingTimeInMinutes,

token: bearerToken,

hubCancellationToken: null

);

// Use the clients

var dataSources = await engineeringClient.GetDataSources();

var excelFiles = await excelClient.GetExcels("ExcelDataSource", liveData: true);

}

}

}

Option 2: Using Windows Authentication (NTLM)

// Create client with NTLM authentication (no token required)

var engineeringClient = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: "https://your-server/integration/v1",

authType: AuthenticationType.NTLM,

waitingTimeInMinutesForLiveData: 60,

token: string.Empty, // Empty or null for NTLM

hubCancellationToken: null

);

// Use the client

var dataSources = await engineeringClient.GetDataSources();

Option 3: Dynamic Authentication Type Selection

// Determine auth type based on token availability

string host = "https://your-server/integration/v1";

string connectToken = GetAccessToken(); // Your method to get token

var engineeringClient = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: host,

authType: !string.IsNullOrEmpty(connectToken)

? AuthenticationType.Connect

: AuthenticationType.NTLM,

waitingTimeInMinutesForLiveData: 60,

token: connectToken,

hubCancellationToken: null

);

Option 4: With Cancellation Token

using System.Threading;

// Create cancellation token for hub operations

var hubCancellationTokenSource = new CancellationTokenSource();

var engineeringClient = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: "https://your-server/integration/v1",

authType: AuthenticationType.Connect,

waitingTimeInMinutesForLiveData: 60,

token: "your-access-token",

hubCancellationToken: hubCancellationTokenSource

);

// Later, cancel if needed

hubCancellationTokenSource.Cancel();

Creating Different Client Types

Each client type must be created separately using the factory method:

string host = "https://your-server/integration/v1";

string token = "your-access-token";

int waitingTime = 60;

// Engineering Client

var engineeringClient = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host, AuthenticationType.Connect, waitingTime, token, null);

// Simulation Client

var simulationClient = DataApiClientFactory.CreateDataApiClient<SimulationClient>(

host, AuthenticationType.Connect, waitingTime, token, null);

// Excel Client

var excelClient = DataApiClientFactory.CreateDataApiClient<ExcelClient>(

host, AuthenticationType.Connect, waitingTime, token, null);

// ETAP Client

var etapClient = DataApiClientFactory.CreateDataApiClient<ETAPClient>(

host, AuthenticationType.Connect, waitingTime, token, null);

// ERM Client

var ermClient = DataApiClientFactory.CreateDataApiClient<ERMClient>(

host, AuthenticationType.Connect, waitingTime, token, null);

// SQL Client

var sqlClient = DataApiClientFactory.CreateDataApiClient<SqlClient>(

host, AuthenticationType.Connect, waitingTime, token, null);

// Oracle Client

var oracleClient = DataApiClientFactory.CreateDataApiClient<OracleClient>(

host, AuthenticationType.Connect, waitingTime, token, null);

// Generic Client

var genericClient = DataApiClientFactory.CreateDataApiClient<GenericClient>(

host, AuthenticationType.Connect, waitingTime, token, null);

// Common Client

var commonClient = DataApiClientFactory.CreateDataApiClient<CommonClient>(

host, AuthenticationType.Connect, waitingTime, token, null);

// Others Client

var othersClient = DataApiClientFactory.CreateDataApiClient<OthersClient>(

host, AuthenticationType.Connect, waitingTime, token, null);

Alternative: Creating Clients Using Interface Type

The factory also supports creating clients using interface types:

var factory = new DataApiClientFactory();

// Create client using interface

var engineeringClient = factory.Create<IEngineeringClient>(

host: "https://your-server/integration/v1",

authType: AuthenticationType.Connect,

waitingTimeInMinutesForLiveData: 60,

token: "your-access-token",

hubCancellationToken: null

);

var excelClient = factory.Create<IExcelClient>(

"https://your-server/integration/v1",

AuthenticationType.Connect,

60,

"your-access-token",

null

);

Creating HealthCheck Client

The HealthCheck client is created separately as it doesn't require authentication:

using AVEVA.IntegrationService.DataAPI.SDK;

using System.Net.Http;

// Option 1: Using HealthCheckClientFactory

var healthCheckFactory = new HealthCheckClientFactory();

var healthCheckClient = healthCheckFactory.CreateHealthCheckClient(

"https://your-server/integration/v1"

);

// Option 2: Creating directly

var httpClient = new HttpClient();

var healthCheckClient2 = new HealthCheckClient(httpClient);

// Use the health check client

var status = await healthCheckClient.HealthCheckAPI(

"https://your-server/integration/v1"

);

Creating SignalR PubSub Client

For real-time messaging, create a SignalR client using the factory:

using AVEVA.IntegrationService.DataAPI.SDK.ApiClient;

using AVEVA.IntegrationService.DataAPI.SDK.Utilities;

using System.Threading;

// Create SignalR client using factory

var signalRClient = await SignalRHubConnectionFactory.CreatePubSubClient(

httpClientFactory: HttpClientUtilities.GetHttpClientFactory(),

hubConnectionManager: new HubConnectionManager(),

authType: AuthenticationType.Connect,

hubUrl: "https://your-server/integration/v1",

token: "your-access-token"

);

// Subscribe to events

signalRClient.MessagePublished += (sender, e) =>

{

Console.WriteLine($"Message received: {e.Message.AckId}");

};

// Subscribe to topics

await signalRClient.Subscribe("MyDataSourceName");

Complete Initialization Example with Token Refresh

using AVEVA.IntegrationService.DataAPI.SDK;

using System;

using System.Threading;

using System.Threading.Tasks;

public class DataApiService

{

private string _host;

private string _accessToken;

private int _waitingTime;

private EngineeringClient _engineeringClient;

private ExcelClient _excelClient;

private SimulationClient _simulationClient;

private SqlClient _sqlClient;

private ISignalRPubSubClient _signalRClient;

public async Task InitializeAsync(string host, string accessToken, int waitingTimeInMinutes = 60)

{

_host = host;

_accessToken = accessToken;

_waitingTime = waitingTimeInMinutes;

// Create individual clients

_engineeringClient = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

_host,

!string.IsNullOrEmpty(_accessToken) ? AuthenticationType.Connect : AuthenticationType.NTLM,

_waitingTime,

_accessToken,

null

);

_excelClient = DataApiClientFactory.CreateDataApiClient<ExcelClient>(

_host,

!string.IsNullOrEmpty(_accessToken) ? AuthenticationType.Connect : AuthenticationType.NTLM,

_waitingTime,

_accessToken,

null

);

_simulationClient = DataApiClientFactory.CreateDataApiClient<SimulationClient>(

_host,

!string.IsNullOrEmpty(_accessToken) ? AuthenticationType.Connect : AuthenticationType.NTLM,

_waitingTime,

_accessToken,

null

);

_sqlClient = DataApiClientFactory.CreateDataApiClient<SqlClient>(

_host,

!string.IsNullOrEmpty(_accessToken) ? AuthenticationType.Connect : AuthenticationType.NTLM,

_waitingTime,

_accessToken,

null

);

// Register token refresh handler for all clients

_engineeringClient.RegisterTokenRefreshHandler(RefreshTokenAsync);

_excelClient.RegisterTokenRefreshHandler(RefreshTokenAsync);

_simulationClient.RegisterTokenRefreshHandler(RefreshTokenAsync);

_sqlClient.RegisterTokenRefreshHandler(RefreshTokenAsync);

// Create SignalR client if using Connect authentication

if (!string.IsNullOrEmpty(_accessToken))

{

_signalRClient = await SignalRHubConnectionFactory.CreatePubSubClient(

httpClientFactory: HttpClientUtilities.GetHttpClientFactory(),

hubConnectionManager: new HubConnectionManager(),

authType: AuthenticationType.Connect,

hubUrl: _host,

token: _accessToken

);

// Register token refresh for SignalR

_signalRClient.RegisterTokenRefreshHandler(RefreshTokenAsync);

}

Console.WriteLine("Data API clients initialized successfully");

}

private async Task<string> RefreshTokenAsync()

{

// Implement your token refresh logic here

Console.WriteLine("Refreshing access token...");

// Your token refresh implementation

string newToken = await YourIdentityService.GetNewTokenAsync();

_accessToken = newToken;

// Update SignalR token

_signalRClient?.UpdateToken(newToken);

return newToken;

}

// Expose clients as properties

public EngineeringClient EngineeringClient => _engineeringClient;

public ExcelClient ExcelClient => _excelClient;

public SimulationClient SimulationClient => _simulationClient;

public SqlClient SqlClient => _sqlClient;

public ISignalRPubSubClient SignalRClient => _signalRClient;

// Cleanup method

public async Task CleanupAsync()

{

if (_signalRClient != null)

{

// Unsubscribe from all topics before disposing

// await _signalRClient.Unsubscribe("TopicName");

}

}

}

// Usage

var service = new DataApiService();

await service.InitializeAsync(

"https://your-server/integration/v1",

"your-access-token",

60

);

// Use the clients

var data = await service.EngineeringClient.GetObjectInfo("DataSource", "Elements");

var excelFiles = await service.ExcelClient.GetExcels("ExcelDataSource", liveData: true);

Configuration Options Summary

Method Signature

public static T CreateDataApiClient<T>(

string host,

AuthenticationType authType = AuthenticationType.NTLM,

int waitingTimeInMinutesForLiveData = 60,

string token = "",

CancellationTokenSource hubCancellationToken = null

) where T : class

API Versioning

The SDK supports multiple API versions. By default, it uses v1. To specify a version:

// The version is typically included in the base URL

string apiBaseUrlV1 = "https://your-server/integration/v1";

string apiBaseUrlV2 = "https://your-server/integration/v2";

// Some clients support explicit version parameter

var sqlClient = new SqlClient(

httpClient: httpClient,

waitingTimeInMinutesForLiveData: 5,

httpClientFactory: httpClientFactory,

hubConnectionManager: hubConnectionManager,

hubCancellationToken: null,

version: "2" // Explicit version

);

Dependency Injection Example (.NET Core / .NET 6+)

using Microsoft.Extensions.DependencyInjection;

using AVEVA.IntegrationService.DataAPI.SDK;

using Microsoft.Extensions.Options;

public class Startup

{

public void ConfigureServices(IServiceCollection services)

{

// Register configuration

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

// Register clients as singletons (or scoped based on your needs)

services.AddSingleton<EngineeringClient>(sp =>

{

var options = sp.GetRequiredService<IOptions<DataApiOptions>>().Value;

return DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: options.Host,

authType: options.AuthType,

waitingTimeInMinutesForLiveData: options.WaitingTime,

token: options.Token,

hubCancellationToken: null

);

});

services.AddSingleton<ExcelClient>(sp =>

{

var options = sp.GetRequiredService<IOptions<DataApiOptions>>().Value;

return DataApiClientFactory.CreateDataApiClient<ExcelClient>(

options.Host,

options.AuthType,

options.WaitingTime,

options.Token,

null

);

});

services.AddSingleton<SqlClient>(sp =>

{

var options = sp.GetRequiredService<IOptions<DataApiOptions>>().Value;

return DataApiClientFactory.CreateDataApiClient<SqlClient>(

options.Host,

options.AuthType,

options.WaitingTime,

options.Token,

null

);

});

// Register other clients as needed

}

}

// Configuration class

public class DataApiOptions

{

public string Host { get; set; }

public AuthenticationType AuthType { get; set; }

public string Token { get; set; }

public int WaitingTime { get; set; } = 60;

}

// appsettings.json

{

"DataApi": {

"Host": "https://your-server/integration/v1",

"AuthType": 1,

"Token": "your-token-here",

"WaitingTime": 60

}

}

// Usage in a controller or service

public class DataService

{

private readonly EngineeringClient _engineeringClient;

private readonly ExcelClient _excelClient;

public DataService(EngineeringClient engineeringClient, ExcelClient excelClient)

{

_engineeringClient = engineeringClient;

_excelClient = excelClient;

}

public async Task<DataTable> GetEngineeringDataAsync(string dataSource, string elements)

{

return await _engineeringClient.GetObjectInfo(dataSource, elements);

}

public async Task<IEnumerable<Excel>> GetExcelFilesAsync(string dataSource)

{

return await _excelClient.GetExcels(dataSource, liveData: true);

}

}

Error Handling During Initialization

try

{

string host = "https://your-server/integration/v1";

string token = "your-access-token";

var engineeringClient = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: host,

authType: AuthenticationType.Connect,

waitingTimeInMinutesForLiveData: 60,

token: token,

hubCancellationToken: null

);

// Verify connection with health check

var healthStatus = await engineeringClient.HealthCheck(host);

if (healthStatus == System.Net.HttpStatusCode.OK)

{

Console.WriteLine("Successfully connected to Data API");

}

else

{

Console.WriteLine($"Health check returned status: {healthStatus}");

}

}

catch (ArgumentNullException ex)

{

Console.WriteLine($"Invalid configuration: {ex.Message}");

}

catch (UriFormatException ex)

{

Console.WriteLine($"Invalid host URL format: {ex.Message}");

}

catch (HttpRequestException ex)

{

Console.WriteLine($"Cannot connect to API: {ex.Message}");

}

catch (Exception ex)

{

Console.WriteLine($"Initialization failed: {ex.Message}");

}

Addtional information

• Factory Pattern: Always use DataApiClientFactory.CreateDataApiClient<T>() to create clients. Each client is created independently.

• Separate Client Instances: Unlike traditional factories that return a single client with multiple properties, this SDK requires creating each client type separately.

• Thread Safety: Client instances created by the factory are thread-safe and can be reused across your application.

• Token Management: For long-running applications using Connect authentication, always implement token refresh handlers to prevent authentication expiration.

• SignalR Connections: SignalR connections are initialized asynchronously. Ensure the connection is established before subscribing to topics.

• Waiting Time: The waitingTimeInMinutesForLiveData parameter controls how long the client waits for acknowledgements from live data requests. Default is 60 minutes.

• Authentication Type Selection: Dynamically select authentication type based on token availability:

  var authType = !string.IsNullOrEmpty(token)

  ? AuthenticationType.Connect

  : AuthenticationType.NTLM;

• Client Reusability: Create clients once and reuse them throughout your application's lifetime for better performance.

• Resource Cleanup: Properly dispose of resources when your application shuts down:

  // Cleanup example

  public async Task CleanupAsync()

  {

  if (_signalRClient != null)

  {

  // Unsubscribe from all topics

  await _signalRClient.Unsubscribe("TopicName");

  }

  // Cancel any pending operations

  _cancellationTokenSource?.Cancel();

  _cancellationTokenSource?.Dispose();

  }

• Version Support: The SDK automatically detects the API version from the host URL (e.g., /v1, /v2).

Now that you know how to create and initialize clients, you can proceed to use the specific client methods documented in the subsequent sections.