FileBasedApp.Toolkit 1.4.0

dotnet add package FileBasedApp.Toolkit --version 1.4.0
                    
NuGet\Install-Package FileBasedApp.Toolkit -Version 1.4.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="FileBasedApp.Toolkit" Version="1.4.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="FileBasedApp.Toolkit" Version="1.4.0" />
                    
Directory.Packages.props
<PackageReference Include="FileBasedApp.Toolkit" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add FileBasedApp.Toolkit --version 1.4.0
                    
#r "nuget: FileBasedApp.Toolkit, 1.4.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package FileBasedApp.Toolkit@1.4.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=FileBasedApp.Toolkit&version=1.4.0
                    
Install as a Cake Addin
#tool nuget:?package=FileBasedApp.Toolkit&version=1.4.0
                    
Install as a Cake Tool

FileBasedApp.Toolkit

A collection of opinionated helpers and extensions for building file-based applications in .NET.

The core package remains framework-neutral: Spectre.Console and SimpleExec integrations are available as separate, optional packages.

Package split and migration (1.4.0-preview-01)

If you previously used integration types from FileBasedApp.Toolkit, add an explicit reference to the corresponding package:

<PackageReference Include="FileBasedApp.Toolkit.Spectre" Version="1.4.0-preview-01" />
<PackageReference Include="FileBasedApp.Toolkit.SimpleExec" Version="1.4.0-preview-01" />

Add only the integrations you use. See Spectre integration for AnsiConsoleFactory and ExtendedCommandSettings, and SimpleExec integration for command runners. Namespaces remain unchanged, but moving types to new assemblies is a binary breaking change: recompile existing consumers after adding the package references. Core-only consumers do not need either integration package. Deserializers and FlexibleFilePath remain in core.

Features

  • Provides a PathUtil class for working with paths and validating string paths, including public static TryGetFile, TryGetFiles, TryGetDirectory, and TryGetDirectories helpers without a Spectre dependency
  • Provides LocalPathExtensions with IsHome, HasHomeDirectoryPrefix(), and ExpandHomeDirectory() for home-directory expansion, IsCurrentDirectory() for lexical current-directory detection, plus GetSegments() and Traverse() for lexical path traversal
  • Provides an IO class to provide methods and extension methods for TruePath
    • FindInFiles — filter files by stream predicate or regex (with ByLine / AllText strategies)
    • Replace — in-place file text transformation
    • SafeDeleteDirectory — safely delete directories with optional exception handling
  • Provides StringExtensions with StringJoin, IsNullOrWhitespace, and IsNullOrEmpty convenience methods
  • Includes the following libraries
    • TruePath 2.0.0
    • TestableIO.System.IO.Abstractions.Wrappers
    • TruePath.TestableIO.System.IO 1.1.0

Example

Path resolution and validation

Use PathUtil.TryGetFile / TryGetDirectory for a single AbsolutePath, or TryGetFiles / TryGetDirectories for an AbsolutePath[]. These helpers are in the core package and do not require ExtendedCommandSettings or Spectre.Console.

using FileBasedApp.Toolkit;
using TruePath;

AbsolutePath directory = PathUtil.TryGetDirectory(
    "input", allowEmpty: false, shouldExist: true,
    root: PredefinedRootPath.CurrentDirectory);

AbsolutePath[] files = PathUtil.TryGetFiles(
    ["settings.json", "defaults.json"], shouldExist: true);

AbsolutePath[] directories = PathUtil.TryGetDirectories(
    ["input", "output"], allowEmpty: false, shouldExist: true,
    root: PathUtil.GetCurrentWorkingFolder());

Directory overloads and batch file overloads accept a predefined root or a single absolute root. The params overloads accept multiple roots; omitted roots default to the current working directory. shouldExist controls existence validation.

Despite their TryGet names, these methods throw on invalid input rather than returning a Boolean. Null candidate arrays are rejected, as are empty file arrays. An empty directory array is treated as a single empty candidate: allowEmpty controls whether it may resolve to a root. Validation errors for multiple candidates are aggregated into an InvalidOperationException.

The protected TryGet* methods in ExtendedCommandSettings remain backward-compatible wrappers over these helpers, including their caller-argument expressions. Spectre's Validate() error conversion remains in the optional integration package.

TruePath IO extensions

using System.IO.Abstractions;
using FileBasedApp.Toolkit;

var applicationData = Environment.SpecialFolder.ApplicationData.GetSpecialFolder();
applicationData.FindRequiredParent(x => x.FileName == "SomeValue");
var ancestors = applicationData.GetAncestors(true).ToList();

// Combining with TruePath.TestableIO.System.IO
// This was orignally part of the FileBased.Toolkit library but moved
// to it's own library
var newDirectory = applicationData / "NewDirectory";
newDirectory.CreateDirectory();

IFileSystem fileSystem = new FileSystem();
fileSystem.File.Create(newDirectory / "test.txt");

(newDirectory / "..").GetDirectories(fileSystem)

Home-directory expansion

HasHomeDirectoryPrefix() detects a leading ~ segment in a relative path. ExpandHomeDirectory() replaces that segment with the user profile directory, preserving the remaining segments. Absolute paths and relative paths without a home-directory prefix are returned unchanged; this does not convert arbitrary relative paths to absolute paths.

using FileBasedApp.Toolkit;
using TruePath;

var path = new LocalPath("~/Documents/file.txt");
var hasHomePrefix = path.HasHomeDirectoryPrefix(); // true
var expanded = path.ExpandHomeDirectory(); // User profile directory / Documents / file.txt

IsHome identifies only the ~ marker itself. GetSegments() enumerates segments root-first, while Traverse() enumerates them leaf-first.

Current-directory paths and traversal

IsCurrentDirectory() checks the normalized path lexically: empty input, . and a/.. all represent the current-directory marker. An absolute path is not a marker, even when it points to the current working directory. This check does not access the file system.

using FileBasedApp.Toolkit;
using TruePath;

var path = new LocalPath("a/..");
var isCurrentDirectory = path.IsCurrentDirectory(); // true; Value is "." in TruePath 2.0
var segments = path.GetSegments(); // No segments; Traverse() is also empty

Traversal preserves absolute roots, Windows roots without a drive, and relative parent markers (..). A rooted-without-drive path such as \foo\bar has segments \, foo, and bar. Drive-relative prefixes remain attached to the first segment: C:foo\bar has segments C:foo and bar, while C: remains a single segment. Combining these segments in root-first order with / reconstructs the normalized path without resolving its drive or current-directory dependencies. Windows-only regression tests assert these segment and reconstruction contracts; cross-platform test execution remains unverified.

TruePath 2.0 migration notes

The toolkit now references TruePath 2.0.0 and the TestableIO bridge 1.1.0. TruePath normalizes empty input and paths such as a/.. to .; the toolkit still returns no traversal segments for these paths.

On Windows, PathUtil.AnalyzeFile() and AnalyzeDirectory() resolve inputs against a supplied absolute root as follows (root: C:\base):

Input Resolved path
\logs C:\logs
C:logs C:\base\logs
C: C:\base
D:logs Resolved against the process's current directory for drive D
D:\logs D:\logs

Drive-relative inputs are currently accepted. Cross-drive relative resolution depends on process/per-drive state, not just the supplied root; use fully qualified paths when deterministic resolution is required. Windows-only regression tests cover these cases for both file and directory analysis.

Absolute-path conversions require fully qualified input

AsAbsolutePath() (string and character-span overloads) and AsRequiredAbsolutePath() validate fully qualified paths; they do not resolve relative input against the current directory.

On Windows, C:\foo is valid, but \foo (unspecified drive), C:foo, and C: (relative to a drive's current directory) throw ArgumentException under TruePath 2.0. On Unix, use an absolute path such as /foo. Empty and relative input also throw.

The nullable-string AsAbsolutePath() returns null only for null input, not for an invalid path. AsRequiredAbsolutePath() throws ArgumentNullException for null. The span overload throws for invalid or empty input rather than returning null.

Use PathUtil.AnalyzeFile() or AnalyzeDirectory() when resolution against a supplied root is intended, or keep a relative path as a LocalPath instead of converting it.

Breaking change in the next minor release: FlexibleFilePath accepts relative paths

This behavioral breaking change will ship in a minor release, not a major release. FlexibleFilePath.GetAsLocalPath() and its implicit conversion to LocalPath now construct a LocalPath directly, selecting Windows on Windows and Unix elsewhere. Previously they constructed an AbsolutePath, rejecting ordinary relative input.

Relative paths such as folder/file.txt are now accepted and remain relative; they are not resolved against the current directory. Empty input and . represent the current-directory marker. Windows inputs such as \foo, C:foo, and C: are also accepted without resolving their drive or current-directory dependencies. Fully qualified paths remain supported.

Migration: Do not assume the returned LocalPath is absolute or rely on conversion throwing for relative input. If an absolute path is required, validate it explicitly with AbsolutePath.Create(localPath.Value) (which rejects non-fully-qualified input), or use PathUtil.AnalyzeFile() / AnalyzeDirectory() to resolve it against a supplied root.

var configured = new FlexibleFilePath(@"data\file.txt", "data/file.txt");
LocalPath path = configured; // Relative on either platform; no longer throws

Web URIs (AbsoluteWebUri / RelativeWebUri)

Strongly-typed, immutable wrappers around System.Uri for composing web URIs. Path segments, query strings, and fragments are represented as validated value objects (UriPathSegment, UriQueryString, UriFragment) and can be combined fluently via the / operator.

using FileBasedApp.Toolkit;

// Build an absolute URI fluently
var url = AbsoluteWebUri.Create("https://example.com")
          / UriPathSegment.From("first")
          / UriPathSegment.From("second")
          / UriQueryString.From("a=1&b=2")
          / UriFragment.From("Fragment");

// https://example.com/first/second?a=1&b=2#Fragment
Console.WriteLine(url.ToString());

// Or use method form
var api = AbsoluteWebUri.Create("https://example.com/api")
    .AddPathSegment(UriPathSegment.From("users"))
    .AddQueryPart("page", "1")
    .WithFragment(UriFragment.From("top"));

// Replace the entire path with a single segment (preserves query/fragment)
var reset = AbsoluteWebUri.Create("https://example.com/old/path?q=1")
    .WithPathSegment(UriPathSegment.From("new"));
// https://example.com/new?q=1

// Relative URIs work the same way
var relative = RelativeWebUri.Create("/search")
               / UriQueryString.From("q=hello");

Each operation returns a new instance, so the originals are never mutated. Invalid inputs (empty segments, illegal characters) throw at the value-object construction step via Vogen validation.

HTTP extensions

AbsoluteWebUriHttpExtensions adds a WithBaseAddress extension on HttpClient that accepts an IWebUri<TSelf>, and HttpResponseMessageExtensions adds ToJson<T> / ToRequiredJson<T> for deserializing response content via a source-generated JsonTypeInfo<T>. Both deserialization helpers call EnsureSuccessStatusCode first; ToRequiredJson additionally throws InvalidOperationException when deserialization yields null.

using System.Text.Json.Serialization;
using FileBasedApp.Toolkit;

[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
[JsonSerializable(typeof(Widget))]
internal partial class AppJsonContext : JsonSerializerContext { }

public record Widget(string Name, int Count);

var baseUri = AbsoluteWebUri.Create("https://example.com/api");
var httpClient = new HttpClient().WithBaseAddress(baseUri);

using var response = await httpClient.GetAsync("widgets?id=1");
var widget = await response.ToRequiredJson(AppJsonContext.Default.Widget);

Template

You can use the FileBasedApp.Toolkit.Template to easily create a new filebase app with FileBasedApp.Toolkit references added https://www.nuget.org/packages/FileBasedApp.Toolkit.Template/

Bugs or things missing

Feel free to create an issue or submit a pull request.

Credits

Floppy disc icons created by IYAHICON - Flaticon

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed.  net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on FileBasedApp.Toolkit:

Package Downloads
FileBasedApp.Toolkit.CSharp

Roslyn-based helpers for detecting and working with file-based .NET apps.

FileBasedApp.Toolkit.Spectre

Spectre.Console output factories and Spectre.Console.Cli settings helpers for file-based apps.

FileBasedApp.Toolkit.SimpleExec

Fluent command runners and testable SimpleExec wrappers for file-based apps.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.4.0 82 11/13/2026
1.3.0 155 11/8/2026
1.2.0 195 10/12/2026
1.1.2 201 9/15/2026
1.1.1 248 8/29/2026
1.1.0 157 8/29/2026 1.1.0 is deprecated.
1.0.1 181 8/25/2026
1.0.0 176 8/23/2026
0.21.0 433 7/12/2026
0.20.0 258 4/17/2026
0.20.0-rc-01 160 4/16/2026
0.19.1 152 4/8/2026
0.19.0 186 4/8/2026
0.19.0-rc-01 161 4/8/2026
0.18.0 195 4/5/2026
0.18.0-rc-01 150 4/5/2026
0.17.0 187 3/29/2026
0.17.0-rc-01 149 3/25/2026
0.16.0 192 3/15/2026
Loading failed

- Update with support for .net sdk 11
         - Spectre integration: add ExtendedCommandSettings.TryGetFiles and TryGetDirectories batch validation for .NET 10 and .NET 11, returning absolute path arrays and aggregating validation errors for multiple candidates.
         - Add predefined-root and single-absolute-root forwarding overloads for batch path validation, with XML documentation.
         - Expose TryGetFile, TryGetFiles, TryGetDirectory, and TryGetDirectories as public static PathUtil helpers in the core package without Spectre dependencies.
         - Retain the protected ExtendedCommandSettings TryGet overloads as backward-compatible wrappers over PathUtil, preserving signatures and caller-argument expressions.
         - Update the file-based app template to call PathUtil directly; add core path-helper and compatibility regression coverage.