Managing PLC libraries and placeholders

This chapter explains how to access and manage PLC libraries and PLC placeholders. Topics:

general information on PLC libraries and placeholders
navigating through references
adding references
removing references
finding available libraries
freezing the placeholder version
working with repositories

General information on PLC libraries and placeholders

In TwinCAT 3, there are two types of library objects: libraries and placeholders. Further information on both types can be found in the TwinCAT 3 documentation on library management.

In a TwinCAT 3 PLC project, references to libraries and placeholders are added as subordinate elements of the References node in the corresponding PLC project. When using the “Standard PLC Project” template, several libraries and placeholders are added to the project by default, such as Tc2_Standard, Tc2_System, etc.

Navigating through references

You can navigate to the References node via the Automation Interface by using the ITcSysManager::LookupTreeItem() method. To process this object correctly in C#, it must be converted to the ITcPlcLibraryManager interface.

C#:

ITcSmTreeItem references = systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References");
ITcPlcLibraryManager libManager = (ITcPlcLibraryManager) references;

PowerShell:

$references = $systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References")

All references can be iterated through using the ITcPlcLibraryManager::References property. This property returns a ITcPlcReferences collection that contains either library objects of type ITcPlcLibrary or placeholder objects of type ITcPlcPlaceholderRef.

C#:

ITcSmTreeItem references = systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References");
ITcPlcLibraryManager libManager = (ITcPlcLibraryManager) references;
foreach (ITcPlcLibRef libRef in libManager.References)
{
    if (libRef is ITcPlcLibrary)
    {
        ITcPlcLibrary library = (ITcPlcLibrary) libRef;
        // do something
    }
    else if (libRef is ITcPlcPlaceholderRef)
    {
        ITcPlcPlaceholderRef placeholder = (ITcPlcPlaceholderRef) libRef;
        // do something
    }
}

The iteration object libRef is of type ITcPlcLibRef, the common base class for ITcPlcLibrary and ITcPlcPlaceholderRef objects. To work with one of the specific classes, the object must be converted accordingly.

PowerShell:

$references = $systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References")
ForEach( $libRef in $references )
{
    $libRef.LanguageIndependentName
}

Adding references

The ITcPlcLibraryManager class provides two methods for adding a library or placeholder reference to a PLC project: AddLibrary() and AddPlaceholder().

A library can be added by specifying the library name, version, and distributor, or by using the library's display name.

Adding libraries

C#:

ITcSmTreeItem references = systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References");
ITcPlcLibraryManager libManager = (ITcPlcLibraryManager) references;
libManager.AddLibrary("Tc2_MDP", "*", "Beckhoff Automation GmbH"); // name, version, distributor
libManager.AddLibrary("Tc2_Math, * (Beckhoff Automation GmbH)"); // display name

PowerShell:

$references = $systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References")
$references.AddLibrary("Tc2_MDP", "*", "Beckhoff Automation GmbH")
$references.AddLibrary("Tc2_Math, * (Beckhoff Automation GmbH)")

Adding placeholders

C#:

ITcSmTreeItem references = systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References");
ITcPlcLibraryManager libManager = (ITcPlcLibraryManager) references;
libManager.AddPlaceholder("Tc2_MC2_Camming"); // add existing placeholder by name
libManager.AddPlaceholder("Placeholder_NC", "Tc2_NC", "*", "Beckhoff Automation GmbH");

PowerShell:

$references = $systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References")
$references.AddPlaceholder("Tc2_MC2_Camming")
$references.AddPlaceholder("Placeholder_NC", "Tc2_NC", "*", "Beckhoff Automation GmbH")

Removing references

To remove a reference, use the ITcPlcLibraryManager::RemoveReference() method.

C#:

ITcSmTreeItem references = systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References");
ITcPlcLibraryManager libManager = (ITcPlcLibraryManager) references;
libManager.RemoveReference("Tc2_Math"); // remove library
libManager.RemoveReference("Placeholder_NC"); // remove placeholder

PowerShell:

$references = $systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References")
$references.RemoveReference("Tc2_Math")
$references.RemoveReference("Placeholder_NC")

Finding available libraries

To search the system for all available PLC libraries, use the ITcPlcLibraryManager::ScanLibraries() method.

C#:

ITcSmTreeItem references = systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References");
ITcPlcLibraryManager libManager = (ITcPlcLibraryManager) references;
ITcPlcReferences libraries = libManager.ScanLibraries();
foreach(ITcPlcLibrary library in libraries)
{
    // do something
}

PowerShell:

$references = $systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References")
$libraries = $references.ScanLibraries()
ForEach( $lib in $libraries )
{
    $lib.Name
}

Freezing the placeholder version

C#:

ITcSmTreeItem references = systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References");
ITcPlcLibraryManager libManager = (ITcPlcLibraryManager) references;
libManager.FreezePlaceholder(); // freeze version of all placeholders
libManager.FreezePlaceholder("Placeholder_NC"); // freeze version of a specific placeholder

PowerShell:
$references = $systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References")
$references.FreezePlaceholder()
$references.FreezePlaceholder("Placeholder_NC")

	The version is locked at the Effective Resolution. If the Effective Resolution is set to `"*"`, the latest version available in the system will be used.

Working with repositories

The Automation Interface contains methods for managing PLC library repositories.

C#:

ITcSmTreeItem references = systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References");
ITcPlcLibraryManager libManager = (ITcPlcLibraryManager) references;
libManager.InsertRepository("TestRepository", @"C:\Temp", 0);
libManager.InstallLibrary("TestRepository", @"C:\SomeFolder\TcTestLibrary.library", false);
libManager.UninstallLibrary("TestRepository", "Tc2_MDP", "*", "Beckhoff Automation GmbH");
libManager.RemoveRepository("TestRepository");

PowerShell:

$references = $systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References")
$references.InsertRepository("TestRepository", "C:\Temp", 0)
$references.InstallLibrary("TestRepository", "C:\SomeFolder\TcTestLibrary.library", $false)
$references.UninstallLibrary("TestRepository", "Tc2_MDP", "*", "Beckhoff Automation GmbH")
$references.RemoveRepository("TestRepository")