用 Rayfin CLI 建立一個 Fabric 應用程式

這個教學會教你如何使用 Rayfin CLI 建立專案、本地執行,然後部署到 Fabric。 你用同一套 CLI 工作流程來處理新應用程式,以及後續的架構或前端更新。

在本教學課程中,您會:

  • 從範本建立一個 Fabric Apps 專案。
  • 在本地啟動應用程式。
  • 從 CLI 登入 Fabric。
  • 將應用程式部署到 Fabric 工作區。
  • 確認部署狀態。

先決條件

  • Fabric 存取權限。
  • 一個 Fabric 工作區,你擁有貢獻者、成員或管理員權限。
  • 你的租戶已啟用 Fabric Apps 工作負載。
  • Node.js 和 NPM 已安裝。

建立帶有 AI 提示的應用程式

請使用以下提示,搭配 GitHub Copilot 或其他程式代理程式來建立、探索、執行、自訂並部署 Fabric 應用程式:

Set up a new Fabric App project called "rayfin-app-ws".

1. Run: npx -y @microsoft/create-rayfin@latest --project-name rayfin-app-ws --template blankapp
2. Open the scaffolded project directory.
3. Explore the project structure and understand the Rayfin app framework.
4. Run: npm run dev
5. Make changes to the app based on my instructions.
6. When ready, deploy with: npx rayfin up

scaffold 命令為非互動式執行提供專案名稱和範本。 代理程式可以要求提供任何剩餘的工作區或部署設定。 部署前請先檢視已產生的檔案與指令輸出。

從 CLI 建立新應用程式

要從範本搭建新應用程式,請使用 npm create:

npm create @microsoft/rayfin@latest -- my-app --workspace <workspacename>

預設 blankapp 範本會解析成 通用應用程式。 它建立一個新的 npm 工作區,後端設定在 rayfin/、前端程式碼在 packages/frontend/、執行階段資料定義在 packages/data/,以及共享合約在 packages/shared/。 在你選擇加入之前,資料功能會停用。

前往專案目錄:

cd my-app

小提示

如果你已經有空的專案資料夾或現有的原始碼,請用 npx rayfin init 代替 npm create。

npx rayfin init .

檢視已產生的專案

支架完成後,專案包含你需要開始開發的檔案:

  • rayfin/rayfin.yml 儲存應用程式服務與部署設定。
  • rayfin/.env 儲存 CLI 所使用的環境值。
  • packages/frontend/ 包含使用者介面與前端建置。
  • packages/data/ 包含執行時實體類別與結構註冊。
  • packages/shared/ 包含面向客戶端的紀錄與結構描述契約。

必要時啟用持續保存的應用程式資料:

npm run pack:add -- data-modeling

此功能可啟用 Data,並新增起始資料及共享定義。 加入檔案前請先檢查rayfin/rayfin.yml中的services.data.path和services.staticHosting.path。 其他範本可以使用平面根 src/ 和 rayfin/data/ 版面配置;那些版面是替代方案,不是通用應用程式的預設版面。

CLI 將活躍部署值保存在 rayfin/.env 中,並記錄部署 於 rayfin/.deployments.json。 公開 RAYFIN_PUBLIC_* 值會映射到前端產生 .env.local的檔案中;用 npx rayfin env --framework vite 來重新產生,但不部署。

如需詳細的逐檔案分解,請參閱 「了解專案結構」。

在本機執行應用程式

啟動在地發展環境:

npx rayfin dev

此指令啟動支架應用的前端開發伺服器,並將後端部署至 Fabric。 要確認應用程式是否正確啟動,請在終端機中開啟本地網址。

將應用程式部署到 Fabric

在你的應用程式中加入更多功能。 測試完變更後,再部署到 Fabric。

npx rayfin up

若要預覽部署而不做更改,請執行:

npx rayfin up --dry-run

驗證部署

請檢查目前的部署狀態:

npx rayfin up status

若要取得機器可讀的回應,請使用 JSON 輸出:

npx rayfin up status --json

成功部署後,CLI 會列印已部署項目的託管應用程式 URL 及 Fabric 入口連結。

僅部署資料庫或靜態內容

如果你只更改了資料模型,請在不完全重新部署的情況下套用資料庫變更:

npx rayfin up db apply

如果你只改了前端程式碼,請重新部署靜態資產:

npx rayfin up staticapp deploy

新增函數

函式是 TypeScript 函式,會在你的 Fabric 應用程式內的伺服器上執行。 將函式用於不能在瀏覽器中執行的邏輯,例如處理秘密、存取特權資料,以及以應用程式身分呼叫外部服務。

npx rayfin functions init

初始化器在設定後會使用 services.functions.path、偵測工作區位置(例如 packages/functions),或保留現有的扁平 rayfin/functions 套件。 用 --path <relative-path> 來明確選擇地點。

已啟用的功能需要 services.functions.auth.type: application。 透過 ctx.Tokens.* 進行外部呼叫時,會使用應用程式的身分及其權限,而非叫用使用者的外部資源權限。 在目前的 Fabric 應用程式中,該身分就是應用程式項目擁有者。 授權它存取每個資源。 相較之下,ctx.getDataClient() 使用調用的 Rayfin 權杖,並保留呼叫者的資料政策。

GitHub Copilot 可以產生並更新所需的檔案與元件。 你也可以請代理執行應用程式、在本地除錯功能,然後部署應用程式。 例如,你可以使用以下提示詞,透過函式建立 AI 提取要求審查助理:

Build an app that lets me view all pull requests for the repository
<repoURL>, chat with my Azure AI Foundry agent <agentName> to review
pull requests, and post review comments. Use Functions with application
authentication to connect to Azure AI Foundry and Azure DevOps. Grant the
app identity the required resource permissions, and preserve the caller's
Rayfin data policies when using ctx.getDataClient().

請參閱 使用函式 與 連接函式至外部資源 以了解身份與部署細節。

排除常見問題

登入失敗,或部署時傳回 401 或 403 錯誤

再跑 npx rayfin login 一次,然後再試 npx rayfin up一次。

你需要檢視 CLI 會執行什麼動作

在部署變更前,先執行 npx rayfin up --dry-run。

應用程式會部署,但你只改變了架構

若要獨立推送結構變更,請使用 npx rayfin up db apply。 如果你執行破壞性變更,例如更改欄位類型或移除欄位,這個指令就會失敗。 若要強制套用你的變更,你可以使用 --force 旗標。 這個動作可能會帶來突破性改變。

下一步