Best practice per la creazione di package e la distribuzione di soluzioni ThingWorx
Per sviluppare e distribuire le estensioni, attenersi alle best practice descritte di seguito.
Sviluppare in un'istanza di piattaforma pulita
ThingWorx non fornisce protezione o sandboxing per il codice. Può accadere che l'ambiente diventi instabile. Per tenere la soluzione fuori dallo stato instabile, effettuare le operazioni descritte di seguito.
• Se viene visualizzato un errore nel processo di sviluppo, riavviare il server Apache Tomcat.
• È possibile che venga richiesto di rimuovere completamente la directory ThingworxStorage. È consigliabile sviluppare la soluzione in un'istanza pulita di ThingWorx per assicurarsi di non perdere lavoro quando si rimuove la directory ThingWorxStorage.
Struttura di un'estensione
Per gli elementi di un'estensione è necessario creare il package all'interno di un file ZIP nella struttura di cartelle seguente:
• /metadata.xml - Informazioni sull'estensione e dettagli dei vari elementi dell'estensione.
• /Entities/ - Zero o più file XML di entità organizzati in sottocartelle in base al tipo di entità.
• /lib/ - File JAR che include le classi Java personalizzate per l'estensione e i file JAR di terze parti richiesti dall'estensione.
• /ui/ - File che definiscono i widget personalizzati utilizzati per creare ed eseguire mashup.
Raggruppare più estensioni in un unico file ZIP per una soluzione
Le soluzioni IoT che contengono più estensioni possono essere raggruppate in un unico file ZIP contenente file ZIP singoli per ciascuna estensione. Ciò garantisce che ogni estensione sia implementata in modo indipendente. È più facile aggiornare le singole estensioni nelle release successive.
Convenzione per versione e nome di estensione
Non esistono restrizioni per la denominazione di un'estensione e del relativo file ZIP. Dopo avere specificato un nome per l'estensione, non è possibile modificarlo, ma è possibile modificare il nome del file ZIP.
Nonostante sia possibile specificare nomi diversi per l'estensione e il relativo file ZIP, è consigliabile utilizzare lo stesso nome. Il nome del file ZIP può contenere anche il numero di versione.
Nel caso di una soluzione IoT che contiene più estensioni raggruppate come uno o più file ZIP, è consigliabile specificare lo stesso numero di release per tutti i file ZIP. Si consideri una soluzione IoT che contiene due estensioni. Ogni estensione è un file ZIP singolo con un numero di release singolo. È consigliabile specificare lo stesso numero di release nel nome delle due estensioni e nel nome del file o dei file ZIP. Ad esempio, se il numero di release della soluzione IoT è 7.9, specificare 7.9 come numero di release nel nome di tutti i file ZIP.
Nel file
metadata.xml, per specificare la versione dell'estensione viene utilizzato l'attributo
packageVersion. Si tratta di un attributo obbligatorio, il cui valore segue il formato
<major>.<minor>.<patch>, in cui ogni parte della versione è numerica. Le estensioni devono seguire le regole semantiche di controllo delle versioni. Per ulteriori informazioni, vedere la pagina relativa al
controllo delle versioni semantiche.
Attributo dei metadati di compatibilità a disponibilità elevata
Con ThingWorx 9.0, è supportato un nuovo attributo di metadati, haCompatible, che permette di specificare se un'estensione funziona in un cluster a disponibilità elevata di ThingWorx. Aggiungere haCompatible":"TRUE" ai metadati dell'estensione per specificare che l'estensione funziona in un ambiente a disponibilità elevata. È possibile impostare l'attributo haCompatible su FALSE per specificare che l'estensione non è conforme alla disponibilità elevata e non deve essere importata in un ambiente di questo tipo.
Si consiglia di utilizzare l'attributo
haCompatible per tutte le estensioni. Per ulteriori informazioni sulla configurazione della piattaforma
ThingWorx per il controllo dell'importazione dell'estensione per la compatibilità a disponibilità elevata, vedere
Dettagli di configurazione di platform-settings.json e
Impostazioni di piattaforma per ThingWorx a disponibilità elevata.
Dipendenza dell'estensione da altre estensioni
Se l'estensione dipende da altre estensioni, è consigliabile utilizzare l'attributo dependsOn nel file metadata.xml per specificare le dipendenze. Il valore dell'attributo è un elenco separato da virgole di versioni e nomi di estensione nel formato <name>:<major>.<minor>.<patch>, in cui le versioni sono specificate solo mediante numeri, ad esempio dependsOn= "ExtensionOne:2.5.1,ExtensionTwo:1.2.0".
È consigliabile evitare troppe dipendenze. Eventuali aggiornamenti a una qualsiasi delle estensioni interessano anche le estensioni dipendenti.
Evitare l'accoppiamento stretto ad altre estensioni
È necessario evitare l'accoppiamento stretto di un'estensione ad altre estensioni.
• Se l'estensione è strettamente accoppiata a un'altra estensione che deve essere aggiornata a un nuovo numero di versione principale, per poter eseguire l'aggiornamento viene chiesto di eliminare l'estensione e l'intera catena di dipendenze.
• Il modo migliore per evitare l'accoppiamento stretto consiste nel creare oggetti e modelli di oggetto della funzionalità richiesta. Oggetti e modelli di oggetto non fanno parte dell'estensione, pertanto non sono inclusi negli aggiornamenti dell'estensione.
• In alcune situazioni può risultare difficile evitare l'accoppiamento stretto quando si utilizzano i widget di altre estensioni nei mashup dell'estensione.
Dimensione di un'estensione
Gestire e aggiornare estensioni grandi e complesse può risultare difficile. Un approccio valido consiste nel suddividere le estensioni in componenti più piccoli in base alla funzionalità per semplificare la manutenzione e l'aggiornamento. È possibile raggruppare più estensioni in un singolo file ZIP. Per ulteriori informazioni, vedere la sezione
Raggruppare più estensioni in un unico file ZIP per una soluzione.
Uso di file JAR esterni in un'estensione
ThingWorx consente agli utenti di includere librerie di terze parti nel codice. Si consiglia tuttavia di evitare di utilizzare i file JAR comuni. Usare invece i file JAR per cui è stato creato il package con l'SDK nella soluzione. Tenere presente quanto descritto di seguito.
• Nell'estensione è possibile utilizzare i file JAR esistenti della cartella /Thingworx/WEB-INF/lib. Se si desidera invece utilizzare un file JAR esterno nell'estensione, assicurarsi che il nome radice del file JAR non sia uguale al nome radice di altri file JAR presenti nella cartella /Thingworx/WEB-INF/lib.
Il nome radice di un file JAR è il nome dal primo carattere fino al primo carattere numerico nel nome del file. La tabella illustra i nomi radice dei seguenti file JAR presenti nella cartella /Thingworx/WEB-INF/lib:
|
Nome file JAR
|
Nome radice
|
|
postgresql-42.2.5.jar
|
postgresql-
|
|
log4j-1.2.17.jar
|
log
|
|
metrics-core-3.1.2.jar
|
metrics-core-
|
• ThingWorx Platform consente a più origini di utilizzare gli stessi file JAR.
• Se più origini usano gli stessi file JAR, si può verificare un conflitto quando si carica un'estensione in ThingWorx Platform o quando si utilizza una versione JAR errata durante la creazione dell'estensione.
• Per continuare a usare le versioni future di ThingWorx Platform, potrebbe essere necessario aggiornare le estensioni.
• Un cliente non può utilizzare contemporaneamente due estensioni che richiedono gli stessi file JAR.
Rendere le entità non modificabili
Quando si creano entità, ad esempio mashup, definizioni di stile e così via, assicurarsi che le entità dell'estensione siano non modificabili. È possibile aggiornare solo le entità non modificabili. Quelle modificabili non possono essere aggiornate. Per default, le nuove entità sono non modificabili.
• Se si desidera modificare alcune entità, raggrupparle in un'estensione separata, in modo da poter aggiornare facilmente gli altri componenti dell'estensione.
• Per le entità modificabili si consiglia di ridurre al minimo le posizioni modificabili in un mashup. Utilizzare mashup incorporati per ridurre al minimo le posizioni modificabili.
Se si desidera offrire la possibilità di personalizzare l'estensione, ad esempio aggiungendo un logo personalizzato, valutare l'eventualità di utilizzare un approccio alternativo.
• Si può utilizzare in alternativa la configurazione di un oggetto? Alla tabella di configurazione di un oggetto non modificabile è comunque possibile apportare delle modifiche.
• È possibile utilizzare un servizio per cercare una configurazione allo scopo di fornire un'entità multimediale o un mashup incorporato?
Duplicazione di entità di estensione
Quando un'entità viene duplicata, viene clonato tutto tranne il nome. Lo stesso vale per la duplicazione delle entità di estensione, ma se un'entità di estensione presenta un insieme di progetti di estensione, viene incluso anche questo campo. Se si tenta di salvare questa entità, l'operazione non riesce perché viene eseguito il tentativo di assegnare l'entità al progetto di estensione e questo non è consentito.
Se si duplica un'entità di estensione a cui è assegnato un progetto di estensione, è necessario cancellare il campo e impostare un nuovo progetto non di estensione. Se si utilizza l'API CloneThing, è necessario utilizzare il servizio SetProject per impostare un progetto. Se non si assegna un progetto, viene assegnato automaticamente a PTCDefaultProject.
Se un'entità di estensione modificabile viene importata in 9.1 e versioni successive, il campo del progetto per l'entità sarà di sola lettura dopo l'importazione dell'estensione e manterrà l'impostazione del progetto precedente l'aggiornamento. Se si assegna un progetto o se il campo Progetto è vuoto, il valore viene mantenuto.
Aggiornare un'estensione con entità modificabili
Quando si aggiorna un'estensione con entità modificabili, eseguire un test di migrazione per verificare se, durante il processo di aggiornamento, vengono perse informazioni, ad esempio i tag.
Organizzare entità
Si consiglia di raggruppare le entità utilizzando i progetti e i tag modello. È necessario usare un solo progetto per tutte le entità dell'estensione. Creare almeno un tag modello che possa essere utilizzato per contrassegnare tutte le entità dell'estensione.
Eseguire il backup dell'archiviazione prima dell'eliminazione
Si consiglia di eseguire il backup della cartella ThingworxStorage corrente prima di eliminarla.
Plug-in Eclipse
Eclipse Plugin semplifica le operazioni di sviluppo e creazione di estensioni. Fornisce azioni che generano automaticamente file di origine, annotazioni e metodi. Le azioni inoltre aggiornano il file di metadati per garantire la corretta configurazione dell'estensione. Inoltre il plug-in garantisce che la sintassi e il formato delle annotazioni e del file di metadati siano corretti.
Per ulteriori informazioni su Eclipse Plugin, vedere
Utilizzo di Eclipse Plugin.