在 Node.js 中協調 Aspire 應用程式

在本文中，您將瞭解如何在Node.js專案中使用npm節點套件管理員 （Aspire） 應用程式。 本文中的範例應用程式示範 Angular、React和 Vue 客戶端體驗。 下列 Aspire API 存在以支援這些情境，且它們是 .AspireHosting.NodeJS NuGet 套件的一部分。

• Node.js：AddNodeApp。
• npm 應用程式：AddNpmApp。

這兩個 API 之間的差異在於，前者用來裝載 Node.js 應用程式，而後者則用來裝載從 package.json 檔案 scripts 區段執行的應用程式，以及對應的 npm run <script-name> 命令。

Tip

本文的範例原始程式碼可在 GitHub 取得，詳細資訊可在 包含 Aspire、Angular 和 React 的 Vue 頁面上找到。

Important

雖然本文著重於 Single-Page 應用程式（SPA）前端位，但 Node.js 頁面提供額外的 Aspire 範例，示範如何使用 Node.js 作為具有 express的伺服器應用程式。

Prerequisites

若要使用 Aspire，您需要在本機安裝下列專案：

• .NET 8.0 或 .NET 9.0。
  • 從 9.4 開始 Aspire ， .NET 支援 10 Preview 5 或更新版本 。
• 符合 OCI 規範的容器運行時間，例如：
  • Docker 桌面 或 Podman。 如需詳細資訊，請參閱 容器運行時間。
• 整合式開發人員環境 （IDE） 或程式碼編輯器，例如：
  • Visual Studio 2022 17.9 版或更高版本 （選用）
  • Visual Studio Code （選擇性）
    • C# Dev Kit：擴充功能（選擇性）
  • 帶有插件的 Aspire JetBrains Rider （可選）

如需詳細資訊，請參閱 設定和工具，以及AspireAspire SDK。

此外，您必須在計算機上安裝 Node.js。 本文中的範例應用程式是使用 Node.js 20.12.2 版和 npm 10.5.1 版所建置。 若要確認您的 Node.js 和 npm 版本，請執行下列命令：

node --version

npm --version

若要下載 （包括 ），請參閱下載頁面。

複製範例原始程式碼

若要從 GitHub複製範例原始程式碼，請執行下列命令：

git clone https://github.com/dotnet/aspire-samples.git

複製存放庫之後，流覽至 samples/AspireWithJavaScript 資料夾：

cd samples/AspireWithJavaScript

在此目錄中，下列列表描述了六個子目錄。

• AspireJavaScript。Angular：Angular 應用程式，會取用天氣預報 API，並在數據表中顯示數據。
• AspireJavaScript.AppHost： Aspire 協調此範例中其他應用程式的專案。 如需詳細資訊，請參閱 Aspire 協調流程概觀。
• AspireJavaScript.MinimalApi：傳回隨機產生的天氣預報數據的 HTTP API。
• AspireJavaScript。React：React 應用程式，會取用天氣預報 API，並在數據表中顯示數據。
• AspireJavaScript.ServiceDefaults：專案的 Aspire 預設共用專案。 如需詳細資訊，請參閱服務Aspire預設值。
• AspireJavaScript。Vue：Vue 應用程式，會取用天氣預報 API，並在數據表中顯示數據。

安裝用戶端依賴套件

範例應用程式示範如何使用建置在 Node.js之上的 JavaScript 用戶端應用程式。 每個用戶端應用程式都是使用 npm create 範本命令或手動撰寫。 下表列出用來建立每個用戶端應用程式的範本命令，以及預設埠：

應用程式類型	建立範本命令	默認埠
Angular	npm create @angular@latest	4200
React	未使用範本。	PORT env var
Vue	npm create vue@latest	5173

Tip

您不需要執行上述任何命令，因為範例應用程式已經包含用戶端。 相反地，這是用來創建客戶端的參考點。 如需詳細資訊，請參閱 npm-init。

若要執行應用程式，您必須先為每個用戶端安裝相依性。 若要這樣做，請瀏覽至每個客戶端資料夾並執行 npm install （或安裝別名 npm i） 命令。

安裝 Angular 依賴項

npm i ./AspireJavaScript.Angular/

如需 Angular 應用程式的詳細資訊，請參閱 探索 Angular 用戶端。

安裝 React 依賴項

npm i ./AspireJavaScript.React/

如需 React 應用程式的詳細資訊，請參閱 探索 React 用戶端。

安裝 Vue 依賴項

npm i ./AspireJavaScript.Vue/

如需 Vue 應用程式的詳細資訊，請參閱 探索 Vue 用戶端。

執行範例應用程式

若要執行範例應用程式，請呼叫 dotnet run 命令，指定協調器 AppHost AspireJavaScript.AppHost.csproj 作為 --project 參數：

dotnet run --project ./AspireJavaScript.AppHost/AspireJavaScript.AppHost.csproj

Aspire儀表板會在預設瀏覽器中啟動，每個用戶端應用程式端點都會顯示在「資源」頁面的「端點」欄下。 下圖描述此範例應用程式的儀錶板：

weatherapi 服務端點會解析到一個記錄 HTTP API 的 Swagger UI 頁面。 每個用戶端應用程式都會使用此服務來顯示天氣預報數據。 您可以瀏覽至儀表板中的 Aspire 對應端點，以檢視每個用戶端應用程式。 下列各節會詳細說明其螢幕快照和從範本起點進行的修改。

在您用來執行應用程式的相同終端機會話中，按下 Ctrl + C 鍵以停止應用程式。

探索 AppHost

若要協助瞭解每個用戶端應用程式資源的協調流程，請查看 AppHost 專案。 AppHost 需要 Aspire.Hosting.NodeJS NuGet 套件來裝載 Node.js 應用程式：

專案檔也會定義建置目標，以確保在建置 AppHost 之前安裝 npm 相依性。 AppHost 程式碼（AppHost.cs_）會使用 AddNpmApp(IDistributedApplicationBuilder, String, String, String, String[]) 來宣告客戶端應用程式資源。

上述程式代碼：

• 建立 DistributedApplicationBuilder。
• 將“weatherapi”服務作為項目添加到 AppHost。
  • 將 HTTP 端點標示為外部端點。
• 使用 「weatherapi」 服務的參考，將 「angular」、“react” 和 「vue」 用戶端應用程式新增為 npm 應用程式。
  • 每個用戶端應用程式都會設定為在不同的容器埠上執行，並使用 PORT 環境變數來判斷埠。
  • 所有用戶端應用程式也都依賴 Dockerfile 來建置其容器映像，並設定為從 PublishAsDockerFile API 以容器的形式在發佈指令清單中表達自己。

如需內部迴圈網路的詳細資訊，請參閱 Aspire 內部迴圈網路概觀。 如需部署應用程式的詳細資訊，請參閱 Aspire 部署工具產生器的資訊清單格式。

當 AppHost 協調每個用戶端應用程式的啟動時，它會使用命令 npm run start 。 此命令定義於每個用戶端應用程式 scripts 檔案的 區段中。 start 文稿可用來在指定的埠上啟動用戶端應用程式。 每個用戶端應用程式都依賴 Proxy 來要求 「weatherapi」 服務。

代理伺服器被設定於：

• 用戶端的 Angular 檔案。
• 用戶端的 React 檔案。
• 用戶端的 Vue 檔案。

探索 Angular 用戶端

相較於原始 Angular 範本，做出了數個主要修改。 第一個是新增 proxy.conf.js 檔案。 此檔案用來將來自 Angular 用戶端的要求代理到「weatherapi」服務。

Aspire AppHost 設定 WEATHERAPI_HTTPS 和 WEATHERAPI_HTTP 環境變數，用於解析「weatherapi」服務端點。 上述組態 Proxy 會將開頭為 /api 的 HTTP 要求傳送至環境變數中指定的目標 URL。

然後將代理檔包含在 angular.json 檔案中。 更新 serve 目標以包含 proxyConfig 選項，並參照建立的 proxy.conf.js 檔案。 Angular CLI 現在會在提供 Angular 用戶端應用程式時使用 Proxy 設定。

第三個更新是 package.json 檔案。 此檔案可用來設定 Angular 用戶端，以在與預設埠不同的埠上執行。 這是透過使用 PORT 環境變數和 run-script-os npm 套件來設定埠以達成此目的。

scripts 檔案的 區段是用來定義 start 腳本。 npm start 命令會使用此腳本來啟動 Angular 客戶端應用程式。 start 腳本被設置為使用 run-script-os 套件來設定埠，這會將任務委派給 ng serve 命令，並根據OS適用的語法傳遞適當的 --port 參數。

若要對 「weatherapi」 服務進行 HTTP 呼叫，Angular 用戶端應用程式必須設定為提供相依性插入 AngularHttpClient。 這可透過在 provideHttpClient 檔案中配置應用程式時，使用 輔助函式來達成。

最後，Angular 用戶端應用程式必須呼叫 /api/WeatherForecast 端點，以擷取天氣預報數據。 有數個 HTML、CSS 和 TypeScript 更新，這些更新全都對下列檔案進行：

• app.component.css：更新 CSS 以設定表格樣式。
• app.component.html：更新 HTML，以在數據表中顯示天氣預報數據。
• app.component.ts：更新 TypeScript 以呼叫 /api/WeatherForecast 端點，並在數據表中顯示數據。

Angular應用程式執行中

若要將 Angular 用戶端應用程式可視化，請流覽至 Aspire 儀錶板中的「angular」端點。 下圖描述 Angular 用戶端應用程式：

探索 React 用戶端

React 應用程式並未使用範本撰寫，而是手動撰寫。 您可以在 dotnet/aspire-samples 存放庫 中找到完整的原始程式碼，。 在 src/App.js 檔案中可以找到一些重點：

App 函式是 React 用戶端應用程式的進入點。 它會使用 useState 和 useEffect 掛鉤來管理天氣預報資料的狀態。 fetch API 可用來對 /api/WeatherForecast 端點提出 HTTP 要求。 然後，回應會轉換成 JSON，並設定為天氣預報數據的狀態。

上述程式代碼會定義 module.exports，如下所示：

• entry 屬性設為 src/index.js 檔案。
• devServer 依賴 Proxy 將要求轉送至 「weatherapi」 服務、將埠設定為 PORT 環境變數，並允許所有主機。
• output 會產生一個包含 bundle.js 檔案的 dist 資料夾。
• plugins 會將 src/index.html 檔案設定為範本，並公開 favicon.ico 檔案。

對以下檔案進行了最後的更新：

• App.css：更新 CSS 以設定表格樣式。
• App.js：更新 JavaScript 以呼叫 /api/WeatherForecast 端點，並在數據表中顯示數據。

React應用程式執行中

若要將 React 用戶端應用程式可視化，請流覽至 Aspire 儀錶板中的「react」端點。 下圖描述 React 用戶端應用程式：

探索 Vue 用戶端

相較於原始 Vue 範本，做出了數個主要修改。 主要更新是在 fetch 檔案中新增 呼叫，以從 /api/WeatherForecast 端點擷取天氣預報數據。 下列代碼段示範 fetch 呼叫：

當 TheWelcome 整合 mounted時，它會呼叫 /api/weatherforecast 端點來擷取天氣預報數據。 然後，回應會設定為 forecasts 數據屬性。 若要設定伺服器埠，Vue 用戶端應用程式會使用 PORT 環境變數。 藉由更新 vite.config.ts 檔案來達成此目的：

此外，Vite 配置中指定了 server.proxy 屬性，以將請求轉發至「weatherapi」服務。 這是透過使用 WEATHERAPI_HTTPS 和 WEATHERAPI_HTTP 環境變數，這些變數是由 Aspire AppHost 設定的來實現的。

已將範本的最終更新應用到 TheWelcome.vue 檔案。 此檔案會呼叫 /api/WeatherForecast 端點來擷取氣象預報數據，並在數據表中顯示數據。 其中包含 CSS、HTML 和 TypeScript 更新。

Vue應用程式執行中

若要將 Vue 用戶端應用程式可視化，請流覽至 Aspire 儀錶板中的 「vue」 端點。 下圖描述 Vue 用戶端應用程式：

部署考慮

本文的範例原始碼是設計為在本機執行。 每個客戶端應用程式都部署為容器映像檔。 每個用戶端應用程式的 Dockerfile 可用來建置容器映像。 每個 Dockerfile 都相同，使用多階段組建來建立可用於生產環境的容器映像檔。

用戶端應用程式目前已設定以純SPA應用程式方式運行，且未設定為在伺服器端渲染模式中運行。 它們位於 nginx後面，用來伺服靜態檔案。 他們會使用default.conf.template檔案來將nginx設定為轉發要求到用戶端應用程式。

Node.js 伺服器應用程式注意事項

雖然本文著重於用戶端應用程式，但您可能需要裝載 Node.js 伺服器應用程式。 托管 Node.js 伺服器應用程式與 SPA 用戶端應用程式需要相同的語義。 Aspire AppHost 需要引用 Aspire.Hosting.NodeJS NuGet 套件，並且程式碼必須呼叫 AddNodeApp 或 AddNpmApp。 這些 API 對於將現有的 JavaScript 應用程式 Aspire 新增至 AppHost 非常有用。

設定秘密並將環境變數傳遞至 JavaScript 型應用程式時，無論是客戶端或伺服器應用程式，請使用參數。 如需詳細資訊，請參閱 Aspire：外部參數 - 密碼。

使用 OpenTelemetry JavaScript SDK

若要從 OpenTelemetry 伺服器應用程式匯出 Node.js 記錄、追蹤和計量，請使用 OpenTelemetry JavaScript SDK。

如需使用 Node.js JavaScript SDK 之 OpenTelemetry 伺服器應用程式的完整範例，您可以參考 程式代碼範例：AspireNode.js 範例 頁面。 請考慮範例的 instrumentation.js 檔案，示範如何設定 OpenTelemetry JavaScript SDK 來導出記錄、追蹤和計量：

Tip

若要設定 Aspire 儀表板 OTEL CORS 設定，請參閱 Aspire 儀表板 OTEL CORS 設定 頁面。

Summary

雖然有數個超出本文範圍的考慮事項，但您已經學習如何建置使用 Aspire 和 Node Package Manager（Node.js）的 npm 專案。 您也瞭解如何使用 AddNpmApp APIs 分別裝載 Node.js 應用程式和從 package.json 檔案執行的應用程式。 最後，您已瞭解如何使用 npm CLI 來建立 Angular、React和 Vue 用戶端應用程式，以及如何設定它們在不同的埠上執行。

另請參閱

• 代碼範例：Aspire 與 Angular、React 和 Vue
• 程式代碼範例：AspireNode.js 應用程式