Accessing, creating and handling PLC-Libraries and -Placeholde

This chapter explains in-depth how to access and handle PLC libraries and PLC placeholders. The following list shows all chapters in this article:

General information about PLC libraries and placeholders

There are two library object types in TwinCAT 3: 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, the references to libraries and placeholders are added as subordinate Tree Items to the reference node below the corresponding PLC project. If the "Standard PLC Project" template is chosen, certain libraries and placeholders are added to the project by default, e.g. Tc2_Standard, Tc2_System, … .

Accessing, creating and handling PLC-Libraries and -Placeholde 1:

When using the Automation Interface, you can simply navigate through the reference node using the ITcSysManager::LookupTreeItem() method.

Code snippet (C#): 

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

Code snippet (PowerShell): 

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

In order to handle this object correctly, it must be subjected to a type cast corresponding to the ITcPlcLibraryManager interface.

ITcPlcLibraryManager libManager = (ITcPlcLibraryManager) references;

Please note that this step is not required in Windows PowerShell.

Navigating through references

You can run through all references using the ITcPlcLibraryManager::References property. This property returns an ITcPlcReferences collection of either library objects (represented by ITcPlcLibrary) or placeholder objects (represented by ITcPlcPlaceholderRef).

Code snippet (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 object libRef; which is used for the iteration, is of type ITcPlcLibRef. This is a common base class for ITcPlcLibrary and ITcPlcPlaceholderRef objects. In order to be able to work with one of these specific classes, we must subject the object to a corresponding type cast, as shown in the code snippet above.

Code snippet (PowerShell): 

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

Adding references

The ITcPlcLibraryManager class offers two methods that can be used to add a library or placeholder reference to a PLC project: AddLibrary() and AddPlaceholder().

A library can be added in two different ways:

The display name of a library can be defined in the properties window of the library or the placeholder:

Accessing, creating and handling PLC-Libraries and -Placeholde 2:

Adding libraries:

Code snippet (C#): 

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

Code snippet (PowerShell): 

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

A placeholder can be added in two different ways:

Adding placeholders:

Code snippet (C#): 

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

Code snippet (PowerShell): 

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

Please note: When adding a new placeholder, the parameters of the AddPlaceholder() method determine its default resolution. To set the effective resolution, simply use the ITcPlcLibraryManager::SetEffectiveResoltion() method.

Removing references

To remove a reference, simply use the ITcPlcLibraryManager::RemoveReference() method. Because this method handles ITcPlcLibRef elements (which is the base class for ITcPlcLibrary and ITcPlcPlaceholderRef objects), you can use this method for both library and placeholder references.

Library references can be removed either by specifying their name, version and distributor or by specifying their display name.

Placeholder references can be removed by specifying their placeholder name.

Code snippet (C#): 

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

Code snippet (PowerShell): 

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

Scanning for available libraries

To scan the system for all available PLC libraries, simply use the ITcPlcLibraryManager::ScanLibraries() method. This method returns an ITcPlcReferences collection of libraries (type ITcPlcLibrary).

Code snippet (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
}

Code snippet (PowerShell): 

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

Freezing the placeholder version

It is possible to freeze the used version of a placeholder to a specific version. This can be achieved with the ITcPlcLibraryManager::FreezePlaceholder() method. This method is called on an object that points to the reference node.

Code snippet (C#): 

ITcSmTreeItem references = systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References");
ITcPlcLibraryManager libManager = (ITcPlcLibraryManager) references;
libManager.FreezePlaceholder(); // freezes the version of all place holders 
libManager.FreezePlaceholder("Placeholder_NC"); // freezes the version of a specific place holder

Code snippet (PowerShell): 

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

Please note: The version is frozen with the effective resolution. If the effective resolution points to "*", then the latest version is used in the system.

Working with repositories

The Automation Interface provides method for handling PLC library repositories. A default repository is part of every TwinCAT installation. To create additional repositories, you can use the ITcPlcLibraryManager::InsertRepository() method.

Code Snippet (C#):

ITcSmTreeItem references = systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References");
ITcPlcLibraryManager libManager = (ITcPlcLibraryManager) references;
libManager.InsertRepository("TestRepository", @"C:\Temp", 0);

Code Snippet (Powershell):

$references = $systemManager.LookupTreeItem("TIPC^Untitled1^Untitled1 Project^References")
$references.InsertRepository("TestRepository", "C:\Temp", 0)

When installing a new library into the system, the library needs to be part of a repository. This insertion can be achieved by using the ITcPlcLibraryManager::InstallLibrary() method.

Code Snippet (C#):

libManager.InstallLibrary("TestRepository", @"C:\SomeFolder\TcTestLibrary.library", false);

Code Snippet (Powershell):

$references.InstallLibrary("TestRepository", "C:\SomeFolder\TcTestLibrary.library", $false)

To uninstall a library from the repository, use the ITcPlcLibraryManager::UninstallLibrary() method.

Code Snippet (C#):

libManager.UninstallLibrary("TestRepository", "Tc2_MDP", "*", "Beckhoff Automation GmbH");

Code Snippet (Powershell):

$references.UninstallLibrary("TestRepository", "Tc2_MDP", "*", "Beckhoff Automation GmbH")

To remove a repository, use the ITcPlcLibraryManager::RemoveRepository() method.

Code Snippet (C#):

libManager.RemoveRepository("TestRepository");

Code Snippet (Powershell):

$references.RemoveRepository("TestRepository")