跳轉到

開發前準備

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

.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 版本

重要提醒

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

安裝 CLI Tool

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

檢查確認環境

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

Image reference-SDK
環境已符合需求

查看目前可安裝版本

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

安裝 UOF X 站台

  • 執行 uofx env install --name <name> --chart-version <version> 安裝
    （例如：uofx env install --name training --chart-version 2.123.303）
  • --name：名稱
  • --chart-version：UOF X 版本，若不指定則安裝最新發佈版本

命名規則

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

確認已完成 UOF X 站台安裝

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

Image reference-SDK
環境已完成安裝

取得環境帳號/密碼與 URL

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

初始化前台公司

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

其他 CLI Tool 指令

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

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

啟動與停止環境

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

下載外掛模組專案

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

更改專案 Port（非必要）

為何需要更改 Port？

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

（※ 可於專案全域搜尋 40001）

掛載北風資料庫

請參考以下指南掛載北風資料庫（Northwind）至本地 SQL Server，作為外掛模組開發練習使用。

啟動專案

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

設定 Nginx

請參考以下指南設定 Nginx，使 UOF X 可讀取您本機開發的項目。

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

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

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

  • 開啟 Visual Studio Code
  • F1 執行 Forward a Port
  • 點擊 轉送連接埠
  • 輸入本機外掛開發環境的 port（8899）
  • 登入 GitHub 帳號（若為第一次使用）
  • 將可見度設定為 公用

確認可新增 Plugin

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

Image add-plugin
在 UOF X 中新增設定檔

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

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

確認可呼叫 API

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

Image check-api
成功呼叫 API

常見問題排解

沒有看到串接服務選單

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

新增 Plugin 發生錯誤

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

API 呼叫失敗

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

下一步

開始你的第一個功能