跳轉到

開發前準備

本指南將協助您從零開始配置 UOFX 外掛開發環境

.NET 8

NodeJS

Angular CLI

前端 Web 採用 Primeng

App 使用 Ionic version

安裝 IDE

安裝 NodeJS

  • 下載 NVM 安裝程式
  • 安裝 NodeJS
    • 使用 NVM 安裝指定版本：終端機執行 nvm install 18.20.3
    • 指定使用該版本：終端機執行 nvm use 18.20.3

NVM 無法使用？

  • 設定環境變數 NVM_HOME 與 NVM_SYMLINK
  • 預設 NVM 安裝位置：C:\\AppData\Roaming\nvm
    （例：C:\Users\ede\AppData\Roaming\nvm）
  • 設定後需重新開啟終端機

安裝 Angular 環境

  • 安裝 Angular CLI 17.3.8：終端機執行 npm install -g @angular/cli@17.3.8
  • 確認 Angular CLI 版本：終端機執行 ng version
    Image reference-SDK
    確認 Angular CLI 版本

為何需要準備開發測試用 UOFX 站台？

  • 外掛模組的開發與測試需要在 UOFX 站台進行，因此需要一個 UOFX 站台環境用於開發與測試
  • 除了可使用公司既有安裝的 UOFX 站台(測試區)外，您也可以選擇於本地端自行安裝一套 UOFX 站台
  • 需注意：安裝本地端開發用 UOFX 站台的系統需求，記憶體至少需具備 16 GB，若您的設備記憶體不足，
    建議進行開發與測試時使用公司既有的 UOFX 站台，以避免系統效能影響開發體驗

安裝本地端開發用 UOFX 站台說明

重要提醒

以下安裝 UOFX 站台的 SQL Server 為開發版本 ，因此此為本地端開發測試使用， 請勿於正式環境使用！

安裝 CLI Tool

  • 使用 系統管理員 開啟終端機
  • 執行 npm i -g @uofx/cli

檢查確認環境

  • 執行 uofx env setup 檢查環境是否符合需求，若缺少環境將詢問是否安裝，輸入 Y 以安裝所需環境
  • 再次執行確認環境符合需求

Image reference-SDK
環境已符合需求

查看目前可安裝版本

  • 執行 uofx env list charts 查看目前可安裝的 UOFX 版本

安裝 UOFX 站台

  • 執行 uofx env install --name <name> --chart-version <version> 安裝
    （例如：uofx env install --name training --chart-version 2.123.303）
  • --name：名稱
  • --chart-version：UOFX 版本，若不指定則安裝最新發佈版本
  • --no-northwind：安裝時不掛載北風資料庫（Northwind），若不指定則安裝時會預設掛載

命名規則

  • 須小於 50 個字元
  • 開頭和結尾必須是英數字元
  • 可以包含連字號（-）

確認已完成 UOFX 站台安裝

完成環境安裝後，將會看到以下畫面，並顯示安裝的 UOFX 站台網址與 SQL Server 連線資訊

Image reference-SDK
環境已完成安裝

取得環境帳號/密碼與 URL

  • 執行 uofx env list credentials --name <name> --reveal

初始化前台公司

UOFX 為多公司架構，安裝完成 UOFX 站台後，需先於後台管理中心（16888 port）建立前台公司，才能於該公司下使用相關功能，如設計表單與表單串接等。
可參考以下章節說明：

其他 UOFX CLI Tool 指令

查看目前安裝與正在執行的環境

  • 執行 uofx env list 查看目前安裝的環境

環境操作

  • 執行 uofx env start --name <name> 啟動環境
  • 執行 uofx env stop --name <name> 停止環境
  • 執行 uofx env delete --name <name> 刪除環境

重要提醒

  • 刪除環境後，將永久刪除該環境中的所有資料，如公司、組織及表單等，請務必再次確認環境名稱是否正確，以避免誤刪重要資料。

更多相關說明

  • 若需了解更多 UOFX CLI Tool 的詳細說明與完整指令，請參考官方文件：UOFX CLI Tool

下載外掛模組專案

  • 至 GitHub 下載專案：UOFX-Plugin-Training
  • 安裝專案相依套件
    • 終端機進入專案 ClientApp 資料夾
    • 執行 npm install
    • 確認相依套件安裝完成
      Image reference-SDK
      確認相依套件安裝完成

設定啟動外掛模組專案網址

  • 調整 Ede.Uofx.Customize.Web\Properties\launchSettings.json 中 applicationUrl
launchSettings.json
"profiles": {
    "Ede.Uofx.Customize.Web": {
        "applicationUrl": "新增 `yourip:port`"
    }
}
  • 例如："applicationUrl": "http://172.1.1.2:8899;http://localhost:8899"

更改專案 Port（非必要）

為何需要更改 Port？

  • 在開發時若遇到 多位開發者使用同一個站台 進行開發時，大家皆使用同一個 port，會發生 畫面不斷重整的問題
  • 原因是外掛模組啟動時，webpack.config.js 預設監聽 ws://localhost:40001，導致頁面載入他人功能時也連接到本機的 40001，只要偵測到變更就會觸發刷新，進而形成不斷重複刷新的狀況
  • 為避免發生重整狀況，多位開發者共同開發時，建議 採用不同的 port 進行開發
  • 調整 applicationUrl 中的 port（例如："applicationUrl": "http://172.1.1.2:8900;http://localhost:8900"）

掛載北風資料庫

依據您的環境安裝方式，請參考以下對應說明：

1. 已透過 UOFX CLI Tool 安裝環境

若您已使用 UOFX CLI Tool 建立環境，並預設掛載北風資料庫（Northwind），則可略過資料庫掛載步驟，並建議您新增一組登入帳號：

補充說明

  • 可先執行以下指令取得 SQL Server 的連線資訊、帳號與密碼：
uofx env list credentials --name <name> --reveal
  • 取得資訊後，即可登入 SQL Server 並進行「新增登入帳號」設定

2. 尚未掛載北風資料庫

若您的環境尚未掛載北風資料庫（Northwind），請參考以下指南，將北風資料庫掛載至本地 SQL Server，作為外掛模組開發與測試使用：

連線字串設定

完成北風資料庫掛載後，請更新外掛模組專案中 appsettings.json 的連線字串：

appsettings.json
{
    "ConnectionStrings": {
        "Default":"data source=<SQL Server 位址>;initial catalog=northwind;user id=<您設定登入名稱>;password=<您設定密碼>;Persist Security Info=True;MultipleActiveResultSets=True;TrustServerCertificate=True"
    }
}

Data Source 設定

  • 透過 UOFX CLI Tool 安裝環境： 設定為 uofx env list credentials --name <name> --reveal 指令取得之 SQL Server 位址
  • 自行掛載北風資料庫： 設定為 (LocalDb)\\MSSQLLocalDB

啟動專案

請參考以下指南將專案啟動。

建立開發人員通道（非必要）

為何需要建立開發人員通道？

由於 UOFX 站台與外掛站台之間需要進行雙向連線， 若使用的 UOFX 站台為對外部公開的環境 ，開發人員於本機開發時，可透過開發人員通道建立一個可公開存取的連線，讓外部的 UOFX 站台能夠連線到本機的外掛開發環境

  • 開啟 Visual Studio Code
  • F1 執行 Forward a Port
  • 點擊 轉送連接埠
  • 輸入專案設定 Port（8899）
  • 登入 GitHub 帳號（若為第一次使用）
  • 將可見度設定為 公用

確認可新增 Plugin

  • 登入 UOFX 站台，並切換至 管理者首頁 > 串接服務 > Plugin 管理 頁面
  • 點擊 新增Plugin
  • 輸入 Plugin 位置
    • 若使用本地端測試：輸入 http://<your-ip>:8899/
    • 若使用開發人員通道：輸入 開發人員通道轉送位址

Image add-plugin
在 UOFX 中新增設定檔

  • 確認載入畫面，點擊安裝

Image install-plugin
確認載入外掛模組

確認可呼叫 API

  • 開啟 Postman 或其他 API 測試工具
  • 輸入 API 位址
    • 若使用本地端測試：輸入 http://<your-ip>:8899/api/northwind/products
    • 若使用開發人員通道：輸入 <開發人員通道轉送位址>/api/northwind/products

Image check-api
成功呼叫 API

常見問題排解

沒有看到串接服務選單

  • 確認登入帳號具備 工作流程管理員 權限（參考手冊說明：角色權限管理）

新增 Plugin 發生錯誤

  • 確認配置檢查工具是否有錯誤訊息（參考手冊說明：配置檢查工具）
  • 確認外掛模組專案是否正在執行

API 呼叫失敗

  • 確認 appsettings.json 中的連線字串，是否可於 SSMS 上成功連線（參考手冊說明：連線字串設定）

下一步

開始你的第一個功能