File system helpers

Browse sample. Browse the sample

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();
}

The following example demonstrates opening a bundled font file from the app package:

await using var myFont = await FileSystem.OpenAppPackageFileAsync("MyFont.ttf");

Copy a bundled file to the app data folder

You can't modify an app's bundled file. But you can copy a bundled file to the cache directory or app data directory. The following example uses OpenAppPackageFileAsync to copy a bundled file to the app data folder:

public async Task CopyFileToAppDataDirectory(string filename)
{
    // Open the source file
    using Stream inputStream = await FileSystem.Current.OpenAppPackageFileAsync(filename);

    // Create an output filename
    string targetFile = Path.Combine(FileSystem.Current.AppDataDirectory, filename);

    // Copy the file to the AppDataDirectory
    using FileStream outputStream = File.Create(targetFile);
    await inputStream.CopyToAsync(outputStream);
}

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.