Sanitizes file and directory names to ensure compatibility with Windows (NTFS & exFat), Linux (ext4), and macOS (APFS).
Implements rules documented by Microsoft + file name length truncation to 255 bytes, which is common on many modern file systems + some unicode edge cases. Runs on any .NET platform.
using Codeuctivity;
string unsafeString = "file*Name";
string safeFileName = unsafeString.SanitizeFilename();
Console.WriteLine($"Unsafe: {unsafeString}");
//Unsafe: file*Name
Console.WriteLine($"Sanitized: {safeFileName}");
//Sanitized: file_Name
string safeFileNameOptionalReplacementChar = unsafeString.SanitizeFilename(' ');
Console.WriteLine($"SafeFileNameOptionalReplacementChar: {safeFileNameOptionalReplacementChar}");
//SafeFileNameOptionalReplacementChar: file NameRestrictions of Windows, Linux and macOS are all combined to an replacement pattern, that will sanitize any filename to be compatible with any of the OS and common filesystem restrictions.
| Pattern | OS that don't support pattern | OS that support pattern | Example |
|---|---|---|---|
| Reserved keywords | Windows | Linux, macOS | CON, PRN, AUX, ... |
| Reserved chars | Linux, Windows, macOS | '/', '\0' | |
| Reserved chars windows | Windows | Linux, macOS | '\', '""', ... |
| Invalid trailing chars | Windows | Linux, macOS | ' ', ',' |
| Max length Linux | Linux, | Windows, macOS | 255 bytes |
| Max length | Linux, Windows, macOS | 255 chars | |
| Unpaired Unicode surrogates | macOS, Linux | Windows | U+D800 - U+DFFF |
| NotAssigned to Unicode | macOS | Linux, Windows | U+67803, ... |
| "New" Unicode (today 17+) | macOS | Linux, Windows | , ... |
- Support for legacy .NET versions will be maintained as long as it is funded.
- Support for .NET Framework 4.6.2 and higher was added in Version 2.0.145.
- Edge case Unicode sanitization: .NET Framework uses Unicode 8.0, while .NET 8+ uses a newer version to detect unpaired surrogates and unassigned code points.
- This is relevant when dealing with emoticons.
- For example, "💏🏻" will be sanitized when running on .NET Framework 4.8, while it is supported as a valid filename on modern filesystems
The exFat specific tests are skipped as long as no exFat filesystem is available. Use this snippet to enable them:
$vhdpath = [System.IO.Path]::Combine($env:TEMP, 'ExFatTestContainer.vhd')
Remove-Item $vhdpath -ErrorAction SilentlyContinue
$vhdsize = 100MB
New-VHD -Path $vhdpath -Dynamic -SizeBytes $vhdsize | Mount-VHD -Passthru |Initialize-Disk -Passthru |New-Partition -AssignDriveLetter -UseMaximumSize |Format-Volume -FileSystem 'exFAT' -Confirm:$false -NewFileSystemLabel '{exfatLabel}' -Force|Out-NullRunning as admin will automatically create and mount a exFat drive while tests are running.
