File system helpers

This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) IFileSystem interface. This interface provides helper methods that access the app's cache and data directories, and helps access files in the app package.

The default implementation of the IFileSystem interface is available through the FileSystem.Current property. Both the IFileSystem interface and FileSystem class are contained in the Microsoft.Maui.Storage namespace.

Using file system helpers

Each operating system will have unique paths to the app cache and app data directories. The IFileSystem interface provides a cross-platform API for accessing these directory paths.

Cache directory

To get the application's directory to store cache data. Cache data can be used for any data that needs to persist longer than temporary data, but shouldn't be data that is required to operate the app, as the operating system may clear this storage.

string cacheDir = FileSystem.Current.CacheDirectory;

App data directory

To get the app's top-level directory for any files that aren't user data files. These files are backed up with the operating system syncing framework.

string mainDir = FileSystem.Current.AppDataDirectory;

Bundled files

To open a file that is bundled into the app package, use the OpenAppPackageFileAsync method and pass the file name. This method returns a read-only Stream representing the file contents. The following example demonstrates using a method to read the text contents of a file:

public async Task<string> ReadTextFile(string filePath)
    using Stream fileStream = await FileSystem.Current.OpenAppPackageFileAsync(filePath);
    using StreamReader reader = new StreamReader(fileStream);

    return await reader.ReadToEndAsync();

Writing from a bundled file to the app data folder

You can't modify an app's bundled file. But you can read it first, then write it back to the cache directory or app data directory. The following example uses OpenAppPackageFileAsync to read a bundled file, alters it, and then writes it to the app data folder:

public async Task ConvertFileToUpperCase(string sourceFile, string targetFileName)
    // Read the source file
    using Stream fileStream = await FileSystem.Current.OpenAppPackageFileAsync(sourceFile);
    using StreamReader reader = new StreamReader(fileStream);

    string content = await reader.ReadToEndAsync();

    // Transform file content to upper case text
    content = content.ToUpperInvariant();

    // Write the file content to the app data directory
    string targetFile = System.IO.Path.Combine(FileSystem.Current.AppDataDirectory, targetFileName);

    using FileStream outputStream = System.IO.File.OpenWrite(targetFile);
    using StreamWriter streamWriter = new StreamWriter(outputStream);

    await streamWriter.WriteAsync(content);

Platform differences

This section describes the platform-specific differences with the file system helpers.

  • FileSystem.CacheDirectory
    Returns the CacheDir of the current context.

  • FileSystem.AppDataDirectory
    Returns the FilesDir of the current context, which are backed up using Auto Backup starting on API 23 and above.

  • FileSystem.OpenAppPackageFileAsync
    Files that were added to the project with the Build Action of MauiAsset can be opened with this method. .NET MAUI projects will process any file in the Resources\Raw folder as a MauiAsset.

    The FileSystem.OpenPackageFileAsync method can't get the length of the stream on Android by accessing the Result.Length property. Instead, you have to read the whole stream and count how many bytes there are to get the size of the asset.