Filprovidrar i ASP.NET Core

ASP.NET Core abstraherar filsystemåtkomst via filproviders. Filprovidrar används i hela ASP.NET Core-ramverket. Till exempel:

• IWebHostEnvironment exponerar appens innehållsrot och webbrot som IFileProvider typer.
• Static File Middleware använder filproviders för att hitta statiska filer.
• Razor använder Filproviders för att hitta sidor och vyer.
• .NET-verktyg använder filproviders och globmönster för att ange vilka filer som ska publiceras.

Visa eller ladda ned exempelkod (hur du laddar ned)

Gränssnitt för filprovider

Det primära gränssnittet är IFileProvider. IFileProvider exponerar metoder för att:

• Hämta filinformation (IFileInfo).
• Hämta kataloginformation (IDirectoryContents).
• Konfigurera ändringsmeddelanden (med hjälp av IChangeToken).

IFileInfo innehåller metoder och egenskaper för att arbeta med filer:

• Exists
• IsDirectory
• Name
• Length (i bytes)
• LastModified datum

Du kan läsa från filen med hjälp av IFileInfo.CreateReadStream metoden .

Exempelappen FileProviderSample visar hur du konfigurerar en filprovider för användning i Startup.ConfigureServices hela appen via beroendeinmatning.

Implementeringar av filprovider

I följande tabell visas implementeringar av IFileProvider.

Fysisk filprovider

PhysicalFileProvider Ger åtkomst till det fysiska filsystemet. PhysicalFileProvider System.IO.File använder typen (för den fysiska providern) och avgränsar alla sökvägar till en katalog och dess undermappar. Det här omfånget förhindrar åtkomst till filsystemet utanför den angivna katalogen och dess underkataloger. Det vanligaste scenariot för att skapa och använda en PhysicalFileProvider är att begära en IFileProvider i en konstruktor via beroendeinmatning.

När du instansierar den här providern direkt krävs en absolut katalogsökväg och fungerar som bassökväg för alla begäranden som görs med providern. Globmönster stöds inte i katalogsökvägen.

Följande kod visar hur du använder PhysicalFileProvider för att hämta kataloginnehåll och filinformation:

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

Typer i föregående exempel:

• provider är en IFileProvider.
• contents är en IDirectoryContents.
• fileInfo är en IFileInfo.

Filprovidern kan användas för att iterera via den katalog som anges av applicationRoot eller anropa GetFileInfo för att hämta en fils information. Globmönster kan inte skickas till GetFileInfo metoden. Filprovidern har ingen åtkomst utanför applicationRoot katalogen.

Exempelappen FileProviderSample skapar providern Startup.ConfigureServices i metoden med hjälp av IHostEnvironment.ContentRootFileProvider:

var physicalProvider = _env.ContentRootFileProvider;

Manifest Embedded-filprovider

ManifestEmbeddedFileProvider Används för att komma åt filer som är inbäddade i sammansättningar. ManifestEmbeddedFileProvider Använder ett manifest som kompilerats till sammansättningen för att rekonstruera de ursprungliga sökvägarna för de inbäddade filerna.

Så här genererar du ett manifest för de inbäddade filerna:

1. Microsoft.Extensions.FileProviders.Embedded Lägg till NuGet-paketet i projektet.

2. Ange egenskapen <GenerateEmbeddedFilesManifest> till true. Ange de filer som ska bäddas in med <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>
   

Använd globmönster för att ange en eller flera filer som ska bäddas in i sammansättningen.

Exempelappen FileProviderSample skapar en ManifestEmbeddedFileProvider och skickar den pågående sammansättningen till konstruktorn.

Startup.cs:

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

Med ytterligare överbelastningar kan du:

• Ange en relativ filsökväg.
• Begränsa filer till ett senaste ändringsdatum.
• Namnge den inbäddade resursen som innehåller det inbäddade filmanifestet.

Sammansatt filleverantör

Kombinerar CompositeFileProviderIFileProvider instanser och exponerar ett enda gränssnitt för att arbeta med filer från flera leverantörer. När du skapar CompositeFileProviderskickar du en eller flera IFileProvider instanser till konstruktorn.

I exempelappen FileProviderSample tillhandahåller en PhysicalFileProvider och en ManifestEmbeddedFileProvider filer till en CompositeFileProvider registrerad i appens tjänstcontainer. Följande kod finns i projektets Startup.ConfigureServices metod:

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

services.AddSingleton<IFileProvider>(compositeProvider);

Håll utkik efter ändringar

Metoden IFileProvider.Watch ger ett scenario där du kan titta på en eller flera filer eller kataloger för ändringar. Watch-metoden:

• Accepterar en filsökvägssträng som kan använda globmönster för att ange flera filer.
• Returnerar en IChangeToken.

Den resulterande ändringstoken avslöjar:

• HasChanged: En egenskap som kan kontrolleras för att avgöra om en ändring har inträffat.
• RegisterChangeCallback: Anropas när ändringar identifieras i den angivna sökvägssträngen. Varje ändringstoken anropar endast sitt associerade återanrop som svar på en enda ändring. Om du vill aktivera konstant övervakning använder du en TaskCompletionSource<TResult> (visas nedan) eller återskapar IChangeToken instanser som svar på ändringar.

Exempelappen WatchConsole skriver ett meddelande när en .txt fil i TextFiles katalogen ändras:

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");
}

Vissa filsystem, till exempel Docker-containrar och nätverksresurser, kanske inte skickar ändringsmeddelanden på ett tillförlitligt sätt. DOTNET_USE_POLLING_FILE_WATCHER Ange miljövariabeln till 1 eller true för att avsöka filsystemet efter ändringar var fjärde sekund (kan inte konfigureras).

Globmönster

Filsystemsökvägar använder jokerteckenmönster som kallas globmönster (eller globbande). Ange grupper av filer med dessa mönster. De två jokertecknet är * och **:

*
Matchar något på den aktuella mappnivån, vilket som helst filnamn eller filändelse. Matchningar avslutas med / och . tecken i filsökvägen.

**
Matchar allt över flera katalognivåer. Kan användas för att rekursivt matcha många filer i en kataloghierarki.

Följande tabell innehåller vanliga exempel på globmönster.

ASP.NET Core abstraherar filsystemåtkomst via filproviders. Filprovidrar används i hela ASP.NET Core-ramverket:

• IHostingEnvironment exponerar appens innehållsrot och webbrot som IFileProvider typer.
• Static File Middleware använder filproviders för att hitta statiska filer.
• Razor använder Filproviders för att hitta sidor och vyer.
• .NET-verktyg använder filproviders och globmönster för att ange vilka filer som ska publiceras.

Visa eller ladda ned exempelkod (hur du laddar ned)

Gränssnitt för filprovider

Det primära gränssnittet är IFileProvider. IFileProvider exponerar metoder för att:

• Hämta filinformation (IFileInfo).
• Hämta kataloginformation (IDirectoryContents).
• Konfigurera ändringsmeddelanden (med hjälp av IChangeToken).

IFileInfo innehåller metoder och egenskaper för att arbeta med filer:

• Exists
• IsDirectory
• Name
• Length (i bytes)
• LastModified datum

Du kan läsa från filen med hjälp av metoden IFileInfo.CreateReadStream .

Exempelappen visar hur du konfigurerar en filprovider för användning i Startup.ConfigureServices hela appen via beroendeinmatning.

Implementeringar av filprovider

Tre implementeringar av IFileProvider är tillgängliga.

PhysicalFileProvider

PhysicalFileProvider Ger åtkomst till det fysiska filsystemet. PhysicalFileProvider System.IO.File använder typen (för den fysiska providern) och avgränsar alla sökvägar till en katalog och dess undermappar. Det här omfånget förhindrar åtkomst till filsystemet utanför den angivna katalogen och dess underkataloger. Det vanligaste scenariot för att skapa och använda en PhysicalFileProvider är att begära en IFileProvider i en konstruktor via beroendeinmatning.

När du instansierar den här providern direkt krävs en katalogsökväg och fungerar som bassökväg för alla begäranden som görs med providern.

Följande kod visar hur du skapar en PhysicalFileProvider och använder den för att hämta kataloginnehåll och filinformation:

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

Typer i föregående exempel:

• provider är en IFileProvider.
• contents är en IDirectoryContents.
• fileInfo är en IFileInfo.

Filprovidern kan användas för att iterera via den katalog som anges av applicationRoot eller anropa GetFileInfo för att hämta en fils information. Filprovidern har ingen åtkomst utanför applicationRoot katalogen.

Exempelappen skapar providern i appens Startup.ConfigureServices klass med IHostingEnvironment.ContentRootFileProvider:

var physicalProvider = _env.ContentRootFileProvider;

ManifestEmbeddedFileProvider

ManifestEmbeddedFileProvider Används för att komma åt filer som är inbäddade i sammansättningar. ManifestEmbeddedFileProvider Använder ett manifest som kompilerats till sammansättningen för att rekonstruera de ursprungliga sökvägarna för de inbäddade filerna.

Om du vill generera ett manifest för de inbäddade filerna anger du <GenerateEmbeddedFilesManifest> egenskapen till true. Ange de filer som ska bäddas in med <EmbeddedResource>:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.2</TargetFramework>
    <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
    <GenerateEmbeddedFilesManifest>true</GenerateEmbeddedFilesManifest>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

  <ItemGroup>
    <EmbeddedResource Include="Resource.txt" />
  </ItemGroup>

</Project>

Använd globmönster för att ange en eller flera filer som ska bäddas in i sammansättningen.

Exempelappen skapar en ManifestEmbeddedFileProvider och skickar den pågående sammansättningen till konstruktorn.

Startup.cs:

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

Med ytterligare överbelastningar kan du:

• Ange en relativ filsökväg.
• Begränsa filer till ett senaste ändringsdatum.
• Namnge den inbäddade resursen som innehåller det inbäddade filmanifestet.

CompositeFileProvider

Kombinerar CompositeFileProviderIFileProvider instanser och exponerar ett enda gränssnitt för att arbeta med filer från flera leverantörer. När du skapar CompositeFileProviderskickar du en eller flera IFileProvider instanser till konstruktorn.

I exempelappen tillhandahåller en PhysicalFileProvider och en ManifestEmbeddedFileProvider filer till en CompositeFileProvider registrerad i appens tjänstcontainer:

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

services.AddSingleton<IFileProvider>(compositeProvider);

Håll utkik efter ändringar

Metoden IFileProvider.Watch innehåller ett scenario där du kan titta på en eller flera filer eller kataloger för ändringar. Watch accepterar en sökvägssträng som kan använda globmönster för att ange flera filer. Watch returnerar ett IChangeToken. Ändringstoken exponerar:

• HasChanged: En egenskap som kan kontrolleras för att avgöra om en ändring har inträffat.
• RegisterChangeCallback: Anropas när ändringar identifieras i den angivna sökvägssträngen. Varje ändringstoken anropar endast sitt associerade återanrop som svar på en enda ändring. Om du vill aktivera konstant övervakning använder du en TaskCompletionSource<TResult> (visas nedan) eller återskapar IChangeToken instanser som svar på ändringar.

I exempelappen är WatchConsole-konsolappen konfigurerad för att visa ett meddelande när en textfil ändras:

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");
}

Vissa filsystem, till exempel Docker-containrar och nätverksresurser, kanske inte skickar ändringsmeddelanden på ett tillförlitligt sätt. DOTNET_USE_POLLING_FILE_WATCHER Ange miljövariabeln till 1 eller true för att avsöka filsystemet efter ändringar var fjärde sekund (kan inte konfigureras).

Globmönster

Filsystemsökvägar använder jokerteckenmönster som kallas globmönster (eller globbande). Ange grupper av filer med dessa mönster. De två jokertecknet är * och **:

*
Matchar något på den aktuella mappnivån, vilket som helst filnamn eller filändelse. Matchningar avslutas med / och . tecken i filsökvägen.

**
Matchar allt över flera katalognivåer. Kan användas för att rekursivt matcha många filer i en kataloghierarki.

Globmönsterexempel

directory/file.txt
Matchar en specifik fil i en specifik katalog.

directory/*.txt
Matchar alla filer med .txt-tillägget i en specifik katalog.

directory/*/appsettings.json
Matchar alla appsettings.json filer i kataloger exakt en nivå under katalogmappen .

directory/**/*.txt
Matchar alla filer med .txt filnamnstillägg som finns var som helst under katalogmappen .