Class FileSettings

Encapsulates configuration options that govern how ScyllaFileUtil performs file I/O operations, including buffering, encoding, share modes, and write behavior.

Inheritance

object

FileSettings

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Core.Util.File

Assembly: ScyllaCore.dll

Syntax

public sealed class FileSettings

Remarks

Most ScyllaFileUtil methods accept an optional FileSettings parameter. When null is passed the method falls back to Default, which is suitable for the majority of single-file read/write scenarios.

Several built-in presets cover common patterns:

Default - UTF-8, 64 KB buffer, overwrite enabled, directories auto-created.
Async - 256 KB buffer with async I/O hint, suitable for large async transfers.
TextFile - UTF-8 with BOM detection, optimized for human-readable text.
BinaryFile - 256 KB buffer, optimized for raw byte throughput.
LargeFile - 256 KB buffer with async I/O, optimized for files larger than LARGE_FILE_THRESHOLD.
LogFile - UTF-8, shared read access, directories auto-created, suitable for appending log entries.

All preset instances are singletons. If you need to modify a preset for a specific call, use Clone() to get a mutable copy first.

Call Validate() before passing a custom FileSettings instance to a file method to catch configuration errors early.

Constructors

FileSettings()

Initializes a new instance of the FileSettings class with all properties set to their documented default values. This is equivalent to using Default but produces a mutable, independent instance.

Declaration

public FileSettings()

FileSettings(FileSettings)

Initializes a new instance of the FileSettings class by performing a shallow copy of all properties from other. If other is null, all properties retain their default values as if the parameterless constructor had been called.

Declaration

public FileSettings(FileSettings other)

Parameters

Type	Name	Description
FileSettings	other	The source FileSettings instance to copy, or `null` to use defaults.

Fields

DEFAULT_BUFFER_SIZE

Default buffer size in bytes used for streaming I/O operations (64 KB). This value balances memory usage against I/O round-trip overhead for typical file sizes.

Declaration

public const int DEFAULT_BUFFER_SIZE = 65536

Field Value

Type	Description
int

LARGE_BUFFER_SIZE

Buffer size in bytes used by the large-file and async presets (256 KB). The larger buffer reduces the number of system calls for sequential reads and writes.

Declaration

public const int LARGE_BUFFER_SIZE = 262144

Field Value

Type	Description
int

LARGE_FILE_THRESHOLD

File size threshold in bytes above which a file is considered "large" (10 MB). Used internally as a heuristic when selecting default settings; exposed so callers can apply the same classification in their own logic.

Declaration

public const long LARGE_FILE_THRESHOLD = 10485760

Field Value

Type	Description
long

MAX_BUFFER_SIZE

Maximum valid value for BufferSize in bytes (16 MB). Values above this limit are rejected by Validate() with InvalidSettings.

Declaration

public const int MAX_BUFFER_SIZE = 16777216

Field Value

Type	Description
int

MIN_BUFFER_SIZE

Minimum valid value for BufferSize in bytes (1 KB). Values below this limit are rejected by Validate() with InvalidSettings.

Declaration

public const int MIN_BUFFER_SIZE = 1024

Field Value

Type	Description
int

Properties

Async

Gets settings tuned for asynchronous file transfers. Uses a 256 KB buffer and sets UseAsyncIO to true so that underlying FileStream instances are opened with the async flag.

Declaration

public static FileSettings Async { get; }

Property Value

Type	Description
FileSettings

Remarks

Prefer this preset when calling the Async-suffixed overloads in ScyllaFileUtil on files larger than a few hundred kilobytes, where the larger buffer and OS-level async I/O provide measurable throughput gains.

BinaryFile

Gets settings optimized for raw binary data transfers. Uses a 256 KB buffer to maximize throughput when reading or writing large byte arrays with no text encoding overhead.

Declaration

public static FileSettings BinaryFile { get; }

Property Value

Type	Description
FileSettings

BufferSize

Gets or sets the internal buffer size in bytes used when streaming file data. Defaults to DEFAULT_BUFFER_SIZE (64 KB). Must be in the range [MIN_BUFFER_SIZE, MAX_BUFFER_SIZE].

Declaration

public int BufferSize { get; set; }

Property Value

Type	Description
int	An integer in the range `1 024` to `16 777 216` bytes inclusive. Values outside this range are rejected by Validate().

CreateDirectories

Gets or sets a value indicating whether missing parent directories in a destination path are created automatically before a write operation begins. When false, writing to a path whose parent directory does not exist will throw a FileException with DirectoryNotFound. Defaults to true.

Declaration

public bool CreateDirectories { get; set; }

Property Value

Type	Description
bool

Default

Gets the default settings instance, suitable for the majority of single-file read and write operations. Uses UTF-8 encoding, a 64 KB buffer, overwrite enabled, parent directory auto-creation, and exclusive write share mode.

Declaration

public static FileSettings Default { get; }

Property Value

Type	Description
FileSettings

Remarks

This is the singleton returned by FileIOUtil.ResolveSettings whenever a caller passes null as the settings argument. Do not mutate its properties directly; call Clone() first if customization is needed.

DetectEncodingFromBOM

Gets or sets a value indicating whether a byte order mark (BOM) at the start of a file is used to override the configured Encoding during text reads. When true, files beginning with a recognized BOM (UTF-8, UTF-16 LE/BE, UTF-32 LE/BE) are decoded accordingly regardless of Encoding. Defaults to true.

Declaration

public bool DetectEncodingFromBOM { get; set; }

Property Value

Type	Description
bool

Encoding

Gets or sets the character encoding used when reading or writing text files. Defaults to UTF8.

Declaration

public Encoding Encoding { get; set; }

Property Value

Type	Description
Encoding	A non-null Encoding instance. Setting this to `null` will cause Validate() to throw a FileException with InvalidSettings.

FlushAfterWrite

Gets or sets a value indicating whether the file stream is explicitly flushed to the OS after each write operation. When true, Stream.Flush() is called after every chunk write, which increases durability at the cost of I/O throughput. Defaults to false.

Declaration

public bool FlushAfterWrite { get; set; }

Property Value

Type	Description
bool

Remarks

This flag does not guarantee that data is committed to physical storage; it only flushes from the .NET stream buffer to the OS page cache. For full durability on crash, use a platform-specific flush API or a transactional file system.

KeepReplaceBackup

Gets or sets a value indicating whether an atomic write keeps a backup copy of the file it replaces, via the destinationBackupFileName parameter of File.Replace. Only consulted when UseAtomicWrite is true. Defaults to false.

Declaration

public bool KeepReplaceBackup { get; set; }

Property Value

Type	Description
bool

LargeFile

Gets settings optimized for files larger than LARGE_FILE_THRESHOLD. Combines the 256 KB buffer of BinaryFile with the async I/O flag of Async to minimize blocking on large sequential transfers.

Declaration

public static FileSettings LargeFile { get; }

Property Value

Type	Description
FileSettings

LogFile

Gets settings suitable for log file append operations. Uses UTF-8 encoding, allows concurrent readers via Read on both read and write opens, and enables CreateDirectories so that log directories are created on first write without requiring prior setup.

Declaration

public static FileSettings LogFile { get; }

Property Value

Type	Description
FileSettings

OverwriteExisting

Gets or sets a value indicating whether an existing file at the destination path may be replaced. When false, a write operation to an existing path throws a FileException with FileExists before any data is written. Defaults to true.

Declaration

public bool OverwriteExisting { get; set; }

Property Value

Type	Description
bool

PreserveTimestamps

Gets or sets a value indicating whether the last-write and creation timestamps of the source file are applied to the destination file during copy operations. Defaults to true.

Declaration

public bool PreserveTimestamps { get; set; }

Property Value

Type	Description
bool

ReadShareMode

Gets or sets the FileShare mode used when a file is opened for reading. Controls which concurrent accesses from other processes or threads are permitted during the read operation. Defaults to Read, which allows other readers but not writers.

Declaration

public FileShare ReadShareMode { get; set; }

Property Value

Type	Description
FileShare

TempFileExtension

Gets or sets the extension appended to the destination file name to form the temporary file path used by an atomic write. The atomic write methods on ScyllaFileUtil always use it, whatever UseAtomicWrite says, and reject an extension that is empty, consists only of dots and whitespace, or contains a directory separator, since the temporary file would then land on the destination itself. Defaults to ".tmp".

Declaration

public string TempFileExtension { get; set; }

Property Value

Type	Description
string

TextFile

Gets settings optimized for reading and writing human-readable text files. Uses UTF-8 encoding and enables BOM detection so that files written with a byte order mark are decoded correctly regardless of the system default encoding.

Declaration

public static FileSettings TextFile { get; }

Property Value

Type	Description
FileSettings

UseAsyncIO

Gets or sets a value indicating whether the underlying FileStream is opened with the Asynchronous flag. When true, overlapped I/O is used on Windows, which is required for efficient async/await read and write operations on large files. Defaults to false.

Declaration

public bool UseAsyncIO { get; set; }

Property Value

Type	Description
bool

Remarks

Enabling async I/O on a stream that is accessed synchronously incurs a small overhead. Use true only when calling the Async-suffixed overloads of ScyllaFileUtil.

UseAtomicWrite

Gets or sets a value indicating whether a write goes through a same-directory temporary file first, rather than targeting the destination path directly. When true, the temporary file is written and flushed to disk, then swapped into place via File.Replace (or a delete-then-move fallback on platforms without it), so a crash or power loss mid-write leaves either the old file intact or the new one complete, never a half-written destination file. Defaults to false, which writes straight to the destination.

Declaration

public bool UseAtomicWrite { get; set; }

Property Value

Type	Description
bool

Remarks

This is a stronger guarantee than FlushAfterWrite, which only drains the managed stream buffer into the OS page cache and does not survive a crash. The atomic write overloads on ScyllaFileUtil call FileStream.Flush(flushToDisk: true) on the temporary file before the swap.

When this is true, the settings-driven WriteText, WriteTextAsync, WriteBytes, WriteBytesAsync, WriteLines and WriteLinesAsync methods on ScyllaFileUtil use the atomic path. The *Atomic methods always write atomically, whatever this flag says. Appending, stream copies (WriteFromStream) and image writes are not affected. The atomic path is not available on WebGL, where a write with this flag set throws a FileException.

WriteShareMode

Gets or sets the FileShare mode used when a file is opened for writing. Controls which concurrent accesses from other processes or threads are permitted during the write operation. Defaults to None, which grants exclusive access and prevents any concurrent readers or writers.

Declaration

public FileShare WriteShareMode { get; set; }

Property Value

Type	Description
FileShare

Methods

Clone()

Creates an independent mutable copy of this FileSettings instance. Use this method to derive a customized set of settings from a preset without mutating the shared preset singleton.