ASP.NET Core Blazor 靜態檔案

發行項
04/12/2024

注意

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

重要

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

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

本文描述提供靜態檔案的 Blazor 應用程式設定。

Blazor 架構靜態檔案

在 .NET 8 之前的版本中，會透過靜態檔案中介軟體提供 Blazor 指令碼這類 Blazor 架構靜態檔案。在 .NET 8 或更新版本中，會使用端點路由來對應 Blazor 架構靜態檔案，而且不再使用靜態檔案中介軟體。

靜態 Web 資產專案模式

本節適用於 Blazor Web 應用程式的 .Client 專案。

Blazor Web 應用程式的 .Client 專案中的必要 <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> 設定會將 Blazor WebAssembly 靜態資產行為還原回預設值，讓專案作為託管專案的一部分運作。 Blazor WebAssembly SDK (Microsoft.NET.Sdk.BlazorWebAssembly) 會以特定方式設定靜態 Web 資產，以「獨立」模式運作，而伺服器只需取用程式庫的輸出即可。這不適用於 Blazor Web 應用程式，其中應用程式的 WebAssembly 部分是主機的邏輯部分，而且必須表現出更像程式庫的行為。例如，專案不會公開樣式組合 (例如 BlazorSample.Client.styles.css)，而是只向主機提供專案組合，讓主機可以將該組合包含在自己的樣式組合中。

不支援變更 <StaticWebAssetProjectMode> 的值 (Default) 或從 .Client 專案移除屬性。

靜態檔案中介軟體

本節適用伺服器端 Blazor 應用程式。

透過在應用程式的要求處理管線中呼叫 UseStaticFiles，設定靜態檔案中介軟體以提供靜態資產給用戶端。如需詳細資訊，請參閱 ASP.NET Core 中的靜態檔案。

非 `Development` 環境中的靜態檔案

本節適用於伺服器端靜態檔案。

在本機執行應用程式時，靜態 Web 資產預設只會在 Development 環境中啟用。若要在本機開發和測試期間為 Development 以外的環境啟用靜態檔案 (例如，Staging)，請在 Program 檔案中的 WebApplicationBuilder 上呼叫 UseStaticWebAssets。

警告

呼叫 UseStaticWebAssets 以取得防止在生產環境中啟用功能的確切環境，因為在生產環境中呼叫時，它會從磁碟上專案以外的不同位置提供檔案。本節中的範例會呼叫 IsStaging 來檢查 Staging 環境。

if (builder.Environment.IsStaging())
{
    builder.WebHost.UseStaticWebAssets();
}

Blazor WebAssembly 資產的前置詞

本節適用於 Blazor Web Apps。

使用 WebAssemblyComponentsEndpointOptions.PathPrefix 端點選項可設定指出 Blazor WebAssembly 資產前置詞的路徑字串。路徑必須對應至參考的 Blazor WebAssembly 應用程式專案。

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "{PATH PREFIX}");

在上述範例中，{PATH PREFIX} 預留位置是路徑前置詞，且開頭必須是正斜線 (/)。

在下列範例中，路徑前置詞會設定為 /path-prefix：

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "/path-prefix");

靜態 Web 資產基礎路徑

本節適用獨立 Blazor WebAssembly 應用程式。

依預設，發佈應用程式會將應用程式的靜態資產，包括 Blazor 架構檔案 (_framework 資料夾資產)，放在已發佈輸出中的根路徑 (/)。專案檔 (.csproj) 中指定的 <StaticWebAssetBasePath> 屬性會將基礎路徑設定為非根路徑：

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

在上述範例中，{PATH} 預留位置是路徑。

若未設定 <StaticWebAssetBasePath> 屬性，獨立應用程式會在 /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/ 發佈。

在上述範例中，{TFM} 預留位置是目標 Framework Moniker (TFM) (例如，net6.0)。

如果獨立 Blazor WebAssembly 應用程式中的 <StaticWebAssetBasePath> 屬性將已發佈的靜態資產路徑設定為 app1，則已發佈輸出中應用程式的根路徑為 /app1。

在獨立 Blazor WebAssembly 應用程式的專案檔中 (.csproj)：

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

在發佈的輸出中，獨立 Blazor WebAssembly 應用程式的路徑為 /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/。

在上述範例中，{TFM} 預留位置是目標 Framework Moniker (TFM) (例如，net6.0)。

本節適用獨立 Blazor WebAssembly 應用程式和裝載的 Blazor WebAssembly 方案。

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

在上述範例中，{PATH} 預留位置是路徑。

若未設定 <StaticWebAssetBasePath> 屬性，裝載的方案或獨立應用程式的用戶端應用程式會在下列路徑發佈：

裝載的 Blazor WebAssembly 方案的 Server 專案：/BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/
在獨立 Blazor WebAssembly 應用程式中：/BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/

如果裝載的 Blazor WebAssembly 應用程式或獨立 Blazor WebAssembly 應用程式中 Client 專案的 <StaticWebAssetBasePath> 屬性將已發佈的靜態資產路徑設定為 app1，則已發佈輸出中應用程式的根路徑為 /app1。

在 Client 應用程式的專案檔 (.csproj) 或獨立 Blazor WebAssembly 應用程式的專案檔中 (.csproj)：

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

在發佈的輸出中：

裝載的 Blazor WebAssembly 方案的 Server 專案中用戶端應用程式的路徑：/BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/app1/
獨立 Blazor WebAssembly 應用程式的路徑：/BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/

<StaticWebAssetBasePath> 屬性最常用來控制單一裝載部署中多個 Blazor WebAssembly 應用程式已發佈的靜態資產的路徑。如需詳細資訊，請參閱多個裝載的 ASP.NET Core Blazor WebAssembly 應用程式。屬性在獨立 Blazor WebAssembly 應用程式中也有效。

在上述範例中，{TFM} 預留位置是目標 Framework Moniker (TFM) (例如，net6.0)。

檔案對應和靜態檔案選項

本節適用於伺服器端靜態檔案。

若要使用 FileExtensionContentTypeProvider 或設定其他 StaticFileOptions 來建立其他檔案對應，請使用下列其中一種方法。在下列範例中，{EXTENSION} 預留位置是副檔名，而 {CONTENT TYPE} 預留位置是內容類型。下列 API 的命名空間為 Microsoft.AspNetCore.StaticFiles。

使用 StaticFileOptions 在 Program 檔案中透過相依性插入 (DI) 設定選項：

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

builder.Services.Configure<StaticFileOptions>(options =>
{
    options.ContentTypeProvider = provider;
});

app.UseStaticFiles();

將 StaticFileOptions 直接傳遞至 Program 檔案中的 UseStaticFiles：

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });

若要使用 FileExtensionContentTypeProvider 或設定其他 StaticFileOptions 來建立其他檔案對應，請使用下列其中一種方法。在下列範例中，{EXTENSION} 預留位置是副檔名，而 {CONTENT TYPE} 預留位置是內容類型。

使用 StaticFileOptions 在 Program 檔案中透過相依性插入 (DI) 設定選項：
```
using Microsoft.AspNetCore.StaticFiles;

...

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

builder.Services.Configure<StaticFileOptions>(options =>
{
    options.ContentTypeProvider = provider;
});
```
此方法會設定用來提供 Blazor 指令碼的相同檔案提供者。請確定您的自訂設定不會干擾提供 Blazor 指令碼。例如，請勿使用 provider.Mappings.Remove(".js") 設定提供者來移除 JavaScript 檔案的對應。

在 Program 檔案中使用對 UseStaticFiles 的兩個呼叫：

使用 StaticFileOptions 在第一次呼叫中設定自訂檔案提供者。
第二個中介軟體會提供 Blazor 指令碼，其會使用 Blazor 架構提供的預設靜態檔案設定。

using Microsoft.AspNetCore.StaticFiles;

...

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });
app.UseStaticFiles();

您可以避免干擾提供 _framework/blazor.server.js，方法是使用 MapWhen 來執行自訂靜態檔案中介軟體：

app.MapWhen(ctx => !ctx.Request.Path
    .StartsWithSegments("/_framework/blazor.server.js"),
        subApp => subApp.UseStaticFiles(new StaticFileOptions() { ... }));

其他資源

應用程式基礎路徑

ASP.NET Core Blazor 靜態檔案

Blazor 架構靜態檔案

靜態 Web 資產專案模式

靜態檔案中介軟體

非 Development 環境中的靜態檔案

Blazor WebAssembly 資產的前置詞

靜態 Web 資產基礎路徑

檔案對應和靜態檔案選項

其他資源

意見反應

其他資源

非 `Development` 環境中的靜態檔案