Provedores de arquivos no ASP.NET Core

ASP.NET Core abstrai o acesso ao sistema de arquivos através do uso de provedores de arquivos. Os provedores de arquivos são usados em toda a estrutura ASP.NET Core. Por exemplo:

• IWebHostEnvironment Expõe a raiz de conteúdo da aplicação e a raiz web como IFileProvider tipos.
• O Middleware de Arquivo Estático usa Provedores de Arquivos para localizar arquivos estáticos.
• Razor usa Provedores de Arquivos para localizar páginas e exibições.
• As ferramentas .NET usam provedores de arquivos e padrões glob para especificar quais arquivos devem ser publicados.

Visualizar ou descarregar amostra de código (como descarregar)

Interfaces do provedor de arquivos

A interface primária é IFileProvider. IFileProvider expõe métodos para:

• Obter informações sobre o arquivo (IFileInfo).
• Obter informações de diretório (IDirectoryContents).
• Configurar notificações de alteração (usando um IChangeToken).

IFileInfo Fornece métodos e propriedades para trabalhar com arquivos:

• Exists
• IsDirectory
• Name
• Length (em bytes)
• LastModified data

Você pode ler a partir do arquivo usando o IFileInfo.CreateReadStream método.

O FileProviderSample aplicativo de exemplo demonstra como configurar um provedor de arquivos para uso em Startup.ConfigureServices todo o aplicativo por meio de injeção de dependência.

Implementações do provedor de arquivos

A tabela a seguir lista as implementações do IFileProvider.

Provedor de arquivos físicos

O PhysicalFileProvider fornece acesso ao sistema de arquivos físico. PhysicalFileProvider usa o tipo System.IO.File (para o provedor físico) e define o escopo de todos os caminhos a um diretório e seus subdiretórios. Esse âmbito impede o acesso ao sistema de arquivos fora do diretório especificado e dos seus subdiretórios. O cenário mais comum para criar e usar um PhysicalFileProvider é solicitar um IFileProvider em um construtor através de injeção de dependência.

Ao instanciar esse provedor diretamente, um caminho de diretório absoluto é necessário e serve como o caminho base para todas as solicitações feitas usando o provedor. Os padrões de Glob não são suportados no caminho do diretório.

O código a seguir mostra como usar PhysicalFileProvider para obter conteúdo de diretório e informações de arquivo:

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

Tipos no exemplo anterior:

• provider é um IFileProvider.
• contents é um IDirectoryContents.
• fileInfo é um IFileInfo.

O Provedor de Arquivos pode ser usado para iterar através do diretório especificado por applicationRoot ou chamar GetFileInfo para obter as informações de um arquivo. Os padrões de Glob não podem ser passados para o GetFileInfo método. O provedor de arquivos não tem acesso fora do applicationRoot diretório.

A aplicação FileProviderSample de exemplo cria o provedor no método Startup.ConfigureServices usando IHostEnvironment.ContentRootFileProvider:

var physicalProvider = _env.ContentRootFileProvider;

Provedor de Arquivos de Manifesto Incorporados

O ManifestEmbeddedFileProvider é usado para acessar arquivos incorporados em assemblies. O ManifestEmbeddedFileProvider usa um manifesto compilado no assembly para reconstruir os caminhos originais dos arquivos incorporados.

Para gerar um manifesto dos ficheiros incorporados:

1. Adicione o pacote NuGet Microsoft.Extensions.FileProviders.Embedded no seu projeto.

2. Defina a propriedade <GenerateEmbeddedFilesManifest> como true. Especifique os arquivos a serem incorporados com <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>
   

Use padrões glob para especificar um ou mais ficheiros a serem incorporados à assemblagem.

O FileProviderSample aplicativo de exemplo cria um ManifestEmbeddedFileProvider e passa o assembly em execução no momento para seu construtor.

Startup.cs:

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

As sobrecargas adicionais permitem-lhe:

• Especifique um caminho de arquivo relativo.
• Limitar arquivos a uma data de última modificação.
• Nomeie o recurso incorporado que contém o manifesto do arquivo incorporado.

Provedor de arquivos compostos

O CompositeFileProvider combina IFileProvider instâncias, expondo uma única interface para trabalhar com arquivos de vários provedores. Ao criar o CompositeFileProvider, passe uma ou mais instâncias de IFileProvider para o respetivo construtor.

FileProviderSample No aplicativo de exemplo, a PhysicalFileProvider e a ManifestEmbeddedFileProvider fornecem arquivos para um CompositeFileProvider registrado no contêiner de serviço do aplicativo. No método do Startup.ConfigureServices projeto, é encontrado o código a seguir:

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

services.AddSingleton<IFileProvider>(compositeProvider);

Fique atento às alterações

O IFileProvider.Watch método fornece um cenário para observar um ou mais arquivos ou diretórios em busca de alterações. O método Watch:

• Aceita uma cadeia de caracteres de caminho de arquivo, que pode usar padrões glob para especificar vários arquivos.
• Retorna um IChangeToken.

O token de alteração resultante expõe:

• HasChanged: Uma propriedade que pode ser inspecionada para determinar se ocorreu uma alteração.
• RegisterChangeCallback: Chamado quando são detetadas alterações na cadeia de caracteres de caminho especificada. Cada token de alteração só chama o seu callback associado em resposta a uma única alteração. Para ativar a monitorização constante, utilize um TaskCompletionSource<TResult> (mostrado abaixo) ou recrie instâncias de IChangeToken em resposta a alterações.

A aplicação de exemplo WatchConsole escreve uma mensagem sempre que um ficheiro no diretório .txt é modificado:

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

Alguns sistemas de arquivos, como contêineres do Docker e compartilhamentos de rede, podem não enviar notificações de alteração de forma confiável. Defina a DOTNET_USE_POLLING_FILE_WATCHER variável de ambiente para 1 ou true sondar o sistema de arquivos para alterações a cada quatro segundos (não configurável).

Padrões de Glob

Os caminhos do sistema de arquivos usam padrões curinga chamados "glob" (ou "globbing"). Especifique grupos de arquivos com esses padrões. Os dois caracteres curinga são * e **:

*
Corresponde a qualquer coisa no nível de pasta atual, qualquer nome de arquivo ou qualquer extensão de arquivo. As correspondências são encerradas pelos caracteres / e . no caminho de ficheiro.

**
Corresponde a qualquer coisa em múltiplos níveis de diretórios. Pode ser usado para corresponder recursivamente muitos arquivos dentro de uma hierarquia de diretórios.

A tabela a seguir fornece exemplos comuns de padrões globais.

ASP.NET Core abstrai o acesso ao sistema de arquivos através do uso de provedores de arquivos. Os provedores de arquivos são usados em toda a estrutura ASP.NET Core:

• IHostingEnvironment Expõe a raiz de conteúdo da aplicação e a raiz web como IFileProvider tipos.
• O Middleware de Arquivo Estático usa Provedores de Arquivos para localizar arquivos estáticos.
• Razor usa Provedores de Arquivos para localizar páginas e exibições.
• As ferramentas .NET usam provedores de arquivos e padrões glob para especificar quais arquivos devem ser publicados.

Visualizar ou descarregar amostra de código (como descarregar)

Interfaces do provedor de arquivos

A interface primária é IFileProvider. IFileProvider expõe métodos para:

• Obter informações sobre o arquivo (IFileInfo).
• Obter informações de diretório (IDirectoryContents).
• Configurar notificações de alteração (usando um IChangeToken).

IFileInfo Fornece métodos e propriedades para trabalhar com arquivos:

• Exists
• IsDirectory
• Name
• Length (em bytes)
• LastModified data

Você pode ler o arquivo usando o método IFileInfo.CreateReadStream .

A aplicação de exemplo demonstra como configurar um File Provider em Startup.ConfigureServices para uso em toda a aplicação por meio de injeção de dependências.

Implementações do provedor de arquivos

Três implementações de IFileProvider estão disponíveis.

PhysicalFileProvider

O PhysicalFileProvider fornece acesso ao sistema de arquivos físico. PhysicalFileProvider usa o tipo System.IO.File (para o provedor físico) e define o escopo de todos os caminhos a um diretório e seus subdiretórios. Esse âmbito impede o acesso ao sistema de arquivos fora do diretório especificado e dos seus subdiretórios. O cenário mais comum para criar e usar um PhysicalFileProvider é solicitar um IFileProvider em um construtor através de injeção de dependência.

Ao instanciar esse provedor diretamente, um caminho de diretório é necessário e serve como o caminho base para todas as solicitações feitas usando o provedor.

O código a seguir mostra como criar um PhysicalFileProvider e usá-lo para obter conteúdo de diretório e informações de arquivo:

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

Tipos no exemplo anterior:

• provider é um IFileProvider.
• contents é um IDirectoryContents.
• fileInfo é um IFileInfo.

O Provedor de Arquivos pode ser usado para iterar através do diretório especificado por applicationRoot ou chamar GetFileInfo para obter as informações de um arquivo. O provedor de arquivos não tem acesso fora do applicationRoot diretório.

O aplicativo de exemplo cria o provedor na classe do Startup.ConfigureServices aplicativo usando IHostingEnvironment.ContentRootFileProvider:

var physicalProvider = _env.ContentRootFileProvider;

ManifestEmbeddedFileProvider

O ManifestEmbeddedFileProvider é usado para acessar arquivos incorporados em assemblies. O ManifestEmbeddedFileProvider usa um manifesto compilado no assembly para reconstruir os caminhos originais dos arquivos incorporados.

Para gerar um manifesto dos arquivos incorporados, defina a <GenerateEmbeddedFilesManifest> propriedade como true. Especifique os arquivos a serem incorporados com <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>

Use padrões glob para especificar um ou mais ficheiros a serem incorporados à assemblagem.

O aplicativo de exemplo cria um ManifestEmbeddedFileProvider e passa o assembly em execução no momento para seu construtor.

Startup.cs:

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

As sobrecargas adicionais permitem-lhe:

• Especifique um caminho de arquivo relativo.
• Limitar arquivos a uma data de última modificação.
• Nomeie o recurso incorporado que contém o manifesto do arquivo incorporado.

CompositeFileProvider

O CompositeFileProvider combina IFileProvider instâncias, expondo uma única interface para trabalhar com arquivos de vários provedores. Ao criar o CompositeFileProvider, passe uma ou mais instâncias de IFileProvider para o respetivo construtor.

No aplicativo de exemplo, a PhysicalFileProvider e a ManifestEmbeddedFileProvider fornecem arquivos para um CompositeFileProvider registrado no contêiner de serviço do aplicativo:

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

services.AddSingleton<IFileProvider>(compositeProvider);

Fique atento às alterações

O método IFileProvider.Watch fornece um cenário para observar um ou mais arquivos ou diretórios em busca de alterações. Watch Aceita uma cadeia de caracteres de caminho, que pode usar padrões glob para especificar vários arquivos. Watch retorna um IChangeToken. O token de alteração expõe:

• HasChanged: Uma propriedade que pode ser inspecionada para determinar se ocorreu uma alteração.
• RegisterChangeCallback: Chamado quando são detetadas alterações na cadeia de caracteres de caminho especificada. Cada token de alteração só chama o seu callback associado em resposta a uma única alteração. Para ativar a monitorização constante, utilize um TaskCompletionSource<TResult> (mostrado abaixo) ou recrie instâncias de IChangeToken em resposta a alterações.

No aplicativo de exemplo, o aplicativo de console WatchConsole é configurado para exibir uma mensagem sempre que um arquivo de texto é modificado:

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

Alguns sistemas de arquivos, como contêineres do Docker e compartilhamentos de rede, podem não enviar notificações de alteração de forma confiável. Defina a DOTNET_USE_POLLING_FILE_WATCHER variável de ambiente para 1 ou true sondar o sistema de arquivos para alterações a cada quatro segundos (não configurável).

Padrões de Glob

Os caminhos do sistema de arquivos usam padrões curinga chamados "glob" (ou "globbing"). Especifique grupos de arquivos com esses padrões. Os dois caracteres curinga são * e **:

*
Corresponde a qualquer coisa no nível de pasta atual, qualquer nome de arquivo ou qualquer extensão de arquivo. As correspondências são encerradas pelos caracteres / e . no caminho de ficheiro.

**
Corresponde a qualquer coisa em múltiplos níveis de diretórios. Pode ser usado para corresponder recursivamente muitos arquivos dentro de uma hierarquia de diretórios.

Exemplos de padrões Glob

directory/file.txt
Corresponde a um arquivo específico em um diretório específico.

directory/*.txt
Corresponde a todos os arquivos com .txt extensão em um diretório específico.

directory/*/appsettings.json
Corresponde a todos os appsettings.json ficheiros em diretórios exatamente um nível abaixo da pasta diretório.

directory/**/*.txt
Corresponde a todos os ficheiros com a extensão .txt encontrados em qualquer lugar na pasta diretório.