{"id":29027324,"url":"https://github.com/rameel/ramstack.fileproviders","last_synced_at":"2025-06-26T06:05:25.479Z","repository":{"id":251462285,"uuid":"837481645","full_name":"rameel/ramstack.fileproviders","owner":"rameel","description":"A lightweight .NET library of useful and convenient extensions for Microsoft.Extensions.FileProviders","archived":false,"fork":false,"pushed_at":"2025-05-18T02:47:00.000Z","size":273,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-22T01:48:51.905Z","etag":null,"topics":["fileprovider","files","filesystem","glob","globbing"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rameel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-03T05:32:47.000Z","updated_at":"2025-05-18T02:43:08.000Z","dependencies_parsed_at":"2024-08-21T18:44:11.637Z","dependency_job_id":"9e42d2cc-733d-4d94-8c69-88e4380da58e","html_url":"https://github.com/rameel/ramstack.fileproviders","commit_stats":null,"previous_names":["rameel/ramstack.fileproviders"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/rameel/ramstack.fileproviders","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameel%2Framstack.fileproviders","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameel%2Framstack.fileproviders/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameel%2Framstack.fileproviders/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameel%2Framstack.fileproviders/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rameel","download_url":"https://codeload.github.com/rameel/ramstack.fileproviders/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameel%2Framstack.fileproviders/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262010867,"owners_count":23244414,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fileprovider","files","filesystem","glob","globbing"],"created_at":"2025-06-26T06:05:24.881Z","updated_at":"2025-06-26T06:05:25.453Z","avatar_url":"https://github.com/rameel.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- TOC --\u003e\r\n* [Ramstack.FileProviders](#ramstackfileproviders)\r\n  * [Projects](#projects)\r\n    * [Ramstack.FileProviders.Extensions](#ramstackfileprovidersextensions)\r\n    * [Ramstack.FileProviders](#ramstackfileproviders-1)\r\n    * [Ramstack.FileProviders.Globbing](#ramstackfileprovidersglobbing)\r\n    * [Ramstack.FileProviders.Composition](#ramstackfileproviderscomposition)\r\n  * [Overview](#overview)\r\n    * [Ramstack.FileProviders](#ramstackfileproviders-2)\r\n      * [PrefixedFileProvider](#prefixedfileprovider)\r\n      * [SubFileProvider](#subfileprovider)\r\n      * [ZipFileProvider](#zipfileprovider)\r\n    * [Ramstack.FileProviders.Globbing](#ramstackfileprovidersglobbing-1)\r\n    * [Ramstack.FileProviders.Extensions](#ramstackfileprovidersextensions-1)\r\n    * [Ramstack.FileProviders.Composition](#ramstackfileproviderscomposition-1)\r\n      * [Flattening Providers](#flattening-providers)\r\n      * [Composing Providers](#composing-providers)\r\n      * [Flattening Change Tokens](#flattening-change-tokens)\r\n  * [NuGet Packages](#nuget-packages)\r\n  * [Supported versions](#supported-versions)\r\n  * [Contributions](#contributions)\r\n  * [License](#license)\r\n\u003c!-- TOC --\u003e\r\n\r\n# Ramstack.FileProviders\r\n\r\n`Ramstack.FileProviders` is a collection of lightweight .NET libraries that enhance file handling capabilities in .NET applications,\r\nbuilding upon `Microsoft.Extensions.FileProviders`.\r\n\r\n## Projects\r\n\r\nThis repository contains projects:\r\n\r\n### Ramstack.FileProviders.Extensions\r\nOffers useful and convenient extensions for `IFileProviders`, bringing its capabilities and experience\r\ncloser to what's provided by the `DirectoryInfo` and `FileInfo` standard classes.\r\n\r\nTo install the `Ramstack.FileProviders.Extensions` [NuGet package](https://www.nuget.org/packages/Ramstack.FileProviders.Extensions) in your project,\r\nrun the following command:\r\n```console\r\ndotnet add package Ramstack.FileProviders.Extensions\r\n```\r\n\r\n### Ramstack.FileProviders\r\nProvides additional implementations of `IFileProvider` including `PrefixedFileProvider`, `SubFileProvider`, and `ZipFileProvider`.\r\n\r\nTo install the `Ramstack.FileProviders` [NuGet package](https://www.nuget.org/packages/Ramstack.FileProviders) in your project,\r\nrun the following command:\r\n```console\r\ndotnet add package Ramstack.FileProviders\r\n```\r\n\r\n### Ramstack.FileProviders.Globbing\r\nProvides an implementation of the `IFileProvider` that filters files using include and/or exclude glob patterns\r\nfor flexible file visibility control.\r\n\r\nTo install the `Ramstack.FileProviders.Globbing` [NuGet package](https://www.nuget.org/packages/Ramstack.FileProviders.Globbing) in your project,\r\nrun the following command:\r\n```console\r\ndotnet add package Ramstack.FileProviders.Globbing\r\n```\r\n\r\n### Ramstack.FileProviders.Composition\r\nProvides a helper class for flattening and composing `IFileProvider` instances.\r\n\r\nTo install the `Ramstack.FileProviders.Composition` [NuGet package](https://www.nuget.org/packages/Ramstack.FileProviders.Composition) in your project,\r\nrun the following command:\r\n```console\r\ndotnet add package Ramstack.FileProviders.Composition\r\n```\r\n\r\n## Overview\r\n\r\n### Ramstack.FileProviders\r\n\r\nThis library offers additional implementations of the [IFileProvider](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.fileproviders.ifileprovider) interface:\r\n\r\n- `SubFileProvider`\r\n- `PrefixedFileProvider`\r\n- `ZipFileProvider`\r\n\r\n#### PrefixedFileProvider\r\n\r\n`PrefixedFileProvider` allows you to apply a prefix to the paths of files and directories.\r\nThis is useful when you need to organize files in a virtual hierarchy.\r\n\r\nExample:\r\n```csharp\r\nIFileProvider provider = new PrefixedFileProvider(innerProvider, \"/project/app\");\r\nIFileInfo file = provider.GetFileInfo(\"/project/app/docs/README\");\r\nConsole.WriteLine(file.Exists);\r\n```\r\n\r\nThis is how you can add virtual directories to your project that are external to the project root:\r\n```csharp\r\nstring packagesPath = Path.Combine(environment.ContentRootPath, \"../Packages\");\r\nstring themesPath   = Path.Combine(environment.ContentRootPath, \"../Themes\");\r\n\r\nenvironment.ContentRootFileProvider = new CompositeFileProvider(\r\n    new PrefixedFileProvider(\"/Packages\", new PhysicalFileProvider(packagesPath)),\r\n    new PrefixedFileProvider(\"/Themes\",   new PhysicalFileProvider(themesPath)),\r\n    environment.ContentRootFileProvider);\r\n```\r\nThe `Packages` and `Themes` directories are now available to the ASP.NET infrastructure under their respective names,\r\nas if they were originally defined within your project.\r\n\r\n**Before:**\r\n```\r\n/App\r\n├── Controllers\r\n├── Models\r\n├── Views\r\n└── wwwroot\r\n\r\n/Packages\r\n├── package-1\r\n└── package-2\r\n\r\n/Themes\r\n├── theme-1\r\n└── theme-2\r\n```\r\n\r\n**After:**\r\n```\r\n/App\r\n├── Controllers\r\n├── Models\r\n├── Views\r\n├── Packages         \u003c-- (virtual)\r\n│   ├── package1\r\n│   └── package2\r\n├── Themes           \u003c-- (virtual)\r\n│   ├── theme1\r\n│   └── theme2\r\n└── wwwroot\r\n```\r\n\r\n#### SubFileProvider\r\n\r\n`SubFileProvider` lets you limit the view of the file system to a specific subdirectory, effectively creating a sandbox.\r\n\r\nExample:\r\n```csharp\r\nIFileProvider provider = new SubFileProvider(innerProvider, \"/docs\");\r\nIFileInfo file = provider.GetFileInfo(\"/README\");\r\nConsole.WriteLine(file.Exists);\r\n```\r\n\r\n#### ZipFileProvider\r\n\r\n`ZipFileProvider` enables access to files within ZIP archives as if they were part of the file system.\r\n\r\nExample:\r\n```csharp\r\nIFileProvider provider = new ZipFileProvider(\"/path/to/archive.zip\");\r\nforeach (IFileInfo file in provider.GetDirectoryContents(\"/\"))\r\n    Console.WriteLine(file.Name);\r\n```\r\n\r\n### Ramstack.FileProviders.Globbing\r\n\r\n`GlobbingFileProvider` class filters files using include and/or exclude glob patterns. Include patterns make only matching files visible,\r\nwhile exclude patterns hide specific files. Both include and exclude patterns can be combined for flexible file visibility control.\r\n\r\nIt relies on the [Ramstack.Globbing](https://www.nuget.org/packages/Ramstack.Globbing) package for its globbing capabilities.\r\n\r\nExample:\r\n```csharp\r\nIFileProvider provider = new GlobbingFileProvider(innerProvider, patterns: [\"**/*.txt\", \"docs/*.md\" ], excludes: [\"**/README.md\"]);\r\nforeach (IFileInfo file in provider.GetDirectoryContents(\"/\"))\r\n    Console.WriteLine(file.Name);\r\n```\r\n\r\n### Ramstack.FileProviders.Extensions\r\n\r\nProvides useful extensions for `IFileProvider`, bringing its capabilities and experience closer to what's being\r\nprovided by `DirectoryInfo` and `FileInfo` classes.\r\n\r\nSimply stated, a `FileNode` knows which directory it is located in, and a directory represented by the `DirectoryNode` class can access\r\nits parent directory and list all files within it, recursively.\r\n\r\n```csharp\r\nusing Ramstack.FileProviders;\r\n\r\nFileNode file = provider.GetFile(\"/docs/README\");\r\n\r\n// Prints the full path of the given file\r\nConsole.WriteLine($\"Reading: {file.FullName}\");\r\n\r\nusing StreamReader reader = file.OpenText();\r\nConsole.WriteLine(reader.ReadToEnd());\r\n```\r\n\r\n```csharp\r\nDirectoryNode directory = provider.GetDirectory(\"/docs\");\r\n\r\nforeach (FileNode file in directory.EnumerateFiles())\r\n    Console.WriteLine(file.FullName);\r\n```\r\n\r\nFurthermore, the methods for enumerating files (`EnumerateFiles`/`EnumerateDirectories`/`EnumerateFileNodes`) allow specifying glob patterns\r\nto search for the desired files, as well as patterns to exclude files from the resulting list.\r\n\r\n```csharp\r\nDirectoryNode directory = provider.GetDirectory(\"/project\");\r\n\r\n// Finds all *.md files and converts them to HTML\r\nforeach (FileNode file in directory.EnumerateFiles(pattern: \"**/*.md\"))\r\n    RenderMarkdown(file);\r\n\r\n// Excludes files in a specific folder\r\nforeach (FileNode file in directory.EnumerateFiles(pattern: \"**/*.md\", exclude: \"vendors/**\"))\r\n    RenderMarkdown(file);\r\n```\r\nFor convenience, many methods specific to `DirectoryNode` or `FileNode` are also available for `IFileProvider`.\r\n\r\nThus, if we know the directory in which to look for files or the file to read, there is no need to obtain the\r\n`DirectoryNode` or `FileNode` object.\r\n\r\n```csharp\r\nusing StreamReader reader = provider.OpenText(\"/docs/README\", Encoding.UTF8);\r\nConsole.WriteLine(reader.ReadToEnd());\r\n\r\n// Finds all *.md files and converts them to HTML\r\nforeach (FileNode file in provider.EnumerateFiles(\"/project\", pattern: \"**/*.md\"))\r\n    RenderMarkdown(file);\r\n```\r\n\r\n### Ramstack.FileProviders.Composition\r\n\r\nProvides a helper class `FileProviderComposer` for flattening and composing `IFileProvider` instances.\r\n\r\n#### Flattening Providers\r\n\r\nThe `FlattenProvider` method attempts to flatten a given `IFileProvider` into a single list of file providers.\r\n\r\nThis is especially useful when dealing with nested `CompositeFileProvider` instances, which might have been created during\r\ndifferent stages of a pipeline or configuration. Flattening helps in removing unnecessary indirectness and improving efficiency\r\nby consolidating all file providers into a single level.\r\n\r\n```csharp\r\nvar builder = WebApplication.CreateBuilder(args);\r\n\r\n// Application pipeline configuration\r\n...\r\n\r\nbuilder.Environment.ContentRootFileProvider = FileProviderComposer.FlattenProvider(\r\n    builder.Environment.ContentRootFileProvider);\r\n```\r\n\r\n#### Composing Providers\r\n\r\nThe `ComposeProviders` method combines a list of `IFileProvider` instances into a single `IFileProvider`.\r\nDuring this process, all encountered `CompositeFileProvider` instances recursively flattened and merged into a single level.\r\nThis eliminates unnecessary indirectness and streamline the file provider hierarchy.\r\n\r\n```csharp\r\nstring packagesPath = Path.Combine(environment.ContentRootPath, \"../Packages\");\r\nstring themesPath   = Path.Combine(environment.ContentRootPath, \"../Themes\");\r\n\r\nenvironment.ContentRootFileProvider = FileProviderComposer.ComposeProviders(\r\n    // Inject external Modules directory\r\n    new PrefixedFileProvider(\"/Packages\", new PhysicalFileProvider(packagesPath)),\r\n\r\n    // Inject external Themes directory\r\n    new PrefixedFileProvider(\"/Themes\", new PhysicalFileProvider(themesPath)),\r\n\r\n    // Current provider\r\n    environment.ContentRootFileProvider);\r\n```\r\n\r\nIn this example, the `ComposeProviders` method handles any unnecessary nesting that might occur, including when the current\r\n`environment.ContentRootFileProvider` is a `CompositeFileProvider`. This ensures that all file providers merged into a single\r\nflat structure, avoiding unnecessary indirectness.\r\n\r\n#### Flattening Change Tokens\r\nThe `Flatten` extension method optimizes the structure of change token hierarchies by flattening nested `CompositeChangeToken` instances\r\nand, most importantly, automatically filters out `NullChangeToken` instances from the hierarchy. Unlike standard `CompositeChangeToken`\r\nbehavior, which retains and processes `NullChangeToken` instances unnecessarily, this utility removes them completely,\r\nresulting in improved performance and simplified change notification chains.\r\n\r\n```csharp\r\nvar changeToken = compositeFileProvider.Watch(\"**/*.json\").Flatten();\r\n```\r\n\r\n\r\n## NuGet Packages\r\n- [Ramstack.FileProviders.Extensions](https://www.nuget.org/packages/Ramstack.FileProviders.Extensions) — Useful and convenient extensions for `IFileProvider`, bringing its capabilities and experience closer to what's provided by the `DirectoryInfo` and `FileInfo` classes.\r\n- [Ramstack.FileProviders](https://www.nuget.org/packages/Ramstack.FileProviders) — Additional file providers, including `ZipFileProvider`, `PrefixedFileProvider`, and `SubFileProvider`.\r\n- [Ramstack.FileProviders.Globbing](https://www.nuget.org/packages/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.\r\n- [Ramstack.FileProviders.Composition](https://www.nuget.org/packages/Ramstack.FileProviders.Composition) — Provides a helper class for flattening and composing `IFileProvider`.\r\n\r\n## Supported versions\r\n\r\n|      | Version    |\r\n|------|------------|\r\n| .NET | 6, 7, 8, 9 |\r\n\r\n## Contributions\r\n\r\nBug reports and contributions are welcome.\r\n\r\n## License\r\n\r\nThis project is released as open source under the **MIT License**.\r\nSee the [LICENSE](https://github.com/rameel/ramstack.fileproviders/blob/main/LICENSE) file for more details.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frameel%2Framstack.fileproviders","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frameel%2Framstack.fileproviders","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frameel%2Framstack.fileproviders/lists"}