Cached Entry Info

Overview

CachedEntryInfo is the library's replacement for System.IO.FileInfo and DirectoryInfo. It captures a consistent snapshot of an entry's metadata in a single file system call. Two concrete types exist:

The design fixes a handful of long-standing pitfalls in the System.IO equivalents.

What's Different

Existence-Guaranteed at Construction

You cannot obtain a CachedEntryInfo for a path that doesn't exist (or is the wrong type). Construction validates both up front and throws otherwise. There's no chance of holding an info object whose properties surprise-throw on first access.

Read-Only Properties

All properties are read-only. To change a file's attributes or timestamps, go through the Path property (which is a real path object) and then call Refresh() to update the cached snapshot:

CachedFileInfo info = file.GetInfo();

info.Path.Attributes |= FileAttributes.Hidden;
info.Path.LastWriteTimeUtc = DateTime.UtcNow;

info.Refresh();   // re-query the file system

Type-Stable

If something on disk changes the entry from a file into a directory (or vice versa), Refresh() throws IOException rather than silently returning misleading data.

Obtaining a CachedEntryInfo

From a Path

Call GetInfo() on any IAbsolutePath. The static return type matches the path:

CachedFileInfo fileInfo = absoluteFilePath.GetInfo();
CachedDirectoryInfo dirInfo = absoluteDirectoryPath.GetInfo();

GetInfo() throws if the entry doesn't exist or is the wrong type.

From Enumeration

Use the *Info enumeration variants (see Searching and Enumeration) to get cached info objects directly without an extra stat per entry:

foreach (CachedFileInfo info in dir.GetChildFilesInfo("*.log"))
    Console.WriteLine($"{info.Path.Name,-30} {info.Length,12:N0} {info.LastWriteTimeUtc:O}");

Properties

CachedEntryInfo (base):

  • Path: the underlying IAbsolutePath.
  • Attributes.
  • CreationTime / CreationTimeUtc.
  • LastAccessTime / LastAccessTimeUtc.
  • LastWriteTime / LastWriteTimeUtc.

CachedFileInfo adds:

  • Path narrowed to IAbsoluteFilePath.
  • IsReadOnly.
  • Length.

CachedDirectoryInfo adds only the narrowed Path to IAbsoluteDirectoryPath.

Refresh

Refresh() re-queries the file system and updates the cached values. Call it whenever you suspect the underlying entry may have changed:

info.Refresh();

If the entry no longer exists or has changed type (a file became a directory, etc.), Refresh() throws IOException.

When to Use Cached Info

Use cached info when you need multiple pieces of metadata for the same entry:

// Multiple property accesses on a path each touch the file system:
file.Length;            // stat
file.LastWriteTimeUtc;  // stat
file.Attributes;        // stat

// One stat, multiple reads:
CachedFileInfo info = file.GetInfo();
info.Length;
info.LastWriteTimeUtc;
info.Attributes;

Use cached info during enumeration (Get*Info methods) whenever you'll read metadata from the results. The file system call that produced the entry already had the metadata, and the *Info variants surface it without a second round-trip.

When Not to Use Cached Info

For one-off checks where you only need a single property, going through the path directly is fine and slightly cheaper than constructing a snapshot:

if (file.LastWriteTimeUtc > cutoff) { /* ... */ }

Next Steps