適用於 ASP.NET Core Blazor 的工具

發行項
11/06/2024

注意

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

警告

不再支援此版本的 ASP.NET Core。如需詳細資訊，請參閱 .NET 和 .NET Core 支援原則。如需目前版本，請參閱本文的 .NET 8 版本。

重要

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

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

本文描述可使用數個工具建置 Blazor 應用程式的工具：

Visual Studio (VS)：Windows 上適用於 .NET 開發人員的最全面整合式開發環境 (IDE)。包含一系列工具和功能，以提升並增强軟體開發的每個階段。
Visual Studio Code (VS Code) 是可用來開發 Blazor 應用程式的開放原始碼、跨平台程式碼編輯器。
.NET CLI：.NET 命令列介面 (CLI) 是用於開發、建立、執行和發佈 .NET 應用程式的跨平台工具鏈。 .NET CLI 隨附於 .NET SDK，並在 SDK 支援的任何平台上執行。

選取本文中符合您工具選擇的關鍵內容。

若要使用 Visual Studio 建立 Blazor 應用程式，請遵照下列指引：

安裝包含 ASP.NET 和 Web 開發工作負載的 Visual Studio 最新版本。
使用其中一個可用的 Blazor 範本建立新專案：
- Blazor Web App：建立支援互動式伺服器端轉譯 (互動式 SSR) 和用戶端轉譯 (CSR) 的 Blazor Web 應用程式。建議使用 Blazor Web App 範本來開始使用 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 應用程式] 範本。選取 [下一步] 。

提供 [專案名稱] 並確認 [位置] 正確。
如需 [其他資訊] 對話方塊中選項的詳細資訊，請參閱 Blazor 專案範本和範本選項一節。

注意

ASP.NET Core 8.0 或更新版本不再提供託管的 Blazor WebAssembly 的專案範本。若要建立託管的 Blazor WebAssembly 應用程式，ASP.NET Core 託管的複選框必須選取早於 .NET 8.0 版本的 Framework 選項。

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

選取建立。

Visual Studio Code 是一種開放原始碼跨平台整合式開發環境 (IDE)，可用來開發 Blazor 應用程式。

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

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

如果您不熟悉 VS Code，請參閱 VS Code 文件。如果您不熟悉 .NET SDK，請參閱什麼是 .NET SDK？，以及 .NET SDK 文件中相關聯的文章。

建立新的專案：

開啟 VS Code。
移至 [總管] 檢視，然後選取 [建立 .NET 專案] 按鈕。或者，您可以使用 Ctrl+Shift+P，啟動 [命令選擇區]，接著輸入 ".NET"，然後尋找並選取 [NET: 新增專案] 命令。
從清單中選取 Blazor 專案範本。
在 [專案位置] 對話方塊中，建立或選取專案的資料夾。
在 [命令選擇區] 中，提供專案的名稱或接受預設名稱。
選取 [建立專案] 以建立專案，或選取 [顯示所有範本選項] 來調整專案的選項。如需範本和選項的詳細資訊，請參閱 Blazor 專案範本和範本選項一節。
在鍵盤上按 F5，搭配偵錯工具執行應用程式，或按 Ctrl+F5，不搭配偵錯工具執行應用程式。

[命令選擇區] 會要求您選取偵錯工具。從清單中選取 C#。

接下來，選取 https 以啟動設定。
若要停止應用程式，請在鍵盤上按 Shift+F5。

在 Blazor 文件的某些部分中，用於 ASP.NET Core 開發的 Visual Studio Code (VS Code) 指示會使用 .NET CLI，這是 .NET SDK 的一部分。 .NET CLI 命令是在 VS Code 的整合式終端機中發出的，預設為 PowerShell 命令殼層。從功能表列中的 [終端機] 功能表選取 [新增終端機]，即可開啟 [終端機]。

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

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

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

檢查 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"
    }
  ]
}

注意

目前僅支援瀏覽器偵錯。

您無法在偵錯期間自動重建裝載的 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",
    ...
],
...

.NET SDK 是一組程式庫和工具，可讓開發人員用來建立 .NET 應用程式和程式庫。

安裝 .NET SDK。命令是在命令殼層中使用 .NET CLI 發出的。

如果您先前已安裝一或多個 .NET SDK，並且想要查看您的作用中版本，請在命令殼層中執行下列命令：

dotnet --version

如果您不熟悉 .NET SDK，請參閱什麼是 .NET SDK？，以及 .NET SDK 文件中相關聯的文章。

建立新的專案：

使用 cd 命令變更至您要在其中建立專案資料夾的目錄 (例如，cd c:/users/Bernie_Kopell/Documents)。
若為具有預設互動式伺服器端轉譯 (互動式 SSR) 的 Blazor Web App 體驗，請執行下列命令：
```
dotnet new blazor -o BlazorApp
```
若為獨立 Blazor WebAssembly 體驗，請在使用 blazorwasm 範本的命令殼層中執行下列命令：
```
dotnet new blazorwasm -o BlazorApp
```

建立新的專案：

使用 cd 命令變更至您要在其中建立專案資料夾的目錄 (例如，cd c:/users/Bernie_Kopell/Documents)。
若為包含示範程式碼和啟動程序的 Blazor Server 體驗，請執行下列命令：
```
dotnet new blazorserver -o BlazorApp
```
若為包含示範程式碼和啟動程序的獨立 Blazor WebAssembly 體驗，請執行下列命令：
```
dotnet new blazorwasm -o BlazorApp
```
若為包含示範程式碼和啟動程序的裝載 Blazor WebAssembly 體驗，請將裝載選項 (-ho/--hosted) 新增至命令：
```
dotnet new blazorwasm -o BlazorApp -ho
```
注意

ASP.NET Core 8.0 或更新版本不再提供託管的 Blazor WebAssembly 的專案範本。若要使用 .NET 8.0 或更新版本的 SDK 建立託管的 Blazor WebAssembly 應用程式，請使用 7.0 目標架構傳遞 -f|--framework 選項（net7.0）：
```
dotnet new blazorwasm -o BlazorApp -ho -f net7.0
```

建立新的專案：

使用 cd 命令變更至您要在其中建立專案資料夾的目錄 (例如，cd c:/users/Bernie_Kopell/Documents)。
若為 Blazor WebAssembly 體驗，請執行下列命令：
```
dotnet new blazorwasm -o BlazorApp
```
若為裝載的 Blazor WebAssembly 體驗，請將裝載選項 (-ho 或 --hosted) 選項新增至命令：
```
dotnet new blazorwasm -o BlazorApp -ho
```
注意

ASP.NET Core 8.0 或更新版本不再提供託管的 Blazor WebAssembly 的專案範本。若要使用 .NET 8.0 或更新版本 SDK 建立託管的 Blazor WebAssembly 應用程式，請使用目標 Framework Moniker 傳遞 -f|--framework 選項（例如 net6.0）：
```
dotnet new blazorwasm -o BlazorApp -ho -f net6.0
```
若為 Blazor Server 體驗，請執行下列命令：
```
dotnet new blazorserver -o BlazorApp
```

如需範本和選項的詳細資訊，請參閱 Blazor 專案範本和範本選項一節。

執行應用程式

重要

執行 Blazor Web App時，請從解決方案的伺服器專案執行應用程式，該專案是名稱不是以 .Client結尾的專案。

重要

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

在鍵盤上按 Ctrl+F5，不搭配偵錯工具執行應用程式。

當專案未設定為使用 SSL 時，Visual Studio 會顯示下列對話方塊：

信任自我簽署憑證對話方塊

如果您信任 ASP.NET Core SSL 憑證，請選取 [是]。

此時會顯示下列對話方塊：

安全性警告對話方塊

選取 [是] 以確認風險並安裝憑證。

Visual Studio：

編譯並執行應用程式。
在 https://localhost:{PORT} 啟動預設瀏覽器，這會顯示應用程式的 UI。 {PORT} 預留位置是在建立應用程式時指派的隨機連接埠。如果由於本機連接埠衝突而需要變更連接埠，請變更專案 Properties/launchSettings.json 檔案中的連接埠。

在 VS Code 中，按 Ctrl+F5 (Windows) 或 ⌘+F5 (macOS)，以執行應用程式而不進行偵錯。

在 VS Code UI 頂端 [命令選擇區] 的 [選取偵錯工具] 提示中，選取 C#。在下一個提示中，選取 HTTPS 設定檔 ([https])。

預設瀏覽器是在 https://localhost:{PORT} 啟動，這會顯示應用程式的 UI。 {PORT} 預留位置是在建立應用程式時指派的隨機連接埠。如果由於本機連接埠衝突而需要變更連接埠，請變更專案 Properties/launchSettings.json 檔案中的連接埠。

在開啟至專案根資料夾的命令殼層中，執行 dotnet watch 命令以編譯並啟動應用程式：

dotnet watch

從 Blazor Web App 專案範本建立的應用程式使用 .NET CLI 執行時，應用程式會在 HTTP (不安全) 端點執行，因為在應用程式啟動設定檔案 (Properties/launchSettings.json) 中找到的第一個設定檔是名為 http的 HTTP (不安全) 設定檔。 HTTP 設定檔放在第一個位置，以方便非 Windows 用戶採用 SSL/HTTPS 安全性的轉換。

搭配 SSL/HTTPS 執行應用程式的一種方法是將具有 https 設定檔名稱的 -lp|--launch-profile 選項傳遞至 dotnet watch 命令：

dotnet watch -lp https

替代方法是將 https 設定檔移至 Properties/launchSettings.json 檔案中 http 設定檔的上方，並儲存變更。在變更檔案中的設定檔順序之後，dotnet watch 命令預設一律使用 https 設定檔。

停止應用程式

請使用下列其中一個方法停止應用程式：

關閉瀏覽器視窗。
在 Visual Studio 中：
- 使用 Visual Studio 功能表列中的 [停止] 按鈕：
- 在鍵盤上按 Shift+F5。

請使用下列方法停止應用程式：

關閉瀏覽器視窗。
在 VS Code 中：
- 從 [執行] 功能表中，選取 [停止偵錯]。
- 在鍵盤上按 Shift+F5。

請使用下列方法停止應用程式：

關閉瀏覽器視窗。
在命令殼層中，按 Ctrl+C (Windows) 或按 ⌘+C (macOS)。

Visual Studio 方案檔 (`.sln`)

方案是指能將一或多個相關程式碼專案組織在一起的容器。方案檔會使用唯一的格式，且不能直接編輯。

Visual Studio 和 Visual Studio Code (VS Code) 會使用解決方案檔案 (.sln) 來儲存解決方案的設定。 .NET CLI 不會使用解決方案檔案組織專案，但可以透過 dotnet sln 命令建立解決方案檔案，以及列出/修改解決方案檔案中的專案。其他 .NET CLI 命令會針對各種發佈、測試和封裝命令使用方案檔的路徑。

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

如需詳細資訊，請參閱以下資源：

Blazor 專案範本和範本選項

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

Blazor Web App 專案範本：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 專案結構。

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

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

互動式轉譯模式

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

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

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

重要

當使用 Blazor Web App時，大部分 Blazor 文件範例元件需要互動功能，才能運作，還會示範文章裡頭涵蓋的概念。當您測試文章所提供的範例元件時，請確定應用程式採用全域互動，或元件採用互動式轉譯模式。

互動性位置

互動性位置選項：

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

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

範例頁面

若要包含範例頁面和基於啟動程序樣式的配置，請使用 [包含範例頁面] 選項。請針對沒有範例頁面和啟動程序樣式的專案停用此選項。

有關範本選項的其他指引

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

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

.NET Core 文件中的「dotnet new 的 .NET 預設範本」文章：
- blazorserver (包括 blazorserver-empty 選項)
- blazorwasm (包括 blazorwasm-empty 選項)
在命令殼層中將說明選項 (-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 預設範本」文章：
- blazorserver
- blazorwasm
在命令殼層中將說明選項 (-h 或 --help) 傳遞至 dotnet new CLI 命令：
- dotnet new blazorserver -h
- dotnet new blazorwasm -h

共用方式為

適用於 ASP.NET Core Blazor 的工具

執行應用程式

停止應用程式

Visual Studio 方案檔 (`.sln`)

Blazor 專案範本和範本選項

互動式轉譯模式

互動性位置

範例頁面

有關範本選項的其他指引

其他資源

其他資源

共用方式為

適用於 ASP.NET Core Blazor 的工具

執行應用程式

停止應用程式

Visual Studio 方案檔 (.sln)

Blazor 專案範本和範本選項

互動式轉譯模式

互動性位置

範例頁面

有關範本選項的其他指引

其他資源

其他資源

Visual Studio 方案檔 (`.sln`)