Breaking Changes and Migration

This section tracks breaking changes and provides migration guidance for different versions of the AVEVA Integration Service Data API SDK.

Version History

Version 4.0.0 (Current)

Current Features

• Full .NET Framework 4.7.2+ support

• .NET 5.0+ support

• NTLM authentication

• AVEVA Connect (token) authentication

• SignalR real-time pub/sub integration

• Specialized clients for Engineering, Excel, ERM, ETAP, Simulation

• Generic DataApiClient for dynamic datasource routing

No Breaking Changes Within 4.0.x

Upgrading within the 4.0.x patch range introduces no breaking changes.

Upgrading from 3.5.0 to 4.0.0

Breaking Change 1: Namespace Changes

Version 3.5.0:

using HAVIA.DataAPI.SDK; // Old namespace

var client = DataApiHttpClientFactory.CreateDataApiHttpClient<T>(host);

Version 4.0.0:

using AVEVA.IntegrationService.DataAPI.SDK; // New namespace

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

Migration: Update all using statements and rename the factory class and method.

Breaking Change 2: Factory Method Signature

Version 3.5.0:

public static T CreateDataApiHttpClient<T>(

HttpClient client,

string host,

AuthenticationType authType = AuthenticationType.NTLM

) where T : class

Version 4.0.0:

public static T CreateDataApiClient<T>(

string host,

AuthenticationType authType = AuthenticationType.NTLM,

int waitingTimeInMinutesForLiveData = 60,

string token = "",

CancellationTokenSource hubCancellationToken = null

) where T : class

Migration:

// Old code

using (var httpClient = new HttpClient(new HttpClientHandler { UseDefaultCredentials = true }))

{

var client = DataApiHttpClientFactory.CreateDataApiHttpClient<EngineeringClient>(

httpClient, host);

}

// New code – HttpClient managed internally

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

Breaking Change 3: Authentication

Migration for CONNECT:

// NTLM remains unchanged

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

// New: Connect authentication

var token = GetAccessToken();

var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: host,

authType: AuthenticationType.Connect,

token: token);

Breaking Change 4: SignalR Initialization

Version 3.5.0:

var signalRClient = new SignalRHubConnectionFactory(httpClient, host);

Version 4.0.0:

var pubSubClient = await SignalRHubConnectionFactory.CreatePubSubClient(

httpClientFactory,

new HubConnectionManager(),

authType,

host);

Migration: Update SignalR initialization to use the new async factory with HubConnectionManager.

Breaking Change 5: Timeout Configuration

Version 3.5.0: No explicit timeout parameter (used HttpClient default)

Version 4.0.0: Explicit live-data timeout via waitingTimeInMinutesForLiveData

Migration:

var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: host,

authType: AuthenticationType.NTLM,

waitingTimeInMinutesForLiveData: 120); // Set desired timeout in minutes

App.config Changes (3.5.0 → 4.0.0)

<!-- Version 3.5.0 -->

<configuration>

<appSettings>

<add key="host" value="https://..."/>

</appSettings>

</configuration>

<!-- Version 4.0.0 -->

<configuration>

<appSettings>

<add key="host" value="https://..."/>

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

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

</appSettings>

</configuration>

Migration Checklist (3.5.0 → 4.0.0)

• Update NuGet package to 4.0.0

• Update namespace: HAVIA.DataAPI.SDK → AVEVA.IntegrationService.DataAPI.SDK

• Rename factory: DataApiHttpClientFactory → DataApiClientFactory

• Rename method: CreateDataApiHttpClient → CreateDataApiClient

• Remove manual HttpClient creation and passing

• Configure Connect auth if needed (new token parameter)

• Update SignalR initialization to use HubConnectionManager

• Add waitingTimeInMinutesForLiveData to App.config

• Test all data retrieval operations

• Rebuild and retest

Upgrading from 2.0.0 to 4.0.0

Version 4.0.0 is not backwards compatible with 2.0.0. A full rewrite is required.

Architecture Comparison

Code Comparison

// Version 2.0.0

var client = new DataSourceClient(host, credentials);

var data = client.GetData(tableName); // Synchronous

// Version 4.0.0

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

var data = await client.GetTableData("DataSource", tableName, ""); // Async

Full Rewrite Steps

1. Create new project for 4.0.0 (or migrate on a branch)

2. Update all API calls to async methods with await

3. Replace client initialization with DataApiClientFactory pattern

4. Implement error handling using the 6 new custom exception types

5. Add configuration per new schema (App.config or appsettings.json)

6. Test thoroughly – API is significantly different

7. Deploy gradually with parallel systems if possible

Deprecated Features

No features are currently deprecated in version 4.0.0.

Future Deprecations (Planned)

• NTLM authentication may be deprecated in favour of Connect for cloud deployments.

• Support for .NET Framework versions earlier than 4.7.2 may end in a future major release.