Zprostředkovatelé souborů v ASP.NET Core

Autor: Steve Smith

ASP.NET Core abstrahuje přístup k systému souborů prostřednictvím použití zprostředkovatelů souborů. Zprostředkovatelé souborů se používají v rámci architektury ASP.NET Core. Příklad:

• IWebHostEnvironmentzveřejňuje kořen obsahu aplikace a kořenový adresář webu jako IFileProvider typy.
• Middleware statického souboru používá k vyhledání statických souborů zprostředkovatele souborů.
• Razor používá zprostředkovatele souborů k vyhledání stránek a zobrazení.
• Nástroje .NET Core používají k určení souborů, které se mají publikovat, pomocí zprostředkovatelů souborů a vzorů globu.

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Rozhraní zprostředkovatele souborů

Primární rozhraní je IFileProvider. IFileProvider zveřejňuje metody pro:

• Získání informací o souboru (IFileInfo).
• Získání informací o adresáři (IDirectoryContents).
• Nastavení oznámení o změnách (pomocí funkce IChangeToken).

IFileInfo poskytuje metody a vlastnosti pro práci se soubory:

• Exists
• IsDirectory
• Name
• Length (v bajtech)
• LastModified Datum

Ze souboru můžete číst pomocí IFileInfo.CreateReadStream metody.

Ukázková FileProviderSample aplikace ukazuje, jak nakonfigurovat zprostředkovatele Startup.ConfigureServices souborů pro použití v celé aplikaci prostřednictvím injektáže závislostí.

Implementace zprostředkovatele souborů

Následující tabulka uvádí implementace .IFileProvider

Implementace	Popis
Zprostředkovatel složených souborů	Používá se k poskytování kombinovaného přístupu k souborům a adresářům od jednoho nebo více jiných poskytovatelů.
Zprostředkovatel souborů Manifest Embedded	Používá se pro přístup k souborům vloženým do sestavení.
Zprostředkovatel fyzických souborů	Používá se pro přístup k fyzickým souborům systému.

Zprostředkovatel fyzických souborů

Poskytuje PhysicalFileProvider přístup k fyzickému systému souborů. PhysicalFileProviderSystem.IO.File používá typ (pro fyzického zprostředkovatele) a definuje všechny cesty k adresáři a jeho podřízeným položkám. Toto určení rozsahu brání přístupu k systému souborů mimo zadaný adresář a jeho podřízené položky. Nejběžnějším scénářem vytvoření a použití objektu PhysicalFileProvider je vyžádání IFileProvider v konstruktoru prostřednictvím injektáže závislostí.

Při přímé instanci tohoto poskytovatele se vyžaduje absolutní cesta k adresáři a slouží jako základní cesta pro všechny požadavky provedené pomocí zprostředkovatele. V cestě k adresáři nejsou podporovány vzory globu.

Následující kód ukazuje, jak získat PhysicalFileProvider obsah adresáře a informace o souborech:

var provider = new PhysicalFileProvider(applicationRoot);
var contents = provider.GetDirectoryContents(string.Empty);
var filePath = Path.Combine("wwwroot", "js", "site.js");
var fileInfo = provider.GetFileInfo(filePath);

Typy v předchozím příkladu:

• providerje .IFileProvider
• contentsje .IDirectoryContents
• fileInfoje .IFileInfo

Zprostředkovatel souborů lze použít k iteraci v adresáři určeném applicationRoot pomocí nebo volání GetFileInfo k získání informací o souboru. Vzory globu nelze metodě předat GetFileInfo . Zprostředkovatel souborů nemá přístup mimo applicationRoot adresář.

Ukázková FileProviderSample aplikace vytvoří zprostředkovatele v Startup.ConfigureServices metodě pomocí IHostEnvironment.ContentRootFileProvider:

var physicalProvider = _env.ContentRootFileProvider;

Zprostředkovatel souborů Manifest Embedded

Slouží ManifestEmbeddedFileProvider k přístupu k souborům vloženým v sestaveních. Pomocí ManifestEmbeddedFileProvider manifestu zkompilovaného do sestavení rekonstruuje původní cesty vložených souborů.

Generování manifestu vložených souborů:

1. Přidejte do Microsoft.Extensions.FileProviders.Embedded projektu balíček NuGet.

2. Nastavte vlastnost <GenerateEmbeddedFilesManifest> na true. Zadejte soubory, které chcete vložit:<EmbeddedResource>

   <Project Sdk="Microsoft.NET.Sdk.Web">
   
     <PropertyGroup>
       <TargetFramework>netcoreapp3.1</TargetFramework>
       <GenerateEmbeddedFilesManifest>true</GenerateEmbeddedFilesManifest>
     </PropertyGroup>
   
     <ItemGroup>
       <PackageReference Include="Microsoft.Extensions.FileProviders.Embedded" Version="3.1.0" />
     </ItemGroup>
   
     <ItemGroup>
       <EmbeddedResource Include="Resource.txt" />
     </ItemGroup>
   
   </Project>
   

Pomocí vzorů globu můžete zadat jeden nebo více souborů pro vložení do sestavení.

Ukázková FileProviderSample aplikace vytvoří ManifestEmbeddedFileProvider a předá aktuálně spuštěné sestavení jeho konstruktoru.

Startup.cs:

var manifestEmbeddedProvider = 
    new ManifestEmbeddedFileProvider(typeof(Program).Assembly);

Další přetížení vám umožní:

• Zadejte relativní cestu k souboru.
• Nastavení rozsahu souborů na datum poslední změny
• Pojmenujte vložený prostředek obsahující manifest vloženého souboru.

Přetížení	Popis
ManifestEmbeddedFileProvider(Assembly, String)	Přijímá volitelný root parametr relativní cesty. root Zadejte rozsah volání těchto GetDirectoryContents prostředků v zadané cestě.
ManifestEmbeddedFileProvider(Assembly, String, DateTimeOffset)	Přijímá volitelný root parametr relativní cesty a lastModified parametr date (DateTimeOffset). Datum lastModified určuje datum poslední změny pro IFileInfo instance vrácené IFileProvidersadou .
ManifestEmbeddedFileProvider(Assembly, String, String, DateTimeOffset)	Přijímá volitelnou root relativní cestu, lastModified datum a manifestName parametry. Představuje manifestName název vloženého prostředku obsahujícího manifest.

Zprostředkovatel složených souborů

IFileProvider Kombinuje CompositeFileProvider instance a zpřístupňuje jedno rozhraní pro práci se soubory z více poskytovatelů. Při vytváření CompositeFileProviderpředejte jednu nebo více IFileProvider instancí jeho konstruktoru.

V ukázkové FileProviderSample aplikaci PhysicalFileProvider a ManifestEmbeddedFileProvider zadejte soubory zaregistrované CompositeFileProvider v kontejneru služby aplikace. V metodě projektu Startup.ConfigureServices se nachází následující kód:

var physicalProvider = _env.ContentRootFileProvider;
var manifestEmbeddedProvider = 
    new ManifestEmbeddedFileProvider(typeof(Program).Assembly);
var compositeProvider = 
    new CompositeFileProvider(physicalProvider, manifestEmbeddedProvider);

services.AddSingleton<IFileProvider>(compositeProvider);

Sledujte změny

Tato IFileProvider.Watch metoda poskytuje scénář sledování změn jednoho nebo více souborů nebo adresářů. Metoda Watch:

• Přijímá řetězec cesty k souboru, který může k určení více souborů použít vzory globu .
• Vrátí hodnotu IChangeToken.

Výsledný token změny zveřejňuje:

• HasChanged: Vlastnost, kterou lze zkontrolovat a zjistit, zda došlo ke změně.
• RegisterChangeCallback: Volá se při zjištění změn v zadaném řetězci cesty. Každý token změny volá pouze přidružené zpětné volání v reakci na jednu změnu. Pokud chcete povolit konstantní monitorování, použijte TaskCompletionSource<TResult> (viz níže) nebo znovu vytvořte IChangeToken instance v reakci na změny.

Ukázková WatchConsole aplikace zapíše zprávu při každé .txt změně souboru v TextFiles adresáři:

private static readonly string _fileFilter = Path.Combine("TextFiles", "*.txt");

public static void Main(string[] args)
{
    Console.WriteLine($"Monitoring for changes with filter '{_fileFilter}' (Ctrl + C to quit)...");

    while (true)
    {
        MainAsync().GetAwaiter().GetResult();
    }
}

private static async Task MainAsync()
{
    var fileProvider = new PhysicalFileProvider(Directory.GetCurrentDirectory());
    IChangeToken token = fileProvider.Watch(_fileFilter);
    var tcs = new TaskCompletionSource<object>();

    token.RegisterChangeCallback(state =>
        ((TaskCompletionSource<object>)state).TrySetResult(null), tcs);

    await tcs.Task.ConfigureAwait(false);

    Console.WriteLine("file changed");
}

Některé systémy souborů, jako jsou kontejnery Dockeru a sdílené síťové složky, nemusí spolehlivě odesílat oznámení o změnách. Nastavte proměnnou DOTNET_USE_POLLING_FILE_WATCHER prostředí na 1 souborový systém nebo true ho dotazujte na změny každých čtyři sekundy (nedají se konfigurovat).

Vzory globů

Cesty k systému souborů používají vzory zástupných znaků označované jako glob (nebo globbing). Zadejte skupiny souborů s těmito vzory. Dva zástupné znaky jsou * a **:

*
Odpovídá všemu na aktuální úrovni složky, libovolnému názvu souboru nebo jakékoli příponě souboru. Shody jsou ukončeny / a . znaky v cestě k souboru.

**
Odpovídá všemu na více úrovních adresáře. Dá se použít k rekurzivnímu párování mnoha souborů v hierarchii adresářů.

Následující tabulka obsahuje běžné příklady vzorů globů.

Vzor	Popis
directory/file.txt	Odpovídá určitému souboru v určitém adresáři.
directory/*.txt	Odpovídá všem souborům s příponou .txt v určitém adresáři.
directory/*/appsettings.json	Odpovídá všem appsettings.json souborům v adresářích přesně o jednu úroveň pod složkou directory .
directory/**/*.txt	Odpovídá všem souborům s příponou .txt , která se nachází kdekoli pod složkou directory .