搭配 ASP.NET Core 使用 Angular 專案範本

  • 發行項

注意

這不是這篇文章的最新版本。 如需目前版本，請參閱本文的 .NET 8 版本。

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

如需目前版本，請參閱本文的 .NET 8 版本。

Visual Studio 提供的專案範本可根據 Angular、React 和 Vue 等具有 ASP.NET Core 後端的 JavaScript 架構來建立單頁應用程式 (SPA)。 這些範本會：

  • 建立一個包含前端專案和後端專案的 Visual Studio 解決方案。
  • 使用 Visual Studio 的 JavaScript 和 TypeScript 專案類型 (.esproj) 來開發前端專案。
  • 使用 ASP.NET Core 專案來開發後端專案。

使用 Visual Studio 範本建立的專案可在 Windows、Linux 和 macOS 上透過命令列執行。 若要執行應用程式，請使用 dotnet run --launch-profile https 執行伺服器專案。 執行伺服器專案會自動啟動前端 JavaScript 開發伺服器。 目前需要 https 啟動設定檔。

Visual Studio 教學課程

若要開始使用 Angular 專案，請遵循 Visual Studio 文件中的使用 Angular 建立 ASP.NET Core 應用程式教學課程。

如需詳細資訊，請參閱 Visual Studio 中的 JavaScript 和 TypeScript

ASP.NET Core SPA 範本

Visual Studio 包含使用 JavaScript 或 TypeScript 前端建置 ASP.NET Core 應用程式的範本。 這些範本可在已安裝 ASP.NET 和 Web 開發工作負載的 Visual Studio 2022 17.8 版或更新版本中取得。

使用 JavaScript 或 TypeScript 前端建置 ASP.NET Core 應用程式的 Visual Studio 範本提供下列優點：

  • 清除前端和後端的專案區隔。
  • 隨時掌握最新的前端架構版本。
  • 整合最新的前端架構命令列工具，例如 Vite。
  • JavaScript 和 TypeScript 的範本 (僅限 TypeScript for Angular)。
  • 豐富的 JavaScript 和 TypeScript 程式碼編輯體驗。
  • 整合 JavaScript 建置工具與 .NET 組建。
  • npm 相依性管理 UI。
  • 與 Visual Studio Code 偵錯和啟動組態相容。
  • 使用 JavaScript 測試架構，在測試總管中執行前端單元測試。

舊版 ASP.NET Core SPA 範本

舊版 .NET SDK 包含使用 ASP.NET Core 建置 SPA 應用程式的舊版範本。 如需這些舊版範本的文件，請參閱 ASP.NET Core 7.0 版的 SPA 概觀 和 Angular 和 React 文章。

ASP.NET Core 搭配 Angular 專案範本很適合作為 ASP.NET Core 應用程式的建置起點，並利用 Angular 和 Angular CLI 來實作功能豐富的用戶端使用者介面 (UI)。

專案範本等同於建立 ASP.NET Core 專案作為 Web API，以及建立 Angular CLI 專案作為 UI。 此專案組合方便您將這兩個專案裝載於單一 ASP.NET Core 專案，而該專案可以單一單元的形式建置和發佈。

專案範本不適用於伺服器端轉譯 (SSR)。

建立新的應用程式

進入命令提示字元，然後在空目錄中使用 dotnet new angular 命令以建立新的專案。 例如，下列命令會在 my-new-app 目錄中建立應用程式並切換到該目錄：

dotnet new angular -o my-new-app
cd my-new-app

從 Visual Studio 或 .NET Core CLI 執行該應用程式：

開啟產生的 .csproj 檔案，然後在該處以一般方式來執行該應用程式。

建置程序會在首次執行時還原 npm 相依性，這可能需要幾分鐘時間才能完成。 後續建置所需的時間將會縮短。

專案範本會建立 ASP.NET Core 應用程式及 Angular 應用程式。 ASP.NET Core 應用程式主要用於存取資料、授權以及其他伺服器端事項。 位在 ClientApp 子目錄中的 Angular 應用程式，是用於所有 UI 方面的作業。

新增頁面、影像、樣式和模組

ClientApp 目錄包含標準 Angular CLI 應用程式。 如需詳細資訊，請參閱 Angular 文件 \(英文\)。

由此範本所建立的 Angular 應用程式，以及由 Angular CLI 本身所建立 (透過 ng new) 的 Angular 應用程式之間存在些許不同，不過應用程式的功能是一樣的。 由範本所建立的應用程式包含以 Bootstrap \(英文\) 為基礎的配置，以及基本的路由範例。

執行 ng 命令

在命令提示字元中，切換至 ClientApp 子目錄：

cd ClientApp

如果您已經以全域的方式安裝 ng 工具，則可以執行它的任何命令。 例如，您可以執行 ng lint、ng test 或任何其他 Angular CLI 命令 \(英文\)。 您並不需要執行 ng serve，因為 ASP.NET Core 應用程式會負責提供應用程式的伺服器端和用戶端部分。 它會在內部針對開發使用 ng serve。

如果您尚未安裝 ng 工具，請改為執行 npm run ng。 例如，您可以選擇執行 npm run ng lint 或 npm run ng test。

安裝 npm 套件

若要安裝協力廠商 npm 套件，請在 ClientApp 子目錄中使用命令提示字元。 例如：

cd ClientApp
npm install <package_name>

發行與部署

在開發時，應用程式會以方便開發人員操作的模式執行。 例如，JavaScript 組合會包含來源對應 (以便在偵錯時，您可以看到原始的 TypeScript 程式碼)。 應用程式會監看磁碟上的 TypeScript、HTML 和 CSS 檔案變更，並在發現檔案變更時，自動重新編譯並重新載入。

在實際執行環境中，請提供具有最佳效能的應用程式版本。 這是設定為自動進行的。 當您發行時，組建組態會發出精簡、預先 (AoT) 編譯的用戶端程式碼組建。 不同於開發組建，實際執行組建不需要在伺服器上安裝 Node.js (除非您已啟用伺服器端轉譯 (SSR))。

您可以使用標準 ASP.NET Core 裝載和部署方法。

獨立執行 "ng serve"

專案已設定為會在 ASP.NET Core 應用程式於開發模式中啟動時，在背景啟動屬於自己的 Angular CLI 伺服器執行個體。 這很方便，因為您不需要手動執行個別的伺服器。

此預設設定有一個缺點。 每當您修改 C# 程式碼，且需要重新啟動 ASP.NET Core 應用程式時，Angular CLI 伺服器都會重新啟動。 開始備份需要大約 10 秒鐘的時間。 如果您經常編輯 C# 程式碼，但又不想要等候 Angular CLI 重新啟動，請獨立於 ASP.NET Core 處理序，於外部執行 Angular CLI 伺服器。

若要在外部執行 Angular CLI 伺服器，請在命令提示字元中切換至 ClientApp 子目錄，然後啟動 Angular CLI 開發伺服器：

cd ClientApp
npm start

當您啟動 ASP.NET Core 應用程式時，它並不會啟動 Angular CLI 伺服器。 而是改為使用您手動啟動的執行個體。 這樣可以加快它的啟動和重新啟動速度。 它再也不必每次都得等候 Angular CLI 重建您的用戶端應用程式。

啟動 Proxy 後，就會從 .NET 所設定的環境變數 (ASPNETCORE_URLS 和 ASPNETCORE_HTTPS_PORTS) 推斷目標 URL 和連接埠。 若要設定 URL 或 HTTPS 連接埠，請使用其中一個環境變數或變更 proxy.conf.json 中的值。

設定 SignalR 的 Proxy 中介軟體

如需詳細資訊，請參閱 http-proxy-middleware。

其他資源

更新的 Angular 專案範本很適合作為 ASP.NET Core 應用程式的建置起點，並利用 Angular 和 Angular CLI 來實作功能豐富的用戶端使用者介面 (UI)。

此範本等同於建立 ASP.NET Core 專案作為 API 後端，並建立 Angular CLI 專案作為 UI。 此範本可讓使用者輕鬆地將這兩種專案類型裝載至單一應用程式專案中。 因此，應用程式專案便可以單一單位的方式進行建置與發佈。

建立新的應用程式

進入命令提示字元，然後在空目錄中使用 dotnet new angular 命令以建立新的專案。 例如，下列命令會在 my-new-app 目錄中建立應用程式並切換到該目錄：

dotnet new angular -o my-new-app
cd my-new-app

從 Visual Studio 或 .NET Core CLI 執行該應用程式：

開啟產生的 .csproj 檔案，然後在該處以一般方式來執行該應用程式。

建置程序會在首次執行時還原 npm 相依性，這可能需要幾分鐘時間才能完成。 後續建置所需的時間將會縮短。

專案範本會建立 ASP.NET Core 應用程式及 Angular 應用程式。 ASP.NET Core 應用程式主要用於存取資料、授權以及其他伺服器端事項。 位在 ClientApp 子目錄中的 Angular 應用程式，是用於所有 UI 方面的作業。

新增頁面、影像、樣式和模組

ClientApp 目錄包含標準 Angular CLI 應用程式。 如需詳細資訊，請參閱 Angular 文件 \(英文\)。

由此範本所建立的 Angular 應用程式，以及由 Angular CLI 本身所建立 (透過 ng new) 的 Angular 應用程式之間存在些許不同，不過應用程式的功能是一樣的。 由範本所建立的應用程式包含以 Bootstrap \(英文\) 為基礎的配置，以及基本的路由範例。

執行 ng 命令

在命令提示字元中，切換至 ClientApp 子目錄：

cd ClientApp

如果您已經以全域的方式安裝 ng 工具，則可以執行它的任何命令。 例如，您可以執行 ng lint、ng test 或任何其他 Angular CLI 命令 \(英文\)。 您並不需要執行 ng serve，因為 ASP.NET Core 應用程式會負責提供應用程式的伺服器端和用戶端部分。 它會在內部針對開發使用 ng serve。

如果您尚未安裝 ng 工具，請改為執行 npm run ng。 例如，您可以選擇執行 npm run ng lint 或 npm run ng test。

安裝 npm 套件

若要安裝協力廠商 npm 套件，請在 ClientApp 子目錄中使用命令提示字元。 例如：

cd ClientApp
npm install --save <package_name>

發行與部署

在開發時，應用程式會以方便開發人員操作的模式執行。 例如，JavaScript 組合會包含來源對應 (以便在偵錯時，您可以看到原始的 TypeScript 程式碼)。 應用程式會監看磁碟上的 TypeScript、HTML 和 CSS 檔案變更，並在發現檔案變更時，自動重新編譯並重新載入。

在實際執行環境中，請提供具有最佳效能的應用程式版本。 這是設定為自動進行的。 當您發行時，組建組態會發出精簡、預先 (AoT) 編譯的用戶端程式碼組建。 不同於開發組建，實際執行組建不需要在伺服器上安裝 Node.js (除非您已啟用伺服器端轉譯 (SSR))。

您可以使用標準 ASP.NET Core 裝載和部署方法。

獨立執行 "ng serve"

專案已設定為會在 ASP.NET Core 應用程式於開發模式中啟動時，在背景啟動屬於自己的 Angular CLI 伺服器執行個體。 這很方便，因為您不需要手動執行個別的伺服器。

此預設設定有一個缺點。 每當您修改 C# 程式碼，且需要重新啟動 ASP.NET Core 應用程式時，Angular CLI 伺服器都會重新啟動。 開始備份需要大約 10 秒鐘的時間。 如果您經常編輯 C# 程式碼，但又不想要等候 Angular CLI 重新啟動，請獨立於 ASP.NET Core 處理序，於外部執行 Angular CLI 伺服器。 若要這麼做︰

  1. 在命令提示字元中，切換至 ClientApp 子目錄，然後啟動 Angular CLI 程式開發伺服器：

    cd ClientApp
npm start

    重要

    使用 npm start 來啟動 Angular CLI 程式開發伺服器，而不是 ng serve，以遵守 package.json 中的設定。 若要將其他參數傳遞給 Angular CLI 伺服器，請將它們新增至 package.json 檔案中相關的 scripts 行。

  2. 修改您的 ASP.NET Core 應用程式來使用外部的 Angular CLI 執行個體，而非自行啟動執行個體。 在 Startup 類別中，將 spa.UseAngularCliServer 引動過程取代為：

    spa.UseProxyToSpaDevelopmentServer("http://localhost:4200");

當您啟動 ASP.NET Core 應用程式時，它並不會啟動 Angular CLI 伺服器。 而是改為使用您手動啟動的執行個體。 這樣可以加快它的啟動和重新啟動速度。 它再也不必每次都得等候 Angular CLI 重建您的用戶端應用程式。

啟動 Proxy 後，就會從 .NET 所設定的環境變數 (ASPNETCORE_URLS 和 ASPNETCORE_HTTPS_PORTS) 推斷目標 URL 和連接埠。 若要設定 URL 或 HTTPS 連接埠，請使用其中一個環境變數或變更 proxy.conf.json 中的值。

將資料從.NET 程式碼傳遞至 TypeScript 程式碼

在 SSR 期間，您可能會想要將針對每個要求的資料從 ASP.NET Core 應用程式傳遞至 Angular 應用程式。 例如，您可以傳遞 cookie 資訊，或是從資料庫讀取的某些資料。 若要這樣做，請編輯您的 Startup 類別。 在 UseSpaPrerendering 的回呼中，請將 options.SupplyData 的值設定為下方所示的內容：

options.SupplyData = (context, data) =>
{
    // Creates a new value called isHttpsRequest that's passed to TypeScript code
    data["isHttpsRequest"] = context.Request.IsHttps;
};

SupplyData 回呼可讓您傳遞任意、針對每個要求、JSON 可序列化的資料 (例如，字串、布林值或數字)。 您的 main.server.ts 程式碼會以 params.data 的形式接收此資料。 例如，上述程式碼範例會將布林值以 params.data.isHttpsRequest 的形式傳遞至 createServerRenderer 回呼。 您可以透過 Angular 所支援的任何方式，將此傳遞至應用程式的其他部分。 例如，請查看 main.server.ts 如何將 BASE_URL 值傳遞至任何其建構函式已宣告要接收此值的元件。

SSR 的缺點

並非所有應用程式都能從 SSR 獲益。 主要優點為可感知的效能。 透過低速網路連線或低速行動裝置連線至您應用程式的訪客，將能很快地看到初始的 UI，即便需要花上一點時間來擷取或剖析 JavaScript 組合。 不過，很多 SPA 主要都是透過使用高速內部公司網路的高速電腦來使用，因此應用程式幾乎會立即出現。

同時，啟用 SSR 會有很多明顯的缺點。 它會增加開發程序的複雜性。 您的程式碼必須在兩個不同環境中執行：用戶端和伺服器端 (在一個從 ASP.NET Core 叫用的 Node.js 環境中)。 以下是需要考量的事項：

  • SSR 需要在您的實際執行伺服器上安裝 Node.js。 這針對某些部署案例 (例如 Azure App Service) 是會自動成立的，不過並不適用於其他如 Azure Service Fabric 的案例。
  • 啟用 BuildServerSideRenderer 組建旗標會使您的 node_modules 目錄進行發行。 此資料夾包含超過 20,000 個檔案，這將會增加部署時間。
  • 若要在 Node.js 環境中執行您的程式碼，它不能仰賴瀏覽器特定 JavaScript API (例如 window 或 localStorage) 的存在。 如果您的程式碼 (或是您參考的某些協力廠商程式庫) 嘗試使用這些 API，則會在 SSR 期間出現錯誤。 例如，不要使用 jQuery，因為它會在許多位置參考瀏覽器特定 API。 若要防止錯誤，您必須避免使用 SSR，或是避免使用瀏覽器特定 API 或程式庫。 您可以將針對這類 API 的呼叫包裝於檢查中，以確保它們不會在 SSR 期間被叫用。 例如，在 JavaScript 或 TypeScript 程式碼中使用類似下列的檢查：
if (typeof window !== 'undefined') {
    // Call browser-specific APIs here
}

設定 SignalR 的 Proxy 中介軟體

如需詳細資訊，請參閱 http-proxy-middleware。

其他資源