AF SDK Reference

AFTable.LinkExternal Method (IDbDataAdapter, Boolean, SecureString)

Save PDF

TABLE OF CONTENTS

AFTable.LinkExternal Method (IDbDataAdapter, Boolean, SecureString)

Save PDF

Last UpdatedNov 18, 2025
6 minute read

This method allows the table to be linked to an external source while protecting security.

Namespace: OSIsoft.AF.Asset
Assembly: OSIsoft.AFSDK (in OSIsoft.AFSDK.dll) Version: 3.1.1.1182

Syntax

public void LinkExternal(
	IDbDataAdapter dataAdapter,
	bool impersonate,
	SecureString password
)

Public Sub LinkExternal ( 
	dataAdapter As IDbDataAdapter,
	impersonate As Boolean,
	password As SecureString
)

Dim instance As AFTable
Dim dataAdapter As IDbDataAdapter
Dim impersonate As Boolean
Dim password As SecureString

instance.LinkExternal(dataAdapter, impersonate, 
	password)

public:
void LinkExternal(
	IDbDataAdapter^ dataAdapter, 
	bool impersonate, 
	SecureString^ password
)

member LinkExternal : 
        dataAdapter : IDbDataAdapter * 
        impersonate : bool * 
        password : SecureString -> unit

Parameters

dataAdapter: Type: System.DataIDbDataAdapter
A DataAdapter which defines the external link. Passing will reset the AFTable back to an internal table.
impersonate: Type: SystemBoolean
Indicates if server should impersonate the client when obtaining this table. Using impersonation may require Kerberos delegation between the PI AF Server and the computer that holds the data. If this is specified, then the PI AF Server must support the ExternallyLinkedTableWithSecurity feature. If this is not set, then the PI AF Server must support the ExternallyLinkedTableWithNonImpersonatedUser feature or a password must be specified.
password: Type: System.SecuritySecureString
Password to the command string. This password will replace '<PASSWORD>' in the connection string. If this is specified, then the PI AF Server must support the ExternallyLinkedTableWithSecurity feature.

Remarks

This method will configure the AFTable to read its data from an external source. The data is read by the PI AF Server and returned to the client, therefore the data adapter's connection string must be defined in terms of the PI AF Server. This method will automatically save any changes to this object to the server by calling the ApplyChanges method. Once defined, use the Table property to retrieve the data.

Use the PISystem.Supports method to check if the PISystem supports the ExternallyLinkedTable, ExternallyLinkedTableWithNonImpersonatedUser, or ExternallyLinkedTableWithSecurity features.

Security Note
If the impersonate parameter is , then the user must have Admin permission on the PISystem to call this method.

Examples

// This example demonstrates how to link an existing external table to an AFTable using an ADODB.Recordset
// and three .NET data adapters (ODBC, OLEDB, and SQL).
// Note: This sample uses a sample MS Access 2010 database that can be downloaded from Microsoft at:
// http://office.microsoft.com/en-us/templates/northwind-sales-web-database-TC101114818.aspx

// This example will work with 64 bit Microsoft Office 2010 and SQL Server 2012 - some 
// modifications to connection strings will be necessary to work with other versions
// of Microsoft Office and Microsoft SQL Server or on 32 bit systems.

// Get the Database 
PISystems myPISystems = new PISystems();
AFDatabase myDB = myPISystems.DefaultPISystem.Databases.DefaultDatabase;

// ****************************************************
// Create an external Table using an OLEDB data adapter
// ****************************************************
AFTable myTable = myDB.Tables.Add("Employees OLEDB");
myTable.Description = "This is my employee table using OLEDB data adapter.";
myTable.CacheInterval = TimeSpan.FromMinutes(30);

string oleDbCommand = "SELECT * FROM Employees";
OleDbConnection oleDbConnection = new OleDbConnection(@"Provider=Microsoft.ACE.OLEDB.12.0;Data Source=c:\Northwind.accdb");
OleDbDataAdapter oleDbDataAdapter = new OleDbDataAdapter(oleDbCommand, oleDbConnection.ConnectionString);

// Link to the External OLEDB data adapter 
myTable.LinkExternal(oleDbDataAdapter, true, null);
myTable.CheckIn();

// ***************************************************
// Create an external Table from Excel using an ODBC data adapter
// ***************************************************
myTable = myDB.Tables.Add("Employees ODBC");
myTable.Description = "This is my employee table from Excel using ODBC data adapter.";
myTable.CacheInterval = TimeSpan.FromMinutes(30);

string odbcCommand = "SELECT * FROM A1:F10";
OdbcConnection odbcConnection = new OdbcConnection(@"DRIVER={Microsoft Excel Driver (*.xls, *.xlsx, *.xlsm, *.xlsb)};DBQ=\Employees.xlsx");
OdbcDataAdapter odbcDataAdapter = new OdbcDataAdapter(odbcCommand, odbcConnection.ConnectionString);

// Link to the External OLEDB data adapter 
myTable.LinkExternal(odbcDataAdapter, true, null);
myTable.CheckIn();

// *************************************************
// Create an external Table using a SQL data adapter
// *************************************************
myTable = myDB.Tables.Add("Employees SQL");
myTable.Description = "This is my employee table using SQL data adapter.";
myTable.CacheInterval = TimeSpan.FromMinutes(30);

string sqlCommand = "SELECT * FROM Employees";
SqlConnection sqlConnection = new SqlConnection($"Server={SqlServerMachineName};Database=Northwind;User Id={SqlUserId};Password=<PASSWORD>;Trusted_Connection=False;");
SqlDataAdapter sqlDataAdapter = new SqlDataAdapter(sqlCommand, sqlConnection);

// Link to the External SQL data adapter 
System.Security.SecureString password = new System.Security.SecureString();
foreach (char c in SqlPassword)
{
    password.AppendChar(c);
}

password.MakeReadOnly();
myTable.LinkExternal(sqlDataAdapter, false, password);
myTable.CheckIn();

// Display the DataTable
StringBuilder line = new StringBuilder();
foreach (DataColumn col in myTable.Table.Columns)
{
    line.AppendFormat("{0}, ", col.ColumnName);
}
Console.WriteLine(line.ToString());
line.Clear();
foreach (DataRow row in myTable.Table.Rows)
{
    foreach (DataColumn col in myTable.Table.Columns)
    {
        line.AppendFormat("{0}, ", row[col.ColumnName]);
    }
    Console.WriteLine(line.ToString());
    line.Clear();
}

// The Table can be Refreshed Manually using AFTable.Refresh
myTable.Refresh();

' This example demonstrates how to link an existing external table to an AFTable using an ADODB.Recordset
' and three .NET data adapters (ODBC, OLEDB, and SQL).
' Note: This sample uses a sample MS Access 2010 database that can be downloaded from Microsoft at:
' http://office.microsoft.com/en-us/templates/northwind-sales-web-database-TC101114818.aspx

' This example will work with 64 bit Microsoft Office 2010 and SQL Server 2012 - some 
' modifications to connection strings will be necessary to work with other versions
' of Microsoft Office and Microsoft SQL Server or on 32 bit systems.

' Get the Database 
Dim myPISystems As New PISystems
Dim myDB As AFDatabase = myPISystems.DefaultPISystem.Databases.DefaultDatabase
Dim myTable As AFTable

' ****************************************************
' Create an external Table using an OLEDB data adapter
' ****************************************************
myTable = myDB.Tables.Add("Employees OLEDB")
myTable.Description = "This is my employee table using OLEDB data adapter."
myTable.CacheInterval = TimeSpan.FromMinutes(30)

Dim oleDbCommand As String = "SELECT * FROM Employees"
Dim oleDbConnection As OleDbConnection = New OleDbConnection("Provider=Microsoft.ACE.OLEDB.12.0;Data Source=c:\Northwind.accdb")
Dim oleDbDataAdapter As OleDbDataAdapter = New OleDbDataAdapter(oleDbCommand, oleDbConnection)

' Link to the External OLEDB data adapter
myTable.LinkExternal(oleDbDataAdapter, True, Nothing)
myTable.CheckIn()

' ***************************************************
' Create an external Table from Excel using an ODBC data adapter
' ***************************************************
myTable = myDB.Tables.Add("Employees ODBC")
myTable.Description = "This is my employee table from Excel using ODBC data adapter."
myTable.CacheInterval = TimeSpan.FromMinutes(30)

Dim odbcCommand As String = "SELECT * FROM A1:F10"
Dim odbcConnection As OdbcConnection = New OdbcConnection("DRIVER={Microsoft Excel Driver (*.xls, *.xlsx, *.xlsm, *.xlsb)};DBQ=\Employees.xlsx")
Dim odbcDataAdapter As OdbcDataAdapter = New OdbcDataAdapter(odbcCommand, odbcConnection.ConnectionString)

' Link to the External OLEDB data adapter 
myTable.LinkExternal(odbcDataAdapter, True, Nothing)
myTable.CheckIn()

' *************************************************
' Create an external Table using a SQL data adapter
' *************************************************
myTable = myDB.Tables.Add("Employees SQL")
myTable.Description = "This is my employee table using SQL data adapter."
myTable.CacheInterval = TimeSpan.FromMinutes(30)

Dim sqlCommand As String = "SELECT * FROM Employees"
Dim sqlConnection As SqlConnection = New SqlConnection($"Server={SqlServerMachineName};Database=Northwind;User Id={SqlUserId};Password=<PASSWORD>;Trusted_Connection=False;")
Dim sqlDbDataAdapter As SqlDataAdapter = New SqlDataAdapter(sqlCommand, sqlConnection)

' Link to the External OLEDB data adapter
Dim password As System.Security.SecureString = New System.Security.SecureString
For Each c As Char In SqlPassword
    password.AppendChar(c)
Next

password.MakeReadOnly()
myTable.LinkExternal(sqlDbDataAdapter, False, password)
myTable.CheckIn()

' Display the DataTable
Dim line As New StringBuilder()
For Each col As DataColumn In myTable.Table.Columns
    line.AppendFormat("{0}, ", col.ColumnName)
Next
Console.WriteLine(line.ToString())
line.Clear()
For Each row As DataRow In myTable.Table.Rows
    For Each col As DataColumn In myTable.Table.Columns
        line.AppendFormat("{0}, ", row(col.ColumnName))
    Next
    Console.WriteLine(line.ToString())
    line.Clear()
Next

' The Table can be Refreshed Manually using AFTable.Refresh
myTable.Refresh()

No code example is currently available or this language may not be supported.

AF SDK Reference