ClientFileSystem

Namespace: Wisej.Ext.ClientFileSystem

Assembly: Wisej.Ext.ClientFileSystem (4.1.0.0)

Implementation of File System Access API. Provides access to files and directories on client machines.

C#

public static class ClientFileSystem

VB.NET

Public Class ClientFileSystem

This extension enables developers to build powerful apps that interact the user's device via the device's file system.

It also allows the application to read or save changes directly to files and folders on the user's device and it also offers the ability to open a directory and enumerate its contents.

Every entry point here opens a picker, because nothing in this API can reach the user's disk without the user choosing what to expose. The browser opens a picker only in response to a user gesture and only in a secure context (HTTPS, or localhost during development). The File System Access API is implemented in Chromium-based browsers; Firefox does not support it, and Safari supports only the origin-private file system, so the pickers below are unavailable there.

The File and Directory objects returned here each hold a handle in the browser and implement IDisposable. Dispose them when they are no longer needed; a session that opens pickers repeatedly without disposing accumulates handles on the client.

Example:

// Let the user pick a folder, then list the text files in it.
using (var directory = await ClientFileSystem.ShowDirectoryPickerAsync())
{
    var files = await directory.GetFilesAsync("*.txt");
    foreach (var file in files)
    {
        AlertBox.Show($"{file.Name} ({file.Size} bytes)");
        file.Dispose();
    }
}

Methods

ShowDirectoryPicker(callback)

Opens a directory picker that lets the user select a folder, and invokes callback with the result.

Parameter	Type	Description
callback	Action<Directory>	A method invoked on the application context with the selected Directory, or with null if the user dismissed the picker or the call failed. The Directory holds a handle in the browser and should be disposed when no longer needed.

This method returns immediately. The browser only opens a picker in response to a user gesture, so call it from a control event rather than during application startup. Selecting a folder grants read access to it; writing to anything inside it additionally requires ReadWrite, which RequestPermissionAsync asks for.

Throws:

• ArgumentNullException callback is null.

Example:

ClientFileSystem.ShowDirectoryPicker(directory =>
{
    if (directory == null)
    {
        AlertBox.Show("No folder was selected.");
        return;
    }

    // Keep the handle for the rest of the session, and dispose it when done.
    this._directory = directory;
    AlertBox.Show($"Selected {directory.Name}.");
});

ShowDirectoryPicker(startIn, callback)

Opens a directory picker in the specified folder that lets the user select a folder, and invokes callback with the result.

Parameter	Type	Description
startIn	WellKnownFolder	One of the WellKnownFolder values naming the folder the picker opens in. None leaves the choice to the browser, which normally reopens the folder the user last visited.
callback	Action<Directory>	A method invoked on the application context with the selected Directory, or with null if the user dismissed the picker or the call failed. The Directory holds a handle in the browser and should be disposed when no longer needed.

This method returns immediately. The browser only opens a picker in response to a user gesture, so call it from a control event rather than during application startup. Selecting a folder grants read access to it; writing to anything inside it additionally requires ReadWrite, which RequestPermissionAsync asks for.

Throws:

• ArgumentNullException callback is null.

Example:

ClientFileSystem.ShowDirectoryPicker(WellKnownFolder.Documents, directory =>
{
    if (directory == null)
        return;

    this._directory = directory;
    AlertBox.Show($"Selected {directory.Name}.");
});

ShowDirectoryPickerAsync()

Opens a directory picker that lets the user select a folder, asynchronously.

Returns: Task<Directory>. An awaitable Task that completes with a Directory handle for the selected folder. The handle should be disposed when no longer needed.

The browser only opens a picker in response to a user gesture, so call this from a control event rather than during application startup. The task faults if the user dismisses the picker, so wrap the call in a try/catch rather than testing the result for null.

Example:

using (var directory = await ClientFileSystem.ShowDirectoryPickerAsync())
{
    var files = await directory.GetFilesAsync("*");
    AlertBox.Show($"{directory.Name} contains {files.Length} file(s).");

    foreach (var file in files)
        file.Dispose();
}

ShowDirectoryPickerAsync(startIn)

Opens a directory picker in the specified folder that lets the user select a folder, asynchronously.

Parameter	Type	Description
startIn	WellKnownFolder	One of the WellKnownFolder values naming the folder the picker opens in. None leaves the choice to the browser, which normally reopens the folder the user last visited.

Returns: Task<Directory>. An awaitable Task that completes with a Directory handle for the selected folder. The handle should be disposed when no longer needed.

The browser only opens a picker in response to a user gesture, so call this from a control event rather than during application startup. The task faults if the user dismisses the picker, so wrap the call in a try/catch rather than testing the result for null.

Example:

using (var directory = await ClientFileSystem.ShowDirectoryPickerAsync(WellKnownFolder.Pictures))
{
    var state = await directory.RequestPermissionAsync(Permission.ReadWrite);
    if (state != PermissionState.Granted)
    {
        AlertBox.Show($"Read-write access was not granted ({state}).");
        return;
    }

    AlertBox.Show($"Ready to write into {directory.Name}.");
}

ShowOpenFilePicker(multiple, excludeAcceptAllOption, filter, callback)

Opens a file picker that lets the user select one or more files, and invokes callback with the result.

Parameter	Type	Description
multiple	Boolean	true to let the user select more than one file; otherwise false.
excludeAcceptAllOption	Boolean	true to hide the picker's "All files" entry, so the user can only choose the types described by filter ; otherwise false.
filter	String	The file types the picker offers, in a Windows-like syntax: "Description|Mime type|Extension;Extension;...". Append another pipe and three more segments for each additional filter. The string is split on '|' and read in groups of three, so a value with fewer than three segments is ignored and no type restriction is applied.
callback	Action<File[]>	A method invoked on the application context with the selected File objects, or with null if the user dismissed the picker or the call failed. Each File holds a handle in the browser and should be disposed when no longer needed.

This method returns immediately. The browser only opens a picker in response to a user gesture, so call it from a control event rather than during application startup. A null or empty filter does not throw here: it faults the underlying operation, which reaches the callback as null.

Throws:

• ArgumentNullException callback is null.

Example:

ClientFileSystem.ShowOpenFilePicker(true, false, "Text files|text/plain|.txt;.log", files =>
{
    if (files == null)
    {
        AlertBox.Show("No file was selected.");
        return;
    }

    foreach (var file in files)
    {
        AlertBox.Show($"{file.Name} ({file.Size} bytes)");
        file.Dispose();
    }
});

ShowOpenFilePicker(multiple, excludeAcceptAllOption, filter, startIn, callback)

Opens a file picker in the specified folder that lets the user select one or more files, and invokes callback with the result.

Parameter	Type	Description
multiple	Boolean	true to let the user select more than one file; otherwise false.
excludeAcceptAllOption	Boolean	true to hide the picker's "All files" entry, so the user can only choose the types described by filter ; otherwise false.
filter	String	The file types the picker offers, in a Windows-like syntax: "Description|Mime type|Extension;Extension;...". Append another pipe and three more segments for each additional filter. The string is split on '|' and read in groups of three, so a value with fewer than three segments is ignored and no type restriction is applied.
startIn	WellKnownFolder	One of the WellKnownFolder values naming the folder the picker opens in. None leaves the choice to the browser, which normally reopens the folder the user last visited.
callback	Action<File[]>	A method invoked on the application context with the selected File objects, or with null if the user dismissed the picker or the call failed. Each File holds a handle in the browser and should be disposed when no longer needed.

This method returns immediately. The browser only opens a picker in response to a user gesture, so call it from a control event rather than during application startup. A null or empty filter does not throw here: it faults the underlying operation, which reaches the callback as null.

Throws:

• ArgumentNullException callback is null.

Example:

ClientFileSystem.ShowOpenFilePicker(false, true, "Images|image/*|.png;.jpg", WellKnownFolder.Pictures, files =>
{
    if (files == null || files.Length == 0)
        return;

    var file = files[0];
    AlertBox.Show($"Selected {file.Name}.");
    file.Dispose();
});

ShowOpenFilePickerAsync(multiple, excludeAcceptAllOption, filter)

Opens a file picker that lets the user select one or more files, asynchronously.

Parameter	Type	Description
multiple	Boolean	true to let the user select more than one file; otherwise false.
excludeAcceptAllOption	Boolean	true to hide the picker's "All files" entry, so the user can only choose the types described by filter ; otherwise false.
filter	String	The file types the picker offers, in a Windows-like syntax: "Description|Mime type|Extension;Extension;...". Append another pipe and three more segments for each additional filter. The string is split on '|' and read in groups of three, so a value with fewer than three segments is ignored and no type restriction is applied.

Returns: Task<File[]>. An awaitable Task that completes with the selected File objects. Each holds a handle in the browser and should be disposed when no longer needed.

The browser only opens a picker in response to a user gesture, so call this from a control event rather than during application startup. The task faults if the user dismisses the picker, so wrap the call in a try/catch rather than testing the result for null.

Throws:

• ArgumentNullException filter is null or empty.

Example:

try
{
    var files = await ClientFileSystem.ShowOpenFilePickerAsync(false, false, "Text files|text/plain|.txt");

    using (var file = files[0])
    {
        var text = await file.ReadTextAsync();
        AlertBox.Show($"{file.Name} contains {text.Length} characters.");
    }
}
catch (Exception ex)
{
    AlertBox.Show($"The picker was dismissed or failed: {ex.Message}");
}

ShowOpenFilePickerAsync(multiple, excludeAcceptAllOption, filter, startIn)

Opens a file picker in the specified folder that lets the user select one or more files, asynchronously.

Parameter	Type	Description
multiple	Boolean	true to let the user select more than one file; otherwise false.
excludeAcceptAllOption	Boolean	true to hide the picker's "All files" entry, so the user can only choose the types described by filter ; otherwise false.
filter	String	The file types the picker offers, in a Windows-like syntax: "Description|Mime type|Extension;Extension;...". Append another pipe and three more segments for each additional filter. The string is split on '|' and read in groups of three, so a value with fewer than three segments is ignored and no type restriction is applied.
startIn	WellKnownFolder	One of the WellKnownFolder values naming the folder the picker opens in. None leaves the choice to the browser, which normally reopens the folder the user last visited.

Returns: Task<File[]>. An awaitable Task that completes with the selected File objects. Each holds a handle in the browser and should be disposed when no longer needed.

The browser only opens a picker in response to a user gesture, so call this from a control event rather than during application startup. The task faults if the user dismisses the picker, so wrap the call in a try/catch rather than testing the result for null.

Throws:

• ArgumentNullException filter is null or empty.

Example:

var files = await ClientFileSystem.ShowOpenFilePickerAsync(
    true, false, "Documents|application/pdf|.pdf", WellKnownFolder.Documents);

foreach (var file in files)
{
    var bytes = await file.ReadBytesAsync();
    AlertBox.Show($"{file.Name}: {bytes.Length} bytes read.");
    file.Dispose();
}

ShowSaveFilePicker(excludeAcceptAllOption, filter, suggestedName, callback)

Opens a file picker that lets the user choose where to save a file, and invokes callback with the resulting handle.

Parameter	Type	Description
excludeAcceptAllOption	Boolean	true to hide the picker's "All files" entry, so the user can only choose the types described by filter ; otherwise false.
filter	String	The file types the picker offers, in a Windows-like syntax: "Description|Mime type|Extension;Extension;...". Append another pipe and three more segments for each additional filter. The string is split on '|' and read in groups of three, so a value with fewer than three segments is ignored and no type restriction is applied.
suggestedName	String	The file name the picker proposes to the user. The user is free to change it.
callback	Action<File>	A method invoked on the application context with the selected File, or with null if the user dismissed the picker or the call failed. The File holds a handle in the browser and should be disposed when no longer needed.

This method returns immediately, and produces a handle rather than writing anything: use WriteText or one of its siblings to fill the file. The browser only opens a picker in response to a user gesture, so call this from a control event rather than during application startup. A null or empty filter does not throw here: it faults the underlying operation, which reaches the callback as null.

Throws:

• ArgumentNullException callback is null.

Example:

ClientFileSystem.ShowSaveFilePicker(false, "Text files|text/plain|.txt", "report.txt", file =>
{
    if (file == null)
    {
        AlertBox.Show("The save dialog was dismissed.");
        return;
    }

    file.WriteText($"Generated on {DateTime.Now}.", 0, success =>
    {
        AlertBox.Show(success ? $"Saved {file.Name}." : "The file could not be written.");
        file.Dispose();
    });
});

ShowSaveFilePicker(excludeAcceptAllOption, filter, suggestedName, startIn, callback)

Opens a file picker in the specified folder that lets the user choose where to save a file, and invokes callback with the resulting handle.

Parameter	Type	Description
excludeAcceptAllOption	Boolean	true to hide the picker's "All files" entry, so the user can only choose the types described by filter ; otherwise false.
filter	String	The file types the picker offers, in a Windows-like syntax: "Description|Mime type|Extension;Extension;...". Append another pipe and three more segments for each additional filter. The string is split on '|' and read in groups of three, so a value with fewer than three segments is ignored and no type restriction is applied.
suggestedName	String	The file name the picker proposes to the user. The user is free to change it.
startIn	WellKnownFolder	One of the WellKnownFolder values naming the folder the picker opens in. None leaves the choice to the browser, which normally reopens the folder the user last visited.
callback	Action<File>	A method invoked on the application context with the selected File, or with null if the user dismissed the picker or the call failed. The File holds a handle in the browser and should be disposed when no longer needed.

This method returns immediately, and produces a handle rather than writing anything: use WriteText or one of its siblings to fill the file. The browser only opens a picker in response to a user gesture, so call this from a control event rather than during application startup. A null or empty filter does not throw here: it faults the underlying operation, which reaches the callback as null.

Throws:

• ArgumentNullException callback is null.

Example:

ClientFileSystem.ShowSaveFilePicker(
    true, "CSV|text/csv|.csv", "export.csv", WellKnownFolder.Downloads, file =>
    {
        if (file == null)
            return;

        file.WriteText(BuildCsv(), 0, success =>
        {
            AlertBox.Show(success ? $"Saved {file.Name}." : "The file could not be written.");
            file.Dispose();
        });
    });

ShowSaveFilePickerAsync(excludeAcceptAllOption, filter, suggestedName)

Opens a file picker that lets the user choose where to save a file, asynchronously.

Parameter	Type	Description
excludeAcceptAllOption	Boolean	true to hide the picker's "All files" entry, so the user can only choose the types described by filter ; otherwise false.
filter	String	The file types the picker offers, in a Windows-like syntax: "Description|Mime type|Extension;Extension;...". Append another pipe and three more segments for each additional filter. The string is split on '|' and read in groups of three, so a value with fewer than three segments is ignored and no type restriction is applied.
suggestedName	String	The file name the picker proposes to the user. The user is free to change it.

Returns: Task<File>. An awaitable Task that completes with a File handle for the chosen location. The file is created empty; write to it with WriteTextAsync or one of its siblings. The handle should be disposed when no longer needed.

The browser only opens a picker in response to a user gesture, so call this from a control event rather than during application startup. The task faults if the user dismisses the picker, so wrap the call in a try/catch rather than testing the result for null.

Throws:

• ArgumentNullException filter is null or empty.

Example:

using (var file = await ClientFileSystem.ShowSaveFilePickerAsync(
    false, "Text files|text/plain|.txt", "notes.txt"))
{
    await file.WriteTextAsync("Saved from Wisej.NET.", 0);
    AlertBox.Show($"Saved {file.Name}.");
}

ShowSaveFilePickerAsync(excludeAcceptAllOption, filter, suggestedName, startIn)

Opens a file picker in the specified folder that lets the user choose where to save a file, asynchronously.

Parameter	Type	Description
excludeAcceptAllOption	Boolean	true to hide the picker's "All files" entry, so the user can only choose the types described by filter ; otherwise false.
filter	String	The file types the picker offers, in a Windows-like syntax: "Description|Mime type|Extension;Extension;...". Append another pipe and three more segments for each additional filter. The string is split on '|' and read in groups of three, so a value with fewer than three segments is ignored and no type restriction is applied.
suggestedName	String	The file name the picker proposes to the user. The user is free to change it.
startIn	WellKnownFolder	One of the WellKnownFolder values naming the folder the picker opens in. None leaves the choice to the browser, which normally reopens the folder the user last visited.

Returns: Task<File>. An awaitable Task that completes with a File handle for the chosen location. The file is created empty; write to it with WriteTextAsync or one of its siblings. The handle should be disposed when no longer needed.

The browser only opens a picker in response to a user gesture, so call this from a control event rather than during application startup. The task faults if the user dismisses the picker, so wrap the call in a try/catch rather than testing the result for null.

Throws:

• ArgumentNullException filter is null or empty.

Example:

using (var file = await ClientFileSystem.ShowSaveFilePickerAsync(
    false, "CSV|text/csv|.csv", "export.csv", WellKnownFolder.Documents))
{
    await file.WriteTextAsync(BuildCsv(), 0);
    AlertBox.Show($"Saved {file.Name}.");
}