Directory

Namespace: Wisej.Ext.ClientFileSystem

Assembly: Wisej.Ext.ClientFileSystem (4.1.0.0)

Represents a Directory of a ClientFileSystem.

C#
VB.NET

public class Directory : IDisposable

Public Class Directory
    Inherits IDisposable

Constructors

Directory(config)

Creates a new instance of Directory.

Name	Type	Description
config	Object	Dynamic configuration object.

Properties

Name

String: Returns the file system directory's name.

Value: A String containing the directory's name, without any path information.

The value reflects the name of the underlying directory handle picked by the user in the browser. The browser never exposes the full path of a directory to the application, so only the last segment of the path is available. The name is read once when the Directory is created and is not updated if the directory is renamed afterwards on the client.

Example:

ClientFileSystem.ShowDirectoryPicker((directory) =>
{
    if (directory != null)
        AlertBox.Show($"Selected folder: {directory.Name}");
});

Methods

CallAsync(name, args)

Asynchronously runs the JavaScript within the component's context in the browser and returns an awaitable Task containing the value returned by the remote call.

Parameter	Type	Description
name	String	Represents the function name.
args	Object[]	The arguments to pass to the function.

Returns: Task<Object>. An awaitable Task that represents the asynchronous operation.

Dispose()

Releases the client-side handle that this Directory represents.

The handle is an entry in the browser's object registry, not an unmanaged resource: this method sends a single fire-and-forget request to release it and does not wait for confirmation. Disposing does not delete anything from the user's disk, and it does not dispose the File and Directory objects obtained from this one — each holds a handle of its own.

The instance is not guarded after disposal: properties keep returning their cached values, and further calls are sent with a handle the browser no longer recognizes, failing with "Invalid file system handle". No ObjectDisposedException is raised.

An undisposed Directory releases its handle from the finalizer instead, which runs at a time the application does not control and may not run at all before the session ends. A session that enumerates folders repeatedly will accumulate handles in the browser until then, so dispose each one as soon as it is no longer needed.

Example:

using (var directory = await ClientFileSystem.ShowDirectoryPickerAsync())
{
    var files = await directory.GetFilesAsync("*.txt");
    foreach (var file in files)
    {
        AlertBox.Show(file.Name);
        file.Dispose();
    }
}

Finalize()

Destroys an instance of Directory.

GetDirectories(pattern, callback)

Begins retrieving the subdirectories of the current Directory that match the specified pattern and invokes callback when the operation completes.

Parameter	Type	Description
pattern	String	A wildcard pattern matched against each subdirectory name, where '' matches any sequence of characters and '?' matches any single character. The pattern is matched as an unanchored, case-sensitive expression, so "src" also matches "mysrcfolder" and does not match "SRC".
callback	Action<Directory[]>	A method invoked on the application context with the matching Directory objects, or with `null` if the operation failed — for example when read permission on the directory has not been granted or has been revoked, or when pattern is `null`. Always test the argument before enumerating it. Each Directory holds a handle in the browser and should be disposed when no longer needed.

This method returns immediately. Only immediate subdirectories are returned: the search does not recurse, and files are excluded — use GetFiles for those. To await the result instead, use GetDirectoriesAsync, which propagates the failure as an exception rather than as a null array.

Throws:

ArgumentNullException callback is null.

Example:

directory.GetDirectories("*", directories =>
{
    if (directories == null)
    {
        AlertBox.Show("Could not read the folder.");
        return;
    }

    foreach (var dir in directories)
    {
        AlertBox.Show($"Found directory: {dir.Name}");
        dir.Dispose();
    }
});

GetDirectoriesAsync(pattern)

Returns the subdirectories of the current Directory that match the specified pattern, asynchronously.

Parameter	Type	Description
pattern	String	A wildcard pattern matched against each subdirectory name, where '' matches any sequence of characters and '?' matches any single character. The pattern is matched as an unanchored, case-sensitive expression, so "src" also matches "mysrcfolder" and does not match "SRC".

Returns: Task<Directory[]>. An awaitable Task that completes with an array of Directory objects, or an empty array if no subdirectory matches. Each Directory holds a handle in the browser and should be disposed when no longer needed.

Only immediate subdirectories are returned: the search does not recurse, and files are excluded — use GetFilesAsync for those. The task faults if read permission on the directory has not been granted or has been revoked, or if pattern is null. Unlike GetDirectories, which reports failure by passing null to its callback, this overload surfaces the error as an exception.

Example:

var directories = await directory.GetDirectoriesAsync("*");
foreach (var dir in directories)
{
    AlertBox.Show(dir.Name);
    dir.Dispose();
}

GetFileAsync(name, create)

Returns the file with the specified name from the Directory, optionally creating it when it does not exist.

Parameter	Type	Description
name	String	The name of the file to open or create, relative to this directory. Path separators are not allowed; the browser rejects a name containing '/' or ''. The argument is not validated on the server and is passed to the browser as given.
create	Boolean	`true` to create the file if it does not exist; otherwise `false`. Creating a file requires that ReadWrite has been granted on this directory — see RequestPermissionAsync.

Returns: Task<File>. An awaitable Task that completes with the File. The returned object holds a handle in the browser and should be disposed when no longer needed.

The task faults if the file does not exist and create is false, if the required permission has not been granted, or if name is not a valid file name.

Example:

using (var file = await directory.GetFileAsync("example.txt", true))
{
    AlertBox.Show($"File {file.Name} is ready for use.");
}

GetFiles(pattern, callback)

Begins retrieving the files in the current Directory that match the specified pattern and invokes callback when the operation completes.

Parameter	Type	Description
pattern	String	A wildcard pattern matched against each file name, where '' matches any sequence of characters and '?' matches any single character. The pattern is matched as an unanchored, case-sensitive expression, so ".txt" also matches "report.txt.bak" and does not match "REPORT.TXT". The pattern applies to the file name only, not to the file's MIME type.
callback	Action<File[]>	A method invoked on the application context with the matching File objects, or with `null` if the operation failed — for example when read permission on the directory has not been granted or has been revoked, or when pattern is `null`. Always test the argument before enumerating it. Each File holds a handle in the browser and should be disposed when no longer needed.

This method returns immediately. Subdirectories are not included; use GetDirectories for those. To await the result instead, use GetFilesAsync, which propagates the failure as an exception rather than as a null array.

Throws:

ArgumentNullException callback is null.

Example:

directory.GetFiles("*.txt", files =>
{
    if (files == null)
    {
        AlertBox.Show("Could not read the folder.");
        return;
    }

    foreach (var file in files)
    {
        AlertBox.Show(file.Name);
        file.Dispose();
    }
});

GetFilesAsync(pattern)

Returns the files in the current Directory that match the specified pattern, asynchronously.

Parameter	Type	Description
pattern	String	A wildcard pattern matched against each file name, where '' matches any sequence of characters and '?' matches any single character. The pattern is matched as an unanchored, case-sensitive expression, so ".txt" also matches "report.txt.bak" and does not match "REPORT.TXT". The pattern applies to the file name only, not to the file's MIME type.

Returns: Task<File[]>. An awaitable Task that completes with an array of File objects, or an empty array if no file matches. Each File holds a handle in the browser and should be disposed when no longer needed.

Example:

var files = await directory.GetFilesAsync("*.txt");
foreach (var file in files)
{
    AlertBox.Show(file.Name);
    file.Dispose();
}

Remove(name, recursive, callback)

Begins removing a file or subdirectory from this Directory and invokes callback when the operation completes.

Parameter	Type	Description
name	String	The name of the file or subdirectory to remove, relative to this directory. The argument is not validated on the server and is passed to the browser as given.
recursive	Boolean	`true` to remove a subdirectory together with everything it contains; `false` to remove only a file or an empty subdirectory. Removing a non-empty subdirectory with `false` fails.
callback	Action<Boolean>	An optional method invoked on the application context with `true` if the removal completed, or `false` if it failed — for example when the entry does not exist, when read-write permission has not been granted, or when the subdirectory is not empty and recursive is `false`. Pass `null` to ignore the result.

This method returns immediately. The deletion is permanent: the entry is not moved to the recycle bin or trash and cannot be recovered from the application. Removing an entry requires that ReadWrite has been granted on this directory — see RequestPermissionAsync. The callback reports only success or failure, with no indication of the cause; use RemoveAsync to observe the underlying exception.

Example:

directory.Remove("example.txt", false, success =>
{
    AlertBox.Show(success ? "File removed." : "Failed to remove the file.");
});

RemoveAsync(name, recursive)

Removes a file or subdirectory from this Directory, asynchronously.

Parameter	Type	Description
name	String	The name of the file or subdirectory to remove. This is a single entry name, not a path: the browser rejects a name containing a path separator. To remove an entry nested deeper, obtain a handle on its parent with GetDirectoriesAsync and call this method on that Directory. The argument is not validated on the server and is passed to the browser as given.
recursive	Boolean	`true` to remove a subdirectory together with everything it contains; `false` to remove only a file or an empty subdirectory.

Returns: Task. An awaitable Task that represents the asynchronous operation.

The deletion is permanent: the entry is not moved to the recycle bin or trash and cannot be recovered from the application. The task faults if the entry does not exist, if ReadWrite has not been granted on this directory — see RequestPermissionAsync — or if the subdirectory is not empty and recursive is false. Unlike Remove, which reports only a boolean, this overload surfaces the cause of the failure.

Example:

await directory.RemoveAsync("exampleDir", true);

RequestPermissionAsync(mode)

Requests read or read-write permission on the Directory, asynchronously.

Parameter	Type	Description
mode	Permission	One of the Permission values indicating the level of access to request.

Returns: Task<PermissionState>. An awaitable Task that completes with one of the PermissionState values: Granted if access is allowed, Denied if the user refused, or Prompt if the browser has not decided and will ask when the directory is next accessed.

Treat Prompt as "not yet granted" rather than as a refusal. Requesting a permission that has already been granted returns Granted without prompting the user again. The browser shows a prompt only in response to a user gesture, so call this from a control event rather than during application startup.

Throws:

NotSupportedException The browser returned a permission state that is not one of the recognized values.

Example:

var state = await directory.RequestPermissionAsync(Permission.ReadWrite);
switch (state)
{
    case PermissionState.Granted:
        AlertBox.Show("Permission granted.");
        break;

    case PermissionState.Prompt:
        AlertBox.Show("The browser will ask for permission on the next access.");
        break;

    default:
        AlertBox.Show("Permission denied.");
        break;
}

Constructors​

Directory(config)​

Properties​

Name​

Methods​

CallAsync(name, args)​

Dispose()​

Finalize()​

GetDirectories(pattern, callback)​

GetDirectoriesAsync(pattern)​

GetFileAsync(name, create)​

GetFiles(pattern, callback)​

GetFilesAsync(pattern)​

Remove(name, recursive, callback)​

RemoveAsync(name, recursive)​

RequestPermissionAsync(mode)​

Constructors

Directory(config)

Properties

Name

Methods

CallAsync(name, args)

Dispose()

Finalize()

GetDirectories(pattern, callback)

GetDirectoriesAsync(pattern)

GetFileAsync(name, create)

GetFiles(pattern, callback)

GetFilesAsync(pattern)

Remove(name, recursive, callback)

RemoveAsync(name, recursive)

RequestPermissionAsync(mode)