適用於 ASP.NET Core Blazor 的工具

  • 發行項

注意

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

重要

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

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

本文說明在各種平台上建置 Blazor 應用程式的工具。 在本文頂端選取您的平台。

若要在 Windows 上建立 Blazor 應用程式，請使用下列指引：

  • 安裝包含 ASP.NET 和 Web 開發工作負載的 Visual Studio 最新版本。

  • 使用其中一個可用的 Blazor 範本建立新專案：

    • Blazor Web 應用程式：建立支援互動式伺服器端轉譯 (互動式 SSR) 和用戶端轉譯 (CSR) 的 Blazor Web 應用程式。 建議使用 Blazor Web 應用程式範本來開始使用 Blazor，以了解伺服器端和用戶端的 Blazor 功能。
    • Blazor WebAssembly 獨立應用程式 ：建立可部署為靜態網站的獨立用戶端 Web 應用程式。

選取 [下一步] 。

  • 安裝包含 ASP.NET 和 Web 開發工作負載的 Visual Studio 最新版本。

  • 建立新的專案：

    • 若為 Blazor Server 體驗，請選擇 [Blazor Server 應用程式]範本，其中包含示範程式碼和啟動程序，或不含示範程式碼和啟動程序的 [ 應用程式空白]Blazor Server範本。 選取 [下一步] 。
    • 若為獨立 Blazor WebAssembly 體驗，請選擇 [Blazor WebAssembly 應用程式] 範本，其中包含示範程式碼和啟動程序，或不含示範程式碼和啟動程序的 [Blazor WebAssembly 應用程式空白]範本。 選取 [下一步] 。

  • 安裝包含 ASP.NET 和 Web 開發工作負載的 Visual Studio 最新版本。

  • 建立新的專案：

    • 若為 Blazor Server 體驗，請選擇 [Blazor Server 應用程式] 範本。 選取 [下一步] 。
    • 若為 Blazor WebAssembly 體驗，請選擇 [Blazor WebAssembly 應用程式] 範本。 選取 [下一步] 。
  • 提供 [專案名稱] 並確認 [位置] 正確。

注意

基本概念概觀文章的下列各節會介紹下列指導中使用的轉譯詞彙和概念：

ASP.NET Core Blazor 轉譯模式一文會提供關於轉譯模式的詳細指導。

  • 若為 Blazor Web 應用程式，請在 [其他資訊] 對話方塊中：

    • [互動式轉譯模式] 下拉式清單

      • [伺服器] 選項預設會啟用互動式伺服器端轉譯 (互動式 SSR)。
      • 若要只啟用用戶端轉譯 (CSR) 的互動功能，請選取 [WebAssembly] 選項。
      • 若要同時啟用這兩種互動式轉譯模式，以及在執行階段自動切換這兩個功能，請選取 [自動 (伺服器和 WebAssembly)] (自動) 轉譯模式選項。
      • 如果互動功能設定為 None，則產生的應用程式沒有互動功能。 應用程式只會設定為靜態伺服器端轉譯。

      當 .NET 應用程式套件組合和執行階段下載至瀏覽器時，[互動式自動轉譯] 模式一開始會使用互動式 SSR。 啟用 .NET WebAssembly 執行階段後，轉譯模式會切換至互動式 WebAssembly 轉譯。

      根據預設，Blazor Web 應用程式範本會使用單一專案來啟用靜態和互動式 SSR。 如果您也啟用 CSR，則專案會包含 WebAssembly 元件的額外用戶端專案 (.Client)。 用戶端專案的建置輸出會下載至瀏覽器，並在用戶端上執行。 任何使用 WebAssembly 或自動轉譯模式的元件都必須從用戶端專案進行建置。

      如需詳細資訊，請參閱 ASP.NET Core Blazor 轉譯模式。

    • [互動位置] 下拉式清單

      • 每個頁面/元件：預設會設定每個頁面或每個元件的互動功能。
      • 全域：選取此選項會設定整個應用程式的全域互動功能。

      只有在 [互動式轉譯模式] 不是 None 且未啟用驗證時，才能設定互動位置。

    • 若要根據啟動程序樣式包含範例頁面和配置，請選取 [包含範例頁面] 核取方塊。 請針對沒有範例頁面和啟動程序樣式的專案停用此選項。

    如需詳細資訊，請參閱 ASP.NET Core Blazor 轉譯模式。

  • 針對裝載的 Blazor WebAssembly 應用程式，請在 [其他資訊] 對話方塊中選取 [已裝載 ASP.NET Core] 核取方塊。

  • 選取建立。

  • 按 Ctrl+F5 (Windows) 或 ⌘+F5 (macOS) 以執行應用程式。

在 Visual Studio 中執行裝載的 Blazor WebAssembly方案時，方案的啟動專案就是 Server 專案。

如需信任 ASP.NET Core HTTPS 開發憑證的詳細資訊，請參閱在 ASP.NET Core 中強制執行 HTTPS。

重要

執行裝載的 Blazor WebAssembly 應用程式時，請從方案的 Server 專案執行應用程式。

啟動應用程式時，只會使用 Server 專案中的 Properties/launchSettings.json 檔案。

若要在 Linux 或 macOS 上建立 Blazor 應用程式，請遵照下列指引：

使用 .NET 命令列介面 (CLI) 在命令殼層中執行命令。

安裝 .NET Core SDK的最新版本。 如果您之前已安裝 SDK，您可以執行下列命令來判斷已安裝的版本：

dotnet --version

為您的平台安裝 Visual Studio Code 的最新版本。

安裝適用於 Visual Studio Code 的 C# 開發套件。 如需詳細資訊，請參閱偵錯 ASP.NET Core Blazor 應用程式。

建立新的專案：

  • 若為具有預設互動式伺服器端轉譯的 Blazor Web 應用程式體驗，請在使用 blazor 專案範本的命令殼層中執行下列命令：

    dotnet new blazor -o BlazorApp

    若要只啟用用戶端轉譯，請使用設定為 WebAssembly 的 -int|--interactivity 選項：

    dotnet new blazor -o BlazorApp -int WebAssembly

    若要啟用互動式伺服器端轉譯，後面接著用戶端轉譯，請使用設定為 Auto 的 -int|--interactivity 選項：

    dotnet new blazor -o BlazorApp -int Auto

    如果將 -int|--interactivity 選項設定為 None 來停用互動功能，則產生的應用程式不會有互動功能。 應用程式只會設定為靜態伺服器端轉譯：

    dotnet new blazor -o BlazorApp -int None

    當 .NET 應用程式套件組合和執行階段下載至瀏覽器時，[互動式自動轉譯] 模式一開始會使用互動式伺服器端轉譯 (互動式 SSR)。 啟用 .NET WebAssembly 執行階段後，轉譯模式會切換至互動式 WebAssembly 轉譯模式。

    根據預設，Blazor Web 應用程式範本會使用單一專案來啟用靜態和互動式伺服器端轉譯。 如果您也啟用互動式 WebAssembly 轉譯模式，則專案會包含 WebAssembly 元件的額外用戶端專案 (.Client)。 用戶端專案的建置輸出會下載至瀏覽器，並在用戶端上執行。 任何使用互動式 WebAssembly 或互動式自動轉譯模式的元件都必須從用戶端專案進行建置。

    如需詳細資訊，請參閱 ASP.NET Core Blazor 轉譯模式。

    應用程式會根據每個元件/頁面來預設互動位置。 若要在整個應用程式中建立互動功能，請使用 -ai|--all-interactive 選項：

    dotnet new blazor -o BlazorApp -ai

    選取此選項會為 App 元件中整個應用程式設定互動功能，方法是為最上層 HeadOutlet 和 Routes 元件指定轉譯模式。 在這些元件上設定互動功能，會將互動功能傳播至應用程式中的所有子元件。

    只有在互動式轉譯模式 (-int|--interactivity) 不是 None 且未啟用驗證時，才能設定互動位置。

    若要建立沒有範例頁面和樣式的應用程式，請使用 -e|--empty 選項：

    dotnet new blazor -o BlazorApp -e

  • 若為獨立 Blazor WebAssembly 體驗，請在使用 blazorwasm 範本的命令殼層中執行下列命令：

    dotnet new blazorwasm -o BlazorApp

    若要建立沒有範例頁面和樣式的獨立 Blazor WebAssembly 應用程式，請使用 -e|--empty 選項：

    dotnet new blazorwasm -o BlazorApp -e

建立新的專案：

  • 若為包含示範程式碼和啟動程序的 Blazor Server 體驗，請執行下列命令：

    dotnet new blazorserver -o BlazorApp

  • 或者，使用 blazorserver-empty 專案範本建立不含示範程式碼和啟動程序的 Blazor Server 應用程式：

    dotnet new blazorserver-empty -o BlazorApp

  • 若為包含示範程式碼和啟動程序的獨立 Blazor WebAssembly 體驗，請執行下列命令：

    dotnet new blazorwasm -o BlazorApp

  • 或者，使用 blazorwasm-empty 專案範本建立不含示範程式碼和啟動程序的獨立 Blazor WebAssembly 應用程式：

    dotnet new blazorwasm-empty -o BlazorApp

  • 若為包含示範程式碼和啟動程序的裝載 Blazor WebAssembly 體驗，請將裝載選項 (-ho/--hosted) 新增至命令：

    dotnet new blazorwasm -o BlazorApp -ho

  • 或者，使用具有裝載選項的 blazorwasm-empty 範本，建立不含示範程式碼和啟動程序的裝載 Blazor WebAssembly 應用程式：

    dotnet new blazorwasm-empty -o BlazorApp -ho

建立新的專案：

  • 若為 Blazor WebAssembly 體驗，請執行下列命令：

    dotnet new blazorwasm -o BlazorApp

  • 若為裝載的 Blazor WebAssembly 體驗，請將裝載選項 (-ho 或 --hosted) 選項新增至命令：

    dotnet new blazorwasm -o BlazorApp -ho

  • 若為 Blazor Server 體驗，請執行下列命令：

    dotnet new blazorserver -o BlazorApp

在 Visual Studio Code 中開啟 BlazorApp 資料夾。

當 Visual Studio Code 要求您新增資產以建置和偵錯專案時，請選取 [是]。

如果 Visual Studio Code 未自動提供新增建置和偵錯資產 (包含 launch.json 和 tasks.json 檔案的 .vscode 資料夾)，請選取 [檢視]>[命令選擇區]，然後在搜尋方塊中輸入 ".NET"。 從命令清單中選取 ".NET: Generate Assets for Build and Debug" 命令。

注意

如需 Visual Studio Code 設定和使用的詳細資訊，請參閱 Visual Studio Code 文件。

專案的 Properties/launchSettings.json 檔案在檔案 profiles 區段中會包含任何設定檔的偵錯 Proxy 的 inspectUri 屬性：

"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",

裝載的 Blazor WebAssembly 啟動和工作設定

針對裝載的 Blazor WebAssembly方案，將具有 launch.json 和 tasks.json 檔案的 .vscode 資料夾新增至方案的父資料夾，也就是包含一般專案資料夾的資料夾：Client、Server 和 Shared。 更新或確認 launch.json 和 tasks.json 檔案中的設定會從 Server 專案執行裝載的 Blazor WebAssembly 應用程式。

重要

執行裝載的 Blazor WebAssembly 應用程式時，請從方案的 Server 專案執行應用程式。

啟動應用程式時，只會使用 Server 專案中的 Properties/launchSettings.json 檔案。

檢查 Properties/launchSettings.json 檔案，並從 applicationUrl 屬性判斷應用程式的URL。 根據架構版本，URL 通訊協定會是安全 (HTTPS) https://localhost:{PORT} 或不安全的 (HTTP) http://localhost:{PORT}，其中 {PORT} 預留位置是指派的連接埠。 記下 launch.json 檔案中使用的URL。

在 .vscode/launch.json 檔案的啟動設定中：

  • 將目前的工作目錄 (cwd) 設定為 Server 專案資料夾。
  • 使用 url 屬性指出應用程式的 URL。 使用稍早從 Properties/launchSettings.json 檔案記錄的值。
"cwd": "${workspaceFolder}/{SERVER APP FOLDER}",
"url": "{URL}"

在上述設定中：

  • {SERVER APP FOLDER} 預留位置是 Server 專案的資料夾，通常是 Server。
  • {URL} 預留位置是應用程式的 URL，該 URL 是在 applicationUrl 屬性中，應用程式的 Properties/launchSettings.json 檔案中指定。

如果 Google Chrome 優先於 Microsoft Edge，請將 "browser": "chrome" 的其他屬性更新或新增至設定。

在下列範例 .vscode/launch.json 檔案中：

  • 將目前的工作目錄設定為 Server 資料夾。
  • 將應用程式的 URL 設定為 http://localhost:7268。
  • 將預設瀏覽器從 Microsoft Edge 變更為 Google Chrome。
"cwd": "${workspaceFolder}/Server",
"url": "http://localhost:7268",
"browser": "chrome"

完整的 .vscode/launch.json 檔案：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "blazorwasm",
      "name": "Launch and Debug Blazor WebAssembly Application",
      "request": "launch",
      "cwd": "${workspaceFolder}/Server",
      "url": "http://localhost:7268",
      "browser": "chrome"
    }
  ]
}

在 .vscode/tasks.json 中，新增 build 引數以指定 Server 應用程式專案檔的路徑：

"${workspaceFolder}/{SERVER APP FOLDER}/{PROJECT NAME}.csproj",

在上述引數中：

  • {SERVER APP FOLDER} 預留位置是 Server 專案的資料夾，通常是 Server。
  • {PROJECT NAME} 預留位置是應用程式的名稱，通常根據從 Blazor WebAssembly 專案範本產生的應用程式，後面會緊接 .Server 的方案名稱。

範例 .vscode/tasks.json 檔案，在方案的 Server 資料夾中，具有名為 BlazorHosted 的 Server 專案。

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "command": "dotnet",
      "type": "process",
        "args": [
          "build",
          "${workspaceFolder}/Server/BlazorHosted.Server.csproj",
          "/property:GenerateFullPaths=true",
          "/consoleloggerparameters:NoSummary",
        ],
        "group": "build",
        "presentation": {
          "reveal": "silent"
        },
        "problemMatcher": "$msCompile"
    }
  ]
}

按 Ctrl+F5 (Windows) 或 ⌘+F5 (macOS) 以執行應用程式。

注意

目前僅支援瀏覽器偵錯。

您無法在偵錯期間自動重建裝載的 Blazor WebAssembly 方案的後端 Server 應用程式，例如使用 dotnet watch run 執行應用程式。

.vscode/launch.json (launch 設定)：:

...
"cwd": "${workspaceFolder}/{SERVER APP FOLDER}",
...

在目前工作目錄 (cwd) 的上述設定，{SERVER APP FOLDER} 預留位置是 Server 專案的資料夾，通常是 "Server"。

如果使用 Microsoft Edge，且未在系統上安裝 Google Chrome，請將 "browser": "edge" 的其他屬性新增至設定。

Server 的專案資料夾範例會繁衍 Microsoft Edge 做為偵錯執行的瀏覽器，而不是預設瀏覽器 Google Chrome：

...
"cwd": "${workspaceFolder}/Server",
"browser": "edge"
...

.vscode/tasks.json (dotnet 命令 引數)：

...
"${workspaceFolder}/{SERVER APP FOLDER}/{PROJECT NAME}.csproj",
...

在上述引數中：

  • {SERVER APP FOLDER} 預留位置是 Server 專案的資料夾，通常是 "Server"。
  • {PROJECT NAME} 預留位置是應用程式的名稱，通常根據從 Blazor 專案範本產生的應用程式，後面會緊接 ".Server" 的方案名稱。

下列使用 SignalR 搭配 Blazor WebAssembly 應用程式的教學課程範例會使用 Server 的專案資料夾名稱和 BlazorWebAssemblySignalRApp.Server 的專案名稱：

...
"args": [
  "build",
    "${workspaceFolder}/Server/BlazorWebAssemblySignalRApp.Server.csproj",
    ...
],
...

按 Ctrl+F5 (Windows) 或 ⌘+F5 (macOS) 以執行應用程式。

信任開發憑證

如需詳細資訊，請參閱在 ASP.NET Core 中強制執行 HTTPS。

Visual Studio 方案檔 (.sln)

方案是指能將一或多個相關程式碼專案組織在一起的容器。 Visual Studio 會使用方案檔 (.sln) 來儲存方案的設定。 方案檔會使用唯一的格式，且不能直接編輯。

Visual Studio 外部的工具可以與方案檔互動：

  • .NET CLI 可以透過 dotnet sln 命令建立方案檔，並列出/修改方案檔中的專案。 其他 .NET CLI 命令會針對各種發佈、測試和封裝命令使用方案檔的路徑。
  • Visual Studio Code 可以透過整合式終端執行 dotnet sln 命令和其他 .NET CLI 命令，但不會直接使用方案檔中的設定。

在整個 Blazor 文件中，會使用方案來描述在啟用 [裝載的 ASP.NET Core] 選項的情況下從 Blazor WebAssembly 專案範本，或從 Blazor Hybrid 專案範本建立的應用程式。 從這些專案範本產生的應用程式預設會包含方案檔 (.sln)。 對於裝載的 Blazor WebAssembly 應用程式 (開發人員在其中未使用 Visual Studio)，如果方案檔未搭配 .NET CLI 命令使用，則可以忽略或刪除方案檔。

如需詳細資訊，請參閱 Visual Studio 文件中的下列資源：

使用 Visual Studio Code 進行跨平台 Blazor 開發

Visual Studio Code 是一種開放原始碼跨平台整合式開發環境 (IDE)，可用來開發 Blazor 應用程式。 使用 .NET CLI 建立新的 Blazor 應用程式，以使用 Visual Studio Code 進行開發。 如需詳細資訊，請參閱本文的 Linux/macOS 版本。

如需 Visual Studio Code 設定和使用的詳細資訊，請參閱 Visual Studio Code 文件。

Blazor 範本選項

Blazor 架構提供用來建立新應用程式的範本。 範本可用來建立新的 Blazor 專案和方案，不論您選用於 Blazor 開發的工具為何 (Visual Studio、Visual Studio Code 或 .NET 命令列介面 (CLI))：

  • Blazor Web 應用程式專案範本：blazor
  • Blazor WebAssembly 獨立應用程式專案範本：blazorwasm
  • Blazor Server 專案範本：blazorserver、blazorserver-empty
  • Blazor WebAssembly 專案範本：blazorwasm、blazorwasm-empty
  • Blazor Server 專案範本：blazorserver
  • Blazor WebAssembly 專案範本：blazorwasm

如需 Blazor 專案範本的詳細資訊，請參閱 ASP.NET Core Blazor 專案結構。

如需範本選項的詳細資訊，請參閱下列資源：

  • .NET Core 文件中的「dotnet new 的 .NET 預設範本」文章：
  • 在命令殼層中將說明選項 (-h 或 --help) 傳遞至 dotnet new CLI 命令：
    • dotnet new blazor -h
    • dotnet new blazorwasm -h
  • .NET Core 文件中的「dotnet new 的 .NET 預設範本」文章：
  • 在命令殼層中將說明選項 (-h 或 --help) 傳遞至 dotnet new CLI 命令：
    • dotnet new blazorserver -h
    • dotnet new blazorserver-empty -h
    • dotnet new blazorwasm -h
    • dotnet new blazorwasm-empty -h
  • .NET Core 文件中的「dotnet new 的 .NET 預設範本」文章：
  • 在命令殼層中將說明選項 (-h 或 --help) 傳遞至 dotnet new CLI 命令：
    • dotnet new blazorserver -h
    • dotnet new blazorwasm -h

其他資源