SanitizeFilename

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.

Example

usingCodeuctivity;stringunsafeString="file*Name";stringsafeFileName=unsafeString.SanitizeFilename();Console.WriteLine($"Unsafe: {unsafeString}");//Unsafe: file*NameConsole.WriteLine($"Sanitized: {safeFileName}");//Sanitized: file_NamestringsafeFileNameOptionalReplacementChar=unsafeString.SanitizeFilename(' ');Console.WriteLine($"SafeFileNameOptionalReplacementChar: {safeFileNameOptionalReplacementChar}");//SafeFileNameOptionalReplacementChar: file Name

Try it yourself: dotnetfiddle.net/bFWqX0

Rules

Restrictions 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	🫈, ...

.NET framework support

• Use Codeuctivity.SanitizeFilename NuGet package version 2.x.x to get the latest version of the library with .NET framework support.
• 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

Test setup

The exFat specific tests are skipped as long as no exFat filesystem is available. Use this snippet to enable them:

Windows

$vhdpath= [System.IO.Path]::Combine($env:TEMP,'ExFatTestContainer.vhd')
Remove-Item$vhdpath-ErrorAction SilentlyContinue
$vhdsize=100MBNew-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-Null

Running as admin will automatically create and mount a exFat drive while tests are running. .