Splitted from #1953

Background and Motivation

In PowerShell Core repo we are trying to migrate to FileSystemEnumerable. Prototype shows great performance improvements.

We need to implement Depth parameter for Get-ChildItem cmdlet (aka dir). The parameter limits a depth of recursion.

This cannot be achieved without creating new classes (based on FileSystemEnumerator and FileSystemEnumerable) and creating non-trivial code as it requires processing a directory tree. All this negates the benefits of this API.

Proposed API

namespace System.IO
{
    public class EnumerationOptions
    {
        /// <summary>
        /// Stop recursion if current depth exceeds the value.
        /// Default is int.MaxValue (no limit).
        /// </summary>
        public int MaxRecursionDepth { get; set; }  // New API
    }
}

Usage Examples

var options = new System.IO.EnumerationOptions
    {
         RecurseSubdirectories = recurse,
         MatchType = MatchType.Win32,
         AttributesToSkip = 0,
         IgnoreInaccessible = false,
         MaxRecursionDepth = 2
    };

var paths = new FileSystemProviderEnumerable<string>(
                directory,
                (ref FileSystemEntry entry) => entry.FileName.ToString()),
                options)
    {
        ShouldIncludePredicate = FileSystemEntryFilter,

        ShouldRecursePredicate = (ref FileSystemEntry entry) => FileSystemRecursionPredicate
    };

Alternative Designs

What is better name - MaxRecursionDepth vs MaxDepthRecursion vs MaxDepthOfRecursion vs MaxDepth ?
(there is JsonSerializerOptions.MaxDepth)

Risks

Minor performance regression due to we have to keep additional uint value in a subdirectory queue.

Implementation details

Current implementation uses Queue to track subdirectories. We could put in the queue current depth +1 value together with subdirectory path. This allow to restore correct depth value at subdirectory dequeue.
And we need add Depth check in recursion condition.