ASP.NET Core Blazor 漸進式 Web 應用程式 (PWA)

Blazor 漸進式 Web 應用程式 (PWA) 是單頁應用程式 (SPA)，其使用新式瀏覽器 API 和功能，以如同傳統型應用程式一樣運作。

Blazor WebAssembly 是標準型用戶端 Web 應用程式平台，因此可以使用任何瀏覽器 API，包括下列功能所需的 PWA API：

• 離線工作並立即載入，與網路速度無關。
• 在自己的應用程式視窗中執行，而不只是瀏覽器視窗。
• 從主機的操作系統的開始選單、Dock 或主畫面自啟動。
• 即使使用者未使用應用程式，仍從後端伺服器接收推播通知。
• 在背景中自動更新。

漸進一字是用來描述這些應用程式，因為：

• 使用者可能會先探索並使用其網頁瀏覽器中的應用程式，就像任何其他 SPA 一樣。
• 稍後，使用者會繼續在其 OS 中加以安裝，並啟用推播通知。

從 PWA 範本建立專案

Visual Studio

建立新的 Blazor WebAssembly 應用程式時，請選取 [漸進式 Web 應用程式] 核取方塊。

Visual Studio Code / .NET CLI

使用下列命令，利用 --pwa 開關在命令列中建立 PWA 專案：

dotnet new blazorwasm -o MyBlazorPwa --pwa

在上述命令中，-o|--output 選項會為名為 MyBlazorPwa 的應用程式建立新資料夾。

將現有的 Blazor WebAssembly 應用程式轉換成 PWA

遵循本節中的指引，將現有的 Blazor WebAssembly 應用程式轉換成 PWA。

在應用程式的專案檔中：

• 將下列 ServiceWorkerAssetsManifest 屬性新增至 PropertyGroup：

    ...
    <ServiceWorkerAssetsManifest>service-worker-assets.js</ServiceWorkerAssetsManifest>
  </PropertyGroup>
  

• 將下列 ServiceWorker 項目新增至 ItemGroup：

  <ItemGroup>
    <ServiceWorker Include="wwwroot\service-worker.js" 
      PublishedContent="wwwroot\service-worker.published.js" />
  </ItemGroup>
  

若要取得靜態資產，請使用下列其中一種方法：

• 在命令殼層中使用 dotnet new 命令來建立個別的新 PWA 專案：

  dotnet new blazorwasm -o MyBlazorPwa --pwa
  

  在上述命令中，-o|--output 選項會為名為 MyBlazorPwa 的應用程式建立新資料夾。

  如果您未轉換最新版本的應用程式，請傳遞 -f|--framework 選項。 下列範例會建立 .NET 5 的應用程式：

  dotnet new blazorwasm -o MyBlazorPwa --pwa -f net5.0
  

• 導覽至位於下列 URL 的 ASP.NET Core GitHub 存放庫，其連結至 main 分支參考來源和資產。 從適用於您的應用程式的 [切換分支或標籤] 下拉式清單中，選取您正在使用的版本。

  Blazor WebAssembly 專案範本 wwwroot 資料夾 (dotnet/aspnetcore GitHub 存放庫 main 分支)

  注意

  .NET 參考原始碼的文件連結通常會載入存放庫的預設分支，該分支代表著即將發佈的下一版 .NET 的目前開發階段。 若要選取特定版本的標籤，請使用下拉式清單中的 [切換分支或標籤]。 如需詳細資訊，請參閱如何選取 ASP.NET Core 原始程式碼 (dotnet/AspNetCore.Docs #26205) 的版本標籤。

  從您所建立的應用程式中，或從 wwwroot GitHub 存放庫中參考資產的來源 dotnet/aspnetcore 資料夾，將下列檔案複製到應用程式的 wwwroot 資料夾中：

  • icon-192.png
  • icon-512.png
  • manifest.webmanifest
  • service-worker.js
  • service-worker.published.js

在應用程式的 wwwroot/index.html 檔案中：

• 新增資訊清單和應用程式圖示的 <link> 元素：

  <link href="manifest.webmanifest" rel="manifest" />
  <link rel="apple-touch-icon" sizes="512x512" href="icon-512.png" />
  <link rel="apple-touch-icon" sizes="192x192" href="icon-192.png" />
  

• 在 <script> 結尾標籤內，緊接於 </body> 指令碼標籤後，新增下列 blazor.webassembly.js 標籤：

      ...
      <script>navigator.serviceWorker.register('service-worker.js');</script>
  </body>
  

安裝和應用程式資訊清單

流覽使用 PWA 範本建立的應用程式時，使用者可以選擇將應用程式安裝到其 OS 的 [開始] 選單、停駐或主畫面。 這個選項呈現的方式取決於使用者的瀏覽器。 使用桌面 Chromium 型瀏覽器 (例如 Edge 或 Chrome) 時，URL 列中會出現 [新增] 按鈕。 使用者選取 [新增] 按鈕之後，他們會收到確認對話方塊：

在 iOS 上，訪客可以使用 Safari 的 共用 按鈕及其 新增至主螢幕 選項來安裝 PWA。 在 Android 版的 Chrome 上，使用者應該選取右上角的 [功能表] 按鈕，後面接著 [新增至 Home畫面]。

安裝之後，應用程式會出現在自己的視窗中，但沒有網址列：

若要自訂視窗的標題、色彩配置、圖示或其他詳細資料，請參閱專案 manifest.json 目錄中的 wwwroot 檔案。 此檔案的結構描述是由 Web 標準所定義。 如需詳細資訊，請參閱 MDN Web 文件：Web 應用程式資訊清單。

離線支援

使用 PWA 範本選項建立的應用程式支援離線執行。 使用者在線上時必須先瀏覽應用程式。 瀏覽器會自動下載並快取離線操作所需的所有資源。

重要

開發支援會干擾進行變更及測試變更的一般開發週期。 因此，僅針對已發佈的應用程式啟用離線支援。

警告

如果您想要散發支援離線功能的 PWA，有數個重要的警告与提示。 這些是離線 PWA 的固有案例，而不是專屬於 Blazor。 請務必在假設您的離線應用程式如何運作之前，先閱讀並了解這些注意事項。

若要查看離線支援的運作方式：

1. 發行應用程式。 如需詳細資訊，請參閱裝載和部署 ASP.NET Core Blazor。

2. 將應用程式部署至支援 HTTPS 的伺服器，並在瀏覽器中存取其安全 HTTPS 位址的應用程式。

3. 開啟瀏覽器的開發者工具，並在「應用程式」標籤下確認已為主機註冊「Service Worker」。

   

4. 重新載入頁面並檢查 [網路] 索引標籤。[服務工作者] 或 [記憶體快取] 會作為所有頁面資產的來源：

   

5. 若要確認瀏覽器與載入應用程式的網路存取無關，請執行下列其中一項動作：

   • 關閉網頁伺服器，並查看應用程式如何持續正常運作，其中包括重載頁面。 同樣地，當網路連線緩慢時，應用程式會繼續正常運作。
   • 指示瀏覽器在 [網路] 索引標籤中模擬離線模式：

   

使用 Service Worker 的離線支援是 Web 標準，而不是專屬於 Blazor。 如需服務工作者的詳細資訊，請參閱 MDN Web 文件：Service Worker API。 若要深入了解服務背景工作角色的常見使用模式，請參閱 Google Web：服務背景工作角色生命週期。

Blazor 的 PWA 範本會產生兩個服務工作者檔案：

• wwwroot/service-worker.js，用於開發過程中。
• wwwroot/service-worker.published.js，會在發佈應用程式之後使用。

若要在兩個服務工作者檔案之間共用邏輯程式碼，請考慮下列方法：

• 新增第三個 JavaScript 檔案來保存一般邏輯。
• 使用 self.importScripts 將一般邏輯載入兩個服務工作者檔案中。

快取優先擷取策略

內建 service-worker.published.js 服務工作者會使用快取優先策略來解析要求。 這表示服務工作者傾向傳回快取的內容，不管使用者是否具有網路存取權或伺服器上是否有較新的內容。

快取優先策略頗具價值，因為：

• 其可確保可靠性。 網路存取不是布林狀態。 使用者不只是線上或離線：

  • 使用者的裝置可能會假設其已上線，但網路可能太慢，等待下去行不通。
  • 網路可能會傳回特定 URL 的無效結果，例如當有目前封鎖或重新導向特定要求的 CAPTIVE WIFI 入口網站時。

  這就是為什麼瀏覽器的 navigator.onLine API 不可靠，且不應該依賴。

• 其可確保正確性。 建置離線資源的暫存時，服務工作器會使用內容雜湊來確保其在單一時間點擷取完整且自我一致的資源快照。 接著，此快取會被用作原子單位。 要求網路取得較新的資源並沒有意義，因為唯一需要的版本是已快取的版本。 任何其他項目都可能造成不一致和不相容的風險 (例如，嘗試使用未一起編譯的 .NET 組件版本)。

如果您必須防止瀏覽器從其 HTTP 快取中擷取 service-worker-assets.js，例如，若要在部署新版本的服務背景工作角色時解決暫時完整性檢查失敗，請更新 wwwroot/index.html 中的服務背景工作角色註冊，並將 updateViaCache 設定為 'none'：

<script>
  navigator.serviceWorker.register('/service-worker.js', {updateViaCache: 'none'});
</script>

背景更新

作為一種心理模型，您可以將離線優先的 PWA 視為一個可以安裝的行動應用程式。 不論網路連線狀態如何，應用程式都會立即啟動，但已安裝的程式邏輯來自特定時間點的快照，可能不是最新版本。

Blazor PWA 範本會產生應用程式，每當使用者造訪並聯網時，應用程式就會自動嘗試在背景進行更新。 其運作方式如下：

• 在編譯期間，專案會產生一個名為 的service-worker-assets.js。 資訊清單會列出應用程式離線運作所需的所有靜態資源，例如 .NET 組件、JavaScript 檔案和 CSS，包括其內容雜湊。 資源清單會由服務工作者載入，以便了解需要快取哪些資源。
• 每次使用者瀏覽應用程式時，瀏覽器會在背景中重新要求 service-worker.js 和 service-worker-assets.js。 檔案會與現有的已安裝服務工作者逐位元組比較。 如果伺服器對這些檔案中的任一個傳回變更內容，Service Worker 會嘗試安裝其自身的新版本。
• 在安裝自己新版本時，Service Worker 會為離線資源建立一個新的獨立快取，並開始將 service-worker-assets.js 中列出資源填入該快取。 此邏輯會在 onInstall 內的 service-worker.published.js 函式中進行實作。
• 當載入所有資源而未發生任何錯誤，且所有內容雜湊相符時，處理序就會順利完成。 如果成功，新的服務工作者就會進入等候啟用狀態。 一旦使用者關閉應用程式（沒有剩餘的應用程式索引標籤或視窗），新的服務工作程序就會變成作用中，並用於後續的應用程式使用。 刪除舊的服務工作者及其快取。
• 如果處理程序未順利完成，則會丟棄新的服務工作人員實例。 當使用者下次造訪時，希望用戶端有更好的網路連線來完成請求，屆時將會再次嘗試更新過程。

透過編輯服務工作者的邏輯來自訂此過程。 上述行為都不是 Blazor 特定的，而只是 PWA 範本選項所提供的預設體驗。 如需詳細資訊，請參閱 MDN 網頁文件：Service Worker API。

如何處理請求

如快取優先擷取策略一節所述，預設服務背景工作角色會使用快取優先策略，這表示其會在可用時嘗試提供快取的內容。 如果某個 URL 沒有快取的內容，例如從後端 API 請求資料時，服務工作器會退回到一般的網路請求模式。 如果伺服器可連線，網路要求就會成功。 此邏輯會在 onFetch 內的 service-worker.published.js 函式內實作。

如果應用程式的 Razor 元件仰賴從後端 API 要求資料，而您希望在因網路不可用而導致的請求失敗時提供良好的使用者體驗，請在這些元件中實施相關邏輯。 例如，使用 try/catch 將 HttpClient 要求包圍起來。

支援伺服器轉譯的頁面

請考慮當使用者第一次瀏覽至 URL 時會發生什麼事，例如 /counter，或應用程式中的任何其他深層連結。 在這些情況下，您不需要傳回快取為 /counter 的內容，而是需要瀏覽器載入快取為 /index.html 的內容，以啟動您的 Blazor WebAssembly 應用程式。 這些初始要求稱為瀏覽要求，而不是：

• 圖片、樣式表或其他檔案的 subresource 要求。
• fetch/XHR 要求 API 資料。

預設服務背景工作角色包含瀏覽要求的特殊案例邏輯。 不論請求的 URL 為何，服務工作者都會傳回 /index.html 的快取內容來解析請求。 此邏輯會在 onFetch 內的 service-worker.published.js 函式中進行實作。

如果您的應用程式有某些 URL 必須傳回伺服器轉譯的 HTML，而不是從快取提供 /index.html ，則您必須編輯服務背景工作角色中的邏輯。 如果包含 /Identity/ 的所有 URL 都必須當作對伺服器的一般線上唯一要求來處理，請修改 service-worker.published.jsonFetch 邏輯。 尋找下列程式碼：

const shouldServeIndexHtml = event.request.mode === 'navigate';

將程式碼變更為下列項目：

const shouldServeIndexHtml = event.request.mode === 'navigate'
  && !event.request.url.includes('/Identity/');

如果您未這麼做，則不論網路連線狀態為何，服務工作者都會攔截這類 URL 的請求，並使用 /index.html 加以解析。

將外部驗證提供者的額外端點新增到檢查中。 在下列範例中，將用於 Google 認證的 /signin-google 新增至檢查中：

const shouldServeIndexHtml = event.request.mode === 'navigate'
  && !event.request.url.includes('/Identity/')
  && !event.request.url.includes('/signin-google');

Development 環境不需要採取任何動作，其一律會從網路擷取內容。

控制資產快取

如果您的專案定義 ServiceWorkerAssetsManifest MSBuild 屬性，Blazor 的建置工具就會產生具有指定名稱的服務背景工作角色資產資訊清單。 預設 PWA 範本會產生包含下列屬性的專案檔：

<ServiceWorkerAssetsManifest>service-worker-assets.js</ServiceWorkerAssetsManifest>

檔案會放在 wwwroot 輸出目錄中，因此瀏覽器可要求 /service-worker-assets.js 以擷取此檔案。 若要查看此檔案的內容，請在文字編輯器中開啟 /bin/Debug/{TARGET FRAMEWORK}/wwwroot/service-worker-assets.js。 不過，請勿編輯檔案，因為檔案會在每個組建上重新產生。

清單列出：

• 任何 Blazor 受控資源，例如 .NET 組件和離線運作所需的 .NET WebAssembly 執行階段檔案。
• 發佈至應用程式 wwwroot 目錄的所有資源，例如影像、樣式表單和 JavaScript 檔案，包括外部專案和 NuGet 套件所提供的靜態 Web 資產。

您可以透過編輯onInstall中的service-worker.published.js邏輯，來控制服務工作者擷取和快取哪些資源。 服務背景工作角色會擷取並快取符合一般 Web 副檔名的檔案，例如 .html、.css、.js 和 .wasm，以及專屬於 Blazor WebAssembly 的檔案類型，例如 .pdb 檔案 (所有版本) 和 .dll 檔案 (.NET 7 或更早版本中的 ASP.NET Core)。

若要包含應用程式 wwwroot 目錄中所沒有的其他資源，請定義額外的 MSBuild ItemGroup 項目，如下列範例所示：

<ItemGroup>
  <ServiceWorkerAssetsManifestItem Include="MyDirectory\AnotherFile.json"
    RelativePath="MyDirectory\AnotherFile.json" AssetUrl="files/AnotherFile.json" />
</ItemGroup>

AssetUrl 中繼資料會指定瀏覽器在擷取資源進行快取時應使用的相對基底 URL。 這可能不依賴磁碟上的原始檔案名稱。

重要

新增 ServiceWorkerAssetsManifestItem 並不會導致檔案在應用程式的 wwwroot 目錄中發佈。 發佈輸出必須分開控制。 ServiceWorkerAssetsManifestItem 只會使額外的項目出現在服務工作者資產清單中。

推播通知

如同任何其他 PWA，Blazor WebAssembly PWA 可從後端伺服器接收推播通知。 伺服器可以隨時傳送推播通知，即使在使用者未主動使用應用程式時也一樣。 例如，當不同的使用者執行相關動作時，可以傳送推播通知。

離線 PWA 的注意事項

並非所有應用程式都應嘗試支援離線使用。 離線支援會大幅增加複雜度，同時不一定與所需的使用案例相關。

離線支援通常僅適用於：

• 如果主要資料儲存區是與瀏覽器本地相連。 例如，此方法在應用程式中與 IoT 裝置的 UI 相關，該裝置會將資料儲存在 localStorage 或 IndexedDB 中。
• 如果應用程式執行大量工作來擷取及快取與每個使用者相關的後端 API 資料，讓他們可以離線瀏覽資料。 如果應用程式必須支援編輯，則必須建置追蹤變更和同步處理資料與後端的系統。
• 如果目標是保證應用程式立即載入，而不論網路狀況為何。 在後端 API 要求周圍實作適當的使用者體驗，以顯示要求進度，並在要求因網路無法使用而失敗時優雅地處理。

此外，具備離線功能的 PWA 必須處理一系列額外的複雜功能。 開發人員應仔細熟悉下列各節中的注意事項。

僅在發佈後提供離線支援

在開發期間，您通常需要查看瀏覽器中立即反映的每個變更，而不需經過背景更新處理序。 因此，Blazor 的 PWA 範本僅在發佈時才會啟用離線支援。

建置具備離線功能的應用程式時，在 Development 環境中測試應用程式並不夠。 您必須以應用程式的已發佈狀態來測試應用程式，以了解應用程式如何回應不同的網路狀況。

在使用者瀏覽離開應用程式之後更新完成

更新不會完成，直到使用者在所有索引標籤中離開該應用程式。 如背景更新一節所述，將更新部署至應用程式之後，瀏覽器會擷取更新的服務背景工作角色檔案，以開始更新處理序。

令許多開發人員感到意外的是，即使此更新完成，也要等到使用者在所有標籤頁中都瀏覽離開後，更新才會生效。 即使顯示應用程式的索引標籤是唯一的，重新整理此索引標籤仍然不足以解決問題。 在您的應用程式完全關閉之前，新的服務工作者會維持在「等候啟動」 狀態中。 這並非專屬於 Blazor，而是標準的 Web 平台行為。

這通常會困擾那些嘗試測試其服務工作者或離線快取資源更新的開發人員。 如果您簽入瀏覽器的開發人員工具，可能會看到類似下列內容：

只要顯示應用程式的索引標籤或視窗的「客戶端」清單不是空的，背景工作執行緒就會繼續等候。 服務工作者這麼做的原因是為了保證一致性。 一致性表示所有資源都從相同的原子快取提取。

測試變更時，您可能會發現選取如上一個螢幕擷取畫面所示的 [skipWaiting] 連結，然後重新載入頁面這個做法很方便。 您可以撰寫服務工作者代碼，以略過「等待」階段，並在更新時立即啟動，讓所有使用者自動執行此作業。 如果您略過等待階段，則放棄確保資源總是從相同的快取實例中一致擷取的保證。

使用者可以執行應用程式的任何歷程記錄版本

Web 開發人員習慣預期使用者只會執行其 Web 應用程式的最新部署版本，因為這是傳統 Web 散發模型中的正常情況。 不過，離線優先 PWA 更類似於原生行動應用程式，其中使用者不一定是執行最新的版本。

如背景更新一節中所述，當您將更新部署至應用程式之後，每個現有使用者都會至少在下一次瀏覽時繼續使用舊版，因為更新會在背景中進行，且在使用者後續瀏覽之後才會啟動。 此外，所使用的舊版不一定是您先前部署的版本。 根據使用者上次完成更新的時間而定，舊版可以是任何歷程記錄版本。

如果您的應用程式前端和後端部分需要與 API 要求的結構描述達成協議，則這可能會是個問題。 在確定所有使用者都已升級之前，您不得部署向後不相容的 API 架構變更。 或者，封鎖使用者使用不相容的舊版應用程式。 此案例需求與原生行動應用程式的需求相同。 如果您在伺服器 API 中進行破壞性變更，尚未更新的使用者將無法正常使用用戶端應用程式。

可能的話，請避免將破壞性變更部署到後端 API。 如果您必須這麼做，請考慮使用 ServiceWorkerRegistration 等標準服務工作者 API 來判斷應用程式是否為最新狀態，如果不是，則避免繼續使用該應用程式。

干擾伺服器渲染頁面

如支援伺服器轉譯的頁面一節中所述，如果您想要繞過 Service Worker 對所有導覽請求返回 /index.html 內容的行為，請編輯 Service Worker 的邏輯。

將所有服務工作者的資產清單內容快取

如控制資產快取一節中所述，service-worker-assets.js 檔案會在建置期間產生，並列出服務背景工作角色應擷取及快取的所有資產。

由於此清單包含發出至 wwwroot 的所有項目，包括外部套件和專案提供的內容，因此您必須小心不要將太多內容放在該處。 如果 wwwroot 目錄包含數百萬個圖片，服務工作角色就會嘗試擷取及快取這些圖片，耗用過多的頻寬，而且很有可能無法順利完成。

請實施任意邏輯，以控制應該擷取及快取哪些資訊清單內容的子集，這可透過編輯 onInstall 中的 service-worker.published.js 函式來實現。

與驗證的互動

PWA 範本可以搭配驗證使用。 具備離線功能的 PWA 也可以在使用者具有初始網路連線能力時支援驗證。

當使用者沒有網路連線能力時，就無法驗證或取得存取權杖。 嘗試在沒有網路存取時瀏覽登入頁面會導致「網路錯誤」訊息。 您必須設計 UI 流程，讓使用者在離線時執行有用的工作，而不嘗試驗證使用者或取得存取權杖。 或者，當網路無法使用時，您可以設計應用程式使其優雅地失敗。 如果無法設計應用程式來處理這些案例，您可能不需要啟用離線支援。

當專為線上和離線使用而設計的應用程式再次上線時：

• 應用程式可能需要佈建新的存取權杖。
• 應用程式必須偵測不同的使用者是否已登入服務，以便將作業套用至離線時所建立的使用者帳戶。

若要建立與驗證互動的離線 PWA 應用程式：

• 將 AccountClaimsPrincipalFactory<TAccount> 取代為儲存上次登入使用者的處理站，並在應用程式離線時，使用預存使用者。
• 應用程式離線時將作業加入佇列，並在應用程式恢復線上時套用這些作業。
• 在登出期間，清除預存使用者。

CarChecker 範例應用程式會示範上述方法。 請參閱應用程式的下列部分：

• OfflineAccountClaimsPrincipalFactory （Client/Data/OfflineAccountClaimsPrincipalFactory.cs）
• LocalVehiclesStore （Client/Data/LocalVehiclesStore.cs）
• LoginStatus 元件 (Client/Shared/LoginStatus.razor)

其他資源

• 針對完整性 PowerShell 指令碼進行疑難排解
• SignalR