Ramstack.FileProviders is a collection of lightweight .NET libraries that enhance file handling capabilities in .NET applications,
building upon Microsoft.Extensions.FileProviders.
This repository contains the following projects:
Offers useful and convenient extensions for IFileProvider, bringing its capabilities and experience
closer to what's provided by the DirectoryInfo and FileInfo classes.
To install the Ramstack.FileProviders.ExtensionsNuGet package in your project,
run the following command:
dotnet add package Ramstack.FileProviders.ExtensionsProvides additional implementations of IFileProvider including PrefixedFileProvider and SubFileProvider.
To install the Ramstack.FileProvidersNuGet package in your project,
run the following command:
dotnet add package Ramstack.FileProvidersProvides an implementation of the IFileProvider that filters files using include and/or exclude glob patterns
for flexible file visibility control.
To install the Ramstack.FileProviders.GlobbingNuGet package in your project,
run the following command:
dotnet add package Ramstack.FileProviders.GlobbingProvides a helper class for flattening and composing IFileProvider instances.
To install the Ramstack.FileProviders.CompositionNuGet package in your project,
run the following command:
dotnet add package Ramstack.FileProviders.CompositionThis library offers additional implementations of the IFileProvider interface:
SubFileProviderPrefixedFileProvider
PrefixedFileProvider allows you to apply a prefix to the paths of files and directories.
This is useful when you need to organize files in a virtual hierarchy.
Example:
IFileProviderprovider=newPrefixedFileProvider("/project/app",innerProvider);IFileInfofile=provider.GetFileInfo("/project/app/docs/README");Console.WriteLine(file.Exists);This is how you can add virtual directories to your project that are outside the project root:
stringpackagesPath=Path.Combine(environment.ContentRootPath,"../Packages");stringthemesPath=Path.Combine(environment.ContentRootPath,"../Themes");environment.ContentRootFileProvider=newCompositeFileProvider(newPrefixedFileProvider("/Packages",newPhysicalFileProvider(packagesPath)),newPrefixedFileProvider("/Themes",newPhysicalFileProvider(themesPath)),environment.ContentRootFileProvider);The Packages and Themes directories are now available to the ASP.NET infrastructure under their respective names,
as if they were originally defined within your project.
Before:
/App
├── Controllers
├── Models
├── Views
└── wwwroot
/Packages
├── package-1
└── package-2
/Themes
├── theme-1
└── theme-2
After:
/App
├── Controllers
├── Models
├── Views
├── Packages <-- (virtual)
│ ├── package-1
│ └── package-2
├── Themes <-- (virtual)
│ ├── theme-1
│ └── theme-2
└── wwwroot
SubFileProvider lets you limit the view of the file system to a specific subdirectory, effectively creating a sandbox.
Example:
IFileProviderprovider=newSubFileProvider("/docs",innerProvider);IFileInfofile=provider.GetFileInfo("/README");Console.WriteLine(file.Exists);The GlobbingFileProvider class filters files using include and/or exclude glob patterns. Include patterns make only matching files visible,
while exclude patterns hide specific files. Both include and exclude patterns can be combined for flexible file visibility control.
It relies on the Ramstack.Globbing package for its globbing capabilities.
Example:
IFileProviderprovider=newGlobbingFileProvider(innerProvider,patterns:["**/*.txt","docs/*.md"],excludes:["**/README.md"]);foreach(IFileInfofileinprovider.GetDirectoryContents("/"))Console.WriteLine(file.Name);Provides useful extensions for IFileProvider, bringing its capabilities and experience closer to what's
provided by the DirectoryInfo and FileInfo classes.
Simply stated, a FileNode knows which directory it is located in, and a directory represented by the DirectoryNode class can access
its parent directory and list all files within it, recursively.
usingRamstack.FileProviders;FileNodefile=provider.GetFile("/docs/README");// Prints the full path of the given fileConsole.WriteLine($"Reading: {file.FullName}");usingStreamReaderreader=file.OpenText();Console.WriteLine(reader.ReadToEnd());DirectoryNodedirectory=provider.GetDirectory("/docs");foreach(FileNodefileindirectory.EnumerateFiles())Console.WriteLine(file.FullName);Furthermore, the methods for enumerating files (EnumerateFiles/EnumerateDirectories/EnumerateFileNodes) allow specifying glob patterns
to search for the desired files, as well as patterns to exclude files from the resulting list.
DirectoryNodedirectory=provider.GetDirectory("/project");// Finds all *.md files and converts them to HTMLforeach(FileNodefileindirectory.EnumerateFiles(pattern:"**/*.md"))RenderMarkdown(file);// Excludes files in a specific folderforeach(FileNodefileindirectory.EnumerateFiles(pattern:"**/*.md",exclude:"vendors/**"))RenderMarkdown(file);For convenience, many methods specific to DirectoryNode or FileNode are also available for IFileProvider.
Thus, if we know the directory in which to look for files or the file to read, there is no need to obtain the
DirectoryNode or FileNode object.
usingStreamReaderreader=provider.OpenText("/docs/README",Encoding.UTF8);Console.WriteLine(reader.ReadToEnd());// Finds all *.md files and converts them to HTMLforeach(FileNodefileinprovider.EnumerateFiles("/project",pattern:"**/*.md"))RenderMarkdown(file);Provides a helper class FileProviderComposer for flattening and composing IFileProvider instances.
The FlattenProvider method attempts to flatten a given IFileProvider into a single list of file providers.
This is especially useful when dealing with nested CompositeFileProvider instances, which might have been created during
different stages of a pipeline or configuration. Flattening helps in removing unnecessary indirectness and improving efficiency
by consolidating all file providers into a single level.
varbuilder=WebApplication.CreateBuilder(args);// Application pipeline configuration
...builder.Environment.ContentRootFileProvider=FileProviderComposer.FlattenProvider(builder.Environment.ContentRootFileProvider);The ComposeProviders method combines a list of IFileProvider instances into a single IFileProvider.
During this process, all encountered CompositeFileProvider instances are recursively flattened and merged into a single level.
This eliminates unnecessary indirectness and streamlines the file provider hierarchy.
stringpackagesPath=Path.Combine(environment.ContentRootPath,"../Packages");stringthemesPath=Path.Combine(environment.ContentRootPath,"../Themes");environment.ContentRootFileProvider=FileProviderComposer.ComposeProviders(// Inject external Packages directorynewPrefixedFileProvider("/Packages",newPhysicalFileProvider(packagesPath)),// Inject external Themes directorynewPrefixedFileProvider("/Themes",newPhysicalFileProvider(themesPath)),// Current providerenvironment.ContentRootFileProvider);In this example, the ComposeProviders method handles any unnecessary nesting that might occur, including when the current
environment.ContentRootFileProvider is a CompositeFileProvider. This ensures that all file providers are merged into a single
flat structure, avoiding unnecessary indirectness.
The Flatten extension method optimizes the structure of change token hierarchies by flattening nested CompositeChangeToken instances
and, most importantly, automatically filters out NullChangeToken instances from the hierarchy. Unlike standard CompositeChangeToken
behavior, which retains and processes NullChangeToken instances unnecessarily, this utility removes them completely,
resulting in improved performance and simplified change notification chains.
varchangeToken=compositeFileProvider.Watch("**/*.json").Flatten();- Ramstack.FileProviders.Extensions — Useful and convenient extensions for
IFileProvider, bringing its capabilities and experience closer to what's provided by theDirectoryInfoandFileInfoclasses. - Ramstack.FileProviders — Additional file providers, including
PrefixedFileProviderandSubFileProvider. - Ramstack.FileProviders.Globbing — A file provider that filters files using include and/or exclude glob patterns. Include patterns make only matching files visible, while exclude patterns hide specific files. Both include and exclude patterns can be combined for flexible file visibility control.
- Ramstack.FileProviders.Composition — Provides a helper class for flattening and composing
IFileProvider.
| Version | |
|---|---|
| .NET | 6, 7, 8, 9, 10 |
Bug reports and contributions are welcome.
This project is released as open source under the MIT License. See the LICENSE file for more details.