Bonnes pratiques pour la création de packages et de déploiement d'applications ThingWorx
Utilisez les bonnes pratiques suivantes lors du développement et du déploiement d'extensions.
Développer sur une instance de plateforme propre
ThingWorx ne fournit ni protection, ni sandboxing pour votre code. Votre environnement peut alors parfois devenir instable. Pour corriger cette instabilité, procédez comme suit :
• Si vous constatez des erreurs dans le processus de développement, redémarrez le serveur Apache Tomcat.
• Vous pouvez être invité à supprimer complètement le répertoire ThingworxStorage. Il est recommandé de développer l'application sur une instance propre de la plateforme afin de ne perdre aucune donnée lors de la suppression du répertoire ThingWorxStorage.
Structure d'une extension
Le fichier Zip contenant les artefacts d'une extension doit être organisé comme suit :
• /metadata.xml : informations sur l'extension et détails des différents artefacts qu'elle contient.
• /Entities/ : zéro ou plusieurs fichiers XML d'entité organisés dans des sous-dossiers par type d'entité.
• /lib/ : fichier Jar qui inclut les classes Java personnalisées pour l'extension et fichiers Jar tiers requis par l'extension.
• /ui/ : fichiers qui définissent les widgets personnalisés utilisés pour créer et exécuter des applications composites.
Regrouper plusieurs extensions dans un fichier Zip pour une application
Les solutions IoT qui contiennent plusieurs extensions peuvent être regroupées dans un seul fichier Zip. Le fichier Zip unique contient des fichiers Zip individuels pour chaque extension. Cela garantit l'implémentation indépendante de chaque extension. Les extensions individuelles sont plus faciles à mettre à jour dans les versions ultérieures.
Convention de nom et de version des extensions
Il n'existe aucune restriction quant à la façon dont vous nommez votre extension et le fichier Zip d'une extension. Notez cependant qu'une fois spécifié, le nom de l'extension ne peut plus être modifié. Le nom du fichier Zip peut quant à lui être modifié.
Bien que vous puissiez spécifier des noms différents pour l'extension et son fichier Zip, il est recommandé de ne pas le faire. Le nom du fichier Zip peut également contenir le numéro de version.
Vous pouvez disposer d'une solution IoT contenant plusieurs extensions regroupées dans un Zip de fichiers Zip. Dans ce cas, il est recommandé d'indiquer le même numéro de version pour tous les fichiers Zip. Prenons en exemple une solution IoT qui contient deux extensions. Chaque extension apparaît en tant que fichier Zip unique avec un numéro de version spécifique. Il est recommandé de spécifier le même numéro de version dans le nom des deux extensions. Spécifiez également le même numéro de version dans le nom du Zip de fichiers Zip. Par exemple, si le numéro de version de votre solution IoT est 7.9, spécifiez 7.9 comme numéro de version dans le nom de tous les fichiers Zip.
Dans le fichier
metadata.xml, l'attribut
packageVersion est utilisé pour spécifier la version de l'extension. Il s'agit d'un attribut obligatoire au format
<major>.<minor>.<patch>, où chaque élément est numérique. Les extensions doivent suivre les règles de gestion sémantique de version. Pour plus d'informations, consultez la page dédiée à la
gestion sémantique de version.
Dépendances d'extension
Cette section décrit les dépendances d'une extension sur d'autres extensions.
Dépendance de l'extension sur d'autres extensions
Si votre extension est liée par une dépendance à d'autres extensions, il est recommandé d'utiliser l'attribut dependsOn dans le fichier metadata.xml pour spécifier les dépendances. La valeur de l'attribut est une liste de noms et de versions d'extension séparées par une virgule au format <name>:<major>.<minor>.<patch>, où les versions sont spécifiées uniquement par des chiffres. Par exemple, dependsOn= "ExtensionOne:2.5.1,ExtensionTwo:1.2.0".
Il est recommandé de limiter le nombre de dépendances. En effet, en cas de mises à niveau de l'une des extensions, les extensions dépendantes sont également affectées.
Eviter un couplage fort avec d'autres extensions
Un couplage fort de votre extension avec d'autres extensions doit être évité.
• Si votre extension est fortement couplée à une autre extension qui doit être mise à niveau vers une nouvelle version majeure, vous serez invité à supprimer votre extension et la totalité de la chaîne de dépendances avant de pouvoir effectuer la mise à niveau.
• Le meilleur moyen d'éviter cette situation est de créer des objets et des modèles d'objet de la fonctionnalité dont vous avez besoin. Ces objets et modèles d'objet ne font pas partie de votre extension et ne sont donc pas inclus dans les mises à niveau d'extension.
• Il peut être difficile d'éviter un couplage fort lorsque vous utilisez des widgets d'autres extensions dans vos applications composites d'extension.
Taille d'une extension
Les extensions volumineuses et complexes peuvent être difficiles à gérer et à mettre à niveau. Pour faciliter ces opérations, il est donc conseillé de diviser les extensions en composants de plus petite taille par fonctionnalités. Vous pouvez ensuite regrouper plusieurs extensions dans un seul fichier Zip. Pour plus d'informations, consultez la section
Regrouper plusieurs extensions dans un fichier Zip pour une application.
Utilisation de fichiers Jar externes dans une extension
ThingWorx permet aux utilisateurs d'inclure des bibliothèques tierces dans leur code. Toutefois, il est recommandé d'éviter d'utiliser des fichiers Jar communs. Utilisez plutôt les fichiers Jar fournis avec le SDK de votre application. Tenez compte des points suivants :
• Vous pouvez utiliser des fichiers JAR existants du dossier /Thingworx/WEB-INF/lib dans votre extension. Toutefois, si vous souhaitez utiliser un fichier JAR externe dans votre extension, celui-ci doit avoir un nom racine différent des autres fichiers JAR présents dans le dossier /Thingworx/WEB-INF/lib.
Par nom racine, nous entendons les caractères du nom de fichier jusqu'au premier caractère numérique. La table répertorie les noms racines des fichiers JAR suivants qui sont présents dans le dossier /Thingworx/WEB-INF/lib :
|
Nom du fichier JAR
|
Nom racine
|
|
postgresql-42.2.5.jar
|
postgresql-
|
|
log4j-1.2.17.jar
|
log
|
|
metrics-core-3.1.2.jar
|
metrics-core-
|
• La plateforme ThingWorx permet à plusieurs sources d'utiliser les mêmes fichiers Jar.
• Lorsque plusieurs sources utilisent les mêmes fichiers Jar, un conflit peut se produire lors du chargement d'une extension sur la plateforme ou lorsqu'une version incorrecte d'un fichier Jar est utilisée lors de la création de l'extension.
• Les versions ultérieures de la plateforme peuvent nécessiter la mise à jour des extensions pour qu'elles continuent à fonctionner.
• Un client ne peut pas utiliser en même temps deux extensions qui nécessitent les mêmes fichiers Jar.
Rendre vos entités non modifiables
Lorsque vous créez des entités, telles que des applications composites ou des définitions de style, assurez-vous que les entités de l'extension ne sont pas modifiables. Seules les entités non modifiables prennent en charge les mises à niveau sur place. Les entités modifiables ne peuvent pas être mises à niveau. Par défaut, les nouvelles entités ne sont pas modifiables.
• Si vous souhaitez que certaines entités soient modifiables, regroupez-les dans une extension distincte afin de pouvoir facilement mettre à niveau les autres composants de l'extension.
• Pour les entités modifiables, il est recommandé de limiter les emplacements modifiables sur une application composite. Utilisez pour cela des applications composites intégrées.
Si vous souhaitez pouvoir personnaliser l'extension, par exemple, en ajoutant un logo personnalisé, déterminez si une approche alternative peut fonctionner :
• La configuration d'un objet peut-elle être utilisée à la place ? Des modifications de la table de configuration peuvent toujours être effectuées pour un objet non modifiable.
• Est-il possible d'utiliser un service pour rechercher une configuration afin de fournir une entité de média ou une application composite intégrée ?
Mettre à niveau une extension avec des entités modifiables
Lors de la mise à niveau d'une extension avec des entités modifiables, effectuez un test de migration pour vérifier si des informations, telles que des tags, sont perdues lors du processus de mise à niveau.
Organiser les entités
Il est recommandé de grouper les entités à l'aide de projets et de tags de modèle. Vous devez utiliser un projet pour toutes les entités de l'extension. Créez au moins un tag de modèle pouvant être utilisé pour taguer toutes les entités de votre extension.
Sauvegarder le dossier de stockage avant suppression
Il est recommandé de sauvegarder votre dossier ThingworxStorage actuel avec de le supprimer.
Plug-in Eclipse
Le plug-in Eclipse facilite le développement et la création d'extensions. Il fournit des actions qui génèrent automatiquement des fichiers source, des annotations et des méthodes. Les actions mettent également à jour le fichier de métadonnées pour garantir la bonne configuration de l'extension. Le plug-in garantit également que la syntaxe et le format des annotations et du fichier de métadonnées sont corrects.