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

In TwinCAT 3 there are two types of library objects: Libraries and Placeholders. For more information about both types please see the TwinCAT 3 documentation about Library Management.

In a TwinCAT 3 PLC project, references to libraries and placeholders are added as child items to the References node under the corresponding PLC project. When choosing the "Standard PLC Project" template, some libraries and placeholders are being added to the project by default, e.g. Tc2_Standard, Tc2_System, ... .

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

Using Automation Interface, you can navigate to the References node simply by 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")

To be able to handle this object correctly, you need to type cast it to the ITcPlcLibraryManager interface.

ITcPlcLibraryManager libManager = (ITcPlcLibraryManager) references;

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

Navigating through references

You can iterate through all references by making use of 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. To work with one of these specific classes, we need to type cast the object accordingly, 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

There are two methods in the ITcPlcLibraryManager class which allow you to add a library or placeholder reference to a PLC project: AddLibrary() and AddPlaceholder().

Adding a library can be achieved in two ways:

The display name of a library can be determined in the properties window of a library or 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)")

Adding a placeholder can be achieved in two 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 specify its Default Resolution. To set the Effective Resolution, simply use the ITcPlcLibraryManager::SetEffectiveResoltion() method.

Removing references

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

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

Placeholder references can be removed by the 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 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 placeholder version

It is possible to freeze the used version of a placeholder to a specific version. This can be achieved by using the method ITcPlcLibraryManager::FreezePlaceholder(). This method is called on an object that points to the References 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 freezed to the Effective Resolution. If the Effective Resolution points to "*", then the newest version in the system is used.

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")