Examples

Basic Setup

NTLM Authentication (Windows domain)

using AVEVA.IntegrationService.DataAPI.SDK;

using AVEVA.IntegrationService.DataAPI.SDK.ApiClient;

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

// Uses current Windows domain credentials automatically

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

AVEVA Connect (Token) Authentication

var token = "your-aveva-connect-access-token";

var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: host,

authType: AuthenticationType.Connect,

token: token

);

Custom Timeout

var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host: host,

authType: AuthenticationType.NTLM,

waitingTimeInMinutesForLiveData: 120 // 2 hours instead of default 60

);

Data Retrieval Examples

Get All Data Sources

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

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

foreach (var ds in dataSources)

{

Console.WriteLine($"[{ds.Type}] {ds.Name}");

}

Get a Single Data Source

var dataSource = await client.GetDataSource("MyDataSourceName", "");

Console.WriteLine($"Name: {dataSource.Name}, Type: {dataSource.Type}");

Get Tables in a Data Source

var tables = await client.GetTables("MyDataSourceName", "");

foreach (var table in tables)

{

Console.WriteLine($"Table: {table.Name}");

}

Get Table Data

var data = await client.GetTableData("MyDataSourceName", "MyTableName", "");

foreach (var row in data)

{

Console.WriteLine($"Row: {row.Name}");

}

Get Table Schema (Columns)

var columns = await client.GetColumns("MyDataSourceName", "MyTableName", "");

foreach (var col in columns)

{

Console.WriteLine($"Column: {col.Name} ({col.DataType})");

}

Generic Data Source Client (IDataApiClient)

Use IDataApiClient when the datasource type is not known at compile time, or to work across multiple types from a single client.

Create a Generic Client

// IDataApiClient routes calls to the correct typed client at runtime

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

Enumerate All Sources by Product Category

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

// Group by type (Engineering, Excel, Simulation, etc.)

var byType = sources.GroupBy(s => s.Type);

foreach (var group in byType)

{

Console.WriteLine($"\n--- {group.Key} ---");

foreach (var source in group)

Console.WriteLine($" {source.Name}");

}

Dynamically Read Tables from Any Datasource

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

foreach (var source in sources)

{

Console.WriteLine($"\nDataSource: {source.Name} ({source.Type})");

var tables = await client.GetTables(source.Name, "");

foreach (var table in tables)

{

Console.WriteLine($" Table: {table.Name}");

// Read data from each table

var data = await client.GetTableData(source.Name, table.Name, "");

Console.WriteLine($" Rows: {data.Count()}");

}

}

Post Data Using the Generic Client

var tableData = new List<TableData>

{

new TableData { Name = "Row1", Value = "Value1" }

};

try

{

var result = await client.PostTableData("DataSourceName", "TableName", tableData, "");

Console.WriteLine($"Post result: {result}");

}

catch (MethodNotApplicableException ex)

{

// This datasource type does not support write operations

Console.WriteLine($"Operation not supported: {ex.Message}");

}

Handle Unsupported Operations Gracefully

// MethodNotApplicableException is thrown when a method is not valid for the datasource type

try

{

var simData = await client.GetSimulations("SomeDataSource", "");

}

catch (MethodNotApplicableException)

{

// GetSimulations is only valid on SimulationClient datasources

Console.WriteLine("GetSimulations not supported for this datasource type.");

}

Excel Integration

List Excel Sheets (as Tables)

var excelClient = DataApiClientFactory.CreateDataApiClient<ExcelClient>(host);

var sheets = await excelClient.GetTables("ExcelDataSourceName", "");

foreach (var sheet in sheets)

{

Console.WriteLine($"Sheet: {sheet.Name}");

}

Read Excel Sheet Data

var sheetData = await excelClient.GetTableData(

datasourceName: "ExcelDataSourceName",

tableName: "Sheet1",

filter: ""

);

foreach (var row in sheetData)

{

Console.WriteLine($"{row.Name} - {row.Value}");

}

Get Excel Data Source Information

var excelDataSource = await excelClient.GetExcelData("ExcelDataSourceName", "MyExcelFile");

foreach (var ds in excelDataSource)

{

Console.WriteLine($"Data: {ds.Name}");

}

Simulation Data

List Available Simulations

var simClient = DataApiClientFactory.CreateDataApiClient<SimulationClient>(host);

var simulations = await simClient.GetSimulations("SimulationDataSourceName", "");

foreach (var sim in simulations)

{

Console.WriteLine($"Simulation: {sim.Name}");

}

Get Simulation Snapshots

var snapshots = await simClient.GetSnapshotsforSimulation(

"SimulationDataSourceName",

"MySimulationName"

);

foreach (var snapshot in snapshots)

{

Console.WriteLine($" Snapshot: {snapshot}");

}

Retrieve SimCentral Data

var simCentralData = await simClient.GetSimCentralData(

datasourceName: "SimulationDataSourceName",

simulationName: "MySimulation",

snapshotName: "Snapshot1",

filter: ""

);

foreach (var data in simCentralData)

{

Console.WriteLine($" Data: {data.Name}");

}

Get PRO/II Simulation Data

var proiiData = await simClient.GetPROIIData(

datasourceName: "PRO/IIDataSourceName",

simulationName: "MySimulation",

filter: ""

);

foreach (var data in proiiData)

{

Console.WriteLine($" Data: {data.Name}");

}

Pub/Sub Messaging

Subscribe to a Topic

using AVEVA.IntegrationService.DataAPI.SDK.Utilities;

var pubSubClient = await SignalRHubConnectionFactory.CreatePubSubClient(

httpClientFactory: HttpClientUtilities.GetHttpClientFactory(),

hubConnectionManager: new HubConnectionManager(),

authType: AuthenticationType.NTLM,

host: host

);

try

{

var result = await pubSubClient.Subscribe("MyTopic");

Console.WriteLine($"Subscription result: {result}");

}

catch (HubConnectionInitializationException ex)

{

Console.WriteLine($"Failed to establish hub connection: {ex.Message}");

}

Unsubscribe from a Topic

var result = await pubSubClient.Unsubscribe("MyTopic");

Console.WriteLine($"Unsubscribe result: {result}");

Publish a Message

using AVEVA.IntegrationService.DataAPI.SDK.Models;

var broadcastMessage = new Broadcast

{

PublisherConnectionId = "your-connection-id",

CreatedTime = DateTime.UtcNow,

User = Environment.UserName,

AcknowledgementId = Guid.NewGuid().ToString(),

CallbackURL = "",

Context = "Your message content here"

};

try

{

var publishResult = await pubSubClient.Publish(broadcastMessage, host, "MyTopic");

Console.WriteLine($"Publish result: {publishResult}");

}

catch (DataPostMessageNotReceivedException ex)

{

Console.WriteLine($"Failed to publish message: {ex.Message}");

}

Error Handling

Basic Try-Catch with Specific Exceptions

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

try

{

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

}

catch (HubConnectionInitializationException ex)

{

Console.WriteLine($"Connection error: {ex.Message}");

// Retry with exponential backoff

}

catch (TimeoutException ex)

{

Console.WriteLine($"Request timed out: {ex.Message}");

// Retry with longer timeout

}

catch (Exception ex)

{

Console.WriteLine($"Unexpected error: {ex.Message}");

// Log and handle

}

Robust Data Retrieval with Retry Logic

public async Task<IEnumerable<DatasourceDto>> GetDataSourcesWithRetry(

string host,

int maxRetries = 3,

int delayMs = 1000)

{

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

for (int attempt = 1; attempt <= maxRetries; attempt++)

{

try

{

return await client.GetDataSources("");

}

catch (TimeoutException) when (attempt < maxRetries)

{

Console.WriteLine($"Attempt {attempt} timed out, retrying...");

await Task.Delay(delayMs * attempt); // Exponential backoff

}

catch (HubConnectionInitializationException) when (attempt < maxRetries)

{

Console.WriteLine($"Connection failed, retrying...");

await Task.Delay(delayMs * attempt);

}

catch (Exception ex)

{

Console.WriteLine($"Unrecoverable error: {ex.Message}");

throw;

}

}

throw new InvalidOperationException($"Failed after {maxRetries} attempts");

}

// Usage

var sources = await GetDataSourcesWithRetry(host);

Filtering Data

Simple Filter

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

// Empty filter – returns all records

var allData = await client.GetTableData("DataSourceName", "TableName", "");

// Filter by column value (OData-style)

var filteredData = await client.GetTableData(

"DataSourceName",

"TableName",

"Name eq 'MyValue'"

);

Complex Filtering

// Combine conditions with 'and'

var filter = "Status eq 1 and LastModified gt datetime'2024-01-01'";

var data = await client.GetTableData("DataSourceName", "TableName", filter);

Acknowledgments

Get Pending Acknowledgements

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

var acknowledgements = await client.GetAcknowledgements("DataSourceName");

foreach (var ack in acknowledgements)

{

Console.WriteLine($"Acknowledgement: {ack.Id} - Status: {ack.Status}");

}

Retrieve Data by Acknowledgement ID

var ackData = await client.GetTableDataByAcknowledgementId(

"DataSourceName",

"acknowledgement-id-guid"

);

foreach (var item in ackData)

{

Console.WriteLine($"Acknowledged Data: {item.Name}");

}

Complete Example: Multi-Source Data Retrieval

public class DataRetrievalExample

{

public async Task RetrieveFromMultipleSources(string host)

{

try

{

// Check API health first

var healthClient = HealthCheckClientFactory.CreateHealthCheckClient(new HttpClient());

var status = await healthClient.HealthCheckAPI(host);

if (status != System.Net.HttpStatusCode.OK)

{

Console.WriteLine("API is not available");

return;

}

// Engineering data

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

var engSources = await engClient.GetDataSources("");

Console.WriteLine($"Engineering Sources: {engSources.Count()}");

// Excel data

var excelClient = DataApiClientFactory.CreateDataApiClient<ExcelClient>(host);

var excelSources = await excelClient.GetDataSources("");

Console.WriteLine($"Excel Sources: {excelSources.Count()}");

// Simulation data

var simClient = DataApiClientFactory.CreateDataApiClient<SimulationClient>(host);

var simSources = await simClient.GetDataSources("");

Console.WriteLine($"Simulation Sources: {simSources.Count()}");

var totalSources = engSources.Count() + excelSources.Count() + simSources.Count();

Console.WriteLine($"Total Data Sources: {totalSources}");

}

catch (Exception ex)

{

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

}

}

}

// Usage

var example = new DataRetrievalExample();

await example.RetrieveFromMultipleSources(host);

Performance Tips

• Reuse clients – Create once and reuse for multiple operations:

  // Good

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

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

  var data2 = await client.GetTables("DS", "");

• Use async/await – Never block threads:

  // Good

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

  // Avoid: var data = client.GetDataSources("").Result;

• Filter server-side – Reduce data transferred:

  // Pass a filter to reduce rows returned

  var data = await client.GetTableData("DS", "Table", "Status eq 'Active'");

• Process as streams – Iterate IEnumerable<T> rather than materialising all at once:

  var data = await client.GetTableData("source", "table", "");

  foreach (var item in data)

  ProcessItem(item); // one at a time