Beschreibungsdateien zu Bibliotheken

Dieses Thema enthält die folgenden Abschnitte:

Allgemeine Informationen

Sie können in PLCnext Engineer Beschreibungsdateien für die in einer Bibliothek veröffentlichten POEs und Datentyp-Arbeitsblätter bereitstellen.

Zu diesem Zweck bietet der Dialog 'Als Bibliothek veröffentlichen' oben rechts (im Eingabebereich für die Metadaten der zu veröffentlichenden Bibliothek) einen Bereich zum Auswählen und Entfernen von Beschreibungsdateien. Über die Schaltfläche 'Datei(en) hinzufügen' können Sie eine oder mehrere Beschreibungsdateien auswählen, die dann in dem Feld aufgelistet werden. Mit 'Datei entfernen' wird die im Feld ausgewählte Beschreibungsdatei gelöscht.

Eine Bibliotheksbeschreibungsdatei ist eine Datei im XML-Format, für die Struktur und Inhalt vorgeschrieben sind. Die Beschreibungsdatei enthält die folgenden Informationen:

Kategorien (Ordner), unter denen die Funktion/Funktionsbaustein-POEs und Datentyp-Arbeitsblätter in den KOMPONENTEN erscheinen.
POEs und Datentyp-Arbeitsblätter.
Formalparameter (Ein-/Ausgangs-Pins) der POEs im grafischen Editor.
Kurzbeschreibungen der POEs und Datentyp-Arbeitsblätter als Tooltip. Dieser erscheint, wenn Sie den Mauszeiger im KOMPONENTEN-Bereich auf ein Element oder auf einen Eingangs- oder Ausgangs-Pin im grafischen Editor setzen.

Für Beschreibungsdateien zu Bibliotheken gilt:

Der Dateiname muss LibraryDescription.xml sein.
Es können Bibliotheksbeschreibungsdateien in anderen Landessprachen hinzugefügt werden. Der Name der sprachspezifischen Beschreibungsdateien muss wie folgt lauten:
LibraryDescription.<Sprachcode>.xml
wobei <Sprachcode> das Kürzel gem. Systemgebietsschema für die verwendete Sprache ist (zum Beispiel, "de" für Deutsch, "fr" für Französisch, "zh-CN" für Chinesisch, ...).
Beispiel: "LibraryDescription.de.xml" für die deutsche Bibliotheksbeschreibungsdatei.
Abgesehen vom Inhalt der Description- und Name-Attribute der <ToolboxCategory>-Elemente, die in die Zielsprache zu übersetzen sind, sind Inhalt und Struktur der lokalisierten Bibliotheksbeschreibungsdatei gleich wie in der englischen Variante.
Das Encoding der XML-Datei muss UTF-8 sein.
In der Bibliotheksbeschreibungsdatei können POEs vom Typ Funktion, Funktionsbaustein und Programm sowie Datentypen-Arbeitsblätter aufgelistet werden. Zusätzlich können Parameter für Funktionen und Funktionsbausteine sowie Methoden von Funktionsbausteinen angegeben werden.
Das Element <ToolboxCategory> wird für die Darstellung der POEs / Datentypen-Arbeitsblätter in Ordnern verwendet. Eine Toolbox-Kategorie kann einzelne Trennzeichen '\' zur Strukturierung in Unterordner verwenden. Eine Toolbox-Kategorie ohne Beschreibung kann verwendet werden, um die POE oder das Datentyp-Arbeitsblatt auf der obersten Ebene anzuzeigen.
Der spezielle Kategorieeintrag <ToolboxCategory Id="Hidden" IsHidden="true"/> wird verwendet, um alle POEs dieser Kategorie für den Anwender zu verbergen. Der betreffende Typ wird dann nicht in der Baumstruktur oder im Intellisense angezeigt, kann aber dennoch durch manuelles Eintippen des Namens verwendet werden.
Das Element ProgramOrganizationUnit kann zur Beschreibung von POEs verwendet werden.
Werden Namespaces verwendet, so müssen diese auch bei der POE-Definition des Namens definiert werden, z. B. Name="Namespace1.POUName".
Das Element DataTypeWorksheet kann zur Organisation von Datentyp-Arbeitsblättern verwendet werden.
Das Unterelement FormalParameter für Funktionen, Funktionsbausteine und Funktionsbaustein-Methoden wird zur Definition von Ein- und Ausgängen verwendet. Der Ausgangsname für eine Funktion/Methode ist der Funktionsname/Methodenname selbst.
Das Unterelement Methode eines Funktionsbausteins listet eine Methode auf. Sie kann wiederum FormalParameter-Einträge enthalten.

Hinweise zu POEs und Datentyp-Arbeitsblättern

Öffentliche POEs und Datentyp-Arbeitsblätter (öffentlich = Sichtbarkeit der Bibliothek ist beim Veröffentlichen auf 'Sichtbar' gesetzt) sind in Ordnern organisiert, wie es auch im aktiven Solution-Projekt der Fall ist. Die Ordnerstruktur der Bibliothek muss homomorph sein. Das bedeutet:
- Eine POE oder ein Datentyp-Arbeitsblatt muss einer Kategorie zugeordnet werden, die dieselbe Tiefe hat wie ihr übergeordneter Ordner im Projekt. Wenn die Tiefe "kleiner" ist, werden die zusätzlichen Ordnernamen aus dem ursprünglichen Quellprojekt aufgefüllt. Wenn die Tiefe größer ist, wird nur die angegebene Tiefe aus dem ursprünglichen Quellprojekt verwendet (mit den Namen aus den angegebenen Kategorien).
  Wenn in der Bibliotheksbeschreibung keine POE-Informationen zu einem Quellordner vorhanden sind, werden die enthaltenen POEs mit der gleichen Tiefe und den gleichen Namen wie im Quellprojekt angezeigt.
- Einschränkungen:
  Wenn zwei POEs oder Datentyp-Arbeitsblätter denselben übergeordneten Ordner im Quellprojekt haben, werden sie in der Bibliotheksbeschreibung in derselben Kategorie angezeigt, unabhängig von der angegebenen zweiten Kategorie. Ordnen Sie daher in der Bibliotheksbeschreibung die POEs und Datentyp-Arbeitsblätter derselben Kategorie zu. Sie dürfen nicht aufgeteilt werden.
  Führen Sie keine POEs oder Datentypen-Arbeitsblätter verschiedener Quellordner in einem zusammen. Verwenden Sie auch verschiedene Bibliotheksbeschreibungsordner.
  Weisen Sie POEs nicht verschiedenen Unterordnern mit demselben Basisordner zu, wenn sie im Quellprojekt unterschiedliche Basisordner hatten.
  Beispiel: aaa/bbb/POUc und ccc/ddd/POUe dürfen nicht zugewiesen werden als fff/ggg/POUc und fff/hhh/POUe. Die Ordner werden nicht zusammengeführt.
  Beschreiben Sie immer alle Quell-POEs und Datentyp-Arbeitsblätter eines Quellordners.
  Die Nichteinhaltung der Beschränkungen führt zu einer unvorhergesehenen Anzeige von Ordnern.
Geschützte POEs
Die POEs in solchen Bibliotheken befinden sich in vorkompilierten DLL-Dateien. Da eine DLL keine Ordnerstruktur enthält, ist die Bibliotheksbeschreibung die einzige Quelle, um POEs in Kategorien zu organisieren. Es gibt keine Beschränkung, wie diese Kategorien verschachtelt werden. Wenn in der Bibliotheksbeschreibung keine POE-Informationen vorhanden sind, wird die POE auf Root-Ebene angezeigt.
Eingeschränkte POEs (POEs mit Sichtbarkeit = 'Eingeschränkt') (gilt auch für C#-POEs in Toolchain-Bibliotheken):
Die POEs in solchen Bibliotheken befinden sich in vorkompilierten DLL-Dateien. Da eine DLL keine Ordnerstruktur enthält, ist die Bibliotheksbeschreibung die einzige Quelle, um POEs und Datentypen in Kategorien zu organisieren. Es gibt keine Beschränkung, wie diese Kategorien verschachtelt werden. Wenn in der Bibliotheksbeschreibung keine Informationen vorhanden sind, werden die POEs und Datentypen auf Root-Ebene angezeigt.

Inhalt der Beschreibungsdatei

Das folgende Beispiel zeigt das Format der XML-Datei einer Bibliotheksbeschreibungsdatei, die Sie mit einer veröffentlichten Bibliothek bereitstellen können. Das Beispiel enthält alle XML-Element und Attribute, die verwendet werden können. Die XML-Datei muss die gezeigte Struktur haben.

<?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>

Die folgende Abbildung zeigt die Bibliotheksbeschreibung in PLCnext Engineer, wie sie in der obigen Beispiel-XML-Datei definiert ist:

XML-Elemente und Attribute

Die folgende Tabelle beschreibt die XML-Elemente und Attribute zur Definition der Bibliotheksbeschreibungsdatei.

Element/Attribut Typ Beschreibung

ToolboxCategories Element Definition der Kategorien (Ordner), unter denen die Funktion/Funktionsbaustein-POEs und Datentyp-Arbeitsblätter in den KOMPONENTEN erscheinen sollen.

ToolboxCategory Element Kategorie (Ordner), unter der die Funktion/Funktionsbaustein-POEs und Datentyp-Arbeitsblätter in den KOMPONENTEN erscheinen sollen.

Id Attribut Eindeutige Kennung der <ToolboxCategory>.
Die Id wird im Attribut ToolboxCategoryId des Elements <ProgramOrganizationUnit> oder <DataTypeWorksheet> (siehe unten) angegeben, um die Kategorie zu referenzieren.
Mit Id="Hidden" und IsHidden="true" (siehe folgende Beschreibung) wird die <ToolboxCategory> mit ihren untergeordneten Elementen in den KOMPONENTEN ausgeblendet.

IsHidden Attribut Boolesches Attribut, das definiert, ob die Kategorie sichtbar ('false') oder verborgen ('true') ist. Das Attribut wird nur in Kombination mit dem Id="Hidden"-Wert (siehe oben) ausgewertet.

Name Attribut Enthält den Namen der <ToolboxCategory>.
Definiert den neuen Ordnernamen im Komponentenbaum. Der Name kann auch Unterordner enthalten, die durch "\" getrennt sind.

ProgramOrganizationUnits Element Führt die Definition der POEs ein.
(Siehe hierzu auch den Hinweis im Anschluss an diese Tabelle.)

ProgramOrganizationUnit Element Definition der POE.

Name Attribut Enthält den Namen der <ProgramOrganizationUnit>.

ToolboxCategoryId Attribut Kennung der <ToolboxCategory>, unter der die POE im KOMPONENTEN-Bereich erscheinen soll. (Nicht verwendet für die Definition von Methoden einer FB-POE.)
Wenn angegeben, muss die Id mit einem Wert eines Id-Attributs des Elements <ToolboxCategory> übereinstimmen.

Description Attribut Text, der angezeigt wird, wenn Sie in den KOMPONENTEN den Mauszeiger über die POE bewegen.

Methods Element Führt die Definition der Methoden einer FB-POE ein.

Method Element Definition der Methoden der FB-POE.

Name Attribut Enthält den Namen der Methode.

Description Attribut Text, der angezeigt wird, wenn Sie in den KOMPONENTEN den Mauszeiger über die POE bewegen.

FormalParameters Element Führt die Definition der Formalparameter der POE/Methode ein.

FormalParameter Element Definition des Formalparameters der POE/Methode.

Name Attribut Enthält den Namen des Formalparameters.

Description Attribut Text, der angezeigt wird, wenn Sie den Mauszeiger über den Formalparameter im grafischen Editor bewegen.

DataTypeWorksheets Element Definition der Datentyp-Arbeitsblätter.

DataTypeWorksheet Element Definition des Datentyp-Arbeitsblattes.

Name Attribut Enthält den Namen des Datentyp-Arbeitsblatts wie angezeigt in den KOMPONENTEN.

ToolboxCategoryId Attribut Kennung der <ToolboxCategory>, unter der das Datentyp-Arbeitsblatt im KOMPONENTEN-Bereich erscheinen soll.
Wenn angegeben, muss die Id mit einem Wert eines Id-Attributs des Elements <ToolboxCategory> übereinstimmen.

Description Attribut Text, der angezeigt wird, wenn Sie den Mauszeiger über das Datentyp-Arbeitsblatt in den KOMPONENTEN bewegen.

Element/Attribut	Typ	Beschreibung
ToolboxCategories	Element	Definition der Kategorien (Ordner), unter denen die Funktion/Funktionsbaustein-POEs und Datentyp-Arbeitsblätter in den KOMPONENTEN erscheinen sollen.
ToolboxCategory	Element	Kategorie (Ordner), unter der die Funktion/Funktionsbaustein-POEs und Datentyp-Arbeitsblätter in den KOMPONENTEN erscheinen sollen.
Id	Attribut	Eindeutige Kennung der <ToolboxCategory>. Die Id wird im Attribut ToolboxCategoryId des Elements <ProgramOrganizationUnit> oder <DataTypeWorksheet> (siehe unten) angegeben, um die Kategorie zu referenzieren. Mit Id="Hidden" und IsHidden="true" (siehe folgende Beschreibung) wird die <ToolboxCategory> mit ihren untergeordneten Elementen in den KOMPONENTEN ausgeblendet.
IsHidden	Attribut	Boolesches Attribut, das definiert, ob die Kategorie sichtbar ('false') oder verborgen ('true') ist. Das Attribut wird nur in Kombination mit dem Id="Hidden"-Wert (siehe oben) ausgewertet.
Name	Attribut	Enthält den Namen der <ToolboxCategory>. Definiert den neuen Ordnernamen im Komponentenbaum. Der Name kann auch Unterordner enthalten, die durch "\" getrennt sind.
ProgramOrganizationUnits	Element	Führt die Definition der POEs ein. (Siehe hierzu auch den Hinweis im Anschluss an diese Tabelle.)
ProgramOrganizationUnit	Element	Definition der POE.
Name	Attribut	Enthält den Namen der <ProgramOrganizationUnit>.
ToolboxCategoryId	Attribut	Kennung der <ToolboxCategory>, unter der die POE im KOMPONENTEN-Bereich erscheinen soll. (Nicht verwendet für die Definition von Methoden einer FB-POE.) Wenn angegeben, muss die Id mit einem Wert eines Id-Attributs des Elements <ToolboxCategory> übereinstimmen.
Description	Attribut	Text, der angezeigt wird, wenn Sie in den KOMPONENTEN den Mauszeiger über die POE bewegen.
Methods	Element	Führt die Definition der Methoden einer FB-POE ein.
Method	Element	Definition der Methoden der FB-POE.
Name	Attribut	Enthält den Namen der Methode.
Description	Attribut	Text, der angezeigt wird, wenn Sie in den KOMPONENTEN den Mauszeiger über die POE bewegen.
FormalParameters	Element	Führt die Definition der Formalparameter der POE/Methode ein.
FormalParameter	Element	Definition des Formalparameters der POE/Methode.
Name	Attribut	Enthält den Namen des Formalparameters.
Description	Attribut	Text, der angezeigt wird, wenn Sie den Mauszeiger über den Formalparameter im grafischen Editor bewegen.
DataTypeWorksheets	Element	Definition der Datentyp-Arbeitsblätter.
DataTypeWorksheet	Element	Definition des Datentyp-Arbeitsblattes.
Name	Attribut	Enthält den Namen des Datentyp-Arbeitsblatts wie angezeigt in den KOMPONENTEN.
ToolboxCategoryId	Attribut	Kennung der <ToolboxCategory>, unter der das Datentyp-Arbeitsblatt im KOMPONENTEN-Bereich erscheinen soll. Wenn angegeben, muss die Id mit einem Wert eines Id-Attributs des Elements <ToolboxCategory> übereinstimmen.
Description	Attribut	Text, der angezeigt wird, wenn Sie den Mauszeiger über das Datentyp-Arbeitsblatt in den KOMPONENTEN bewegen.

Tipp: Verwenden Sie zu Beginn eine automatisch generierte Bibliotheksbeschreibungsdatei als Basis für Ihre eigene Beschreibungsdatei. Alle notwendigen Einträge können aus einer generierten Bibliotheken-Datei (*.pcwlx) kopiert werden. Die *.pcwlx-Datei ist eine gezippte Datei, die mit jedem geeigneten Unzip-Programm extrahiert werden kann. Passen Sie die automatisch generierte Datei LibraryDescription.xml nach Bedarf an und fügen Sie sie im Dialog 'Als Bibliothek veröffentlichen' hinzu.