Adds -Credential parameter and Truncate Warning

docs/en-US/Get-ADTreeGroupMember.md

@@ -102,7 +102,7 @@ The `-ShowAll` switch indicates that the cmdlet should display the hierarchy of
 ### -Depth
 
 Determines the number of nested groups and their members included in the recursion.
-By default, only 3 levels of recursion are included.
+By default, only 3 levels of recursion are included. `Get-ADTreeGroupMember` emits a warning if the levels exceed this number.
 
 ```yaml
 Type: Int32

docs/en-US/Get-ADTreePrincipalGroupMembership.md

@@ -98,7 +98,7 @@ The `-ShowAll` switch indicates that the cmdlet should display the hierarchy of
 ### -Depth
 
 Determines the number of nested group memberships included in the recursion.
-By default, only 3 levels of recursion are included.
+By default, only 3 levels of recursion are included. `Get-ADTreePrincipalGroupMembership` emits a warning if the levels exceed this number.
 
 ```yaml
 Type: Int32

src/PSADTree/Commands/GetADTreeGroupMemberCommand.cs

@@ -21,33 +21,35 @@ protected override void ProcessRecord()
     {
         Dbg.Assert(Identity is not null);
         Dbg.Assert(_context is not null);
+        _truncatedOutput = false;
 
         try
         {
             using GroupPrincipal? group = GroupPrincipal.FindByIdentity(_context, Identity);
             if (group is null)
             {
-                WriteError(ErrorHelper.IdentityNotFound(Identity));
+                WriteError(Exceptions.IdentityNotFound(Identity));
                 return;
             }
 
-            WriteObject(
-                sendToPipeline: Traverse(
-                    groupPrincipal: group,
-                    source: group.DistinguishedName),
-                enumerateCollection: true);
+            TreeObjectBase[] result = Traverse(
+                groupPrincipal: group,
+                source: group.DistinguishedName);
+
+            DisplayWarningIfTruncatedOutput();
+            WriteObject(sendToPipeline: result, enumerateCollection: true);
         }
-        catch (Exception e) when (e is PipelineStoppedException or FlowControlException)
+        catch (Exception _) when (_ is PipelineStoppedException or FlowControlException)
         {
             throw;
         }
-        catch (MultipleMatchesException e)
+        catch (MultipleMatchesException exception)
         {
-            WriteError(e.AmbiguousIdentity(Identity));
+            WriteError(exception.AmbiguousIdentity(Identity));
         }
-        catch (Exception e)
+        catch (Exception exception)
         {
-            WriteError(e.Unspecified(Identity));
+            WriteError(exception.Unspecified(Identity));
         }
     }
 
@@ -105,13 +107,13 @@ private TreeObjectBase[] Traverse(
                 _index.TryAddPrincipals();
                 current?.Dispose();
             }
-            catch (Exception e) when (e is PipelineStoppedException or FlowControlException)
+            catch (Exception _) when (_ is PipelineStoppedException or FlowControlException)
             {
                 throw;
             }
-            catch (Exception e)
+            catch (Exception exception)
             {
-                WriteError(e.EnumerationFailure(current));
+                WriteError(exception.EnumerationFailure(current));
             }
         }
 
@@ -183,7 +185,7 @@ private TreeObjectBase ProcessPrincipal(
 
         TreeObjectBase AddTreeObject(TreeObjectBase obj)
         {
-            if (Recursive.IsPresent || depth <= Depth)
+            if (depth <= Depth)
             {
                 _index.AddPrincipal(obj);
             }
@@ -211,7 +213,6 @@ TreeObjectBase HandleGroup(
 
     private void EnumerateMembers(TreeGroup parent, int depth)
     {
-        bool shouldProcess = Recursive.IsPresent || depth <= Depth;
         foreach (TreeObjectBase member in parent.Childs)
         {
             if (member is TreeGroup treeGroup)
@@ -220,7 +221,7 @@ private void EnumerateMembers(TreeGroup parent, int depth)
                 continue;
             }
 
-            if (shouldProcess)
+            if (depth <= Depth)
             {
                 _index.Add(member.Clone(parent, depth));
             }

src/PSADTree/Commands/GetADTreePrincipalGroupMembershipCommand.cs

@@ -18,31 +18,32 @@ protected override void ProcessRecord()
     {
         Dbg.Assert(Identity is not null);
         Dbg.Assert(_context is not null);
+        _truncatedOutput = false;
         Principal? principal;
         Clear();
 
         try
         {
             principal = Principal.FindByIdentity(_context, Identity);
         }
-        catch (Exception e) when (e is PipelineStoppedException or FlowControlException)
+        catch (Exception _) when (_ is PipelineStoppedException or FlowControlException)
         {
             throw;
         }
-        catch (MultipleMatchesException e)
+        catch (MultipleMatchesException exception)
         {
-            WriteError(e.AmbiguousIdentity(Identity));
+            WriteError(exception.AmbiguousIdentity(Identity));
             return;
         }
-        catch (Exception e)
+        catch (Exception exception)
         {
-            WriteError(e.Unspecified(Identity));
+            WriteError(exception.Unspecified(Identity));
             return;
         }
 
         if (principal is null)
         {
-            WriteError(ErrorHelper.IdentityNotFound(Identity));
+            WriteError(Exceptions.IdentityNotFound(Identity));
             return;
         }
 
@@ -69,7 +70,7 @@ protected override void ProcessRecord()
 
         try
         {
-            using PrincipalSearchResult<Principal> search = principal.GetGroups();
+            using PrincipalSearchResult<Principal> search = principal.GetGroups(_context);
             foreach (Principal parent in search.GetSortedEnumerable(_comparer))
             {
                 if (ShouldExclude(parent, _exclusionPatterns))
@@ -82,22 +83,22 @@ protected override void ProcessRecord()
                 Push(groupPrincipal, treeGroup);
             }
         }
-        catch (Exception e) when (e is PipelineStoppedException or FlowControlException)
+        catch (Exception _) when (_ is PipelineStoppedException or FlowControlException)
         {
             throw;
         }
-        catch (Exception e)
+        catch (Exception exception)
         {
-            WriteError(e.EnumerationFailure(null));
+            WriteError(exception.EnumerationFailure(null));
         }
         finally
         {
             principal?.Dispose();
         }
 
-        WriteObject(
-            sendToPipeline: Traverse(source),
-            enumerateCollection: true);
+        TreeObjectBase[] result = Traverse(source);
+        DisplayWarningIfTruncatedOutput();
+        WriteObject(sendToPipeline: result, enumerateCollection: true);
     }
 
     private TreeObjectBase[] Traverse(string source)
@@ -138,7 +139,7 @@ private TreeObjectBase[] Traverse(string source)
                     continue;
                 }
 
-                using PrincipalSearchResult<Principal>? search = current?.GetGroups();
+                using PrincipalSearchResult<Principal>? search = current?.GetGroups(_context);
 
                 if (search is not null)
                 {
@@ -148,13 +149,13 @@ private TreeObjectBase[] Traverse(string source)
                 _index.Add(treeGroup);
                 current?.Dispose();
             }
-            catch (Exception e) when (e is PipelineStoppedException or FlowControlException)
+            catch (Exception _) when (_ is PipelineStoppedException or FlowControlException)
             {
                 throw;
             }
-            catch (Exception e)
+            catch (Exception exception)
             {
-                WriteError(e.EnumerationFailure(current));
+                WriteError(exception.EnumerationFailure(current));
             }
         }
 
@@ -197,7 +198,7 @@ TreeGroup ProcessGroup(GroupPrincipal group)
 
     private void EnumerateMembership(TreeGroup parent, int depth)
     {
-        if (!Recursive.IsPresent && depth > Depth)
+        if (depth > Depth)
         {
             return;
         }

src/PSADTree/ErrorHelper.cs → src/PSADTree/Exceptions.cs

@@ -4,7 +4,7 @@
 
 namespace PSADTree;
 
-internal static class ErrorHelper
+internal static class Exceptions
 {
     internal static ErrorRecord IdentityNotFound(string? identity) =>
         new(
@@ -13,6 +13,13 @@ internal static ErrorRecord IdentityNotFound(string? identity) =>
             ErrorCategory.ObjectNotFound,
             identity);
 
+    internal static ErrorRecord CredentialRequiresServer() =>
+        new(
+            new ArgumentException("Server parameter is required when Credential parameter is used."),
+            "CredentialRequiresServer",
+            ErrorCategory.InvalidOperation,
+            null);
+
     internal static ErrorRecord AmbiguousIdentity(this Exception exception, string? identity) =>
         new(exception, "AmbiguousIdentity", ErrorCategory.InvalidResult, identity);
 

src/PSADTree/PSADTreeCmdletBase.cs

@@ -16,6 +16,8 @@ public abstract class PSADTreeCmdletBase : PSCmdlet, IDisposable
 
     private bool _disposed;
 
+    protected bool _truncatedOutput;
+
     protected readonly Stack<(GroupPrincipal? group, TreeGroup treeGroup)> _stack = new();
 
     internal readonly TreeCache _cache = new();
@@ -30,7 +32,6 @@ public abstract class PSADTreeCmdletBase : PSCmdlet, IDisposable
         | WildcardOptions.CultureInvariant
         | WildcardOptions.IgnoreCase;
 
-
     [Parameter(
             Position = 0,
             Mandatory = true,
@@ -40,7 +41,11 @@ public abstract class PSADTreeCmdletBase : PSCmdlet, IDisposable
     public string? Identity { get; set; }
 
     [Parameter]
-    public string? Server { get; set; }
+    public string Server { get; set; } = Environment.UserDomainName;
+
+    [Parameter]
+    [Credential]
+    public PSCredential? Credential { get; set; }
 
     [Parameter(ParameterSetName = DepthParameterSet)]
     [ValidateRange(0, int.MaxValue)]
@@ -60,20 +65,29 @@ protected override void BeginProcessing()
     {
         try
         {
+            if (Recursive.IsPresent)
+            {
+                Depth = int.MaxValue;
+            }
+
             if (Exclude is not null)
             {
                 _exclusionPatterns = Exclude
                     .Select(e => new WildcardPattern(e, _wpoptions))
                     .ToArray();
             }
 
-            if (Server is null)
+            if (Credential is null)
             {
-                _context = new PrincipalContext(ContextType.Domain);
+                _context = new PrincipalContext(ContextType.Domain, Server);
                 return;
             }
 
-            _context = new PrincipalContext(ContextType.Domain, Server);
+            _context = new PrincipalContext(
+                ContextType.Domain,
+                Server,
+                Credential.UserName,
+                Credential.GetNetworkCredential().Password);
         }
         catch (Exception exception)
         {
@@ -83,9 +97,24 @@ protected override void BeginProcessing()
 
     protected void Push(GroupPrincipal? groupPrincipal, TreeGroup treeGroup)
     {
-        if (Recursive.IsPresent || treeGroup.Depth <= Depth)
+        if (treeGroup.Depth > Depth)
+        {
+            return;
+        }
+
+        if (treeGroup.Depth == Depth)
+        {
+            _truncatedOutput = true;
+        }
+
+        _stack.Push((groupPrincipal, treeGroup));
+    }
+
+    protected void DisplayWarningIfTruncatedOutput()
+    {
+        if (_truncatedOutput)
         {
-            _stack.Push((groupPrincipal, treeGroup));
+            WriteWarning($"Result is truncated as enumeration has exceeded the set depth of {Depth}.");
         }
     }