ASP.NET Core File Providers

原文地址：FileProvider

By Steve Smith

ASP.NET Core通過對File Providers的使用實現了對文件系統訪問的抽象。

查看或下載示例代碼

File Provider 抽象

File Providers是文件系統之上的一層抽象。它的主要接口是IFileProvider。IFileProvider公開了相應方法用來獲取文件信息（IFileInfo）， 目錄信息（IDirectoryContents），以及設置更改通知（通過使用一個IChangeToken）。

IFileInfo接口提供了操作單個文件和目錄的方法和屬性。它有兩個boolean屬性，Exists和IsDirectory，以及兩個描述文件的兩個屬性Name和Length（按字節），還包括一個LastModified日期屬性。你還可以通過CreateReadStream方法讀取文件內容。

File Provider 實現

有三種對於IFileProvider的實現可供選擇：物理式，嵌入式和復合式。物理式用於訪問實際系統中的文件。嵌入式用於訪問嵌入在程序集中的文件。 復合式則是對前兩種方式的組合使用。

PhysicalFileProvider

PhysicalFileProvider提供了對物理文件系統的訪問。它封裝了System.IO.File類型，范圍限定到一個目錄及其子目錄的所有路徑。這類作用域會限制訪問某個目錄及其子目錄，防止作用域以外的其他操作訪問文件系統。當實例化此類provider時，你必須為它提供一個目錄路徑，以供服務器拿來當做由這個provider發出的所有請求的基礎路徑（這個provider會限制路徑以外的訪問請求）。在一個ASP.NET Core應用，你可以直接實例化出一個PhysicalFileProvider provider，或者你也可以通過在控制器和服務中使用構造函數依賴注入的方式，請求一個IFileProvider接口。后者生成的解決方案通常更靈活以及更便於測試。

要創建一個PhysicalFileProvider其實很簡單，只需要對其實化，再傳遞給它一個物理路徑。之后你就可以通過它的目錄遍歷內容或提供子路徑獲取特定文件的信息。

IFileProvider provider = new PhysicalFileProvider(applicationRoot);
IDirectoryContents contents = provider.GetDirectoryContents(""); // the applicationRoot contents
IFileInfo fileInfo = provider.GetFileInfo("wwwroot/js/site.js"); // a file under applicationRoot

為了在控制器中請求一個provider，需要在控制器的構造函數中指定類型參數並賦值給本地屬性。之后你就可以在你的動作器方法中使用本地實例了。

public class HomeController : Controller
{
    private readonly IFileProvider _fileProvider;

    public HomeController(IFileProvider fileProvider)
    {
        _fileProvider = fileProvider;
    }

    public IActionResult Index()
    {
        var contents = _fileProvider.GetDirectoryContents("");
        return View(contents);
    }
}

在應用的Startup類中創建provider的代碼如下：

using System.Linq;
using System.Reflection;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.FileProviders;
using Microsoft.Extensions.Logging;

namespace FileProviderSample
{
    public class Startup
    {
        private IHostingEnvironment _hostingEnvironment;
        public Startup(IHostingEnvironment env)
        {
            var builder = new ConfigurationBuilder()
                .SetBasePath(env.ContentRootPath)
                .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true)
                .AddEnvironmentVariables();
            Configuration = builder.Build();

            _hostingEnvironment = env;
        }

        public IConfigurationRoot Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            // Add framework services.
            services.AddMvc();

            var physicalProvider = _hostingEnvironment.ContentRootFileProvider;
            var embeddedProvider = new EmbeddedFileProvider(Assembly.GetEntryAssembly());
            var compositeProvider = new CompositeFileProvider(physicalProvider, embeddedProvider);

            // choose one provider to use for the app and register it
            //services.AddSingleton<IFileProvider>(physicalProvider);
            //services.AddSingleton<IFileProvider>(embeddedProvider);
            services.AddSingleton<IFileProvider>(compositeProvider);
        }
    }
}

在 Index.chhtml 視圖中，可以遍歷操作IDirectoryContents模型參數

@using Microsoft.Extensions.FileProviders
@model  IDirectoryContents

<h2>Folder Contents</h2>

<ul>
    @foreach (IFileInfo item in Model)
    {
        if (item.IsDirectory)
        {
            <li><strong>@item.Name</strong></li>
        }
        else
        {
            <li>@item.Name - @item.Length bytes</li>
        }
    }
</ul>

結果如下：

EmbeddedFileProvider

EmbeddedFileProvider用於訪問嵌入到程序集中的文件。在.NET Core中，你可以通過修改 project.json 文件的buildOptions屬性參數來把文件嵌入到程序集中。

"buildOptions": {
  "emitEntryPoint": true,
  "preserveCompilationContext": true,
  "embed": [
    "Resource.txt",
    "**/*.js"
  ]
}

當你把文件嵌入到程序集中時，你可以使用通配符模式。這些模式可以被用來匹配一個或多個文件。

Note
把項目中所有的.js文件都嵌入到項目程序集里的情況是不太可能發生的，以上示例僅作為demo給出。

當創建一個EmbeddedFileProvider時，請在其構造函數中傳入一個程序集實例供其讀取。

var embeddedProvider = new EmbeddedFileProvider(Assembly.GetEntryAssembly());

以上的代碼片段描述了如何創建一個能訪問當前工作程序集的EmbeddedFileProvider類型變量。

使用EmbeddedFileProvider更新示例項目代碼后的輸出結果如下：

Note
如上圖所示，嵌入式資源不會公開目錄。相反的，資源路徑（經由資源的命名空間）會被嵌入到它的文件名中並以.作為分隔符。

Tip
EmbeddedFileProvider構造器接受一個可選的baseNamespace參數，指定此參數將限定GetDirectoryContents方法調用該命名空間下的資源。

CompositeFileProvider

CompositeFileProvider聯合IFileProvider實例公開了一個單一的接口，用以和來自多種provider的文件工作。當創建一個CompositeFileProvider時，你可以為它的構造函數傳入一個或多個IFileProvider實例。

var physicalProvider = _hostingEnvironment.ContentRootFileProvider;
var embeddedProvider = new EmbeddedFileProvider(Assembly.GetEntryAssembly());
var compositeProvider = new CompositeFileProvider(physicalProvider, embeddedProvider);

使用包含物理式provider（在前）和嵌入式provider的CompositeFileProvider更新示例項目代碼后的輸出結果如下：

查看更改

IFileProvider的Watch方法能用來查看一個或多個文件/目錄的更改信息。Watch方法接受一個路徑字符串，它也可以使用通配符模式來指定多個文件，Watch方法最終返回一個IChangeToken。這個token公開了一個HasChanged屬性用以檢視狀態，公開了一個RegisterChangeCallback方法，此方法會在指定的路徑字符串檢測到更改時被調用。請注意每個更改token只調用其關聯回調以響應單次更改。為了使監控持續，你可以使用如下所示的TaskCompletionSource方法，或者重建IChangeToken以響應更改。

在這個文章的示例中，無論何時當文本文件內容發生修改，按如下代碼配置的console應用都會顯示相應的信息。

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.Extensions.FileProviders;
using Microsoft.Extensions.Primitives;

namespace WatchConsole
{
    public class Program
    {
        private static PhysicalFileProvider _fileProvider = 
            new PhysicalFileProvider(Directory.GetCurrentDirectory());
        public static void Main(string[] args)
        {
            Console.WriteLine("Monitoring quotes.txt for changes (ctrl-c to quit)...");
            while (true)
            {
                MainAsync().GetAwaiter().GetResult();
            }
        }

        private static async Task MainAsync()
        {
            IChangeToken token = _fileProvider.Watch("quotes.txt");
            var tcs = new TaskCompletionSource<object>();
            token.RegisterChangeCallback(state => 
                ((TaskCompletionSource<object>)state).TrySetResult(null), tcs);
            await tcs.Task.ConfigureAwait(false);
            Console.WriteLine("quotes.txt changed");
        }
    }
}

以下是執行過幾次文本保存動作后的運行結果截圖：

Note
有一些文件系統，例如Docker容器和網絡共享，可能不能很可靠地發送更改通知。設置環境變量DOTNET_USE_POLLINGFILEWATCHER的值為1或true，使得每四秒輪詢一次文件系統的變更。

通配符模式

文件系統路徑規則使用叫作globbing patterns的通配符模式，這類簡單模式可以被用來指定文件組。這兩個通配符分別是*和**。

*
*表示在當前文件夾級別上匹配任何文件名稱或文件擴展名。匹配以文件路徑字符串中的/和.符號結尾。

**
**表示在多個目錄級別上匹配任何文件名稱或文件擴展名。可用於在一個目錄層次結構中遞歸地匹配多個文件。

通配符模式示例

directory/file.txt

在指定的文件夾中匹配指定的文件。

directory/*.txt

在指定的文件夾中匹配所有以.txt擴展名結尾的文件。

directory/*/project.json

在指定的directory文件夾下的一級目錄位置中匹配所有符合project.json名稱的文件

directory/**/*.txt

在指定的directory文件夾下的所有位置中匹配所有以.txt擴展名結尾的文件。

在ASP.NET Core中File Provider的用法

ASP.NET Core有幾個組件使用file provider功能。IHostingEnvironment以IFileProvider接口類型公開了應用的目錄根和Web根。靜態文件中間件使用file provider來定位靜態文件。Razor更是大量使用IFileProvider來定位視圖。Dotnet的發布功能使用file provider和通配符模式來指定需要跟隨發布的文件。

在應用程序中使用的建議

如果你的ASP.NET Core應用需要訪問文件系統，你可以通過依賴注入創建IFileProvider接口實例，然后再通過前文所示的相應方法執行訪問。當應用啟動的時候，這些方法允許你一次性配置provider並減少應用初始化時生成的實例類型數目。