Prácticas recomendadas para empaquetar e implementar soluciones de ThingWorx
Utilice las siguientes prácticas recomendadas durante el desarrollo y la implementación de extensiones.
Desarrollo en una instancia de plataforma limpia
ThingWorx no proporcionan ninguna medida de seguridad ni funciones sandbox para el código. Es posible que a veces el entorno se vuelva inestable. Para que la solución salga del estado inestable, se debe realizar lo siguiente:
• Si se producen errores en el proceso de desarrollo, reinicie el servidor de Apache Tomcat.
• Es posible que se le pregunte al usuario si desea quitar completamente el directorio ThingworxStorage. Se recomienda desarrollar la solución en una instancia limpia de ThingWorx Platform para asegurarse de que no se pierda ningún trabajo al quitar el directorio ThingWorxStorage.
Estructura de una extensión
Los elementos de una extensión se deben empaquetar en un fichero ZIP en la siguiente estructura de carpetas:
• /metadata.xml: información sobre la extensión y detalles de los distintos elementos de la extensión.
• /Entities/: cero o más ficheros XML de entidad organizados en subcarpetas por tipo de entidad.
• /lib/: fichero JAR en el que se incluyen las clases Java personalizadas para la extensión y los ficheros JAR de terceros que requiere la extensión.
• /ui/: ficheros en los que se definen widgets personalizados que se utilizan para crear y ejecutar mashups.
Empaquetado de varias extensiones en un fichero zip para una solución
Las soluciones de IoT que contienen varias extensiones se pueden empaquetar como un único fichero ZIP. En el fichero ZIP único se incluyen ficheros ZIP individuales para cada extensión. De este modo, se garantiza que todas las extensiones se implementan de forma independiente. Las extensiones individuales son más fáciles de actualizar en las versiones posteriores.
Convención de asignación de nombre y versión a la extensión
No hay restricciones para el nombre de la extensión ni el fichero ZIP de una extensión. Se debe tener en cuenta que después de especificar un nombre para la extensión, este no se puede cambiar. Sin embargo, se puede cambiar el nombre del fichero ZIP.
Aunque se pueden especificar nombres diferentes para la extensión y su fichero ZIP, se recomienda utilizar el mismo nombre para la extensión y su fichero ZIP. En el nombre del fichero ZIP también se puede incluir el número de versión.
Se puede tener una solución de IoT que contenga varias extensiones empaquetadas, como un fichero ZIP de ficheros ZIP. En este caso, se recomienda que todos los ficheros ZIP tengan el mismo número de versión. Considere una solución de IoT que contenga dos extensiones. Cada extensión es un único fichero ZIP con un número de versión individual. Se recomienda especificar el mismo número de versión en el nombre de las dos extensiones. Asimismo, se debe especificar el mismo número de versión en el nombre del fichero ZIP de los ficheros ZIP. Por ejemplo, si el número de versión de la solución de IoT es 7.9, especifique 7.9 como número de versión en el nombre de todos los ficheros ZIP.
En el fichero
metadata.xml, el atributo
packageVersion se utiliza para especificar la versión de la extensión. Se trata de un atributo obligatorio cuyo valor tiene el formato
<major>.<minor>.<patch>, donde cada parte de la versión es numérica. Las extensiones deben seguir las reglas de asignación de versiones semánticas. Consulte
Semantic Versioning para obtener más información.
Atributo de metadatos de compatibilidad con la alta disponibilidad
Con ThingWorx 9.0, se soporta un nuevo atributo de metadatos, haCompatible, para identificar si una extensión funcionará correctamente en un clúster de alta disponibilidad de ThingWorx. Añada haCompatible":"TRUE" a los metadatos de la extensión para identificar que la extensión funcionará en un panorama de alta disponibilidad. El atributo haCompatible se puede definir en FALSO para identificar que la extensión no es conforme a la alta disponibilidad y no se debe importar en un panorama de alta disponibilidad.
Se recomienda utilizar el atributo
haCompatible en todas las extensiones. Para obtener más información sobre la configuración de
ThingWorx Platform con el fin de controlar la importación de la extensión para la compatibilidad con la alta disponibilidad, consulte
Detalles de la configuración de platform-settings.json y
para la alta disponibilidad de ThingWorx.
Dependencia de la extensión con respecto a otras extensiones
Si la extensión es dependiente de otras extensiones, se recomienda utilizar el atributo dependsOn en el fichero metadata.xml para especificar las dependencias. El valor del atributo es una lista de nombres y versiones de extensiones separados por comas con el formato <name>:<major>.<minor>.<patch>, donde las versiones solo se especifican en números. Por ejemplo, dependsOn= "ExtensionOne:2.5.1,ExtensionTwo:1.2.0".
Es una práctica recomendada evitar demasiadas dependencias. Si hay actualizaciones para cualquiera de las extensiones, las extensiones dependientes también se ven afectadas.
Exclusión de un acoplamiento estrecho con otras extensiones
Se debe evitar el acoplamiento estrecho de la extensión con otras extensiones.
• Si la extensión está estrechamente acoplada a otra extensión que se debe actualizar a una nueva versión principal, se solicitará al usuario que borre la extensión y toda la cadena de dependencias antes de poder realizar la actualización.
• La mejor manera de evitar el vínculo estrecho es crear cosas y plantillas de cosa de la funcionalidad que se requiere. Estas cosas y plantillas de cosa no forman parte de la extensión y, por lo tanto, no se incluyen en sus actualizaciones.
• A veces, puede resultar difícil evitar un acoplamiento estrecho cuando se utilizan widgets de otras extensiones en los mashups de la extensión.
Tamaño de una extensión
Las extensiones grandes y complejas pueden ser difíciles en cuanto al mantenimiento y la actualización. Un método más adecuado es la división de extensiones en componentes más pequeños según la funcionalidad para facilitar el mantenimiento y la actualización. Se pueden empaquetar varias extensiones en un único fichero ZIP. Para obtener más información, consulte la sección
Empaquetado de varias extensiones en un fichero ZIP para una solución.
Uso de ficheros JAR externos en una extensión
ThingWorx permite a los usuarios incluir bibliotecas de terceros en su código. Sin embargo, se recomienda evitar el uso de los ficheros JAR comunes. En su lugar, utilice los ficheros JAR empaquetados con el SDK en la solución. Se debe tener en cuenta lo siguiente:
• Se pueden utilizar los ficheros JAR existentes de la carpeta /Thingworx/WEB-INF/lib en la extensión. Sin embargo, si desea utilizar un fichero JAR externo en la extensión, asegúrese de que el fichero JAR no tenga el mismo nombre raíz que ninguno de los demás ficheros JAR presentes en la carpeta /Thingworx/WEB-INF/lib.
El nombre raíz de un fichero JAR es el nombre desde el primer carácter hasta el primer carácter numérico en el nombre del fichero. En la tabla se proporcionan los nombres de raíz de los siguientes ficheros JAR que se encuentran en la carpeta /Thingworx/WEB-INF/lib:
|
Nombre de fichero JAR
|
Nombre raíz
|
|
postgresql-42.2.5.jar
|
postgresql-
|
|
log4j-1.2.17.jar
|
log
|
|
metrics-core-3.1.2.jar
|
metrics-core-
|
• ThingWorx Platform permite que varios orígenes utilicen los mismos ficheros JAR.
• Cuando varios orígenes utilizan los mismos ficheros JAR, se puede producir un conflicto al cargar una extensión en ThingWorx Platform o cuando se utiliza una versión incorrecta de JAR al crear la extensión.
• Es posible que las versiones futuras de ThingWorx Platform requieran actualizaciones de las extensiones para seguir funcionando.
• Un cliente no puede utilizar dos extensiones que requieran los mismos ficheros JAR a la vez.
Conversión de entidades en no editables
Al crear entidades, tales como mashups, definiciones de estilo, etc., asegúrese de que las entidades de la extensión no sean editables. Solo se pueden actualizar localmente las entidades no editables. Las entidades editables no se pueden actualizar. Por defecto, las entidades nuevas no se pueden editar.
• Si desea que algunas entidades se puedan editar, empaquételas en una extensión independiente, de modo que se puedan actualizar fácilmente los demás componentes de la extensión.
• Para las entidades editables, se recomienda minimizar las ubicaciones editables en un mashup. Utilice mashups integrados para minimizar las ubicaciones editables.
Si se desea proporcionar la capacidad de personalizar la extensión, por ejemplo, añadir un logotipo personalizado, se debe tener en cuenta si puede funcionar un enfoque alternativo:
• ¿Se puede utilizar la configuración de una cosa en su lugar? Se pueden realizar cambios en la tabla de configuración de una cosa no editable.
• ¿Se puede utilizar un servicio para buscar una configuración con el fin de proporcionar una entidad multimedia o un mashup integrado?
Duplicación de entidades de extensión
Cuando se duplica una entidad, se clona todo excepto el nombre. Lo mismo ocurre al duplicar entidades de extensión, pero si una entidad de extensión tiene un conjunto de proyectos de extensión, este campo también se transfiere. Si se intenta guardar esta entidad, se producirá un error porque se intenta asignar la entidad al proyecto de extensión, lo que no está permitido.
Si se duplica una entidad de extensión que tiene un proyecto de extensión asignado, se debe despejar ese campo y definir un proyecto nuevo sin extensión. Si se utiliza la API CloneThing, se debe utilizar el servicio SetProject para definir un proyecto. Si no se asigna un proyecto, se asignará automáticamente a PTCDefaultProject.
Si una entidad de extensión editable se importa a la versión 9.1 y versiones posteriores, el campo de proyecto de la entidad será de solo lectura después de importar la extensión, y conservará la configuración del proyecto anterior a la actualización. Si un proyecto está asignado o el campo Proyecto está en blanco, se conserva ese valor.
Actualización de una extensión con entidades editables
Al actualizar una extensión con entidades editables, realice una prueba de migración para comprobar si se pierde cualquier información, como etiquetas, durante el proceso de actualización.
Organización de entidades
Se recomienda agrupar entidades mediante proyectos y etiquetas de modelo. Se debe utilizar un proyecto para todas las entidades de la extensión. Cree al menos una etiqueta de modelo que se pueda utilizar para etiquetar todas las entidades de la extensión.
Copia de seguridad del almacenamiento antes de borrar
Se recomienda hacer una copia de seguridad de la carpeta ThingworxStorage actual antes de borrarla.
Plug-in de Eclipse
El plug-in de Eclipse facilita el desarrollo y la creación de extensiones. Se proporcionan acciones que generan automáticamente ficheros de origen, anotaciones y métodos. Las acciones también actualizan el fichero de metadatos para garantizar una configuración correcta de la extensión. El plug-in también garantiza que la sintaxis y el formato de las anotaciones y el fichero de metadatos sean correctos.
Para obtener más información sobre el plug-in de Eclipse, consulte la sección
Uso del plug-in de Eclipse.