ASP.NET Core Blazor 靜態檔案
注意
這不是這篇文章的最新版本。 如需目前版本,請參閱本文的 .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 方案。
依預設,發佈應用程式會將應用程式的靜態資產,包括 Blazor 架構檔案 (_framework
資料夾資產),放在已發佈輸出中的根路徑 (/
)。 專案檔 (.csproj
) 中指定的 <StaticWebAssetBasePath>
屬性會將基礎路徑設定為非根路徑:
<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() { ... }));
其他資源
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應