--- title: File Providers in ASP.NET Core author: guardrex description: Learn how ASP.NET Core abstracts file system access through the use of File Providers. monikerRange: '>= aspnetcore-2.1' ms.author: riande ms.custom: mvc ms.date: 08/26/2019 uid: fundamentals/file-providers --- # File Providers in ASP.NET Core By [Steve Smith](https://ardalis.com/) and [Luke Latham](https://github.com/guardrex) ::: moniker range=">= aspnetcore-3.0" ASP.NET Core abstracts file system access through the use of File Providers. File Providers are used throughout the ASP.NET Core framework: * `IWebHostEnvironment` exposes the app's content root and web root as `IFileProvider` types. * [Static File Middleware](xref:fundamentals/static-files) uses File Providers to locate static files. * [Razor](xref:mvc/views/razor) uses File Providers to locate pages and views. * .NET Core tooling uses File Providers and glob patterns to specify which files should be published. [View or download sample code](https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/fundamentals/file-providers/samples) ([how to download](xref:index#how-to-download-a-sample)) ## File Provider interfaces The primary interface is . `IFileProvider` exposes methods to: * Obtain file information (). * Obtain directory information (). * Set up change notifications (using an ). `IFileInfo` provides methods and properties for working with files: * * * * (in bytes) * date You can read from the file using the [IFileInfo.CreateReadStream](xref:Microsoft.Extensions.FileProviders.IFileInfo.CreateReadStream*) method. The sample app demonstrates how to configure a File Provider in `Startup.ConfigureServices` for use throughout the app via [dependency injection](xref:fundamentals/dependency-injection). ## File Provider implementations Three implementations of `IFileProvider` are available. | Implementation | Description | | -------------- | ----------- | | [PhysicalFileProvider](#physicalfileprovider) | The physical provider is used to access the system's physical files. | | [ManifestEmbeddedFileProvider](#manifestembeddedfileprovider) | The manifest embedded provider is used to access files embedded in assemblies. | | [CompositeFileProvider](#compositefileprovider) | The composite provider is used to provide combined access to files and directories from one or more other providers. | ### PhysicalFileProvider The provides access to the physical file system. `PhysicalFileProvider` uses the type (for the physical provider) and scopes all paths to a directory and its children. This scoping prevents access to the file system outside of the specified directory and its children. The most common scenario for creating and using a `PhysicalFileProvider` is to request an `IFileProvider` in a constructor through [dependency injection](xref:fundamentals/dependency-injection). When instantiating this provider directly, a directory path is required and serves as the base path for all requests made using the provider. The following code shows how to create a `PhysicalFileProvider` and use it to obtain directory contents and file information: ```csharp var provider = new PhysicalFileProvider(applicationRoot); var contents = provider.GetDirectoryContents(string.Empty); var fileInfo = provider.GetFileInfo("wwwroot/js/site.js"); ``` Types in the preceding example: * `provider` is an `IFileProvider`. * `contents` is an `IDirectoryContents`. * `fileInfo` is an `IFileInfo`. The File Provider can be used to iterate through the directory specified by `applicationRoot` or call `GetFileInfo` to obtain a file's information. The File Provider has no access outside of the `applicationRoot` directory. The sample app creates the provider in the app's `Startup.ConfigureServices` class using [IHostingEnvironment.ContentRootFileProvider](xref:Microsoft.Extensions.Hosting.IHostingEnvironment.ContentRootFileProvider): ```csharp var physicalProvider = _env.ContentRootFileProvider; ``` ### ManifestEmbeddedFileProvider The is used to access files embedded within assemblies. The `ManifestEmbeddedFileProvider` uses a manifest compiled into the assembly to reconstruct the original paths of the embedded files. Add a package reference to the project for the [Microsoft.Extensions.FileProviders.Embedded](https://www.nuget.org/packages/Microsoft.Extensions.FileProviders.Embedded) package. To generate a manifest of the embedded files, set the `` property to `true`. Specify the files to embed with [\](/dotnet/core/tools/csproj#default-compilation-includes-in-net-core-projects): [!code-csharp[](file-providers/samples/3.x/FileProviderSample/FileProviderSample.csproj?highlight=6,14)] Use [glob patterns](#glob-patterns) to specify one or more files to embed into the assembly. The sample app creates an `ManifestEmbeddedFileProvider` and passes the currently executing assembly to its constructor. *Startup.cs*: ```csharp var manifestEmbeddedProvider = new ManifestEmbeddedFileProvider(Assembly.GetEntryAssembly()); ``` Additional overloads allow you to: * Specify a relative file path. * Scope files to a last modified date. * Name the embedded resource containing the embedded file manifest. | Overload | Description | | -------- | ----------- | | `ManifestEmbeddedFileProvider(Assembly, String)` | Accepts an optional `root` relative path parameter. Specify the `root` to scope calls to to those resources under the provided path. | | `ManifestEmbeddedFileProvider(Assembly, String, DateTimeOffset)` | Accepts an optional `root` relative path parameter and a `lastModified` date () parameter. The `lastModified` date scopes the last modification date for the instances returned by the . | | `ManifestEmbeddedFileProvider(Assembly, String, String, DateTimeOffset)` | Accepts an optional `root` relative path, `lastModified` date, and `manifestName` parameters. The `manifestName` represents the name of the embedded resource containing the manifest. | ### CompositeFileProvider The combines `IFileProvider` instances, exposing a single interface for working with files from multiple providers. When creating the `CompositeFileProvider`, pass one or more `IFileProvider` instances to its constructor. In the sample app, a `PhysicalFileProvider` and a `ManifestEmbeddedFileProvider` provide files to a `CompositeFileProvider` registered in the app's service container: [!code-csharp[](file-providers/samples/3.x/FileProviderSample/Startup.cs?name=snippet1)] ## Watch for changes The [IFileProvider.Watch](xref:Microsoft.Extensions.FileProviders.IFileProvider.Watch*) method provides a scenario to watch one or more files or directories for changes. `Watch` accepts a path string, which can use [glob patterns](#glob-patterns) to specify multiple files. `Watch` returns an . The change token exposes: * – A property that can be inspected to determine if a change has occurred. * – Called when changes are detected to the specified path string. Each change token only calls its associated callback in response to a single change. To enable constant monitoring, use a (shown below) or recreate `IChangeToken` instances in response to changes. In the sample app, the *WatchConsole* console app is configured to display a message whenever a text file is modified: [!code-csharp[](file-providers/samples/3.x/WatchConsole/Program.cs?name=snippet1&highlight=1-2,16,19-20)] Some file systems, such as Docker containers and network shares, may not reliably send change notifications. Set the `DOTNET_USE_POLLING_FILE_WATCHER` environment variable to `1` or `true` to poll the file system for changes every four seconds (not configurable). ## Glob patterns File system paths use wildcard patterns called *glob (or globbing) patterns*. Specify groups of files with these patterns. The two wildcard characters are `*` and `**`: **`*`** Matches anything at the current folder level, any filename, or any file extension. Matches are terminated by `/` and `.` characters in the file path. **`**`** Matches anything across multiple directory levels. Can be used to recursively match many files within a directory hierarchy. **Glob pattern examples** **`directory/file.txt`** Matches a specific file in a specific directory. **`directory/*.txt`** Matches all files with *.txt* extension in a specific directory. **`directory/*/appsettings.json`** Matches all `appsettings.json` files in directories exactly one level below the *directory* folder. **`directory/**/*.txt`** Matches all files with *.txt* extension found anywhere under the *directory* folder. ::: moniker-end ::: moniker range="< aspnetcore-3.0" ASP.NET Core abstracts file system access through the use of File Providers. File Providers are used throughout the ASP.NET Core framework: * exposes the app's content root and web root as `IFileProvider` types. * [Static File Middleware](xref:fundamentals/static-files) uses File Providers to locate static files. * [Razor](xref:mvc/views/razor) uses File Providers to locate pages and views. * .NET Core tooling uses File Providers and glob patterns to specify which files should be published. [View or download sample code](https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/fundamentals/file-providers/samples) ([how to download](xref:index#how-to-download-a-sample)) ## File Provider interfaces The primary interface is . `IFileProvider` exposes methods to: * Obtain file information (). * Obtain directory information (). * Set up change notifications (using an ). `IFileInfo` provides methods and properties for working with files: * * * * (in bytes) * date You can read from the file using the [IFileInfo.CreateReadStream](xref:Microsoft.Extensions.FileProviders.IFileInfo.CreateReadStream*) method. The sample app demonstrates how to configure a File Provider in `Startup.ConfigureServices` for use throughout the app via [dependency injection](xref:fundamentals/dependency-injection). ## File Provider implementations Three implementations of `IFileProvider` are available. | Implementation | Description | | -------------- | ----------- | | [PhysicalFileProvider](#physicalfileprovider) | The physical provider is used to access the system's physical files. | | [ManifestEmbeddedFileProvider](#manifestembeddedfileprovider) | The manifest embedded provider is used to access files embedded in assemblies. | | [CompositeFileProvider](#compositefileprovider) | The composite provider is used to provide combined access to files and directories from one or more other providers. | ### PhysicalFileProvider The provides access to the physical file system. `PhysicalFileProvider` uses the type (for the physical provider) and scopes all paths to a directory and its children. This scoping prevents access to the file system outside of the specified directory and its children. The most common scenario for creating and using a `PhysicalFileProvider` is to request an `IFileProvider` in a constructor through [dependency injection](xref:fundamentals/dependency-injection). When instantiating this provider directly, a directory path is required and serves as the base path for all requests made using the provider. The following code shows how to create a `PhysicalFileProvider` and use it to obtain directory contents and file information: ```csharp var provider = new PhysicalFileProvider(applicationRoot); var contents = provider.GetDirectoryContents(string.Empty); var fileInfo = provider.GetFileInfo("wwwroot/js/site.js"); ``` Types in the preceding example: * `provider` is an `IFileProvider`. * `contents` is an `IDirectoryContents`. * `fileInfo` is an `IFileInfo`. The File Provider can be used to iterate through the directory specified by `applicationRoot` or call `GetFileInfo` to obtain a file's information. The File Provider has no access outside of the `applicationRoot` directory. The sample app creates the provider in the app's `Startup.ConfigureServices` class using [IHostingEnvironment.ContentRootFileProvider](xref:Microsoft.Extensions.Hosting.IHostingEnvironment.ContentRootFileProvider): ```csharp var physicalProvider = _env.ContentRootFileProvider; ``` ### ManifestEmbeddedFileProvider The is used to access files embedded within assemblies. The `ManifestEmbeddedFileProvider` uses a manifest compiled into the assembly to reconstruct the original paths of the embedded files. To generate a manifest of the embedded files, set the `` property to `true`. Specify the files to embed with [<EmbeddedResource>](/dotnet/core/tools/csproj#default-compilation-includes-in-net-core-projects): [!code-csharp[](file-providers/samples/2.x/FileProviderSample/FileProviderSample.csproj?highlight=6,14)] Use [glob patterns](#glob-patterns) to specify one or more files to embed into the assembly. The sample app creates an `ManifestEmbeddedFileProvider` and passes the currently executing assembly to its constructor. *Startup.cs*: ```csharp var manifestEmbeddedProvider = new ManifestEmbeddedFileProvider(Assembly.GetEntryAssembly()); ``` Additional overloads allow you to: * Specify a relative file path. * Scope files to a last modified date. * Name the embedded resource containing the embedded file manifest. | Overload | Description | | -------- | ----------- | | `ManifestEmbeddedFileProvider(Assembly, String)` | Accepts an optional `root` relative path parameter. Specify the `root` to scope calls to to those resources under the provided path. | | `ManifestEmbeddedFileProvider(Assembly, String, DateTimeOffset)` | Accepts an optional `root` relative path parameter and a `lastModified` date () parameter. The `lastModified` date scopes the last modification date for the instances returned by the . | | `ManifestEmbeddedFileProvider(Assembly, String, String, DateTimeOffset)` | Accepts an optional `root` relative path, `lastModified` date, and `manifestName` parameters. The `manifestName` represents the name of the embedded resource containing the manifest. | ### CompositeFileProvider The combines `IFileProvider` instances, exposing a single interface for working with files from multiple providers. When creating the `CompositeFileProvider`, pass one or more `IFileProvider` instances to its constructor. In the sample app, a `PhysicalFileProvider` and a `ManifestEmbeddedFileProvider` provide files to a `CompositeFileProvider` registered in the app's service container: [!code-csharp[](file-providers/samples/2.x/FileProviderSample/Startup.cs?name=snippet1)] ## Watch for changes The [IFileProvider.Watch](xref:Microsoft.Extensions.FileProviders.IFileProvider.Watch*) method provides a scenario to watch one or more files or directories for changes. `Watch` accepts a path string, which can use [glob patterns](#glob-patterns) to specify multiple files. `Watch` returns an . The change token exposes: * – A property that can be inspected to determine if a change has occurred. * – Called when changes are detected to the specified path string. Each change token only calls its associated callback in response to a single change. To enable constant monitoring, use a (shown below) or recreate `IChangeToken` instances in response to changes. In the sample app, the *WatchConsole* console app is configured to display a message whenever a text file is modified: [!code-csharp[](file-providers/samples/2.x/WatchConsole/Program.cs?name=snippet1&highlight=1-2,16,19-20)] Some file systems, such as Docker containers and network shares, may not reliably send change notifications. Set the `DOTNET_USE_POLLING_FILE_WATCHER` environment variable to `1` or `true` to poll the file system for changes every four seconds (not configurable). ## Glob patterns File system paths use wildcard patterns called *glob (or globbing) patterns*. Specify groups of files with these patterns. The two wildcard characters are `*` and `**`: **`*`** Matches anything at the current folder level, any filename, or any file extension. Matches are terminated by `/` and `.` characters in the file path. **`**`** Matches anything across multiple directory levels. Can be used to recursively match many files within a directory hierarchy. **Glob pattern examples** **`directory/file.txt`** Matches a specific file in a specific directory. **`directory/*.txt`** Matches all files with *.txt* extension in a specific directory. **`directory/*/appsettings.json`** Matches all `appsettings.json` files in directories exactly one level below the *directory* folder. **`directory/**/*.txt`** Matches all files with *.txt* extension found anywhere under the *directory* folder. ::: moniker-end