Getting Started

System.IO.SafeTraversal v2.0.0

This library only contains one class called SafeTraversal that contains both instance methods and static methods. Let's jump to the code!

1. Reference all the required namespaces.

using System.IO;
using static System.Console;
//For .NET Framework
using System.IO.SafeTraversal;
//For .NET Core
using System.IO.SafeTraversal.Core;

2. To use instance error logging functionality, instantiate SafeTraversal class inside a method or as a global variable and subscribe its event within method or constructor

 SafeTraversal safeTraversal = new SafeTraversal();
 safeTraversal.LogError += (e, v) => WriteLine($"Error=`{v.ErrorMessage}`");

3. Let's define the path that we would like to traverse as a global variable.

 private readonly static string PATH_ONE = @"E:\sample data";

4. Traverse top level files or directories

//files
foreach (string file in safeTraversal.TraverseFiles(PATH_ONE))
{
	//process result here
}
//or 
foreach (string file in safeTraversal.TraverseFiles(PATH_ONE, SearchOption.TopDirectoryOnly))
{
	//process result here
}
//or
foreach (FileInfo file in safeTraversal.TraverseFiles(new DirectoryInfo(PATH_ONE), SearchOption.TopDirectoryOnly))
{
	//process result here
}

//dirs
foreach(DirectoryInfo dir in safeTraversal.TraverseDirectories(new DirectoryInfo(PATH_ONE)))
{
	//process result here
}

foreach(string dir in safeTraversal.TraverseDirectories(PATH_ONE, SearchOption.TopDirectoryOnly))
{
	//process result here
}

These methods are just small subsets used for demonstration purpose. The key concept is, when you pass path parameter as a string you'll get an IEnumerable of string whereas when you pass path as DirectoryInfo you'll get an IEnumerable of FileInfo or IEnumerable of DirectoryInfo. When you hit an unauthorized folders, the traversal won't stop and you can inspect the error message through LogError event.

5. Traverse all level files and directories

foreach (string file in safeTraversal.TraverseFiles(PATH_ONE, SearchOption.AllDirectories))
{
	//process result here
}
foreach(string dir in safeTraversal.TraverseDirectories(PATH_ONE, SearchOption.AllDirectories))
{
	//process result here
}

6. Traverse all level files and filter them by CommonSize enumeration

foreach (FileInfo file in safeTraversal.TraverseFiles(new DirectoryInfo(PATH_ONE), SearchOption.AllDirectories, CommonSize.Large))
{
	//process result here
}

Note: CommonSize is an enumeration that depicts Windows Explorer size filtering.

7. Traverse all level files and filter them by SearchFileByName option

foreach (FileInfo file in safeTraversal.TraverseFiles(new DirectoryInfo(PATH_ONE), SearchOption.AllDirectories,  new SearchFileByNameOption("myimage.jpg", includeExtension:true, caseSensitive:false)))
{
	//process result here
}

8. Traverse all level files and filter them by SearchFileBySize option

foreach (FileInfo file in safeTraversal.TraverseFiles(new DirectoryInfo(PATH_ONE), SearchOption.AllDirectories, new SearchFileBySizeOption(160, SizeType.KiloBytes)))
{
	//process result here
}

9. Traverse all level files and filter them by SearchFileBySizeRangeOption option

foreach (FileInfo file in safeTraversal.TraverseFiles(new DirectoryInfo(PATH_ONE), SearchOption.AllDirectories, new SearchFileBySizeRangeOption(1, 100, SizeType.MegaBytes)))
{
	//process result here
}

10. Traverse all level files and filter them by SearchFileByDateOption option

foreach (FileInfo file in safeTraversal.TraverseFiles(new DirectoryInfo(PATH_ONE), SearchOption.AllDirectories, new SearchFileByDateOption(new DateTime(2016, 7, 1), DateComparisonType.LastModificationDate)))
{
	//process result here
}

11. Traverse all files and filter them by SearchFileByDateRangeOption option

foreach (FileInfo file in safeTraversal.TraverseFiles(new DirectoryInfo(PATH_ONE), SearchOption.AllDirectories, new SearchFileByDateRangeOption(new DateTime(2016, 1, 1), new DateTime(2016, 12, 30), DateComparisonType.CreationDate)))
{
	//process result here
}

11. Traverse all files and filter them by SearchFileByRegularExpressionOption option

foreach (FileInfo file in safeTraversal.TraverseFiles(new DirectoryInfo(PATH_ONE), SearchOption.AllDirectories, new SearchFileByRegularExpressionOption(@"(?ix)myproject\d{1,3}", includeExtension:false)))
{
	//process result here
}

12. Traverse all files and filter them by SafeTraversalFileSearchOptions option

foreach (FileInfo file in safeTraversal.TraverseFiles(new DirectoryInfo(PATH_ONE), SearchOption.AllDirectories,  new SafeTraversalFileSearchOptions()
                {
                    CommonSize = CommonSize.Medium,
                    DateRangeOption = new SearchFileByDateRangeOption(new DateTime(2015, 1, 1), 
                    new DateTime(2017, 7, 1), DateComparisonType.LastModificationDate),
                    Extension = ".exe",
                    RegularExpressionOption = new SearchFileByRegularExpressionOption(@"(?i)(ab|xy)-random*?\d{5}")
                })))
{
	//process result here
}

SafeTraversalFileSearchOptions is composite option where you are free to specify more than one criteria to filter the result.

13. Traverse all files and filter them by custom filter

foreach (FileInfo file in safeTraversal.TraverseFiles(new DirectoryInfo(PATH_ONE), SearchOption.AllDirectories,
    x =>
    {
        return (x.IsReadOnly &&
                x.Extension.Equals(".txt", StringComparison.InvariantCultureIgnoreCase) &&
                String.IsNullOrEmpty(x.OpenText().ReadToEnd())? 
                false : x.OpenText().ReadToEnd().Contains("testing..."));
    }))
{
	//process result here
}

foreach (FileInfo file in safeTraversal.TraverseFiles(new DirectoryInfo(PATH_ONE), SearchOption.AllDirectories,
    x =>
    {
        bool success = true;
        try
        {
        	//Encrypt is just fictitious method
            success = Encrypt(x.FullName);
        }
        catch { success = false; }
        return success;
    }))
{
}

Using custom filter provides greater flexibility in filtering files or folders that satisfy our need. Keep in mind that this custom filter is error free. Although you pass exception inside this filter, no exception will be thrown. Allowing you to stay focus on the result rather than re-catching the exceptions. Take a look this snippet code for sample:

foreach (FileInfo file in safeTraversal.TraverseFiles(new DirectoryInfo(PATH_ONE), SearchOption.AllDirectories,
    x =>
    {
        if (x.Length > 0)
            throw new Exception();
        return true;
    }))
{
    WriteLine(file.FullName);
}

This snippet code won't throw an exception although you have non-empty files inside targeted path.