封裝及部署 ThingWorx 解決方案的最佳作法
開發及部署延伸功能時，請遵循下列最佳作法：
在乾淨的平台實例上開發
ThingWorx 不為您的程式碼提供保護或沙箱功能。有時，您的環境可能會變得不穩定。若要讓您的解決方案脫離不穩定狀態，請執行下列操作：
• 若您在開發流程看到錯誤，請重新啟動 Apache Tomcat 伺服器。
• 系統可能會提示您完全移除 ThingworxStorage 目錄。建議您在乾淨的 ThingWorx Platform 實例上開發解決方案，以確保在移除 ThingWorxStorage 目錄時，不會遺失任何工作。
延伸功能的結構
延伸功能的加工品必須以下列資料夾結構封裝到 ZIP 檔中：
• /metadata.xml - 有關延伸功能及延伸功能中各種加工品詳細資料的資訊。
• /Entities/ - 按實體類型組織在子資料夾中的零或多個實體 XML 檔案。
• /lib/ - 包括延伸功能自訂 Java 類別的 JAR 檔案，以及延伸功能所需的協力廠商 JAR 檔案。
• /ui/ - 定義用來建構及執行混搭之自訂小器具的檔案。
針對解決方案將多個延伸功能包裝成一個 ZIP 檔
可將包含多個延伸功能的 IoT 解決方案包裝為單一 ZIP 檔。單一 zip 檔案針對每個延伸功能包含一個單獨的 ZIP 檔。這樣可確保各延伸功能獨立實行。在後續發行版本中，單獨的延伸功能更新起來也更輕鬆。
延伸功能名稱與版本慣例
您如何為延伸功能及延伸功能的 ZIP 檔命名並沒有限制。請注意，在為延伸功能指定名稱之後，您無法予以變更。但是，ZIP 檔的名稱可以變更。
雖然您可以為延伸功能及其 ZIP 檔指定不同名稱，但建議為延伸功能及其 ZIP 檔指定相同名稱。ZIP 檔名稱也可以包含版本編號。
您可以將包含多個延伸功能的 IoT 解決方案包裝為內含多個 ZIP 的一個 ZIP。在此情況下，建議針對所有 ZIP 使用相同的發行版本編號。請考慮包含兩個延伸功能的 IoT 解決方案。每個延伸功能都是一個具有單獨發行版本編號的單一 ZIP 檔。最佳作法是在兩個延伸功能的名稱中指定相同的發行版本編號。此外，也請為多個 ZIP 所屬 ZIP 的名稱指定相同的發行版本編號。例如，如果您 IoT 解決方案的發行版本編號為 7.9，請在所有 ZIP 檔的名稱中指定 7.9 作為發行版本編號。
在
metadata.xml 檔案中，
packageVersion 屬性用來指定延伸功能版本。這是必要屬性，其值遵循
<major>.<minor>.<patch> 格式，其中版本的各部份都是數字。延伸功能必須遵循語意版本化規則。如需詳細資訊，請參閱
語義版本化。
HA 相容性中繼資料屬性
在 ThingWorx 9.0 中，支援新中繼資料屬性 haCompatible，可用來識別延伸功能在 ThingWorx 高可用性叢集中是否能夠正確運作。將 haCompatible":"TRUE" 新增至延伸功能中繼資料可識別延伸功能可在 HA 環境中運作。您可以將 haCompatible 屬性設定為 FALSE，來識別延伸功能不符合 HA 標準且不應匯入到 HA 環境。
強烈建議對所有延伸功能使用
haCompatible 屬性。如需有關配置
ThingWorx Platform 以控制匯入 HA 相容性延伸功能的詳細資訊，請參閱
platform-settings.json 組態詳細資訊與
ThingWorx HA 的平台設定。
延伸功能對於其他延伸功能的相依性
如果您的延伸功能對於其他延伸功能具有相依性，建議使用 metadata.xml 檔案中的 dependsOn 屬性來指定相依性。屬性值是延伸功能名稱與版本的逗號分隔清單，格式為 <name>:<major>.<minor>.<patch>，其中的版本僅以數字指定。例如，dependsOn= "ExtensionOne:2.5.1,ExtensionTwo:1.2.0"。
最好避免過多的相依性。如果有任何延伸功能需要升級，相依的延伸功能也會受到影響。
避免與其他延伸功能緊密結合
您必須避免使您的延伸功能與其他延伸功能緊密結合。
• 如果您的延伸功能與必須升級至新主要版本的另一個延伸功能緊密結合，系統會提示您先刪除您的延伸功能及其完整的相依性鏈，然後才能執行升級。
• 避免緊密結合的最佳方式就是為您需要的功能建立「物件」及「物範本」。這些物件與物範本並不屬於您延伸功能的一部份，因此不會包括在延伸功能升級中。
• 有時，當在延伸功能混搭中使用來自其他延伸功能的小器具時，可能很難避免緊密結合的情況。
延伸功能的大小
大型的複雜延伸功能很難維護與升級。比較好的方法是，根據功能將延伸功能分割成較小的元件，以便更輕鬆地維護及升級。您可以將多個延伸功能包裝在一個 ZIP 檔中。如需詳細資訊，請參閱
針對解決方案將多個延伸功能包裝成一個 ZIP 檔部份的內容。
在延伸功能中使用外部 JAR 檔案
ThingWorx 可讓使用者在其程式碼中包括協力廠商程式庫。不過，建議您避免使用通用 JAR 檔案。請改為使用透過 SDK 封裝在您解決方案中的 JAR 檔案。請考慮以下內容：
• 您可在延伸功能中使用 /Thingworx/WEB-INF/lib 資料夾中的現有 JAR 檔案。不過，如果您要在延伸功能中使用外部 JAR 檔案，則請確保 JAR 檔案的根名稱不得與存在於 /Thingworx/WEB-INF/lib 資料夾中的其他任何 JAR 檔案相同。
JAR 檔案的根名稱是檔案名稱中從第一個字元開始到第一個數字字元之前的這部份名稱。下表提供了下列存在於 /Thingworx/WEB-INF/lib 資料夾中之 JAR 檔案的根名稱：
|
JAR 檔案名稱
|
根名稱
|
|
postgresql-42.2.5.jar
|
postgresql-
|
|
log4j-1.2.17.jar
|
log
|
|
metrics-core-3.1.2.jar
|
metrics-core-
|
• ThingWorx Platform 允許多個來源使用相同的 JAR 檔案。
• 當多個來源使用相同的 JAR 檔案時，若將延伸功能上載至 ThingWorx Platform，或在建構延伸功能時使用了錯誤的 JAR 版本，可能會發生衝突。
• ThingWorx Platform 的未來版本可能需要更新延伸功能才能繼續使用。
• 客戶無法同時使用需要相同 JAR 檔案的兩個延伸功能。
將您的實體設定為無法編輯
在建立實體 (例如混搭、樣式定義等) 時，請確保延伸功能的實體無法編輯。只有無法編輯的實體才能就地升級。可編輯的實體無法升級。依預設，新實體是無法編輯的。
• 如果您想要讓某些實體可以編輯，請將這些實體包裝在一個單獨的延伸功能中，如此您便可以輕鬆升級延伸功能的其他元件。
• 對於可編輯的實體，建議最小化混搭上的可編輯位置。可使用內嵌混搭來最小化可編輯位置。
如果您想要提供自訂延伸功能的能力，例如，新增自訂標誌，請考慮是否可以使用另一種方法：
• 是否可以改用物件組態？無法編輯的物件仍然可以具有組態表變更。
• 是否可以使用服務查詢組態，以提供媒體實體或內嵌混搭？
複製延伸功能實體
複製實體時，會複製除名稱以外的所有項目。複製延伸功能實體時也是如此，但如果延伸功能實體已設定延伸功能專案，也會延續此欄位。如果您嘗試儲存此實體，將會失敗，這是因為它正嘗試將實體指派給延伸功能專案，而這是不允許的。
如果您複製已獲指派延伸功能專案的延伸功能實體，則必須清除該欄位並設定一個新的非延伸功能專案。如果您使用 CloneThing API，必須使用 SetProject 服務來設定專案。如果未指派專案，會自動將其指派給 PTCDefaultProject。
如果將可編輯的延伸功能實體匯入至 9.1 及更新版本，在匯入延伸功能之後，實體的專案欄位將為唯讀，並會保留其在升級之前的專案設定。無論是指派專案還是「專案」欄位為空白，都會保留該值。
升級包含可編輯實體的延伸功能
升級包含可編輯實體的延伸功能時，請執行移轉測試，以檢查在升級過程中是否有任何資訊 (例如標籤) 遺失。
組織實體
建議使用專案與模型標籤為實體編組。您必須針對延伸功能的所有實體使用一個專案。至少建立一個可用來標記您延伸功能所有實體的模型標籤。
刪除前先備份儲存
建議您在刪除之前先備份目前的 ThingworxStorage 資料夾。
Eclipse 外掛程式
Eclipse 外掛程式可讓您更輕鬆地開發及建構延伸功能。此外掛程式提供一些動作，可自動產生來源檔案、註釋及方法。動作也會更新中繼資料檔案，以確保正確配置延伸功能。此外掛程式也可確保註釋與中繼資料檔案的語法及格式正確。
如需有關 Eclipse 外掛程式的詳細資訊，請參閱
使用 Eclipse 外掛程式。