Library Description Files

This topic contains the following sections:

General information

PLCnext Engineer allows you to provide library description files with the POUs and data type worksheets contained in your released libraries.

For this purpose, the 'Release As Library' dialog offers an area for selecting and removing description files at the top right (in the input area for the metadata of the library to be published). The 'Add file(s)' button allows you to select one or more description files and then lists them in the field. 'Remove file' deletes the description file selected in the field.

The library description file is a file in XML format which has a pre-defined structure and content (see below). The description file contains the following information:

Categories (folders) under which the function/function block POUs and data type worksheets appear in the COMPONENTS area.
POUs and data type worksheets.
Formal parameters (input/output pins) of the POUs inside the graphical editor.
Short descriptions of the POUs and data type worksheets that are shown when hovering with the mouse over an element in the COMPONENTS area and when hovering over input and output pins of POUs inside the graphical editor.

For library description files, the following applies:

The file name must be LibraryDescription.xml.
Localized library description files can be added. The name of the language-specific library description files must be as follows:
LibraryDescription.<langcode>.xml
where <langcode> represents the locale code of the used language (for example, "de" for German, "fr" for French, "zh-CN" for Chinese, ...).
Example: "LibraryDescription.de.xml" for German library description file.
The content and structure of the localized library description file is the same as with the English version, except that the content of all Description attributes and the Name attributes of the <ToolboxCategory> elements must be translated.
The XML file must be saved with UTF-8 encoding.
POUs of type Function, Function Block and Programs and also Data Type worksheets can be listed in the library description file. Additionally, parameters for functions and function blocks can be specified and methods of function blocks.
The element <ToolboxCategory> is used for showing the POUs / Data Type worksheets in folders. A toolbox category may use single separators '\' for structuring in sub folders. A toolbox category with no description can be used to show the POU or data type worksheet on the root level.
The special category entry <ToolboxCategory Id="Hidden" IsHidden="true"/> is used to hide all POUs of that category from the user. The type is not shown in the tree or Intellisense, but can still be used by entering the name manually.
The element ProgramOrganizationUnit can be used to describe POUs.
If namespaces are used, then they must also be defined at the POU definition of the name; e.g. Name="Namespace1.POUName".
The element DataTypeWorksheet can be used to organize Data Type worksheets.
The sub element FormalParameter for functions, function blocks, and function block methods is used for defining inputs and outputs. The output name for a function / method is the function name / method name itself.
The sub element Method of a function block lists a method. It can contain again FormalParameter entries.

Notes on POUs and data type worksheets

Public POUs and data type worksheets (public = visibility set to 'Visible' when releasing the library) are organized using folders as it is the case inside the active solution project. The folder structure of the library must be homomorphic. This means that:
- A POU or data type worksheet must be assigned to a category, which has the same depth as its parent folder inside the project. If the depth is smaller, the additional folder names are filled up from the original source project. If the depth is larger, only the specified depth from the original source project is used (with the names from the specified categories).
  If no POU information of a source folder is available in the library description, the containing POUs are shown with the same depth and names as in the source project.
- Restrictions:
  If two POUs or data type worksheets have the same parent folder in the source project, they are shown in the same category in the library description independent from the specified 2nd category. Therefore, assign the POUs and data type worksheets to the same category in the library description. Do not split them.
  Do not merge POUs or data type worksheets of different source folders into one. Use different library description folders as well.
  Do not assign POUs to different subfolders with the same base folder if they had in the source project different base folders.
  Example: aaa/bbb/POUc and ccc/ddd/POUe shall not be assigned as fff/ggg/POUc and fff/hhh/POUe. The folders will not be merged.
  Describe always all source POUs and data type worksheets of a source folder.
  Not fulfilling the restrictions will result in unpredicted folder appearance.
Protected POUs
The POUs inside such libraries are located in precompiled DLL files. Because a DLL does not provide a folder structure, the library description is the only source to organize POUs in categories. There is no folder limitation how these categories are nested. If no POU information is available in the library description, the POUs are shown at root level.
Restricted POUs (POUs released with visibility set to 'Restricted') (applies also for C# POUs of Toolchain libraries):
The POUs inside such libraries are located in precompiled DLL files. Because a DLL does not provide a folder structure, the library description is the only source to organize POUs and data types in categories. There is no folder limitation how these categories are nested. When no information is available in the library description, the POUs and data types are shown at root level.

Content of the library description file

The following example shows the format of the XML file that defines a library description file you can provide with a released library. The example contains all XML elements and attributes that can be used. The XML file must have the structure as shown.

<?xml version="1.0" encoding="UTF-8"?>
<Library>
  <ToolboxCategories>
    <ToolboxCategory Id="Root" Name="" />
    <ToolboxCategory Id="Container" Name="Container" />
    <ToolboxCategory Id="ContainerMonitor" Name="Container\Monitor" />
    <ToolboxCategory Id="ContainerCheck" Name="Container\Check" />
    <ToolboxCategory Id="Robot" Name="Robot" />
    <ToolboxCategory Id="Hidden" IsHidden="true"/>
  </ToolboxCategories>
  <ProgramOrganizationUnits>
    <ProgramOrganizationUnit Name="Container.Container" ToolboxCategoryId="Container" Description="Container Program" />
    <ProgramOrganizationUnit Name="Container.Recording" ToolboxCategoryId="Container" Description="Recording Program" />
    <ProgramOrganizationUnit Name="LadderProgram" ToolboxCategoryId="Hidden" Description="" />
    <ProgramOrganizationUnit Name="Container.ContainerTrend" ToolboxCategoryId="ContainerMonitor" Description="Trend FB" />
    <ProgramOrganizationUnit Name="Container.DrainCheck" ToolboxCategoryId="ContainerCheck" Description="Drain Check FB" />
    <ProgramOrganizationUnit Name="Container.MinMaxCheck" ToolboxCategoryId="ContainerCheck" Description="MinMax Check FB" />
    <ProgramOrganizationUnit Name="Robot.RobotFB" ToolboxCategoryId="Robot" Description="Robot FB" />
    <ProgramOrganizationUnit Name="Robot.Robot" ToolboxCategoryId="Hidden" Description="" />
     <ProgramOrganizationUnit Name="Container.ContainerLevelMonitor" ToolboxCategoryId="ContainerMonitor" Description="Monitor FB" >
        <Methods>
            <Method Name="Reset" Description="Resets monitor" >
                <FormalParameters>
                    <FormalParameter Name="mode" Description="Reset mode"/>
                    <FormalParameter Name="Reset" Description="Success"/>
                </FormalParameters>
            </Method>
        </Methods>
    </ProgramOrganizationUnit>
    <ProgramOrganizationUnit Name="BaseFunction" ToolboxCategoryId="Root" Description="Setting base values" >
        <FormalParameters>
            <FormalParameter Name="value" Description="Setting of depth level"/>
            <FormalParameter Name="BaseFunction" Description="Error code"/>
        </FormalParameters>
    </ProgramOrganizationUnit>
  </ProgramOrganizationUnits>
  <DataTypeWorksheets>
    <DataTypeWorksheet Name="Container" ToolboxCategoryId="Container" Description="Container Types" />
    <DataTypeWorksheet Name="Robot" ToolboxCategoryId="Root" Description="Robot Types" />
  </DataTypeWorksheets>
</Library>

The following figure shows the library description in PLCnext Engineer as defined in the example XML file above:

XML elements and attributes

The following table describes the XML elements and attributes that are used to the define the library description file.

Element/Attribute Type Description

ToolboxCategories Element Introduces the definition of the categories (folders) under which the function/function block POUs and data type worksheets shall appear in the COMPONENTS area.

ToolboxCategory Element Category (folder) under which the function/function block POUs and data type worksheets shall appear in the COMPONENTS area.

Id Attribute Unique identifier that identifies the <ToolboxCategory>.
The Id is used in the ToolboxCategoryId attribute of the <ProgramOrganizationUnit> or <DataTypeWorksheet> element (see below) to refer to the category.
With Id="Hidden" and IsHidden="true" (see the following description), the <ToolboxCategory> and all of its elements will be hidden in the COMPONENTS area.

IsHidden Attribute Boolean attribute that specifies whether the category will be visible ('false') or hidden ('true'). The attribute is only considered in combination with the Id="Hidden" value (see above).

Name Attribute Contains the name of the <ToolboxCategory>.
It defines the new folder name inside the components tree. The name can contain also subfolders separated by "\".

ProgramOrganizationUnits Element Introduces the definition of the POUs.
(See also the notes below this table.)

ProgramOrganizationUnit Element Definition of the POU.

Name Attribute Contains the name of the <ProgramOrganizationUnit>.

ToolboxCategoryId Attribute Identifier of the <ToolboxCategory> under which the POU shall appear inside the COMPONENTS area. (Not used for the definition of FB POU methods.)
If used, the Id must be equal to a value of an Id attribute of the <ToolboxCategory> element.

Description Attribute Text that is shown when hovering the mouse over the POU in the COMPONENTS area.

Methods Element Introduces the definition of the methods of an FB POU.

Method Element Definition of the method of the FB POU.

Name Attribute Contains the name of the method.

Description Attribute Text that is shown when hovering the mouse over the POU in the COMPONENTS area.

FormalParameters Element Introduces the definition of the formal parameters of the POU/method.

FormalParameter Element Definition of the formal parameter of the POU/method.

Name Attribute Contains the name of the formal parameter.

Description Attribute Text that is shown when hovering the mouse over the formal parameter inside the graphical editor.

DataTypeWorksheets Element Introduces the definition of the data type worksheets.

DataTypeWorksheet Element Definition of the data type worksheet.

Name Attribute Contains the name of the data type worksheet as shown inside the COMPONENTS area.

ToolboxCategoryId Attribute Identifier of the <ToolboxCategory> under which the data type worksheet shall appear inside the COMPONENTS area.
If used, the Id must be equal to a value of an Id attribute of the <ToolboxCategory> element.

Description Attribute Text that is shown when hovering the mouse over the data type worksheet in the COMPONENTS area.

Element/Attribute	Type	Description
ToolboxCategories	Element	Introduces the definition of the categories (folders) under which the function/function block POUs and data type worksheets shall appear in the COMPONENTS area.
ToolboxCategory	Element	Category (folder) under which the function/function block POUs and data type worksheets shall appear in the COMPONENTS area.
Id	Attribute	Unique identifier that identifies the <ToolboxCategory>. The Id is used in the ToolboxCategoryId attribute of the <ProgramOrganizationUnit> or <DataTypeWorksheet> element (see below) to refer to the category. With Id="Hidden" and IsHidden="true" (see the following description), the <ToolboxCategory> and all of its elements will be hidden in the COMPONENTS area.
IsHidden	Attribute	Boolean attribute that specifies whether the category will be visible ('false') or hidden ('true'). The attribute is only considered in combination with the Id="Hidden" value (see above).
Name	Attribute	Contains the name of the <ToolboxCategory>. It defines the new folder name inside the components tree. The name can contain also subfolders separated by "\".
ProgramOrganizationUnits	Element	Introduces the definition of the POUs. (See also the notes below this table.)
ProgramOrganizationUnit	Element	Definition of the POU.
Name	Attribute	Contains the name of the <ProgramOrganizationUnit>.
ToolboxCategoryId	Attribute	Identifier of the <ToolboxCategory> under which the POU shall appear inside the COMPONENTS area. (Not used for the definition of FB POU methods.) If used, the Id must be equal to a value of an Id attribute of the <ToolboxCategory> element.
Description	Attribute	Text that is shown when hovering the mouse over the POU in the COMPONENTS area.
Methods	Element	Introduces the definition of the methods of an FB POU.
Method	Element	Definition of the method of the FB POU.
Name	Attribute	Contains the name of the method.
Description	Attribute	Text that is shown when hovering the mouse over the POU in the COMPONENTS area.
FormalParameters	Element	Introduces the definition of the formal parameters of the POU/method.
FormalParameter	Element	Definition of the formal parameter of the POU/method.
Name	Attribute	Contains the name of the formal parameter.
Description	Attribute	Text that is shown when hovering the mouse over the formal parameter inside the graphical editor.
DataTypeWorksheets	Element	Introduces the definition of the data type worksheets.
DataTypeWorksheet	Element	Definition of the data type worksheet.
Name	Attribute	Contains the name of the data type worksheet as shown inside the COMPONENTS area.
ToolboxCategoryId	Attribute	Identifier of the <ToolboxCategory> under which the data type worksheet shall appear inside the COMPONENTS area. If used, the Id must be equal to a value of an Id attribute of the <ToolboxCategory> element.
Description	Attribute	Text that is shown when hovering the mouse over the data type worksheet in the COMPONENTS area.

Tip: When providing an own library description file, please start with the automatically generated library description file (when not providing an own file) as a base. All necessary entries are generated and can be found in the library file (*.pcwlx). The .pcwlx file is a zipped file which can be opened and extracted with any unzip program. Modify the automatically generated containing LibraryDescription.xml file to your needs and then add the file in the 'Release As Library' dialog.