Optimale Vorgehensweisen für das Bündeln und Bereitstellen von ThingWorx Lösungen
Verwenden Sie beim Entwickeln und Bereitstellen von Erweiterungen die folgenden optimalen Vorgehensweisen.
Auf einer sauberen Plattforminstanz entwickeln
ThingWorx stellt keine Sicherheitsvorkehrungen oder Sandbox-Funktionen für Ihren Code bereit. Es kann vorkommen, dass Ihre Umgebung teilweise instabil wird. Um wieder für Stabilität der Lösung zu sorgen, gehen Sie wie folgt vor:
• Wenn Sie Fehler im Entwicklungsprozess beobachten, starten Sie den Apache Tomcat-Server neu.
• Sie werden möglicherweise aufgefordert, das ThingworxStorage-Verzeichnis vollständig zu entfernen. Es wird empfohlen, die Anwendung auf einer sauberen Instanz von ThingWorx Platform zu entwickeln, um sicherzustellen, dass beim Entfernen des ThingWorxStorage Verzeichnisses keine Arbeit verloren geht.
Struktur einer Erweiterung
Die Artefakte einer Erweiterung müssen in einer ZIP-Datei in der folgenden Ordnerstruktur gebündelt werden:
• /metadata.xml – Informationen über die Erweiterung und Details der verschiedenen Artefakte in der Erweiterung
• /Entities/ – 0 oder mehr Entitäts-XML-Dateien, die in Unterordnern nach Entitätstyp organisiert sind
• /lib/ – JAR-Datei, die die benutzerdefinierten Java-Klassen für die Erweiterung und JAR-Dateien von Drittanbietern enthält, die für die Erweiterung erforderlich sind
• /ui/ – Dateien, die benutzerdefinierte Widgets definieren, die zum Erstellen und Ausführen von Mashups verwendet werden
Mehrere Erweiterungen in einer ZIP-Datei für eine Lösung bündeln
IoT-Lösungen, die mehrere Erweiterungen enthalten, können als einzelne ZIP-Datei gebündelt werden. Die einzelne ZIP-Datei enthält individuelle ZIP-Dateien für jede Erweiterung. Dadurch wird sichergestellt, dass jede Erweiterung unabhängig implementiert wird. Individuelle Erweiterungen sind in nachfolgenden Versionen einfacher zu aktualisieren.
Konvention für Erweiterungsname und -version
Es gibt keine Einschränkungen, wie Sie die Erweiterung und die ZIP-Datei einer Erweiterung benennen. Nachdem Sie einen Namen für die Erweiterung angegeben haben, können Sie ihn nicht mehr ändern. Der Name der ZIP-Datei kann jedoch geändert werden.
Obwohl Sie unterschiedliche Namen für die Erweiterung und ihre ZIP-Datei angeben können, wird empfohlen, denselben Namen für die Erweiterung und ihre ZIP-Datei zu verwenden. Der Name der ZIP-Datei kann auch die Versionsnummer enthalten.
Sie können eine IoT-Lösung verwenden, die mehrere Erweiterungen enthält (gebündelt als ZIP mit ZIPs). In diesem Fall wird empfohlen, dieselbe Versionsnummer für alle ZIPs zu verwenden. Ziehen Sie eine IoT-Lösung mit zwei Erweiterungen in Betracht. Jede Erweiterung ist eine einzelne ZIP-Datei mit einer individuellen Versionsnummer. Es empfiehlt sich, dieselbe Versionsnummer im Namen der beiden Erweiterungen anzugeben. Geben Sie außerdem dieselbe Versionsnummer im Namen der ZIP mit ZIPs an. Wenn beispielsweise die Versionsnummer Ihrer IoT-Lösung 7.9 ist, geben Sie 7.9 als Versionsnummer im Namen aller ZIP-Dateien an.
In der Datei
metadata.xml wird das Attribut
packageVersion verwendet, um die Version der Erweiterung anzugeben. Dies ist ein erforderliches Attribut, dessen Wert dem Format
<major>.<minor>.<patch> entspricht, wobei jeder Teil der Version numerisch ist. Erweiterungen müssen den semantischen Versionsregeln folgen. Weitere Informationen finden Sie unter
Semantic Versioning.
Metadatenattribut für HA-Kompatibilität
In ThingWorx 9.0 wird ein neues Metadatenattribut, haCompatible, unterstützt, um zu identifizieren, ob eine Erweiterung in einem ThingWorx High Availability-Cluster ordnungsgemäß funktioniert. Fügen Sie haCompatible":"TRUE" zu den Erweiterungsmetadaten hinzu, um zu identifizieren, ob die Erweiterung in einer HA-Umgebung funktioniert. Sie können das haCompatible-Attribut auf FALSE festlegen, um zu identifizieren, ob die Erweiterung nicht HA-kompatibel ist und nicht in eine HA-Umgebung importiert werden sollte.
Es wird dringend empfohlen, das
haCompatible-Attribut für alle Erweiterungen zu verwenden. Weitere Informationen zum Konfigurieren von
ThingWorx Platform zum Steuern des Imports der Erweiterung für HA-Kompatibilität finden Sie unter
platform-settings.json – Konfigurationsdetails und
Plattformeinstellungen für ThingWorx HA.
Abhängigkeit der Erweiterung von anderen Erweiterungen
Wenn Ihre Erweiterung von anderen Erweiterungen abhängig ist, wird empfohlen, das Attribut dependsOn in der Datei metadata.xml zu verwenden, um die Abhängigkeiten anzugeben. Der Wert des Attributs ist eine durch Kommas getrennte Liste von Erweiterungsnamen und Versionen im Format <name>:<major>.<minor>.<patch>, wobei Versionen nur in Zahlen angegeben werden. Beispiel: dependsOn= "ExtensionOne:2.5.1,ExtensionTwo:1.2.0".
Es empfiehlt sich, zu viele Abhängigkeiten zu vermeiden. Wenn Upgrades für eine der Erweiterungen vorhanden sind, sind auch abhängige Erweiterungen betroffen.
Enge Kopplung mit anderen Verlängerungen vermeiden
Sie müssen eine enge Kopplung Ihrer Erweiterung mit anderen Erweiterungen vermeiden.
• Wenn Ihre Erweiterung eng mit einer anderen Erweiterung gekoppelt ist, die auf eine neue Hauptversion aktualisiert werden muss, werden Sie aufgefordert, Ihre Erweiterung und die gesamte Kette von Abhängigkeiten zu löschen, bevor Sie das Upgrade durchführen können.
• Die beste Möglichkeit, eine enge Kopplung zu vermeiden, besteht darin, Dinge und Dingvorlagen der erforderlichen Funktionalität zu erstellen. Diese Dinge und Dingvorlagen sind nicht Teil Ihrer Erweiterung und daher nicht in den Erweiterungsupgrades enthalten.
• Gelegentlich kann es schwierig sein, eine enge Kopplung zu vermeiden, wenn Sie Widgets von anderen Erweiterungen in Ihren Erweiterungs-Mashups verwenden.
Größe einer Erweiterung
Große und komplexe Erweiterungen können schwierig zu warten und zu aktualisieren sein. Ein besserer Ansatz ist, Erweiterungen in kleinere Komponenten basierend auf Funktionen aufzuteilen, um Wartung und Upgrade zu vereinfachen. Sie können mehrere Erweiterungen in einer einzigen ZIP-Datei bündeln. Weitere Informationen finden Sie im Abschnitt
Mehrere Erweiterungen in einer ZIP-Datei für eine Lösung bündeln.
Verwendung externer JAR-Dateien in einer Erweiterung
ThingWorx ermöglicht es Benutzern, Bibliotheken von Drittanbietern in ihren Code einzuschließen. Es wird jedoch empfohlen, die Verwendung der allgemeinen JAR-Dateien zu vermeiden. Verwenden Sie stattdessen die JAR-Dateien, die mit dem SDK in Ihrer Lösung gebündelt sind. Beachten Sie Folgendes:
• Sie können vorhandene JAR-Dateien aus dem Ordner /Thingworx/Web-INF/lib in Ihrer Erweiterung verwenden. Wenn Sie jedoch eine externe JAR-Datei in Ihrer Erweiterung verwenden möchten, stellen Sie sicher, dass die JAR-Datei nicht denselben Stammnamen wie die anderen JAR-Dateien im Ordner /Thingworx/Web-INF/lib hat.
Der Stammname einer JAR-Datei ist der Name des ersten Zeichens bis zum ersten numerischen Zeichen im Dateinamen. Die Tabelle enthält die Stammnamen der folgenden JAR-Dateien, die im Ordner /Thingworx/Web-INF/lib vorhanden sind:
|
JAR-Dateiname
|
Stammname
|
|
postgresql-42.2.5.jar
|
postgresql-
|
|
log4j-1.2.17.jar
|
log
|
|
metrics-core-3.1.2.jar
|
metrics-core-
|
• ThingWorx Platform ermöglicht es mehreren Quellen, dieselben JAR-Dateien zu verwenden.
• Wenn mehrere Quellen dieselben JAR-Dateien verwenden, kann ein Konflikt auftreten, wenn eine Erweiterung auf die ThingWorx Platform hochgeladen oder wenn beim Erstellen der Erweiterung eine falsche JAR-Version verwendet wird.
• Zukünftige Versionen der ThingWorx Platform erfordern möglicherweise Aktualisierungen an Erweiterungen, um weiterzuarbeiten.
• Ein Kunde kann nicht zwei Erweiterungen verwenden, die gleichzeitig dieselben JAR-Dateien benötigen.
Entitäten nicht bearbeitbar machen
Wenn Sie Entitäten wie Mashups, Stildefinitionen usw. erstellen, stellen Sie sicher, dass die Entitäten der Erweiterung nicht bearbeitbar sind. Nur für nicht bearbeitbare Entitäten kann ein In-Place Upgrade durchgeführt werden. Bearbeitbare Entitäten können nicht aktualisiert werden. Standardmäßig sind neue Entitäten nicht bearbeitbar.
• Wenn einige Entitäten bearbeitbar sein sollen, bündeln Sie diese Entitäten in einer separaten Erweiterung, sodass Sie die anderen Komponenten der Erweiterung problemlos aktualisieren können.
• Für bearbeitbare Entitäten wird empfohlen, die bearbeitbaren Stellen in einem Mashup zu minimieren. Verwenden Sie eingebettete Mashups, um bearbeitbare Stellen zu minimieren.
Wenn Sie die Möglichkeit bieten möchten, die Erweiterung anzupassen, z.B. durch Hinzufügen eines benutzerdefinierten Logos, sollten Sie prüfen, ob ein alternativer Ansatz möglich ist:
• Kann stattdessen die Konfiguration eines Dings verwendet werden? Ein nicht bearbeitbares Ding kann weiterhin Konfigurationstabellen-Änderungen aufweisen.
• Kann ein Dienst zum Suchen einer Konfiguration verwendet werden, um eine Media-Entität oder ein eingebettetes Mashup bereitzustellen?
Erweiterungsentitäten duplizieren
Wenn eine Entität dupliziert wird, wird alles mit Ausnahme des Namens geklont. Dasselbe gilt, wenn Sie Erweiterungsentitäten duplizieren. Wenn jedoch für eine Erweiterungsentität ein Erweiterungsprojekt festgelegt ist, wird dieses Feld ebenfalls übertragen. Wenn Sie versuchen, diese Entität zu speichern, schlägt der Vorgang fehl, da dabei versucht wird, die Entität dem Erweiterungsprojekt zuzuweisen; dies ist nicht zulässig.
Wenn Sie eine Erweiterungsentität duplizieren, der ein Erweiterungsprojekt zugewiesen ist, müssen Sie dieses Feld löschen und ein neues, Nicht-Erweiterungsprojekt festlegen. Wenn Sie die CloneThing-API verwenden, müssen Sie den Dienst SetProject zum Festlegen eines Projekts verwenden. Wenn ein Projekt nicht zugewiesen ist, wird es automatisch dem PTCDefaultProject zugewiesen.
Wenn eine bearbeitbare Erweiterungsentität in 9.1 und höher importiert wird, ist das Projektfeld für die Entität nach dem Import der Erweiterung schreibgeschützt und behält die vor dem Upgrade festgelegte Projekteinstellung bei. Unabhängig davon, ob ein Projekt zugewiesen oder das Feld Projekt leer ist, wird dieser Wert beibehalten.
Erweiterung mit bearbeitbaren Entitäten aktualisieren
Führen Sie beim Aktualisieren einer Erweiterung mit bearbeitbaren Entitäten einen Migrationstest aus, um zu prüfen, ob Informationen wie Tags während des Upgrade-Prozesses verloren gehen.
Entitäten organisieren
Es wird empfohlen, Entitäten mithilfe von Projekten und Modell-Tags zu gruppieren. Sie müssen ein Projekt für alle Entitäten der Erweiterung verwenden. Erstellen Sie mindestens ein Modell-Tag, das verwendet werden kann, um alle Entitäten der Erweiterung mit einem Tag zu versehen.
Speicher vor dem Löschen sichern
Es wird empfohlen, den aktuellen ThingworxStorage-Ordner zu sichern, bevor Sie ihn löschen.
Eclipse-Plugin
Das Eclipse-Plugin erleichtert das Entwickeln und Erstellen von Erweiterungen. Es stellt Aktionen bereit, die automatisch Quelldateien, Anmerkungen und Methoden generieren. Die Aktionen aktualisieren auch die Metadatendatei, um eine ordnungsgemäße Konfiguration der Erweiterung sicherzustellen. Das Plugin stellt außerdem sicher, dass Syntax und Format von Anmerkungen und Metadatendatei korrekt sind.
Weitere Informationen zum Eclipse-Plugin finden Sie unter
Eclipse-Plugin verwenden.