{"id":29026768,"url":"https://github.com/rameel/ramstack.filesystem","last_synced_at":"2026-04-02T22:30:25.810Z","repository":{"id":253965327,"uuid":"845065816","full_name":"rameel/ramstack.filesystem","owner":"rameel","description":"A .NET library that provides an abstraction for virtual file systems, including built-in implementations.","archived":false,"fork":false,"pushed_at":"2025-04-23T20:03:20.000Z","size":406,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-23T21:49:30.919Z","etag":null,"topics":["amazon-s3","azure","azure-storage","fileprovider","files","filesystem","s3-storage","virtualfilesystem"],"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-20T14:10:41.000Z","updated_at":"2025-04-23T20:02:47.000Z","dependencies_parsed_at":"2024-08-29T11:29:58.373Z","dependency_job_id":"91b691bf-f444-4d7a-894a-95f09d056869","html_url":"https://github.com/rameel/ramstack.filesystem","commit_stats":null,"previous_names":["rameel/ramstack.filesystem"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/rameel/ramstack.filesystem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameel%2Framstack.filesystem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameel%2Framstack.filesystem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameel%2Framstack.filesystem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameel%2Framstack.filesystem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rameel","download_url":"https://codeload.github.com/rameel/ramstack.filesystem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameel%2Framstack.filesystem/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261601478,"owners_count":23183092,"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":["amazon-s3","azure","azure-storage","fileprovider","files","filesystem","s3-storage","virtualfilesystem"],"created_at":"2025-06-26T06:01:00.106Z","updated_at":"2026-04-02T22:30:25.804Z","avatar_url":"https://github.com/rameel.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ramstack.FileSystem\r\n[![NuGet](https://img.shields.io/nuget/v/Ramstack.FileSystem.Abstractions.svg)](https://nuget.org/packages/Ramstack.FileSystem.Abstractions)\r\n[![MIT](https://img.shields.io/github/license/rameel/ramstack.filesystem)](https://github.com/rameel/ramstack.filesystem/blob/main/LICENSE)\r\n\r\nA .NET library providing a virtual file system abstraction.\r\n\r\n**For current implementations, see [Related Projects](#related-projects)**\r\n\r\n## Overview\r\n\r\nThe primary interface is `IVirtualFileSystem`, which exposes methods to:\r\n- Access files (`VirtualFile`).\r\n- Access directories (`VirtualDirectory`).\r\n\r\n### VirtualFile\r\n\r\nThe `VirtualFile` class provides properties and methods for creating, deleting, copying, and opening files within the virtual file system.\r\n\r\n```csharp\r\nusing Ramstack.FileSystem;\r\n\r\npublic class Program\r\n{\r\n    public static async Task Sample(IVirtualFileSystem fs)\r\n    {\r\n        var file = fs.GetFile(\"/sample/hello.txt\");\r\n\r\n        Console.WriteLine($\"Writing 'Hello, World!' to '{file.FullName}'\");\r\n\r\n        await using (Stream stream = await file.OpenWriteAsync())\r\n        await using (StreamWriter writer = new StreamWriter(stream))\r\n        {\r\n            await writer.WriteLineAsync(\"Hello, World!\");\r\n        }\r\n\r\n        Console.WriteLine($\"Reading contents of '{file.FullName}'\");\r\n        using (StreamReader reader = await file.OpenTextAsync())\r\n        {\r\n            Console.WriteLine(await reader.ReadToEndAsync());\r\n        }\r\n\r\n        // Replace content of the file with data from an existing file\r\n        await using FileStream input = File.OpenRead(@\"D:\\sample\\hello-world.txt\");\r\n        await file.WriteAsync(input, overwrite: true);\r\n\r\n        Console.WriteLine($\"The file '{file.Name}' has a length of {await file.GetLengthAsync()} bytes\");\r\n\r\n        Console.WriteLine($\"Deleting file '{file.FullName}'\");\r\n        await file.DeleteAsync();\r\n    }\r\n}\r\n```\r\n\r\nThe `VirtualFile` class provides the following properties to retrieve information about a file:\r\n- `FileSystem`: Gets the `IVirtualFileSystem` associated with the file.\r\n- `Directory`: Gets the `VirtualDirectory` representing the parent directory.\r\n- `DirectoryName`: Gets the full path of the parent directory.\r\n- `IsReadOnly`: Indicates whether the file is read-only.\r\n- `Name`: Gets the name of the file.\r\n- `Extension`: Gets the extension of the file.\r\n\r\nThe `VirtualFile` class also exposes a `GetPropertiesAsync` method to retrieve file properties:\r\n- `Length`: Gets the size of the file in bytes.\r\n- `Exists`: Indicates whether the file exists.\r\n- `CreationTime`: Gets the creation time of the file.\r\n- `LastAccessTime`: Gets the last access time of the file.\r\n- `LastWriteTime`: Gets the last modification time of the file.\r\n\r\nFor convenience, many methods specific to `VirtualFile` are also available as extension methods on `IVirtualFileSystem`.\r\n\r\nFor example, if we know the path of the file we want to read, we don't need to obtain a `VirtualFile` object explicitly:\r\n```csharp\r\nusing StreamReader reader = await fs.OpenTextAsync(\"/docs/README\", Encoding.UTF8);\r\nConsole.WriteLine(await reader.ReadToEndAsync());\r\n```\r\n\r\n### VirtualDirectory\r\n\r\nThe `VirtualDirectory` class provides properties and methods for creating, deleting, and enumerating directories and subdirectories.\r\n\r\n```csharp\r\npublic static async Task PrintFilesAsync(VirtualDirectory directory, string padding = \"\", CancellationToken cancellationToken = default)\r\n{\r\n    await foreach (VirtualNode node in directory.GetFileNodesAsync(cancellationToken))\r\n    {\r\n        Console.WriteLine($\"{padding}{node.Name}\");\r\n\r\n        if (node is VirtualDirectory dir)\r\n        {\r\n            await PrintFilesAsync(dir, padding + \"   \", cancellationToken);\r\n        }\r\n    }\r\n}\r\n\r\n// Print the file tree\r\nawait PrintFilesAsync(fs.GetDirectory(\"/sample\"));\r\n```\r\n\r\nThe `VirtualDirectory` class provides the following properties to retrieve information about a directory:\r\n- `FileSystem`: Gets the `IVirtualFileSystem` associated with the directory.\r\n- `IsRoot`: Indicates whether the directory is the root directory.\r\n- `Parent`: Gets the `VirtualDirectory` representing the parent directory.\r\n- `DirectoryName`: Gets the full path of the parent directory.\r\n- `IsReadOnly`: Indicates whether the directory is read-only.\r\n- `Name`: Gets the name of the directory.\r\n\r\nThe `VirtualDirectory` class also exposes a `GetPropertiesAsync` method to retrieve directory properties, if available:\r\n- `Exists`: Indicates whether the directory exists.\r\n- `CreationTime`: Gets the creation time of the directory.\r\n- `LastAccessTime`: Gets the last access time of the directory.\r\n- `LastWriteTime`: Gets the last modification time of the directory.\r\n- `Length`: Always returns `0` for directories.\r\n\r\nFor convenience, many methods specific to `VirtualDirectory` are also available as extension methods on `IVirtualFileSystem`.\r\n\r\nFor example, if we know the path of the desired directory, we don't need to obtain a `VirtualDirectory` object explicitly:\r\n```csharp\r\nawait foreach (VirtualFile file in fs.GetFilesAsync(\"/sample/directory\"))\r\n{\r\n    Console.WriteLine($\"Processing: {file.FullName}\");\r\n}\r\n\r\n// Delete the directory recursively\r\nawait fs.DeleteDirectoryAsync(\"/sample/directory\");\r\n```\r\n\r\n## Remarks\r\n\r\nThe file system in use may be read-only, and as a result, any modifying operations on files and directories will throw an exception.\r\nTo check if the file system is read-only, the `IVirtualFileSystem`, `VirtualFile`, and `VirtualDirectory` classes provide the `IsReadOnly` property.\r\n\r\n```csharp\r\nif (!fs.IsReadOnly)\r\n{\r\n    await fs.DeleteFileAsync(\"/hello.txt\");\r\n}\r\n```\r\n\r\n## Related Projects\r\n- [Ramstack.FileSystem.Abstractions](https://www.nuget.org/packages/Ramstack.FileSystem.Abstractions) - Provides a virtual file system abstraction.\r\n- [Ramstack.FileSystem.Physical](https://www.nuget.org/packages/Ramstack.FileSystem.Physical) - Provides an implementation based on the local file system.\r\n- [Ramstack.FileSystem.Azure](https://www.nuget.org/packages/Ramstack.FileSystem.Azure) - Provides an implementation using Azure Blob Storage.\r\n- [Ramstack.FileSystem.Amazon](https://www.nuget.org/packages/Ramstack.FileSystem.Amazon) - Provides an implementation using Amazon S3 storage.\r\n- [Ramstack.FileSystem.Google](https://www.nuget.org/packages/Ramstack.FileSystem.Google) - Provides an implementation using Google Cloud Storage.\r\n- [Ramstack.FileSystem.Readonly](https://www.nuget.org/packages/Ramstack.FileSystem.Readonly) - Provides a read-only wrapper for the underlying file system.\r\n- [Ramstack.FileSystem.Globbing](https://www.nuget.org/packages/Ramstack.FileSystem.Globbing) - Wraps the file system, filtering files and directories using glob patterns.\r\n- [Ramstack.FileSystem.Prefixed](https://www.nuget.org/packages/Ramstack.FileSystem.Prefixed) - Adds a prefix to file paths within the underlying file system.\r\n- [Ramstack.FileSystem.Sub](https://www.nuget.org/packages/Ramstack.FileSystem.Sub) - Wraps the underlying file system, restricting access to a specific subpath.\r\n- [Ramstack.FileSystem.Adapters](https://www.nuget.org/packages/Ramstack.FileSystem.Adapters) - Provides integration with `Microsoft.Extensions.FileProviders`.\r\n- [Ramstack.FileSystem.Composite](https://www.nuget.org/packages/Ramstack.FileSystem.Composite) - Provides an implementation that combines multiple file systems into a single composite file system.\r\n\r\n## Supported Versions\r\n\r\n|      | Version        |\r\n|------|----------------|\r\n| .NET | 6, 7, 8, 9, 10 |\r\n\r\n## Contributions\r\n\r\nBug reports and contributions are welcome.\r\n\r\n## License\r\n\r\nThis package is released as open source under the **MIT License**.\r\nSee the [LICENSE](https://github.com/rameel/ramstack.filesystem/blob/main/LICENSE) file for more details.\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frameel%2Framstack.filesystem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frameel%2Framstack.filesystem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frameel%2Framstack.filesystem/lists"}