Interface IReliableFileStorage
Service to interact with the file system, as a replacement for standard C# file I/O. Writes and reads using this service are, to the best of our ability, atomic and reliable.
All data is synced to disk immediately and written to a database, additionally to files on disk. This means that in case of file corruption, data can likely be recovered from the database.
However, this also means that operations using this service duplicate data on disk, so we don't recommend performing large file operations. The service will not permit files larger than Dalamud.Plugin.Services.IReliableFileStorage.MaxFileSizeBytes (64MB) to be written.
Saved configuration data using the Dalamud.Configuration.PluginConfigurations class uses this functionality implicitly.
Assembly: Dalamud.dll
public interface IReliableFileStorage : IDalamudService
Derived:
Dalamud.Storage.ReliableFileStoragePluginScoped
Properties
MaxFileSizeBytes
Gets the maximum file size, in bytes, that can be written using this service.
long MaxFileSizeBytes { get; }
Remarks
The service enforces this limit when writing files and fails with an appropriate exception
(for example System.ArgumentException or a custom exception) when a caller attempts to write
more than this number of bytes.
Methods
Exists(string)
Check whether a file exists either on the local filesystem or in the transparent backup database.
bool Exists(string path)
Returns
System.Boolean: True if the file exists on disk or a backup copy exists in the storage's internal journal/backup database;
otherwise false.
Parameters
| Type | Name | Description |
|---|---|---|
System.String | path | The file system path to check. Must not be null or empty. |
Exceptions
System.ArgumentException
Thrown when <code class="paramref">path</code> is null or empty.
WriteAllTextAsync(string, string?)
Write the given text into a file using UTF-8 encoding. The write is performed atomically and is persisted to both the filesystem and the internal backup database used by this service.
Task WriteAllTextAsync(string path, string? contents)
Returns
System.Threading.Tasks.Task: A System.Threading.Tasks.Task that completes when the write has finished and been flushed to disk and the backup.
Parameters
| Type | Name | Description |
|---|---|---|
System.String | path | The file path to write to. Must not be null or empty. |
System.String | contents | The string contents to write. May be null, in which case an empty file is written. |
Exceptions
System.ArgumentException
Thrown when <code class="paramref">path</code> is null or empty.
WriteAllTextAsync(string, string?, Encoding)
Write the given text into a file using the provided <code class="paramref">encoding</code>. The write is performed atomically (to the extent possible) and is persisted to both the filesystem and the internal backup database used by this service.
Task WriteAllTextAsync(string path, string? contents, Encoding encoding)
Returns
System.Threading.Tasks.Task: A System.Threading.Tasks.Task that completes when the write has finished and been flushed to disk and the backup.
Parameters
| Type | Name | Description |
|---|---|---|
System.String | path | The file path to write to. Must not be null or empty. |
System.String | contents | The string contents to write. May be null, in which case an empty file is written. |
System.Text.Encoding | encoding | The text encoding to use when serializing the string to bytes. Must not be null. |
Exceptions
System.ArgumentException
Thrown when <code class="paramref">path</code> is null or empty.
System.ArgumentNullException
Thrown when <code class="paramref">encoding</code> is null.
WriteAllBytesAsync(string, byte[])
Write the given bytes to a file. The write is persisted to both the filesystem and the service's internal backup database. Avoid writing extremely large byte arrays because this service duplicates data on disk.
Task WriteAllBytesAsync(string path, byte[] bytes)
Returns
System.Threading.Tasks.Task: A System.Threading.Tasks.Task that completes when the write has finished and been flushed to disk and the backup.
Parameters
| Type | Name | Description |
|---|---|---|
System.String | path | The file path to write to. Must not be null or empty. |
System.Byte[] | bytes | The raw bytes to write. Must not be null. |
Exceptions
System.ArgumentException
Thrown when <code class="paramref">path</code> is null or empty.
System.ArgumentNullException
Thrown when <code class="paramref">bytes</code> is null.
ReadAllTextAsync(string, bool)
Read all text from a file using UTF-8 encoding. If the file is unreadable or missing on disk, the service attempts to return a backed-up copy from its internal journal/backup database.
Task<string> ReadAllTextAsync(string path, bool forceBackup = false)
Returns
System.Threading.Tasks.Task<System.String>: The textual contents of the file, decoded using UTF-8.
Parameters
| Type | Name | Description |
|---|---|---|
System.String | path | The file path to read. Must not be null or empty. |
System.Boolean | forceBackup | When true the service prefers the internal backup database and returns backed-up contents if available. When |
| false the service tries the filesystem first and falls back to the backup only on error or when the file is missing. |
Exceptions
System.ArgumentException
Thrown when <code class="paramref">path</code> is null or empty.
System.IO.FileNotFoundException
Thrown when the file does not exist on disk and no backup copy is available.
ReadAllTextAsync(string, Encoding, bool)
Read all text from a file using the specified <code class="paramref">encoding</code>. If the file is unreadable or missing on disk, the service attempts to return a backed-up copy from its internal journal/backup database.
Task<string> ReadAllTextAsync(string path, Encoding encoding, bool forceBackup = false)
Returns
System.Threading.Tasks.Task<System.String>: The textual contents of the file decoded using the provided <code class="paramref">encoding</code>.
Parameters
| Type | Name | Description |
|---|---|---|
System.String | path | The file path to read. Must not be null or empty. |
System.Text.Encoding | encoding | The encoding to use when decoding the stored bytes into text. Must not be null. |
System.Boolean | forceBackup | When true the service prefers the internal backup database and returns backed-up contents if available. When |
| false the service tries the filesystem first and falls back to the backup only on error or when the file is missing. |
Exceptions
System.ArgumentException
Thrown when <code class="paramref">path</code> is null or empty.
System.ArgumentNullException
Thrown when <code class="paramref">encoding</code> is null.
System.IO.FileNotFoundException
Thrown when the file does not exist on disk and no backup copy is available.
ReadAllTextAsync(string, Action<string>)
Read all text from a file and invoke the provided <code class="paramref">reader</code> callback with the string contents. If the reader throws or the initial read fails, the service attempts a backup read and invokes the reader again with the backup contents. If both reads fail the service surfaces an exception to the caller.
Task ReadAllTextAsync(string path, Action<string> reader)
Returns
System.Threading.Tasks.Task: A System.Threading.Tasks.Task that completes when the read (and any attempted fallback) and callback invocation have finished.
Parameters
| Type | Name | Description |
|---|---|---|
System.String | path | The file path to read. Must not be null or empty. |
System.Action<System.String> | reader | A callback invoked with the file's textual contents. Must not be null. |
| If the callback throws an exception the service treats that as a signal to retry the read using the | ||
| internal backup database and will invoke the callback again with the backup contents when available. | ||
| For example, the callback can throw when JSON deserialization fails to request the backup copy instead of | ||
| silently accepting corrupt data. |
Exceptions
System.ArgumentException
Thrown when <code class="paramref">path</code> is null or empty.
System.ArgumentNullException
Thrown when <code class="paramref">reader</code> is null.
System.IO.FileNotFoundException
Thrown when the file does not exist on disk and no backup copy is available.
Dalamud.Storage.FileReadException
Thrown when both the filesystem read and the backup read fail for other reasons.
ReadAllTextAsync(string, Encoding, Action<string>)
Read all text from a file using the specified <code class="paramref">encoding</code> and invoke the provided <code class="paramref">reader</code> callback with the decoded string contents. If the reader throws or the initial read fails, the service attempts a backup read and invokes the reader again with the backup contents. If both reads fail the service surfaces an exception to the caller.
Task ReadAllTextAsync(string path, Encoding encoding, Action<string> reader)
Returns
System.Threading.Tasks.Task: A System.Threading.Tasks.Task that completes when the read (and any attempted fallback) and callback invocation have finished.
Parameters
| Type | Name | Description |
|---|---|---|
System.String | path | The file path to read. Must not be null or empty. |
System.Text.Encoding | encoding | The encoding to use when decoding the stored bytes into text. Must not be null. |
System.Action<System.String> | reader | A callback invoked with the file's textual contents. Must not be null. |
| If the callback throws an exception the service treats that as a signal to retry the read using the | ||
| internal backup database and will invoke the callback again with the backup contents when available. | ||
| For example, the callback can throw when JSON deserialization fails to request the backup copy instead of | ||
| silently accepting corrupt data. |
Exceptions
System.ArgumentException
Thrown when <code class="paramref">path</code> is null or empty.
System.ArgumentNullException
Thrown when <code class="paramref">encoding</code> or <code class="paramref">reader</code> is null.
System.IO.FileNotFoundException
Thrown when the file does not exist on disk and no backup copy is available.
Dalamud.Storage.FileReadException
Thrown when both the filesystem read and the backup read fail for other reasons.
ReadAllBytesAsync(string, bool)
Read all bytes from a file. If the file is unreadable or missing on disk, the service may try to return a backed-up copy from its internal journal/backup database.
Task<byte[]> ReadAllBytesAsync(string path, bool forceBackup = false)
Returns
System.Threading.Tasks.Task<System.Byte[]>: The raw bytes stored in the file.
Parameters
| Type | Name | Description |
|---|---|---|
System.String | path | The file path to read. Must not be null or empty. |
System.Boolean | forceBackup | When true the service prefers the internal backup database and returns the backed-up contents |
| if available. When false the service tries the filesystem first and falls back to the backup only | ||
| on error or when the file is missing. |
Exceptions
System.ArgumentException
Thrown when <code class="paramref">path</code> is null or empty.
System.IO.FileNotFoundException
Thrown when the file does not exist on disk and no backup copy is available.