PstFileOptions Class
Definition
Controls how a PstFile is opened and validated.
public sealed class PstFileOptions
- Inheritance
-
PstFileOptions
- Inherited Members
- Extension Methods
Constructors
PstFileOptions()
public PstFileOptions()
Properties
BlockCacheSize
Gets the maximum number of decoded pages, and separately of decoded block payloads, the session keeps in its least-recently-used caches.
public int BlockCacheSize { get; init; }
Property Value
- int
The entry budget of each cache;
256by default.0disables caching entirely.
Remarks
Pages and blocks are cached separately, each cache holding up to this many entries. A cached page is 512 bytes and a cached block at most 8,192 bytes, so the default budget bounds the two caches at roughly 2.2 MB per open session. Repeated structural reads - B-tree walks, property-context and table-context access over the same nodes - are served from the cache instead of re-reading and re-decoding from the source stream.
Exceptions
- ArgumentOutOfRangeException
The value is negative.
MaxDataTreeLeaves
Gets the largest number of leaf data blocks a node's data tree may reference.
public int MaxDataTreeLeaves { get; init; }
Property Value
- int
The fan-out limit; 65,536 by default.
Remarks
The limit is enforced while the tree's internal blocks are walked, before any leaf payload is read, and applies to streaming and buffered reads alike - the leaf list itself is the allocation it bounds. A tree exceeding it is refused with PstFileFormatException and LimitExceeded.
Exceptions
- ArgumentOutOfRangeException
The value is zero or negative.
MaxNodeDataLength
Gets the largest node payload, in bytes, the session materializes in memory.
public long MaxNodeDataLength { get; init; }
Property Value
- long
The materialization limit; 256 MiB by default.
Remarks
The limit governs every read that assembles a node's whole payload - ReadAllBytes(), the heap-on-node parse behind the property and table contexts, and subnode-resident property values. It does not govern OpenDataStream(), which reads one block at a time and is unbounded by design.
A data tree declaring more than this is refused with PstFileFormatException and LimitExceeded at every validation level: a crafted tree can reference the same physical block many thousands of times, so the declared size - not the file size - is what bounds the allocation.
Exceptions
- ArgumentOutOfRangeException
The value is zero or negative.
OmitUnresolvableValues
Gets a value indicating whether a property value or table cell whose value reference does not resolve is omitted rather than failing the read.
public bool OmitUnresolvableValues { get; init; }
Property Value
- bool
true to omit such a value and record its identifier in OmittedPropertyIds or OmittedPropertyIds; false, the default, to raise PstFileFormatException.
Remarks
A value reference does not resolve when it names a heap item the context's heap does not hold, when a property's fixed-width value is shorter than its type, or when it names a subnode the node does not hold or whose data tree cannot be resolved. Without this option each of these is container corruption that fails the whole context at every validation level. With it the value is omitted and the rest of the context stays readable, so a damaged object still yields what it can: the option is for recovering data from a damaged file.
The option is independent of ValidationLevel and covers individual values only. A fault in a heap's header, page map, or B-tree, in a table's column descriptions or row matrix, or in a node's subnode tree still fails the read, and a value whose reference resolves but whose data blocks fail their checks still raises PstFileFormatException when it is read.
ValidationLevel
Gets how strictly the file's structures and checksums are validated.
public PstValidationLevel ValidationLevel { get; init; }
Property Value
- PstValidationLevel
The validation level; Compatible by default.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |