OpenParable
Skip to content
← Back to skills

Use Fullpath

Development
use-fullpath

Use Fullpath is an Agent Skill for development published in the meziantou/Meziantou.Framework repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Ensure .NET projects use `Meziantou.Framework.FullPath` for local file path manipulation instead of raw strings. Use when: reviewing or writing code that constructs, combines, compares, or passes around local file/directory paths as strings in .NET/C# projects.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/meziantou/Meziantou.Framework/blob/HEAD/.github/skills/use-fullpath/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/use-fullpath, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Use FullPath for Local Path Manipulation

Use this skill when reviewing or writing .NET code that manipulates local file or directory paths.

Why

Raw string paths are a common source of bugs:

  • A path can be absolute or relative (c:\a\b vs .\a\b)
  • A path that looks absolute can actually be relative (c:a is relative)
  • Paths may contain . or .. segments that aren't resolved
  • Trailing directory separators cause inconsistent comparisons (c:\a vs c:\a\)
  • Path comparison must be case-insensitive on Windows and case-sensitive on Linux
  • Reserved device names on Windows (CON, PRN, NUL) can cause subtle failures
  • When a FileNotFoundException occurs, relative paths make debugging difficult
  • A string parameter gives no signal whether a full path or a relative path is expected

The FullPath struct from Meziantou.Framework.FullPath solves these problems by guaranteeing the stored value is always a fully-resolved absolute path with normalized separators.

Installation

# .NET 10+
dotnet package add Meziantou.Framework.FullPath

# .NET 9 and earlier
dotnet add package Meziantou.Framework.FullPath

The namespace is Meziantou.Framework.

Core Patterns

Creating a FullPath

// From a string (relative paths are resolved against the current directory)
FullPath path = FullPath.FromPath("demo");

// Well-known locations
FullPath temp = FullPath.GetTempPath();
FullPath cwd  = FullPath.CurrentDirectory();
FullPath docs = FullPath.GetFolderPath(Environment.SpecialFolder.MyDocuments);

Combining Paths

Use the / operator or FullPath.Combine — never string.Concat or string interpolation.

FullPath root = FullPath.FromPath("/repo");

// / operator (preferred for readability)
FullPath file = root / "src" / "Program.cs";

// Combine (useful when the number of segments is dynamic)
FullPath file2 = FullPath.Combine(root, "src", "Program.cs");

Comparing Paths

Comparisons are case-insensitive on Windows/macOS and case-sensitive on Linux by default. Navigation segments and trailing separators are already resolved, so equality just works.

// == and != use the OS-default comparison
if (pathA == pathB) { /* same file */ }

// Explicit case-sensitivity control
bool equal = pathA.Equals(pathB, ignoreCase: false);

Navigating the Path Tree

FullPath file = FullPath.FromPath("/repo/src/Program.cs");

FullPath dir       = file.Parent;              // /repo/src
string   name      = file.Name;               // Program.cs
string   nameNoExt = file.NameWithoutExtension; // Program
string   ext       = file.Extension;           // .cs

FullPath renamed = file.ChangeExtension(".vb"); // /repo/src/Program.vb

Checking Hierarchy

FullPath root = FullPath.FromPath("/repo");
FullPath file = root / "src" / "Program.cs";

bool isChild = file.IsChildOf(root); // true

Making a Relative Path

FullPath root = FullPath.FromPath("/repo");
FullPath file = root / "src" / "Program.cs";

string relative = file.MakePathRelativeTo(root); // src/Program.cs (or src\Program.cs on Windows)

Walking Up the Tree

FullPath start = FullPath.FromPath("/repo/src/deep/nested");

// Find the first ancestor (or self) matching a predicate
if (start.TryFindFirstAncestorOrSelf(
        p => File.Exists(p / ".editorconfig"), out FullPath match))
{
    // match is the closest directory containing .editorconfig
}

// Shortcut: find the Git repository root
if (start.TryFindGitRepositoryRoot(out FullPath gitRoot))
{
    // gitRoot is the closest directory containing .git
}

Interop with System.IO

FullPath has an implicit conversion to string, so it works directly with File, Directory, and most APIs that accept a string path.

FullPath config = root / "appsettings.json";

// No .Value or .ToString() needed
string json = File.ReadAllText(config);
File.WriteAllText(config, json);
Directory.CreateDirectory(config.Parent);

When you need the raw string explicitly (e.g., for logging or interpolation):

logger.LogInformation("Loading config from {Path}", config.Value);

Ensuring the Parent Directory Exists

FullPath output = root / "artifacts" / "report.html";
output.CreateParentDirectory(); // creates "artifacts" if it doesn't exist
File.WriteAllText(output, html);

JSON Serialization

FullPath has a built-in System.Text.Json converter. It serializes to a plain JSON string and deserializes back through FullPath.FromPath.

public sealed class AppSettings
{
    public FullPath OutputDirectory { get; set; }
}

// { "OutputDirectory": "C:\\repo\\output" }
var settings = JsonSerializer.Deserialize<AppSettings>(json);

Using FullPath in Method Signatures

Prefer FullPath over string in APIs that expect an absolute path. This makes intent explicit at the type level.

// ❌ Ambiguous — is this a full path or a relative fragment?
void Export(string outputPath) { }

// ✅ Clear contract — the caller must provide a resolved path
void Export(FullPath outputPath) { }

Collections and Dictionaries

Use FullPathComparer when storing paths in sets or dictionaries to get correct OS-aware equality.

var seen = new HashSet<FullPath>(); // uses default OS comparison
var map  = new Dictionary<FullPath, int>();

// Explicit comparer if needed
var caseSensitiveSet = new HashSet<FullPath>(FullPathComparer.CaseSensitive);

What to Look For in Reviews

SmellRefactor to
string filePath = Path.Combine(root, "sub", "file.txt");FullPath filePath = root / "sub" / "file.txt";
string fullPath = Path.GetFullPath(relative);FullPath fullPath = FullPath.FromPath(relative);
if (path1.Equals(path2, StringComparison.OrdinalIgnoreCase))if (path1 == path2) (with FullPath)
path.StartsWith(root) to check containmentpath.IsChildOf(root)
Path.GetDirectoryName(path)path.Parent
Path.GetFileName(path)path.Name
Path.GetExtension(path)path.Extension
Path.ChangeExtension(path, ext)path.ChangeExtension(ext)
Directory.CreateDirectory(Path.GetDirectoryName(path))path.CreateParentDirectory()
void Foo(string path) for an absolute-path parametervoid Foo(FullPath path)

Scope

This skill targets local file-system paths only. It does not apply to:

  • URLs or URIs
  • Cloud/blob storage paths
  • Database connection strings
  • Paths that must remain relative by design (e.g., entries inside a ZIP archive)