Interop and Migration

Overview

This article is a practical guide for code that already uses System.IO, either because you're migrating an existing application or because you depend on a third-party library that takes string, FileInfo or DirectoryInfo parameters. The library is designed to coexist with System.IO so you can adopt it incrementally.

Bridging at the Boundaries

The two key bridges are:

Use them at the boundaries of your code where it interacts with non-library APIs. Inside your own code, work with path objects.

Strings → Paths

To turn a string you got from somewhere else into a path, parse it with the parser that matches what you know about the input:

IAbsoluteFilePath path = FilePath.ParseAbsolute(stringFromExternalApi, PathOptions.None);

Use None when the string came from the file system itself (e.g. an OS file picker). The OS may surface "unfriendly" paths that exist and need to be opened. Use NoUnfriendlyNames (the default) for application-defined or user-typed input.

See Parsing Paths and PathOptions.

Paths → Strings

When an external API takes a string path, hand it PathExport (only available on absolute paths):

ThirdPartyApi.OpenFile(file.PathExport);
Important

Use PathExport, not PathDisplay or ToString, when calling APIs outside this library. PathExport is specially formatted (e.g. with \\?\ on Windows) so the OS won't silently rewrite it.

FileInfo / DirectoryInfo → Paths

Use the SystemExtensions extension methods:

using Singulink.IO;

DirectoryInfo di = new(@"C:\some\path");
FileInfo fi = new(@"C:\some\file.txt");

IAbsoluteDirectoryPath dirPath = di.ToPath();
IAbsoluteFilePath filePath = fi.ToPath();

Both extensions parse FullName with NoUnfriendlyNames by default; pass None to accept any path:

IAbsoluteFilePath filePath = fi.ToPath(PathOptions.None);

When you only have a FileSystemInfo reference (e.g. from a file-picker that surfaces either kind), call ToPath on the base type. The returned IAbsolutePath has the runtime type that matches the underlying info object:

FileSystemInfo fsi = picker.SelectedItem;
IAbsolutePath path = fsi.ToPath();

switch (path)
{
    case IAbsoluteFilePath file: /* ... */ break;
    case IAbsoluteDirectoryPath dir: /* ... */ break;
}

If you also need cached metadata for the entry, use ToCachedInfo instead of ToPath. It returns a CachedFileInfo / CachedDirectoryInfo for a FileInfo / DirectoryInfo, or the matching concrete type when called on a FileSystemInfo:

CachedFileInfo cached = fi.ToCachedInfo();
CachedEntryInfo info = fsi.ToCachedInfo();
Caution

FullName may have already been rewritten by System.IO (trimming trailing spaces and dots) before ToPath sees it. If preserving the exact original characters matters, parse the original string directly with ParseAbsolute.

Paths → FileInfo / DirectoryInfo

When an external API takes a FileInfo or DirectoryInfo, construct one from PathExport:

FileInfo fi = new(absoluteFilePath.PathExport);
DirectoryInfo di = new(absoluteDirectoryPath.PathExport);

ThirdPartyApi.Process(fi);

System.IO → Library Mapping

A reference of common System.IO operations and their library equivalents:

Path Construction

System.IO Library
Combine CombineFile / CombineDirectory / dir + relative
GetDirectoryName path.ParentDirectory.PathDisplay
GetFileName Name
GetFileNameWithoutExtension NameWithoutExtension
GetExtension Extension
ChangeExtension WithExtension
GetFullPath ParseAbsolute (or Parse if it could be relative)
GetTempPath GetTemp
GetTempFileName CreateTempFile

Files

System.IO Library
Exists Exists
Open OpenStream
Copy CopyTo
Move MoveTo
Replace Replace
Delete Delete
GetAttributes Attributes
GetLastWriteTimeUtc LastWriteTimeUtc
new FileInfo(p) (for metadata) GetInfo (returns CachedFileInfo)

Directories

System.IO Library
Exists Exists
CreateDirectory Create
Delete Delete
GetCurrentDirectory GetCurrent
SetCurrentDirectory SetCurrent
GetParent ParentDirectory
GetFiles GetChildFiles
GetDirectories GetChildDirectories
EnumerateFileSystemEntries GetChildEntries

Drives

System.IO Library
GetDrives GetMountingPoints
AvailableFreeSpace AvailableFreeSpace (on any absolute directory)
TotalFreeSpace TotalFreeSpace
TotalSize TotalSize
DriveType DriveType
DriveFormat FileSystem

See Drive and Disk Information.

Migration Strategy

A pragmatic order of operations:

  1. Adopt at the edges first. New code parses inputs into path objects; old code keeps working with strings until you touch it.
  2. Use ToPath to bridge existing FileInfo / DirectoryInfo chains without rewriting the calling code.
  3. Replace try/catch ladders with the parse-vs-IO split. Anything inside a parse step catches ArgumentException; anything inside an I/O step catches IOException. See Exception Handling.
  4. Convert GetFiles / EnumerateFiles calls to GetChild* enumeration with SearchOptions. Pay attention to MatchCasing: the library's case-insensitive default is consistent across platforms, which is a behavior change from System.IO on Unix.
  5. Drop DriveInfo workarounds. UNC paths, mounted subdirs and per-user quotas Just Work via the disk-space members on absolute directories.

When You Still Need Strings

You'll still encounter APIs that demand a string. Continue using PathExport:

public Task UploadAsync(IAbsoluteFilePath file)
{
    return _httpClient.PostAsync(_url, new StreamContent(File.OpenRead(file.PathExport)));
}

Don't use PathDisplay for I/O even if it looks the same as PathExport for typical paths; the difference is invisible until something subtle goes wrong.

Next Steps