-### DESCRIPTION
-Gets Group's and User's membership or Group parentship and draws it's hierarchy.
-Helps identifying Circular Nested Groups.
+
+ Tree like cmdlets for Active Directory Principals!
+
-### PARAMETER
+[](https://github.com/santisq/PSADTree/actions/workflows/ci.yml)
+[](https://www.powershellgallery.com/packages/PSADTree)
+[](https://github.com/santisq/PSADTree/blob/main/LICENSE)
-| Parameter Name | Description |
-| --- | --- |
-| `-Name ` | __Name, SamAccountName or DistinguishedName__ of an AD Object of the class __User__ or __Group__ |
-| `[-RecursionProperty ]` | Set AD attribute for recursion. __Valid Values__: `Member` / `MemberOf`. __Default Value__: `Member` |
-| `[-Server ]` | __FQDN or NetBIOS name__ for the instance to connect to. |
-| `[]` | See [`about_CommonParameters`](https://go.microsoft.com/fwlink/?LinkID=113216) |
+
-### OUTPUTS
-``
+PSADTree is a PowerShell Module with cmdlets that emulate the [`tree` command](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/tree) for Active Directory Principals.
+This Module currently includes two cmdlets:
-- `InputParameter` The input user or group
-- `Index` The object on each level of recursion
-- `Recursion` The level of recursion or nesting
-- `Class` The objectClass
-- `Hierarchy` The hierarchy map of the input paremeter
+- [Get-ADTreeGroupMember](Get-ADTreeGroupMember.md) for AD Group Members.
+- [Get-ADTreePrincipalGroupMembership](Get-ADTreePrincipalGroupMembership.md) for AD Principal Group Membership.
-### REQUIREMENTS
+__Both cmdlets help with discovery of Circular Nested Groups.__
-- PowerShell v5.1
+## Documentation
+Check out [__the docs__](./docs/en-US/PSADTree.md) for information about how to use this Module.
-### USAGE EXAMPLES
+## Installation
+### Gallery
+
+The module is available through the [PowerShell Gallery](https://www.powershellgallery.com/packages/PSADTree):
+
+```powershell
+Install-Module PSADTree -Scope CurrentUser
+```
+
+### Source
+
+```powershell
+git clone 'https://github.com/santisq/PSADTree.git'
+Set-Location ./PSADTree
+./build.ps1
```
-PS C:\> Get-Hierarchy ExampleGroup
-PS C:\> gh ExampleGroup -RecursionProperty MemberOf
-PS C:\> Get-ADGroup ExampleGroup | Get-Hierarchy -RecursionProperty MemberOf
-PS C:\> Get-ADGroup ExampleGroup | gh
-PS C:\> Get-ADGroup -Filter "Name -like 'ExampleGroups*'" | Get-Hierarchy
-PS C:\> 'Group1,Group2,Group3'.split(',') | Get-Hierarchy -RecursionProperty MemberOf
+
+## Requirements
+
+This Module uses the [`System.DirectoryServices.AccountManagement` Namespace](https://learn.microsoft.com/en-us/dotnet/api/system.directoryservices.accountmanagement?view=dotnet-plat-ext-7.0) to query Active Directory, its System Requirement is __Windows OS__ and is compatible with __Windows PowerShell v5.1__ or [__PowerShell 7+__](https://github.com/PowerShell/PowerShell).
+
+## Usage
+
+These are some examples of what the cmdlets from this Module allow you to do. For more examples check out the docs.
+
+### Get the members of a group
+
+```powershell
+PS ..\PSADTree> Get-ADTreeGroupMember TestGroup007
+
+ Source: CN=TestGroup007,OU=Operations,DC=ChildDomain,DC=ParentDomain,DC=myDomain,DC=xyz
+
+Domain ObjectClass Hierarchy
+------ ----------- ---------
+ChildDomain group TestGroup007
+ChildDomain msDS-ManagedServiceAccount ├── testMSA$
+ChildDomain user ├── TestUser013
+ChildDomain user ├── TestUser010
+ChildDomain user ├── TestUser007
+ChildDomain group ├── TestGroup001
+ChildDomain user │ ├── TestUser015
+ChildDomain user │ ├── TestUser013
+ChildDomain user │ ├── TestUser010
+ChildDomain user │ ├── TestUser007
+ChildDomain user │ ├── TestUser002
+ChildDomain group │ ├── TestGroup005
+ParentDomain group │ │ ├── TestGroup001
+ParentDomain group │ │ └── TestGroup002
+ChildDomain group │ ├── TestGroup006
+ChildDomain computer │ │ ├── TestComputer0000004$
+ChildDomain computer │ │ ├── TestComputer0000003$
+ChildDomain computer │ │ ├── TestComputer0000002$
+ChildDomain computer │ │ └── TestComputer0000001$
+ChildDomain group │ └── TestGroup007 ↔ Circular Reference
+ChildDomain group ├── TestGroup005 ↔ Processed Group
+ChildDomain group └── TestGroup006 ↔ Processed Group
+```
+
+### Control the grade of recursion with the `-Depth` parameter
+
+The default value for `-Depth` is 3.
+
+```powershell
+PS ..\PSADTree> Get-ADTreeGroupMember TestGroup007 -Depth 2
+
+ Source: CN=TestGroup007,OU=Operations,DC=ChildDomain,DC=ParentDomain,DC=myDomain,DC=xyz
+
+Domain ObjectClass Hierarchy
+------ ----------- ---------
+ChildDomain group TestGroup007
+ChildDomain msDS-ManagedServiceAccount ├── testMSA$
+ChildDomain user ├── TestUser013
+ChildDomain user ├── TestUser010
+ChildDomain user ├── TestUser007
+ChildDomain group ├── TestGroup001
+ChildDomain user │ ├── TestUser015
+ChildDomain user │ ├── TestUser013
+ChildDomain user │ ├── TestUser010
+ChildDomain user │ ├── TestUser007
+ChildDomain user │ ├── TestUser002
+ChildDomain group │ ├── TestGroup005
+ChildDomain group │ ├── TestGroup006
+ChildDomain group │ └── TestGroup007 ↔ Circular Reference
+ChildDomain group ├── TestGroup005 ↔ Processed Group
+ChildDomain group └── TestGroup006 ↔ Processed Group
+```
+
+### Get group members recursively, include only groups and display all processed groups
+
+The `-Recursive` switch indicates that the cmdlet should traverse all the group hierarchy.
+The `-Group` switch limits the members tree view to nested groups only.
+By default, previously processed groups will be marked as _"Processed Group"_ and their hierarchy will not be displayed.
+The `-ShowAll` switch indicates that the cmdlet should display the hierarchy of all previously processed groups.
+
+```powershell
+PS ..\PSADTree> Get-ADTreeGroupMember TestGroup007 -Recursive -Group -ShowAll
+
+ Source: CN=TestGroup007,OU=Operations,DC=ChildDomain,DC=ParentDomain,DC=myDomain,DC=xyz
+
+Domain ObjectClass Hierarchy
+------ ----------- ---------
+ChildDomain group TestGroup007
+ChildDomain group ├── TestGroup001
+ChildDomain group │ ├── TestGroup005
+ParentDomain group │ │ ├── TestGroup001
+ParentDomain group │ │ │ └── TestGroup002
+ParentDomain group │ │ └── TestGroup002
+ChildDomain group │ ├── TestGroup006
+ChildDomain group │ └── TestGroup007 ↔ Circular Reference
+ChildDomain group ├── TestGroup005
+ParentDomain group │ ├── TestGroup001
+ParentDomain group │ │ └── TestGroup002
+ParentDomain group │ └── TestGroup002
+ChildDomain group └── TestGroup006
+```
+
+### Get group memberships for a user
+
+```powershell
+PS ..\PSADTree> Get-ADTreePrincipalGroupMembership TestUser002
+
+ Source: CN=TestUser002,OU=Operations,DC=ChildDomain,DC=ParentDomain,DC=myDomain,DC=xyz
+
+Domain ObjectClass Hierarchy
+------ ----------- ---------
+ChildDomain user TestUser002
+ChildDomain group ├── TestGroup003
+ChildDomain group │ └── TestGroup000
+ChildDomain group ├── TestGroup001
+ChildDomain group │ ├── TestGroup007
+ChildDomain group │ │ ├── TestGroup004
+ChildDomain group │ │ ├── TestGroup002
+ChildDomain group │ │ └── TestGroup001 ↔ Circular Reference
+ChildDomain group │ └── TestGroup000 ↔ Processed Group
+ChildDomain group ├── Terminal Server License Servers
+ChildDomain group └── Domain Users
+ChildDomain group └── Users
+```
+
+### Control the grade of recursion with the `-Depth` parameter
+
+Same as `Get-ADTreeGroupMember`, the default depth to display the principal memberships is 2.
+
+```powershell
+PS ..\PSADTree> Get-ADTreePrincipalGroupMembership TestUser002 -Depth 2
+
+ Source: CN=TestUser002,OU=Operations,DC=ChildDomain,DC=ParentDomain,DC=myDomain,DC=xyz
+
+Domain ObjectClass Hierarchy
+------ ----------- ---------
+ChildDomain user TestUser002
+ChildDomain group ├── TestGroup003
+ChildDomain group │ └── TestGroup000
+ChildDomain group ├── TestGroup001
+ChildDomain group │ ├── TestGroup007
+ChildDomain group │ └── TestGroup000 ↔ Processed Group
+ChildDomain group ├── Terminal Server License Servers
+ChildDomain group └── Domain Users
+ChildDomain group └── Users
+```
+
+### Get the user principal membership recursively and display all processed groups
+
+```powershell
+PS ..\PSADTree> Get-ADTreePrincipalGroupMembership TestUser002 -Recursive -ShowAll
+
+ Source: CN=TestUser002,OU=Operations,DC=ChildDomain,DC=ParentDomain,DC=myDomain,DC=xyz
+
+Domain ObjectClass Hierarchy
+------ ----------- ---------
+ChildDomain user TestUser002
+ChildDomain group ├── TestGroup003
+ChildDomain group │ └── TestGroup000
+ChildDomain group ├── TestGroup001
+ChildDomain group │ ├── TestGroup007
+ChildDomain group │ │ ├── TestGroup004
+ChildDomain group │ │ ├── TestGroup002
+ChildDomain group │ │ │ └── TestGroup000
+ChildDomain group │ │ └── TestGroup001 ↔ Circular Reference
+ChildDomain group │ └── TestGroup000
+ChildDomain group ├── Terminal Server License Servers
+ChildDomain group └── Domain Users
+ChildDomain group └── Users
```
+## Contributing
-
-
-
+Contributions are more than welcome, if you wish to contribute, fork this repository and submit a pull request with the changes.
diff --git a/ScriptAnalyzerSettings.psd1 b/ScriptAnalyzerSettings.psd1
new file mode 100644
index 0000000..882e626
--- /dev/null
+++ b/ScriptAnalyzerSettings.psd1
@@ -0,0 +1,29 @@
+# The PowerShell Script Analyzer will generate a warning
+# diagnostic record for this file due to a bug -
+# https://github.com/PowerShell/PSScriptAnalyzer/issues/472
+@{
+ # Only diagnostic records of the specified severity will be generated.
+ # Uncomment the following line if you only want Errors and Warnings but
+ # not Information diagnostic records.
+
+ # Severity = @('Error','Warning')
+
+ # Analyze **only** the following rules. Use IncludeRules when you want
+ # to invoke only a small subset of the defualt rules.
+
+ # IncludeRules = @('PSAvoidDefaultValueSwitchParameter',
+ # 'PSMissingModuleManifestField',
+ # 'PSReservedCmdletChar',
+ # 'PSReservedParams',
+ # 'PSShouldProcess',
+ # 'PSUseApprovedVerbs',
+ # 'PSUseDeclaredVarsMoreThanAssigments')
+
+ # Do not analyze the following rules. Use ExcludeRules when you have
+ # commented out the IncludeRules settings above and want to include all
+ # the default rules except for those you exclude below.
+ # Note: if a rule is in both IncludeRules and ExcludeRules, the rule
+ # will be excluded.
+
+ # ExcludeRules = @('')
+}
diff --git a/build.ps1 b/build.ps1
new file mode 100644
index 0000000..26e2b0b
--- /dev/null
+++ b/build.ps1
@@ -0,0 +1,70 @@
+# I may've totally stolen this from jborean93 :D
+[CmdletBinding()]
+param(
+ [Parameter()]
+ [ValidateSet('Debug', 'Release')]
+ [string]
+ $Configuration = 'Debug',
+
+ [Parameter()]
+ [string[]]
+ $Task = 'Build'
+)
+
+end {
+ if ($PSEdition -eq 'Desktop') {
+ [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 'Tls12'
+ }
+
+ $modulePath = [IO.Path]::Combine($PSScriptRoot, 'tools', 'Modules')
+ $requirements = Import-PowerShellDataFile ([IO.Path]::Combine($PSScriptRoot, 'tools', 'requiredModules.psd1'))
+
+ foreach ($req in $requirements.GetEnumerator()) {
+ $targetPath = [IO.Path]::Combine($modulePath, $req.Key)
+
+ if (Test-Path -LiteralPath $targetPath) {
+ Import-Module -Name $targetPath -Force -ErrorAction Stop
+ continue
+ }
+
+ Write-Host "Installing build pre-req $($req.Key) as it is not installed"
+ $null = New-Item -Path $targetPath -ItemType Directory -Force
+
+ $webParams = @{
+ Uri = "https://www.powershellgallery.com/api/v2/package/$($req.Key)/$($req.Value)"
+ OutFile = [IO.Path]::Combine($modulePath, "$($req.Key).zip")
+ UseBasicParsing = $true
+ }
+
+ if ('Authentication' -in (Get-Command -Name Invoke-WebRequest).Parameters.Keys) {
+ $webParams.Authentication = 'None'
+ }
+
+ $oldProgress = $ProgressPreference
+ $ProgressPreference = 'SilentlyContinue'
+
+ try {
+ Invoke-WebRequest @webParams
+ Expand-Archive -Path $webParams.OutFile -DestinationPath $targetPath -Force
+ Remove-Item -LiteralPath $webParams.OutFile -Force
+ }
+ finally {
+ $ProgressPreference = $oldProgress
+ }
+
+ Import-Module -Name $targetPath -Force -ErrorAction Stop
+ }
+
+ $dotnetTools = @(dotnet tool list --global) -join "`n"
+ if (-not $dotnetTools.Contains('coverlet.console')) {
+ Write-Host 'Installing dotnet tool coverlet.console'
+ dotnet tool install --global coverlet.console
+ }
+
+ $invokeBuildSplat = @{
+ Task = $Task
+ File = (Get-Item ([IO.Path]::Combine($PSScriptRoot, '*.build.ps1'))).FullName
+ Configuration = $Configuration
+ }
+ Invoke-Build @invokeBuildSplat
+}
diff --git a/docs/en-US/Get-ADTreeGroupMember.md b/docs/en-US/Get-ADTreeGroupMember.md
new file mode 100644
index 0000000..e085ac4
--- /dev/null
+++ b/docs/en-US/Get-ADTreeGroupMember.md
@@ -0,0 +1,231 @@
+---
+external help file: PSADTree.dll-Help.xml
+Module Name: PSADTree
+online version:
+schema: 2.0.0
+---
+
+# Get-ADTreeGroupMember
+
+## SYNOPSIS
+
+`tree` like cmdlet for Active Directory group members.
+
+## SYNTAX
+
+### Depth (Default)
+
+```powershell
+Get-ADTreeGroupMember [-Group] [-Identity] [-Server ] [-Depth ] [-ShowAll]
+ []
+```
+
+### Recursive
+
+```powershell
+Get-ADTreeGroupMember [-Group] [-Identity] [-Server ] [-Recursive] [-ShowAll]
+ []
+```
+
+## DESCRIPTION
+
+The `Get-ADTreeGroupMember` cmdlet gets the Active Directory members of a specified group and displays them in a tree like structure. The members of a group can be users, groups, computers and service accounts. This cmdlet also helps identifying Circular Nested Groups.
+
+## EXAMPLES
+
+### Example 1: Get the members of a group
+
+```powershell
+PS ..\PSADTree\> Get-ADTreeGroupMember TestGroup001
+```
+
+By default, this cmdlet uses `-Depth` with a default value of `3`.
+
+### Example 2: Get the members of a group recursively
+
+```powershell
+PS ..\PSADTree\> Get-ADTreeGroupMember TestGroup001 -Recursive
+```
+
+### Example 3: Get the members of all groups under an Organizational Unit
+
+```powershell
+PS ..\PSADTree\> Get-ADGroup -Filter * -SearchBase 'OU=myOU,DC=myDomain,DC=com' |
+ Get-ADTreeGroupMember
+```
+
+You can pipe strings containing an identity to this cmdlet. [__`ADGroup`__](https://learn.microsoft.com/en-us/dotnet/api/microsoft.activedirectory.management.adgroup?view=activedirectory-management-10.0) instances piped to this cmdlet are also supported.
+
+### Example 4: Find any Circular Nested Groups from previous example
+
+```powershell
+PS ..\PSADTree\> Get-ADComputer -Filter * -SearchBase 'OU=myOU,DC=myDomain,DC=com' |
+ Get-ADTreeGroupMember -Recursive -Group |
+ Where-Object IsCircular
+```
+
+The `-Group` switch limits the members tree view to nested groups only.
+
+### Example 5: Get group members in a different Domain
+
+```powershell
+PS ..\PSADTree\> Get-ADTreeGroupMember TestGroup001 -Server otherDomain
+```
+
+### Example 6: Get group members including processed groups
+
+```powershell
+PS ..\PSADTree\> Get-ADTreeGroupMember TestGroup001 -ShowAll
+```
+
+By default, previously processed groups will be marked as _"Processed Group"_ and their hierarchy will not be displayed.
+The `-ShowAll` switch indicates that the cmdlet should display the hierarchy of all previously processed groups.
+
+__NOTE:__ The use of this switch should not infer in a great performance cost, for more details see the parameter details.
+
+## PARAMETERS
+
+### -Depth
+
+Determines the number of nested groups and their members included in the recursion.
+By default, only 3 levels of recursion are included.
+
+```yaml
+Type: UInt32
+Parameter Sets: Depth
+Aliases:
+
+Required: False
+Position: Named
+Default value: 3
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Group
+
+The `-Group` switch indicates that the cmdlet should display nested group members only. Essentially, a built-in filter where [`ObjectClass`](https://learn.microsoft.com/en-us/windows/win32/adschema/a-objectclass) is `group`.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Identity
+
+Specifies an Active Directory group by providing one of the following property values:
+
+- A DistinguishedName
+- A GUID
+- A SID (Security Identifier)
+- A sAMAccountName
+- A UserPrincipalName
+
+See [`IdentityType` Enum](https://learn.microsoft.com/en-us/dotnet/api/system.directoryservices.accountmanagement.identitytype?view=dotnet-plat-ext-7.0) for more information.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases: DistinguishedName
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: True (ByPropertyName, ByValue)
+Accept wildcard characters: False
+```
+
+### -Recursive
+
+Specifies that the cmdlet should get all group members of the specified group.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: Recursive
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Server
+
+Specifies the AD DS instance to connect to by providing one of the following values for a corresponding domain name or directory server.
+
+Domain name values:
+
+- Fully qualified domain name
+- NetBIOS name
+
+Directory server values:
+
+- Fully qualified directory server name
+- NetBIOS name
+- Fully qualified directory server name and port
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ShowAll
+
+By default, previously processed groups will be marked as _"Processed Group"_ and their hierarchy will not be displayed.
+This switch forces the cmdlet to display the full hierarchy including previously processed groups.
+
+> __NOTE:__ This cmdlet uses a caching mechanism to ensure that Active Directory Groups are only queried once per Identity.
+This caching mechanism is also used to reconstruct the pre-processed group's hierarchy when the `-ShowAll` switch is used, thus not incurring a performance cost.
+The intent behind this switch is to not clutter the cmdlet's output by default.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### System.String
+
+You can pipe strings containing an identity to this cmdlet. [__`ADGroup`__](https://learn.microsoft.com/en-us/dotnet/api/microsoft.activedirectory.management.adgroup?view=activedirectory-management-10.0) instances piped to this cmdlet are also supported.
+
+## OUTPUTS
+
+### PSADTree.TreeGroup
+
+### PSADTree.TreeUser
+
+### PSADTree.TreeComputer
+
+## NOTES
+
+`treegroupmember` is the alias for this cmdlet.
+
+## RELATED LINKS
diff --git a/docs/en-US/Get-ADTreePrincipalGroupMembership.md b/docs/en-US/Get-ADTreePrincipalGroupMembership.md
new file mode 100644
index 0000000..93ffdac
--- /dev/null
+++ b/docs/en-US/Get-ADTreePrincipalGroupMembership.md
@@ -0,0 +1,213 @@
+---
+external help file: PSADTree.dll-Help.xml
+Module Name: PSADTree
+online version:
+schema: 2.0.0
+---
+
+# Get-ADTreePrincipalGroupMembership
+
+## SYNOPSIS
+
+`tree` like cmdlet for Active Directory Principals Group Membership.
+
+## SYNTAX
+
+### Depth (Default)
+
+```powershell
+Get-ADTreePrincipalGroupMembership [-Identity] [-Server ] [-Depth ] [-ShowAll]
+ []
+```
+
+### Recursive
+
+```powershell
+Get-ADTreePrincipalGroupMembership [-Identity] [-Server ] [-Recursive] [-ShowAll]
+ []
+```
+
+## DESCRIPTION
+
+The `Get-ADTreePrincipalGroupMembership` cmdlet gets the Active Directory groups that have a specified user, computer, group, or service account as a member and displays them in a tree like structure. This cmdlet also helps identifying Circular Nested Groups.
+
+## EXAMPLES
+
+### Example 1: Get group memberships for a user
+
+```powershell
+PS ..\PSADTree\> Get-ADTreePrincipalGroupMembership john.doe
+```
+
+By default, this cmdlet uses `-Depth` with a default value of `3`.
+
+### Example 2: Get the recursive group memberships for a user
+
+```powershell
+PS ..\PSADTree\> Get-ADTreePrincipalGroupMembership john.doe -Recursive
+```
+
+### Example 3: Get group memberships for all computers under an Organizational Unit
+
+```powershell
+PS ..\PSADTree\> Get-ADComputer -Filter * -SearchBase 'OU=myOU,DC=myDomain,DC=com' |
+ Get-ADTreePrincipalGroupMembership
+```
+
+You can pipe strings containing an identity to this cmdlet. [__`ADObject`__](https://learn.microsoft.com/en-us/dotnet/api/microsoft.activedirectory.management.adobject?view=activedirectory-management-10.0) instances piped to this cmdlet are also supported.
+
+### Example 4: Find any Circular Nested Groups from previous example
+
+```powershell
+PS ..\PSADTree\> Get-ADComputer -Filter * -SearchBase 'OU=myOU,DC=myDomain,DC=com' |
+ Get-ADTreePrincipalGroupMembership -Recursive |
+ Where-Object IsCircular
+```
+
+### Example 5: Get group memberships for a user in a different Domain
+
+```powershell
+PS ..\PSADTree\> Get-ADTreePrincipalGroupMembership john.doe -Server otherDomain
+```
+
+### Example 6: Get group memberships for a user, including processed groups
+
+```powershell
+PS ..\PSADTree\> Get-ADTreePrincipalGroupMembership john.doe -ShowAll
+```
+
+By default, previously processed groups will be marked as _"Processed Group"_ and their hierarchy will not be displayed.
+The `-ShowAll` switch indicates that the cmdlet should display the hierarchy of all previously processed groups.
+
+__NOTE:__ The use of this switch should not infer in a great performance cost, for more details see the parameter details.
+
+## PARAMETERS
+
+### -Depth
+
+Determines the number of nested group memberships included in the recursion.
+By default, only 3 levels of recursion are included.
+
+```yaml
+Type: UInt32
+Parameter Sets: Depth
+Aliases:
+
+Required: False
+Position: Named
+Default value: 3
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Identity
+
+Specifies an Active Directory principal by providing one of the following property values:
+
+- A DistinguishedName
+- A GUID
+- A SID (Security Identifier)
+- A sAMAccountName
+- A UserPrincipalName
+
+See [`IdentityType` Enum](https://learn.microsoft.com/en-us/dotnet/api/system.directoryservices.accountmanagement.identitytype?view=dotnet-plat-ext-7.0) for more information.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases: DistinguishedName
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: True (ByPropertyName, ByValue)
+Accept wildcard characters: False
+```
+
+### -Recursive
+
+Specifies that the cmdlet should get all group membership of the specified principal.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: Recursive
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Server
+
+Specifies the AD DS instance to connect to by providing one of the following values for a corresponding domain name or directory server.
+
+Domain name values:
+
+- Fully qualified domain name
+- NetBIOS name
+
+Directory server values:
+
+- Fully qualified directory server name
+- NetBIOS name
+- Fully qualified directory server name and port
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ShowAll
+
+By default, previously processed groups will be marked as _"Processed Group"_ and their hierarchy will not be displayed.
+This switch forces the cmdlet to display the full hierarchy including previously processed groups.
+
+> __NOTE:__ This cmdlet uses a caching mechanism to ensure that Active Directory Groups are only queried once per Identity.
+This caching mechanism is also used to reconstruct the pre-processed group's hierarchy when the `-ShowAll` switch is used, thus not incurring a performance cost.
+The intent behind this switch is to not clutter the cmdlet's output by default.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### System.String
+
+You can pipe strings containing an identity to this cmdlet. [`ADObject`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.activedirectory.management.adobject?view=activedirectory-management-10.0) instances piped to this cmdlet are also supported.
+
+## OUTPUTS
+
+### PSADTree.TreeGroup
+
+### PSADTree.TreeUser
+
+### PSADTree.TreeComputer
+
+## NOTES
+
+`treeprincipalmembership` is the alias for this cmdlet.
+
+## RELATED LINKS
diff --git a/docs/en-US/PSADTree.md b/docs/en-US/PSADTree.md
new file mode 100644
index 0000000..82e6f4b
--- /dev/null
+++ b/docs/en-US/PSADTree.md
@@ -0,0 +1,23 @@
+---
+Module Name: PSADTree
+Module Guid: e49013dc-4106-4a95-aebc-b2669cbadeab
+Download Help Link:
+Help Version: 1.0.0.0
+Locale: en-US
+---
+
+# PSADTree Module
+
+## Description
+
+PSADTree is a PowerShell Module with cmdlets that emulate the [`tree` command](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/tree) for Active Directory Principals.
+
+## PSADTree Cmdlets
+
+### [Get-ADTreeGroupMember](Get-ADTreeGroupMember.md)
+
+The `Get-ADTreeGroupMember` cmdlet displays members of an Active Directory Group in a tree structure.
+
+### [Get-ADTreePrincipalGroupMembership](Get-ADTreePrincipalGroupMembership.md)
+
+The `Get-ADTreePrincipalGroupMembership` cmdlet displays an Active Directory Principal group membership in a tree structure.
diff --git a/module/PSADTree.Format.ps1xml b/module/PSADTree.Format.ps1xml
new file mode 100644
index 0000000..9eef827
--- /dev/null
+++ b/module/PSADTree.Format.ps1xml
@@ -0,0 +1,56 @@
+
+
+
+
+ treeview
+
+ PSADTree.TreeObjectBase
+
+
+ [PSADTree.Internal._FormattingInternals]::GetSource($_)
+
+
+
+
+
+
+
+
+ Left
+
+
+
+
+ Right
+
+
+
+ Left
+
+
+
+
+
+
+
+ $_.Domain -replace '^DC=|(?<!\\),.+'
+
+
+ ObjectClass
+
+
+ Hierarchy
+
+
+
+
+
+
+
+
diff --git a/module/PSADTree.psd1 b/module/PSADTree.psd1
new file mode 100644
index 0000000..3755427
--- /dev/null
+++ b/module/PSADTree.psd1
@@ -0,0 +1,143 @@
+#
+# Module manifest for module 'PSADTree'
+#
+# Generated by: Santiago Squarzon
+#
+# Generated on: 8/14/2023
+#
+
+@{
+
+ # Script module or binary module file associated with this manifest.
+ RootModule = if ($PSEdition -eq 'Core') {
+ 'bin/net6.0/PSADTree.dll'
+ }
+ else {
+ 'bin/net472/PSADTree.dll'
+ }
+
+ # Version number of this module.
+ ModuleVersion = '1.1.0'
+
+ # Supported PSEditions
+ # CompatiblePSEditions = @()
+
+ # ID used to uniquely identify this module
+ GUID = 'e49013dc-4106-4a95-aebc-b2669cbadeab'
+
+ # Author of this module
+ Author = 'Santiago Squarzon'
+
+ # Company or vendor of this module
+ CompanyName = 'Unknown'
+
+ # Copyright statement for this module
+ Copyright = '(c) Santiago Squarzon. All rights reserved.'
+
+ # Description of the functionality provided by this module
+ Description = 'tree commands for Active Directory'
+
+ # Minimum version of the PowerShell engine required by this module
+ PowerShellVersion = '5.1'
+
+ # Name of the PowerShell host required by this module
+ # PowerShellHostName = ''
+
+ # Minimum version of the PowerShell host required by this module
+ # PowerShellHostVersion = ''
+
+ # Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
+ # DotNetFrameworkVersion = ''
+
+ # Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
+ # ClrVersion = ''
+
+ # Processor architecture (None, X86, Amd64) required by this module
+ # ProcessorArchitecture = ''
+
+ # Modules that must be imported into the global environment prior to importing this module
+ # RequiredModules = @()
+
+ # Assemblies that must be loaded prior to importing this module
+ RequiredAssemblies = @('System.DirectoryServices.AccountManagement')
+
+ # Script files (.ps1) that are run in the caller's environment prior to importing this module.
+ # ScriptsToProcess = @()
+
+ # Type files (.ps1xml) to be loaded when importing this module
+ # TypesToProcess = @()
+
+ # Format files (.ps1xml) to be loaded when importing this module
+ FormatsToProcess = @('PSADTree.Format.ps1xml')
+
+ # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
+ # NestedModules = @()
+
+ # Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
+ FunctionsToExport = @()
+
+ # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
+ CmdletsToExport = @(
+ 'Get-ADTreeGroupMember'
+ 'Get-ADTreePrincipalGroupMembership'
+ )
+
+ # Variables to export from this module
+ VariablesToExport = @()
+
+ # Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
+ AliasesToExport = @(
+ 'treegroupmember'
+ 'treeprincipalmembership'
+ )
+
+ # DSC resources to export from this module
+ # DscResourcesToExport = @()
+
+ # List of all modules packaged with this module
+ # ModuleList = @()
+
+ # List of all files packaged with this module
+ # FileList = @()
+
+ # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
+ PrivateData = @{
+
+ PSData = @{
+
+ # Tags applied to this module. These help with module discovery in online galleries.
+ # Tags = @()
+
+ # A URL to the license for this module.
+ LicenseUri = 'https://github.com/santisq/PSADTree/blob/main/LICENSE'
+
+ # A URL to the main website for this project.
+ ProjectUri = 'https://github.com/santisq/PSADTree'
+
+ # A URL to an icon representing this module.
+ # IconUri = ''
+
+ # ReleaseNotes of this module
+ # ReleaseNotes = ''
+
+ # Prerelease string of this module
+ # Prerelease = ''
+
+ # Flag to indicate whether the module requires explicit user acceptance for install/update/save
+ # RequireLicenseAcceptance = $false
+
+ # External dependent modules of this module
+ # ExternalModuleDependencies = @()
+
+ } # End of PSData hashtable
+
+ } # End of PrivateData hashtable
+
+ # HelpInfo URI of this module
+ # HelpInfoURI = ''
+
+ # Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
+ # DefaultCommandPrefix = ''
+
+}
+
diff --git a/src/PSADTree/Commands/GetADTreeGroupMemberCommand.cs b/src/PSADTree/Commands/GetADTreeGroupMemberCommand.cs
new file mode 100644
index 0000000..ab2ffca
--- /dev/null
+++ b/src/PSADTree/Commands/GetADTreeGroupMemberCommand.cs
@@ -0,0 +1,225 @@
+using System;
+using System.DirectoryServices.AccountManagement;
+using System.Management.Automation;
+
+namespace PSADTree;
+
+[Cmdlet(
+ VerbsCommon.Get, "ADTreeGroupMember",
+ DefaultParameterSetName = DepthParameterSet)]
+[Alias("treegroupmember")]
+[OutputType(
+ typeof(TreeGroup),
+ typeof(TreeUser),
+ typeof(TreeComputer))]
+public sealed class GetADTreeGroupMemberCommand : PSADTreeCmdletBase
+{
+ [Parameter]
+ public SwitchParameter Group { get; set; }
+
+ protected override void ProcessRecord()
+ {
+ Dbg.Assert(Identity is not null);
+ Dbg.Assert(_context is not null);
+
+ try
+ {
+ using GroupPrincipal? group = GroupPrincipal.FindByIdentity(_context, Identity);
+ if (group is null)
+ {
+ WriteError(ErrorHelper.IdentityNotFound(Identity));
+ return;
+ }
+
+ WriteObject(
+ sendToPipeline: Traverse(
+ groupPrincipal: group,
+ source: group.DistinguishedName),
+ enumerateCollection: true);
+ }
+ catch (Exception e) when (e is PipelineStoppedException or FlowControlException)
+ {
+ throw;
+ }
+ catch (MultipleMatchesException e)
+ {
+ WriteError(ErrorHelper.AmbiguousIdentity(Identity, e));
+ }
+ catch (Exception e)
+ {
+ WriteError(ErrorHelper.Unspecified(Identity, e));
+ }
+ }
+
+ private TreeObjectBase[] Traverse(
+ GroupPrincipal groupPrincipal,
+ string source)
+ {
+ int depth;
+ Clear();
+ Push(groupPrincipal, new TreeGroup(source, groupPrincipal));
+
+ while (_stack.Count > 0)
+ {
+ (GroupPrincipal? current, TreeGroup treeGroup) = _stack.Pop();
+
+ try
+ {
+ depth = treeGroup.Depth + 1;
+
+ // if this node has been already processed
+ if (!_cache.TryAdd(treeGroup))
+ {
+ current?.Dispose();
+ treeGroup.Hook(_cache);
+ _index.Add(treeGroup);
+
+ // if it's a circular reference, go next
+ if (TreeCache.IsCircular(treeGroup))
+ {
+ treeGroup.SetCircularNested();
+ continue;
+ }
+
+ // else, if we want to show all nodes
+ if (ShowAll.IsPresent)
+ {
+ // reconstruct the output without querying AD again
+ EnumerateMembers(treeGroup, depth);
+ continue;
+ }
+
+ // else, just skip this reference and go next
+ treeGroup.SetProcessed();
+ continue;
+ }
+
+ using PrincipalSearchResult? search = current?.GetMembers();
+
+ if (search is not null)
+ {
+ EnumerateMembers(treeGroup, search, source, depth);
+ }
+
+ _index.Add(treeGroup);
+ _index.TryAddPrincipals();
+ current?.Dispose();
+ }
+ catch (Exception e) when (e is PipelineStoppedException or FlowControlException)
+ {
+ throw;
+ }
+ catch (Exception e)
+ {
+ WriteError(ErrorHelper.EnumerationFailure(current, e));
+ }
+ }
+
+ return _index.GetTree();
+ }
+
+ private void EnumerateMembers(
+ TreeGroup parent,
+ PrincipalSearchResult searchResult,
+ string source,
+ int depth)
+ {
+ foreach (Principal member in searchResult)
+ {
+ IDisposable? disposable = null;
+ try
+ {
+ if (member is { DistinguishedName: null })
+ {
+ disposable = member;
+ continue;
+ }
+
+ if (member is not GroupPrincipal)
+ {
+ disposable = member;
+
+ if (Group.IsPresent)
+ {
+ continue;
+ }
+ }
+
+ TreeObjectBase treeObject = ProcessPrincipal(
+ principal: member,
+ parent: parent,
+ source: source,
+ depth: depth);
+
+ if (ShowAll.IsPresent)
+ {
+ parent.AddChild(treeObject);
+ }
+ }
+ finally
+ {
+ disposable?.Dispose();
+ }
+ }
+ }
+
+ private TreeObjectBase ProcessPrincipal(
+ Principal principal,
+ TreeGroup parent,
+ string source,
+ int depth)
+ {
+ return principal switch
+ {
+ UserPrincipal user => AddTreeObject(new TreeUser(source, parent, user, depth)),
+ ComputerPrincipal computer => AddTreeObject(new TreeComputer(source, parent, computer, depth)),
+ GroupPrincipal group => HandleGroup(parent, group, source, depth),
+ _ => throw new ArgumentOutOfRangeException(nameof(principal)),
+ };
+
+ TreeObjectBase AddTreeObject(TreeObjectBase obj)
+ {
+ if (Recursive.IsPresent || depth <= Depth)
+ {
+ _index.AddPrincipal(obj);
+ }
+
+ return obj;
+ }
+
+ TreeObjectBase HandleGroup(
+ TreeGroup parent,
+ GroupPrincipal group,
+ string source,
+ int depth)
+ {
+ if (_cache.TryGet(group.DistinguishedName, out TreeGroup? treeGroup))
+ {
+ Push(group, (TreeGroup)treeGroup.Clone(parent, depth));
+ return treeGroup;
+ }
+
+ treeGroup = new(source, parent, group, depth);
+ Push(group, treeGroup);
+ return treeGroup;
+ }
+ }
+
+ private void EnumerateMembers(TreeGroup parent, int depth)
+ {
+ bool shouldProcess = Recursive.IsPresent || depth <= Depth;
+ foreach (TreeObjectBase member in parent.Childs)
+ {
+ if (member is TreeGroup treeGroup)
+ {
+ Push(null, (TreeGroup)treeGroup.Clone(parent, depth));
+ continue;
+ }
+
+ if (shouldProcess)
+ {
+ _index.Add(member.Clone(parent, depth));
+ }
+ }
+ }
+}
diff --git a/src/PSADTree/Commands/GetADTreePrincipalGroupMembershipCommand.cs b/src/PSADTree/Commands/GetADTreePrincipalGroupMembershipCommand.cs
new file mode 100644
index 0000000..799e703
--- /dev/null
+++ b/src/PSADTree/Commands/GetADTreePrincipalGroupMembershipCommand.cs
@@ -0,0 +1,200 @@
+using System;
+using System.DirectoryServices.AccountManagement;
+using System.Linq;
+using System.Management.Automation;
+
+namespace PSADTree;
+
+[Cmdlet(
+ VerbsCommon.Get, "ADTreePrincipalGroupMembership",
+ DefaultParameterSetName = DepthParameterSet)]
+[Alias("treeprincipalmembership")]
+[OutputType(
+ typeof(TreeGroup),
+ typeof(TreeUser),
+ typeof(TreeComputer))]
+public sealed class GetADTreePrincipalGroupMembershipCommand : PSADTreeCmdletBase
+{
+ protected override void ProcessRecord()
+ {
+ Dbg.Assert(Identity is not null);
+ Dbg.Assert(_context is not null);
+ Principal? principal;
+ Clear();
+
+ try
+ {
+ principal = Principal.FindByIdentity(_context, Identity);
+ }
+ catch (Exception e) when (e is PipelineStoppedException or FlowControlException)
+ {
+ throw;
+ }
+ catch (MultipleMatchesException e)
+ {
+ WriteError(ErrorHelper.AmbiguousIdentity(Identity, e));
+ return;
+ }
+ catch (Exception e)
+ {
+ WriteError(ErrorHelper.Unspecified(Identity, e));
+ return;
+ }
+
+ if (principal is null)
+ {
+ WriteError(ErrorHelper.IdentityNotFound(Identity));
+ return;
+ }
+
+ string source = principal.DistinguishedName;
+ switch (principal)
+ {
+ case UserPrincipal user:
+ _index.Add(new TreeUser(source, user));
+ break;
+
+ case ComputerPrincipal computer:
+ _index.Add(new TreeComputer(source, computer));
+ break;
+
+ case GroupPrincipal group:
+ TreeGroup treeGroup = new(source, group);
+ _index.Add(treeGroup);
+ _cache.Add(treeGroup);
+ break;
+
+ default:
+ throw new ArgumentOutOfRangeException(nameof(principal));
+ }
+
+ try
+ {
+ using PrincipalSearchResult search = principal.GetGroups();
+ foreach (GroupPrincipal parent in search.Cast())
+ {
+ TreeGroup treeGroup = new(source, null, parent, 1);
+ Push(parent, treeGroup);
+ }
+ }
+ catch (Exception e) when (e is PipelineStoppedException or FlowControlException)
+ {
+ throw;
+ }
+ catch (Exception e)
+ {
+ WriteError(ErrorHelper.EnumerationFailure(null, e));
+ }
+ finally
+ {
+ principal?.Dispose();
+ }
+
+ WriteObject(
+ sendToPipeline: Traverse(source),
+ enumerateCollection: true);
+ }
+
+ private TreeObjectBase[] Traverse(string source)
+ {
+ int depth;
+ while (_stack.Count > 0)
+ {
+ (GroupPrincipal? current, TreeGroup treeGroup) = _stack.Pop();
+
+ try
+ {
+ depth = treeGroup.Depth + 1;
+
+ // if this node has been already processed
+ if (!_cache.TryAdd(treeGroup))
+ {
+ current?.Dispose();
+ treeGroup.Hook(_cache);
+ _index.Add(treeGroup);
+
+ // if it's a circular reference, go next
+ if (TreeCache.IsCircular(treeGroup))
+ {
+ treeGroup.SetCircularNested();
+ continue;
+ }
+
+ // else, if we want to show all nodes
+ if (ShowAll.IsPresent)
+ {
+ // reconstruct the output without querying AD again
+ EnumerateMembership(treeGroup, depth);
+ continue;
+ }
+
+ // else, just skip this reference and go next
+ treeGroup.SetProcessed();
+ continue;
+ }
+
+ using PrincipalSearchResult? search = current?.GetGroups();
+
+ if (search is not null)
+ {
+ EnumerateMembership(treeGroup, search, source, depth);
+ }
+
+ _index.Add(treeGroup);
+ current?.Dispose();
+ }
+ catch (Exception e) when (e is PipelineStoppedException or FlowControlException)
+ {
+ throw;
+ }
+ catch (Exception e)
+ {
+ WriteError(ErrorHelper.EnumerationFailure(current, e));
+ }
+ }
+
+ return _index.GetTree();
+ }
+
+ private void EnumerateMembership(
+ TreeGroup parent,
+ PrincipalSearchResult searchResult,
+ string source,
+ int depth)
+ {
+ foreach (GroupPrincipal group in searchResult.Cast())
+ {
+ TreeGroup treeGroup = ProcessGroup(group);
+ if (ShowAll.IsPresent)
+ {
+ parent.AddChild(treeGroup);
+ }
+ }
+
+ TreeGroup ProcessGroup(GroupPrincipal group)
+ {
+ if (_cache.TryGet(group.DistinguishedName, out TreeGroup? treeGroup))
+ {
+ Push(group, (TreeGroup)treeGroup.Clone(parent, depth));
+ return treeGroup;
+ }
+
+ treeGroup = new(source, parent, group, depth);
+ Push(group, treeGroup);
+ return treeGroup;
+ }
+ }
+
+ private void EnumerateMembership(TreeGroup parent, int depth)
+ {
+ if (!Recursive.IsPresent && depth > Depth)
+ {
+ return;
+ }
+
+ foreach (TreeGroup group in parent.Childs.Cast())
+ {
+ Push(null, (TreeGroup)group.Clone(parent, depth));
+ }
+ }
+}
diff --git a/src/PSADTree/Dbg.cs b/src/PSADTree/Dbg.cs
new file mode 100644
index 0000000..1dee2c7
--- /dev/null
+++ b/src/PSADTree/Dbg.cs
@@ -0,0 +1,11 @@
+using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
+
+namespace PSADTree;
+
+internal static class Dbg
+{
+ [Conditional("DEBUG")]
+ public static void Assert([DoesNotReturnIf(false)] bool condition) =>
+ Debug.Assert(condition);
+}
diff --git a/src/PSADTree/ErrorHelper.cs b/src/PSADTree/ErrorHelper.cs
new file mode 100644
index 0000000..dddb695
--- /dev/null
+++ b/src/PSADTree/ErrorHelper.cs
@@ -0,0 +1,26 @@
+using System;
+using System.DirectoryServices.AccountManagement;
+using System.Management.Automation;
+
+namespace PSADTree;
+
+internal static class ErrorHelper
+{
+ internal static ErrorRecord IdentityNotFound(string? identity) =>
+ new(
+ new NoMatchingPrincipalException($"Cannot find an object with identity: '{identity}'."),
+ "IdentityNotFound",
+ ErrorCategory.ObjectNotFound,
+ identity);
+
+ internal static ErrorRecord AmbiguousIdentity(string? identity, Exception exception) =>
+ new(exception, "AmbiguousIdentity", ErrorCategory.InvalidResult, identity);
+
+ internal static ErrorRecord Unspecified(string? identity, Exception exception) =>
+ new(exception, "Unspecified", ErrorCategory.NotSpecified, identity);
+
+ internal static ErrorRecord EnumerationFailure(
+ GroupPrincipal? groupPrincipal,
+ Exception exception) =>
+ new(exception, "EnumerationFailure", ErrorCategory.NotSpecified, groupPrincipal);
+}
diff --git a/src/PSADTree/Internal/_FormattingInternals.cs b/src/PSADTree/Internal/_FormattingInternals.cs
new file mode 100644
index 0000000..4cb3171
--- /dev/null
+++ b/src/PSADTree/Internal/_FormattingInternals.cs
@@ -0,0 +1,14 @@
+using System.ComponentModel;
+using System.Management.Automation;
+
+namespace PSADTree.Internal;
+
+#pragma warning disable IDE1006
+
+[EditorBrowsable(EditorBrowsableState.Never)]
+public static class _FormattingInternals
+{
+ [Hidden, EditorBrowsable(EditorBrowsableState.Never)]
+ public static string GetSource(TreeObjectBase treeObject) =>
+ treeObject.Source;
+}
diff --git a/src/PSADTree/Nullable.cs b/src/PSADTree/Nullable.cs
new file mode 100644
index 0000000..97c2603
--- /dev/null
+++ b/src/PSADTree/Nullable.cs
@@ -0,0 +1,140 @@
+#if !NETCOREAPP
+
+namespace System.Diagnostics.CodeAnalysis
+{
+ /// Specifies that null is allowed as an input even if the corresponding type disallows it.
+ [AttributeUsage(AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property, Inherited = false)]
+ internal sealed class AllowNullAttribute : Attribute { }
+
+ /// Specifies that null is disallowed as an input even if the corresponding type allows it.
+ [AttributeUsage(AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property, Inherited = false)]
+ internal sealed class DisallowNullAttribute : Attribute { }
+
+ /// Specifies that an output may be null even if the corresponding type disallows it.
+ [AttributeUsage(AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property | AttributeTargets.ReturnValue, Inherited = false)]
+ internal sealed class MaybeNullAttribute : Attribute { }
+
+ /// Specifies that an output will not be null even if the corresponding type allows it. Specifies that an input argument was not null when the call returns.
+ [AttributeUsage(AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property | AttributeTargets.ReturnValue, Inherited = false)]
+ internal sealed class NotNullAttribute : Attribute { }
+
+ /// Specifies that when a method returns , the parameter may be null even if the corresponding type disallows it.
+ [AttributeUsage(AttributeTargets.Parameter, Inherited = false)]
+ internal sealed class MaybeNullWhenAttribute : Attribute
+ {
+ /// Initializes the attribute with the specified return value condition.
+ ///
+ /// The return value condition. If the method returns this value, the associated parameter may be null.
+ ///
+ public MaybeNullWhenAttribute(bool returnValue) => ReturnValue = returnValue;
+
+ /// Gets the return value condition.
+ public bool ReturnValue { get; }
+ }
+
+ /// Specifies that when a method returns , the parameter will not be null even if the corresponding type allows it.
+ [AttributeUsage(AttributeTargets.Parameter, Inherited = false)]
+ internal sealed class NotNullWhenAttribute : Attribute
+ {
+ /// Initializes the attribute with the specified return value condition.
+ ///
+ /// The return value condition. If the method returns this value, the associated parameter will not be null.
+ ///
+ public NotNullWhenAttribute(bool returnValue) => ReturnValue = returnValue;
+
+ /// Gets the return value condition.
+ public bool ReturnValue { get; }
+ }
+
+ /// Specifies that the output will be non-null if the named parameter is non-null.
+ [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property | AttributeTargets.ReturnValue, AllowMultiple = true, Inherited = false)]
+ internal sealed class NotNullIfNotNullAttribute : Attribute
+ {
+ /// Initializes the attribute with the associated parameter name.
+ ///
+ /// The associated parameter name. The output will be non-null if the argument to the parameter specified is non-null.
+ ///
+ public NotNullIfNotNullAttribute(string parameterName) => ParameterName = parameterName;
+
+ /// Gets the associated parameter name.
+ public string ParameterName { get; }
+ }
+
+ /// Applied to a method that will never return under any circumstance.
+ [AttributeUsage(AttributeTargets.Method, Inherited = false)]
+ internal sealed class DoesNotReturnAttribute : Attribute { }
+
+ /// Specifies that the method will not return if the associated Boolean parameter is passed the specified value.
+ [AttributeUsage(AttributeTargets.Parameter, Inherited = false)]
+ internal sealed class DoesNotReturnIfAttribute : Attribute
+ {
+ /// Initializes the attribute with the specified parameter value.
+ ///
+ /// The condition parameter value. Code after the method will be considered unreachable by diagnostics if the argument to
+ /// the associated parameter matches this value.
+ ///
+ public DoesNotReturnIfAttribute(bool parameterValue) => ParameterValue = parameterValue;
+
+ /// Gets the condition parameter value.
+ public bool ParameterValue { get; }
+ }
+
+ /// Specifies that the method or property will ensure that the listed field and property members have not-null values.
+ [AttributeUsage(AttributeTargets.Method | AttributeTargets.Property, Inherited = false, AllowMultiple = true)]
+ internal sealed class MemberNotNullAttribute : Attribute
+ {
+ /// Initializes the attribute with a field or property member.
+ ///
+ /// The field or property member that is promised to be not-null.
+ ///
+ public MemberNotNullAttribute(string member) => Members = new[] { member };
+
+ /// Initializes the attribute with the list of field and property members.
+ ///
+ /// The list of field and property members that are promised to be not-null.
+ ///
+ public MemberNotNullAttribute(params string[] members) => Members = members;
+
+ /// Gets field or property member names.
+ public string[] Members { get; }
+ }
+
+ /// Specifies that the method or property will ensure that the listed field and property members have not-null values when returning with the specified return value condition.
+ [AttributeUsage(AttributeTargets.Method | AttributeTargets.Property, Inherited = false, AllowMultiple = true)]
+ internal sealed class MemberNotNullWhenAttribute : Attribute
+ {
+ /// Initializes the attribute with the specified return value condition and a field or property member.
+ ///
+ /// The return value condition. If the method returns this value, the associated parameter will not be null.
+ ///
+ ///
+ /// The field or property member that is promised to be not-null.
+ ///
+ public MemberNotNullWhenAttribute(bool returnValue, string member)
+ {
+ ReturnValue = returnValue;
+ Members = new[] { member };
+ }
+
+ /// Initializes the attribute with the specified return value condition and list of field and property members.
+ ///
+ /// The return value condition. If the method returns this value, the associated parameter will not be null.
+ ///
+ ///
+ /// The list of field and property members that are promised to be not-null.
+ ///
+ public MemberNotNullWhenAttribute(bool returnValue, params string[] members)
+ {
+ ReturnValue = returnValue;
+ Members = members;
+ }
+
+ /// Gets the return value condition.
+ public bool ReturnValue { get; }
+
+ /// Gets field or property member names.
+ public string[] Members { get; }
+ }
+}
+
+#endif
diff --git a/src/PSADTree/PSADTree.csproj b/src/PSADTree/PSADTree.csproj
new file mode 100644
index 0000000..55fd80f
--- /dev/null
+++ b/src/PSADTree/PSADTree.csproj
@@ -0,0 +1,28 @@
+
+
+
+ net6.0;net472
+ enable
+ true
+ PSADTree
+ latest
+ CA1416
+
+
+
+ $(DefineConstants);CORE
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/src/PSADTree/PSADTreeCmdletBase.cs b/src/PSADTree/PSADTreeCmdletBase.cs
new file mode 100644
index 0000000..1c801c1
--- /dev/null
+++ b/src/PSADTree/PSADTreeCmdletBase.cs
@@ -0,0 +1,91 @@
+using System;
+using System.Collections.Generic;
+using System.DirectoryServices.AccountManagement;
+using System.Management.Automation;
+
+namespace PSADTree;
+
+public abstract class PSADTreeCmdletBase : PSCmdlet, IDisposable
+{
+ protected const string DepthParameterSet = "Depth";
+
+ protected const string RecursiveParameterSet = "Recursive";
+
+ protected PrincipalContext? _context;
+
+ private bool _disposed;
+
+ protected readonly Stack<(GroupPrincipal? group, TreeGroup treeGroup)> _stack = new();
+
+ internal readonly TreeCache _cache = new();
+
+ internal readonly TreeIndex _index = new();
+
+ [Parameter(
+ Position = 0,
+ Mandatory = true,
+ ValueFromPipeline = true,
+ ValueFromPipelineByPropertyName = true)]
+ [Alias("DistinguishedName")]
+ public string? Identity { get; set; }
+
+ [Parameter]
+ public string? Server { get; set; }
+
+ [Parameter(ParameterSetName = DepthParameterSet)]
+ public uint Depth { get; set; } = 3;
+
+ [Parameter(ParameterSetName = RecursiveParameterSet)]
+ public SwitchParameter Recursive { get; set; }
+
+ [Parameter]
+ public SwitchParameter ShowAll { get; set; }
+
+ protected override void BeginProcessing()
+ {
+ try
+ {
+ if (Server is null)
+ {
+ _context = new PrincipalContext(ContextType.Domain);
+ return;
+ }
+
+ _context = new PrincipalContext(ContextType.Domain, Server);
+ }
+ catch (Exception e)
+ {
+ ThrowTerminatingError(new ErrorRecord(
+ e, "SetPrincipalContext", ErrorCategory.ConnectionError, null));
+ }
+ }
+
+ protected void Push(GroupPrincipal? groupPrincipal, TreeGroup treeGroup)
+ {
+ if (Recursive.IsPresent || treeGroup.Depth <= Depth)
+ {
+ _stack.Push((groupPrincipal, treeGroup));
+ }
+ }
+
+ protected virtual void Dispose(bool disposing)
+ {
+ if (disposing && !_disposed)
+ {
+ _context?.Dispose();
+ _disposed = true;
+ }
+ }
+
+ protected void Clear()
+ {
+ _index.Clear();
+ _cache.Clear();
+ }
+
+ public void Dispose()
+ {
+ Dispose(disposing: true);
+ GC.SuppressFinalize(this);
+ }
+}
diff --git a/src/PSADTree/TreeCache.cs b/src/PSADTree/TreeCache.cs
new file mode 100644
index 0000000..f045052
--- /dev/null
+++ b/src/PSADTree/TreeCache.cs
@@ -0,0 +1,56 @@
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+
+namespace PSADTree;
+
+internal sealed class TreeCache
+{
+ private readonly Dictionary _cache;
+
+ internal TreeGroup this[string distinguishedName] =>
+ _cache[distinguishedName];
+
+ internal TreeCache() => _cache = new();
+
+ internal void Add(TreeGroup treeGroup) =>
+ _cache.Add(treeGroup.DistinguishedName, treeGroup);
+
+ internal bool TryAdd(TreeGroup group)
+ {
+ if (_cache.ContainsKey(group.DistinguishedName))
+ {
+ return false;
+ }
+
+ _cache.Add(group.DistinguishedName, group);
+ return true;
+ }
+
+ internal bool TryGet(
+ string distinguishedName,
+ [NotNullWhen(true)] out TreeGroup? principal) =>
+ _cache.TryGetValue(distinguishedName, out principal);
+
+ internal static bool IsCircular(TreeGroup node)
+ {
+ if (node.Parent is null)
+ {
+ return false;
+ }
+
+ TreeGroup? current = node.Parent;
+ while (current is not null)
+ {
+ if (node.DistinguishedName == current.DistinguishedName)
+ {
+ return true;
+ }
+
+ current = current.Parent;
+ }
+
+ return false;
+ }
+
+ internal void Clear() => _cache.Clear();
+}
diff --git a/src/PSADTree/TreeComputer.cs b/src/PSADTree/TreeComputer.cs
new file mode 100644
index 0000000..e06906a
--- /dev/null
+++ b/src/PSADTree/TreeComputer.cs
@@ -0,0 +1,30 @@
+using System.DirectoryServices.AccountManagement;
+
+namespace PSADTree;
+
+public sealed class TreeComputer : TreeObjectBase
+{
+ private TreeComputer(
+ TreeComputer computer,
+ TreeGroup parent,
+ int depth)
+ : base(computer, parent, depth)
+ { }
+
+ internal TreeComputer(
+ string source,
+ TreeGroup? parent,
+ ComputerPrincipal computer,
+ int depth)
+ : base(source, parent, computer, depth)
+ { }
+
+ internal TreeComputer(
+ string source,
+ ComputerPrincipal computer)
+ : base(source, computer)
+ { }
+
+ internal override TreeObjectBase Clone(TreeGroup parent, int depth) =>
+ new TreeComputer(this, parent, depth);
+}
diff --git a/src/PSADTree/TreeExtensions.cs b/src/PSADTree/TreeExtensions.cs
new file mode 100644
index 0000000..d489690
--- /dev/null
+++ b/src/PSADTree/TreeExtensions.cs
@@ -0,0 +1,70 @@
+using System.Text;
+using System.Text.RegularExpressions;
+
+namespace PSADTree;
+
+internal static class TreeExtensions
+{
+ private static readonly Regex s_reDefaultNamingContext = new(
+ "(?<=,)DC=.+$",
+ RegexOptions.Compiled);
+
+ private static readonly StringBuilder s_sb = new();
+
+ internal static string Indent(this string inputString, int indentation)
+ {
+ s_sb.Clear();
+
+ return s_sb
+ .Append(' ', (4 * indentation) - 4)
+ .Append("└── ")
+ .Append(inputString)
+ .ToString();
+ }
+
+ internal static string GetDefaultNamingContext(this string distinguishedName) =>
+ s_reDefaultNamingContext.Match(distinguishedName).Value;
+
+ internal static TreeObjectBase[] ConvertToTree(
+ this TreeObjectBase[] inputObject)
+ {
+ int index;
+ TreeObjectBase current;
+ for (int i = 0; i < inputObject.Length; i++)
+ {
+ current = inputObject[i];
+ if ((index = current.Hierarchy.IndexOf('└')) == -1)
+ {
+ continue;
+ }
+
+ int z;
+ char[] replace;
+ for (z = i - 1; z >= 0; z--)
+ {
+ current = inputObject[z];
+ if (!char.IsWhiteSpace(current.Hierarchy[index]))
+ {
+ UpdateCorner(index, current);
+ break;
+ }
+
+ replace = current.Hierarchy.ToCharArray();
+ replace[index] = '│';
+ current.Hierarchy = new string(replace);
+ }
+ }
+
+ return inputObject;
+ }
+
+ private static void UpdateCorner(int index, TreeObjectBase current)
+ {
+ if (current.Hierarchy[index] == '└')
+ {
+ char[] replace = current.Hierarchy.ToCharArray();
+ replace[index] = '├';
+ current.Hierarchy = new string(replace);
+ }
+ }
+}
diff --git a/src/PSADTree/TreeGroup.cs b/src/PSADTree/TreeGroup.cs
new file mode 100644
index 0000000..54696c6
--- /dev/null
+++ b/src/PSADTree/TreeGroup.cs
@@ -0,0 +1,71 @@
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+using System.DirectoryServices.AccountManagement;
+
+namespace PSADTree;
+
+public sealed class TreeGroup : TreeObjectBase
+{
+ private const string _isCircular = " ↔ Circular Reference";
+
+ private const string _isProcessed = " ↔ Processed Group";
+
+ private const string _vtBrightRed = "\x1B[91m";
+
+ private const string _vtReset = "\x1B[0m";
+
+ private List? _childs;
+
+ public ReadOnlyCollection Childs => new(_childs ??= new());
+
+ public bool IsCircular { get; private set; }
+
+ private TreeGroup(
+ TreeGroup group,
+ TreeGroup parent,
+ int depth)
+ : base(group, parent, depth)
+ {
+ _childs = group._childs;
+ }
+
+ internal TreeGroup(
+ string source,
+ GroupPrincipal group)
+ : base(source, group)
+ { }
+
+ internal TreeGroup(
+ string source,
+ TreeGroup? parent,
+ GroupPrincipal group,
+ int depth)
+ : base(source, parent, group, depth)
+ { }
+
+ internal void SetCircularNested()
+ {
+ IsCircular = true;
+ Hierarchy = string.Concat(
+ Hierarchy.Insert(
+ Hierarchy.IndexOf("─ ") + 2,
+ _vtBrightRed),
+ _isCircular,
+ _vtReset);
+ }
+
+ internal void SetProcessed() =>
+ Hierarchy = string.Concat(Hierarchy, _isProcessed);
+
+ internal void Hook(TreeCache cache) =>
+ _childs ??= cache[DistinguishedName]._childs;
+
+ internal void AddChild(TreeObjectBase child)
+ {
+ _childs ??= new();
+ _childs.Add(child);
+ }
+
+ internal override TreeObjectBase Clone(TreeGroup parent, int depth) =>
+ new TreeGroup(this, parent, depth);
+}
diff --git a/src/PSADTree/TreeIndex.cs b/src/PSADTree/TreeIndex.cs
new file mode 100644
index 0000000..8df3a0c
--- /dev/null
+++ b/src/PSADTree/TreeIndex.cs
@@ -0,0 +1,40 @@
+using System.Collections.Generic;
+
+namespace PSADTree;
+
+internal sealed class TreeIndex
+{
+ private readonly List _principals;
+
+ private readonly List _output;
+
+ internal TreeIndex()
+ {
+ _principals = new();
+ _output = new();
+ }
+
+ internal void AddPrincipal(TreeObjectBase principal) =>
+ _principals.Add(principal);
+
+ internal void Add(TreeObjectBase principal) =>
+ _output.Add(principal);
+
+ internal void TryAddPrincipals()
+ {
+ if (_principals.Count > 0)
+ {
+ _output.AddRange(_principals.ToArray());
+ _principals.Clear();
+ }
+ }
+
+ internal TreeObjectBase[] GetTree() =>
+ _output.ToArray().ConvertToTree();
+
+ internal void Clear()
+ {
+ _output.Clear();
+ _principals.Clear();
+ }
+}
diff --git a/src/PSADTree/TreeObjectBase.cs b/src/PSADTree/TreeObjectBase.cs
new file mode 100644
index 0000000..ed515a0
--- /dev/null
+++ b/src/PSADTree/TreeObjectBase.cs
@@ -0,0 +1,87 @@
+using System;
+using System.DirectoryServices.AccountManagement;
+using System.Security.Principal;
+
+namespace PSADTree;
+
+public abstract class TreeObjectBase
+{
+ internal int Depth { get; set; }
+
+ internal string Source { get; }
+
+ public TreeGroup? Parent { get; }
+
+ public string Domain { get; }
+
+ public string SamAccountName { get; }
+
+ public string ObjectClass { get; }
+
+ public string Hierarchy { get; internal set; }
+
+ public string DistinguishedName { get; }
+
+ public Guid? ObjectGuid { get; }
+
+ public string UserPrincipalName { get; }
+
+ public string Description { get; }
+
+ public string DisplayName { get; }
+
+ public SecurityIdentifier ObjectSid { get; }
+
+ protected TreeObjectBase(
+ TreeObjectBase treeObject,
+ TreeGroup? parent,
+ int depth)
+ {
+ Depth = depth;
+ Source = treeObject.Source;
+ SamAccountName = treeObject.SamAccountName;
+ Domain = treeObject.Domain;
+ ObjectClass = treeObject.ObjectClass;
+ DistinguishedName = treeObject.DistinguishedName;
+ ObjectGuid = treeObject.ObjectGuid;
+ ObjectSid = treeObject.ObjectSid;
+ Hierarchy = treeObject.SamAccountName.Indent(depth);
+ Parent = parent;
+ UserPrincipalName = treeObject.UserPrincipalName;
+ Description = treeObject.Description;
+ DisplayName = treeObject.DisplayName;
+ }
+
+ protected TreeObjectBase(
+ string source,
+ Principal principal)
+ {
+ Source = source;
+ SamAccountName = principal.SamAccountName;
+ Domain = principal.DistinguishedName.GetDefaultNamingContext();
+ ObjectClass = principal.StructuralObjectClass;
+ DistinguishedName = principal.DistinguishedName;
+ ObjectGuid = principal.Guid;
+ ObjectSid = principal.Sid;
+ Hierarchy = SamAccountName;
+ UserPrincipalName = principal.UserPrincipalName;
+ Description = principal.Description;
+ DisplayName = principal.DisplayName;
+ }
+
+ protected TreeObjectBase(
+ string source,
+ TreeGroup? parent,
+ Principal principal,
+ int depth)
+ : this(source, principal)
+ {
+ Depth = depth;
+ Hierarchy = principal.SamAccountName.Indent(depth);
+ Parent = parent;
+ }
+
+ public override string ToString() => DistinguishedName;
+
+ internal abstract TreeObjectBase Clone(TreeGroup parent, int depth);
+}
diff --git a/src/PSADTree/TreeUser.cs b/src/PSADTree/TreeUser.cs
new file mode 100644
index 0000000..2497243
--- /dev/null
+++ b/src/PSADTree/TreeUser.cs
@@ -0,0 +1,30 @@
+using System.DirectoryServices.AccountManagement;
+
+namespace PSADTree;
+
+public sealed class TreeUser : TreeObjectBase
+{
+ private TreeUser(
+ TreeUser user,
+ TreeGroup parent,
+ int depth)
+ : base(user, parent, depth)
+ { }
+
+ internal TreeUser(
+ string source,
+ TreeGroup? parent,
+ UserPrincipal user,
+ int depth)
+ : base(source, parent, user, depth)
+ { }
+
+ internal TreeUser(
+ string source,
+ UserPrincipal user)
+ : base(source, user)
+ { }
+
+ internal override TreeObjectBase Clone(TreeGroup parent, int depth) =>
+ new TreeUser(this, parent, depth);
+}
diff --git a/tests/PSADTree.tests.ps1 b/tests/PSADTree.tests.ps1
new file mode 100644
index 0000000..5d1eb4d
--- /dev/null
+++ b/tests/PSADTree.tests.ps1
@@ -0,0 +1,11 @@
+# I know, this is a shame but setting up a Domain for tests is too much trouble :D
+$ErrorActionPreference = 'Stop'
+
+Describe 'PSADTreeModule' {
+ It 'Should not throw on import' {
+ $moduleName = (Get-Item ([IO.Path]::Combine($PSScriptRoot, '..', 'module', '*.psd1'))).BaseName
+ $manifestPath = [IO.Path]::Combine($PSScriptRoot, '..', 'output', $moduleName)
+
+ { Import-Module $manifestPath } | Should -Not -Throw
+ }
+}
diff --git a/tools/PesterTest.ps1 b/tools/PesterTest.ps1
new file mode 100644
index 0000000..92c4a15
--- /dev/null
+++ b/tools/PesterTest.ps1
@@ -0,0 +1,63 @@
+<#
+.SYNOPSIS
+Run Pester test
+
+.PARAMETER TestPath
+The path to the tests to run
+
+.PARAMETER OutputFile
+The path to write the Pester test results to.
+#>
+[CmdletBinding()]
+param (
+ [Parameter(Mandatory)]
+ [String]
+ $TestPath,
+
+ [Parameter(Mandatory)]
+ [String]
+ $OutputFile
+)
+
+$ErrorActionPreference = 'Stop'
+$requirements = Import-PowerShellDataFile ([IO.Path]::Combine($PSScriptRoot, 'requiredModules.psd1'))
+foreach ($req in $requirements.GetEnumerator()) {
+ $importModuleSplat = @{
+ Name = ([IO.Path]::Combine($PSScriptRoot, 'Modules', $req.Key))
+ Force = $true
+ DisableNameChecking = $true
+ }
+
+ Write-Host "Importing: $($importModuleSplat['Name'])"
+ Import-Module @importModuleSplat
+}
+
+[PSCustomObject] $PSVersionTable |
+ Select-Object -Property *, @{
+ Name = 'Architecture'
+ Expression = {
+ switch ([IntPtr]::Size) {
+ 4 {
+ 'x86'
+ }
+ 8 {
+ 'x64'
+ }
+ default {
+ 'Unknown'
+ }
+ }
+ }
+ } |
+ Format-List |
+ Out-Host
+
+$configuration = [PesterConfiguration]::Default
+$configuration.Output.Verbosity = 'Detailed'
+$configuration.Run.Exit = $true
+$configuration.Run.Path = $TestPath
+$configuration.TestResult.Enabled = $true
+$configuration.TestResult.OutputPath = $OutputFile
+$configuration.TestResult.OutputFormat = 'NUnitXml'
+
+Invoke-Pester -Configuration $configuration -WarningAction Ignore
diff --git a/tools/requiredModules.psd1 b/tools/requiredModules.psd1
new file mode 100644
index 0000000..b40540a
--- /dev/null
+++ b/tools/requiredModules.psd1
@@ -0,0 +1,6 @@
+@{
+ InvokeBuild = '5.10.3'
+ platyPS = '0.14.2'
+ PSScriptAnalyzer = '1.21.0'
+ Pester = '5.4.1'
+}