[NETCore] ASP.NET Core 靜態檔案設定 - UseStaticFiles ~ m@rcus 學習筆記

前言
在過去開發 .NET Framework 時代在專案使用靜態檔案是一塊小蛋糕，只需要在專案指定 Folder 加入需要的靜態檔案內容即可，像是圖片就放在 image、javascript 內容就放在 js 資料底下...等等，但同樣事情在 ASP.NET Core 專案可就完全不同，在 .NET Core 專案中是無法直接瀏覽靜態檔案的，需要透過一些設定方式才可以在專案看到像是 HTML、CSS、Image 或是 javascript 靜態檔案，這篇文章就是簡單說明在 ASP.NET Core 專案中如何設定才可以看到靜態檔案內容，若有問題歡迎提出一起討論或是給予指導。

靜態檔案
在 ASP.NET Core 中 Web 檔案會存放在專案根目錄中，預設存放位置是專案根目錄 project / wwwroot 底下，其資料夾底下可以存放多個資料夾如下，如果要存取 image 子資料夾底下的 test.jpg，其 URL 格式為 http:// yourApplicaitonName:9487/image/test.jpg

以下就透過簡單的範例，在 ASP.NET Core 專案簡單示範如何加上靜態檔案
簡單來說兩個步驟可以完成

加入靜態實體檔案
加入 UseStaticFiles 方法

Step 1 : 前面提到預設靜態檔案目錄是 wwwroot，在 wwwroot 目錄底下新增一個 helloworrld.html 檔案

其 html 內容就簡單輸入 Hello World ASP.NET Core !!!

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title></title>
</head>
<body>
    Hello World ! ASP.NET Core 
</body>
</html>

Step 2 : 在 Startup 中 Configure 新增 UseStaticFiles 方法，UseStaticFile 是 IApplicationBuilder 的擴充方法，主要是啟用靜態文件服務，背後其實是呼叫另一個 middleware 幫妳進行靜態檔案的設定

app.UseStaticFiles();

好的，經過設定完畢之後在開啟網站並在網頁 url 後面加上 helloworld.html，即可在網頁上看到 Hello world ! ASP.NET Core 字眼，新增成功 !!

未設定 UseStaticFiles
如果未設定 UseStaticFiles 或是未將檔案放置在預設路徑底下，則會出現 Http Error 404 not found 錯誤畫面，如下圖所示

透過以上步驟，就可以輕鬆解決在 ASP.NET Core 無法顯示靜態檔案問題，讓靜態檔案找到回家的路(咦

UseStaticFiles
為何透過 UseStaticFiles 方法就可以啟用靜態檔案呢? 接下來我們在往下追看看方法做了什麼事情以及實作細節，在 UseStaticFiles 方法提供三種多載情境給開發者使用，三種方法分別是

預設路徑 : 無任何參數
指定靜態檔案路徑 : requestPath
指定 StaticFileOptions 物件

UseStaticFiles
無參數的方法如下

/// <summary>
/// Enables static file serving for the current request path
/// </summary>
/// <param name="app"></param>
/// <returns></returns>
public static IApplicationBuilder UseStaticFiles(this IApplicationBuilder app)
{
  if (app == null)
    throw new ArgumentNullException(nameof (app));
  return app.UseMiddleware<StaticFileMiddleware>(Array.Empty<object>());
}

從上述代碼可以看到，無參數的方法主要是透過設定 StaticFileMiddleware 來做靜態檔案的設定，在其 middleware invoke 方法中主要是處理已知靜態檔案 Request 請求，也就是確認 MIME 的 Content Type 是可以被識別的才會處理其靜態檔案請求內容，路徑則是透過預設的 wwwroot 路徑位置來讀取檔案位置，

UseStaticFiles 指定靜態檔案路徑
此方法是指定檔案路徑位置作為參數，接著再透過 UseStaticFiles 指定其 StaticFileOptions 作為參數，相關代碼如下

/// <summary>
/// Enables static file serving for the given request path
/// </summary>
/// <param name="app"></param>
/// <param name="requestPath">The relative request path.</param>
/// <returns></returns>
public static IApplicationBuilder UseStaticFiles(this IApplicationBuilder app, string requestPath)
{
  if (app == null)
    throw new ArgumentNullException(nameof (app));
  IApplicationBuilder app1 = app;
  StaticFileOptions options = new StaticFileOptions();
  options.RequestPath = new PathString(requestPath);
  return app1.UseStaticFiles(options);
}

或者這樣講有點抽象，這就簡單的舉個範例讓大家更容易了解，下面的範例是透過設定 StaticFileOptions 公開 MyStaticFiles 目錄資料夾作為存放靜態檔案的位置

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles(); // 預設公開位置 wwwroot 
    app.UseStaticFiles(new StaticFileOptions
    {
        FileProvider = new PhysicalFileProvider(
            Path.Combine(Directory.GetCurrentDirectory(), "MyStaticFiles")),
        RequestPath = "/StaticFiles"
    });
}

UseStaticFiles 指定 StaticOptions
UseStaticFiles 指定靜態檔案路徑與此方法有點類似，都是設定其 StaticOptions 參數資料，差異是上面的方法僅提供設定路徑位置 RequestPath，此方法提供設定範圍比較廣，可以定義 StaticOptions 類別更多的細節，先看看 API 簽章

/// <summary>Enables static file serving with the given options</summary>
/// <param name="app"></param>
/// <param name="options"></param>
/// <returns></returns>
public static IApplicationBuilder UseStaticFiles(this IApplicationBuilder app, StaticFileOptions options)
{
  if (app == null)
    throw new ArgumentNullException(nameof (app));
  if (options == null)
    throw new ArgumentNullException(nameof (options));
  return app.UseMiddleware<StaticFileMiddleware>((object) Microsoft.Extensions.Options.Options.Create<StaticFileOptions>(options));
}

甚麼時候有可能會用到呢? 舉例來說有時希望在回傳靜態檔案時加上 cache 機器，讓瀏覽器的 Browser 幫忙做點事不用相同檔案的 Request 重複跟 Server 要資料，這時就可以透過 OnPrepareResponse 方法在回傳前做點小加工，實作方式如下

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    var cachePeriod = "600";
    app.UseStaticFiles(new StaticFileOptions
    {
        OnPrepareResponse = ctx =>
        {            
            ctx.Context.Response.Headers.Append("Cache-Control", $"public, max-age={cachePeriod}");
        }
    });
}

在回傳的 Head 上加上 cache 有效時間為 600 秒，從網頁 Response 結果就可以看出設定成功

後記
以上簡單介紹關於 UseStaticFiles 的基本應用與說明，在其中有更多進階的應用像是檔案授權、如何開啟靜態檔案目錄方式瀏覽、提供預設文件的方式等更多情境的應用，如果有需要可以參考官方網站的說明與 sample code : 傳送門在此，當然對以上的內容說是有疑問的地方歡迎隨時提出來，謝謝

參考
ASP.NET Core 中的靜態檔案

[NETCore] 移除未使用的 ASP.NET Core SDK問題最近電腦一直跳出硬碟空間不足訊息提示，在清理硬碟的空間過程中發現電腦安裝多個版本的 ASP.NET Core SDK，身為一位專案自以為跟上技術潮流的開發人員這種狀況應該常遇到，用硬碟的空間來換取跟上潮流的速度是合情合理，但由於公司筆電硬碟空間有限口袋空空也是很苦惱，這篇文章就針對此問題的解決方式做簡單分享，若是有不清楚或是錯誤的地方歡迎討論予糾正。解決方案最直覺的解決方式是透過控制台應用程式，在逐步的點選每一項進行解… Read More
[NETCore] 使用 Dotnet Watch 自動編譯 ASP.NET Core 應用程式前言在開發完代碼的時候，為了確保代碼在應用程式執行的狀況，會在 Visual Studio IDE 使用偵錯模式 F5 或是 Ctrl+F5 進行偵錯，如果執行狀況不如預期時就會關閉偵錯，重新修改代碼在編譯再重新進行偵錯，簡單來說流程像是改 Code > 編譯 Ctrl + Shift + B > 測試 F5 or Ctrl + F5 > 不如預期 > 改 Code ，仔細想… Read More
[.NETCore] 在 IIS 執行 ASP.NET Core 應用程式前言在 IIS 執行 ASP.NET Core 專案時與過去 .NET Framework 運作不同，.NET Core Application 預設以 Kestrel 為 HTTP Server 與 IIS 做溝通，流程可以參考下圖所示；因此要將開發好的 .NET Core 網站專案佈署至 IIS 設定方式是不同的，這篇介紹如何將 ASP.NET Core 應用程式佈署至 IIS 的步驟說明，若有問題歡迎提出一起討論或是給予指導 … Read More
[NETCore] ASP.NET Core 啟動失敗 - failed to start process with commandline 問題新專案使用 ASP.NET Core 2.2 開發完成並佈署至 Production 機器，在瀏覽網頁時跳出應用程式無法正常啟動的畫面，錯誤訊息為 'HTTP Error 502.5 - ANCM Out-Of-Process Startup Failure' ，不知為何最近跟 ASP.NET Core 啟動失敗特別有緣分 (一直常遇到這類的事情 XD)，這篇文章就針對此問題的解決方式做簡單分享，… Read More
[Docker] Docker for windows 初體驗前言 Docker 是一個 open source 專案，誕生於 2013 年初，Docker 屬於 Linux 容器的一種封裝，提供了簡單且易用的容器接口，在 2016 推出 Docker for windows 版本，相信大家或多或少都聽過甚至已經有在使用，自己也接觸過 docker 一小段時間，但都屬於玩票性質未好好研究，或許在新筆電重新安裝的時候是一個好契機可以靜下心來深入研究，以下簡單介紹 Docker 在 Windows 上的安裝流程… Read More

m@rcus 學習筆記

只有累積，沒有奇蹟

2020年7月1日星期三