Add Get-VSTeamGroup / Get-VSTeamDescriptor (#140)

* Add Get-VSTeamGroup / Get-VSTeamDescriptor

* Changed Azure DevOps abbreviation from ADO to AzD.

* Got all unit tests for Group and Descriptor passing.

* All unit tests updated to work with  VSTeamDescriptor type.

* Add working -SubjectTypes to Get-VSTeamGroup

* Updated gen-help to copy into the Source folder now.

* Fixed title in Get-VSTeamDescriptor help.

* Defaulting to 5.x api for AzD

* Get-VSTeamOptions can get options for any SubDomain

* Added code to make sure the account supported the Graph API.

* Updating changelog and version.

.docs/Get-VSTeamDescriptor.md

@@ -0,0 +1,35 @@
+<!-- #include "./common/header.md" -->
+
+# Get-VSTeamDescriptor
+
+## SYNOPSIS
+
+<!-- #include "./synopsis/Get-VSTeamDescriptor.md" -->
+
+## SYNTAX
+
+## DESCRIPTION
+
+<!-- #include "./synopsis/Get-VSTeamDescriptor.md" -->
+
+## EXAMPLES
+
+## PARAMETERS
+
+### -StorageKey
+
+Storage key of the subject (user, group, scope, etc.) to resolve
+
+```yaml
+Type: String
+Required: True
+Parameter Sets: ByStorageKey
+```
+
+## INPUTS
+
+## OUTPUTS
+
+## NOTES
+
+## RELATED LINKS

.docs/Get-VSTeamGroup.md

@@ -0,0 +1,61 @@
+<!-- #include "./common/header.md" -->
+
+# Get-VSTeamGroup
+
+## SYNOPSIS
+
+<!-- #include "./synopsis/Get-VSTeamGroup.md" -->
+
+## SYNTAX
+
+## DESCRIPTION
+
+<!-- #include "./synopsis/Get-VSTeamGroup.md" -->
+
+## EXAMPLES
+
+## PARAMETERS
+
+<!-- #include "./params/projectName.md" -->
+
+### -SubjectTypes
+
+A comma separated list of user subject subtypes to reduce the retrieved results.
+Valid subject types:
+
+- vssgp (Azure DevOps Group)
+- aadgp (Azure Active Directory Group)
+
+```yaml
+Type: String[]
+Required: False
+Parameter Sets: List, ListByProjectName
+```
+
+### -ScopeDescriptor
+
+Specify a non-default scope (collection, project) to search for groups.
+
+```yaml
+Type: String
+Required: False
+Parameter Sets: List
+```
+
+### -Descriptor
+
+The descriptor of the desired graph group.
+
+```yaml
+Type: String
+Required: False
+Parameter Sets: ByGroupDescriptor
+```
+
+## INPUTS
+
+## OUTPUTS
+
+## NOTES
+
+## RELATED LINKS

.docs/Get-VSTeamOption.md

@@ -36,14 +36,29 @@ PS C:\> Get-VSTeamOption | Format-Table -View Versions
 
 This will display all the versions of supported APIs for your account using the 'Versions' custom table format.
 
+### -------------------------- EXAMPLE 3 --------------------------
+
+```PowerShell
+PS C:\> Get-VSTeamOption -SubDomain vsrm 
+```
+
+This will display all the versions of supported APIs for the release management service.
+
 ## PARAMETERS
 
-### -Release
+### -SubDomain
+
+Returns options for that sub domain APIs. Some examples include:
 
-Returns options for Release Management APIs
+- vsaex = Member Entitlement Management
+- feeds = Artifacts
+- vsrm = Release Management
+- vssps = Graph
+- extmgmt = Extensions
 
 ```yaml
-Type: SwitchParameter
+Type: String
+Required: false
 ```
 
 ## INPUTS

.docs/gen-help.ps1

@@ -16,6 +16,14 @@ foreach ($file in $files) {
    # to avoid sending any unwanted data down the pipeline.
    $null = $sb.Append("### [$($file.BaseName)]($($file.Name))`r`n`r`n")
    $null = $sb.Append("<!-- #include ""./synopsis/$($file.Name)"" -->`r`n`r`n")
+
+   # I found files where the name of the file did not match the top most
+   # title in the file. This will cause issues trying to load help for that
+   # function. So test that you can find # {FileName} in the file.
+   $stringToFind = "# $($file.BaseName)"
+   if($null -eq $(Get-ChildItem $($file.Name) | Select-String $stringToFind)) {
+      Write-Error "Title cannot be found in $($file.Name). Make sure the first header is # $($file.BaseName)`n$($File.Directory)\$File" -ErrorAction Stop
+   }
 }
 
 Set-Content -Path files.md -Value $sb.ToString()
@@ -33,7 +41,7 @@ if(-not (Get-Module platyPS -ListAvailable)) {
    Install-Module platyPS -Scope CurrentUser -Force
 }
 
-New-ExternalHelp ..\docs -OutputPath ..\en-US -Force
+New-ExternalHelp ..\docs -OutputPath ..\Source\en-US -Force
 
 # Run again and strip header
 Write-Output 'Cleaning doc files for publishing'

.docs/synopsis/Get-VSTeamDescriptor.md

@@ -0,0 +1 @@
+Resolve a storage key to a descriptor.

.docs/synopsis/Get-VSTeamGroup.md

@@ -0,0 +1 @@
+Returns a Group or List of Groups.

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 6.1.0
+
+The AzD API now defaults to the 5.x versions.
+
+Merged [Pull Request](https://github.com/DarqueWarrior/vsteam/pull/140) from [Michel Zehnder](https://github.com/MichelZ) which included the following:
+
+Added Get-VSTeamGroup to retrieve Groups
+Added Get-VSTeamDescriptor to resolve ID's to Descriptors
+
+**Breaking changes**:
+
+Replaced the -Release parameter of Get-VSTeamOption with -SubDomain parameter so any domain can be used.
+
 ## 6.0.1
 
 Fixing issue with mapping drive.

Source/Classes/VSTeamDescriptor.ps1

@@ -0,0 +1,30 @@
+using namespace Microsoft.PowerShell.SHiPS
+
+[SHiPSProvider(UseCache = $true)]
+[SHiPSProvider(BuiltinProgress = $false)]
+class VSTeamDescriptor : VSTeamLeaf {
+
+   [string]$Descriptor = $null
+   [hashtable]$Links = $null
+
+   VSTeamDescriptor (
+      [object]$obj
+   ) : base($obj.value, $obj.value, $null) {
+
+      $this.Links = @{
+         'Self' = $obj._links.self.href;
+         'StorageKey' = $obj._links.storageKey.href;
+         'Subject'= $obj._links.subject.href;
+      }
+
+      $this.Descriptor = $obj.value
+
+      $this._internalObj = $obj
+
+      $this.AddTypeName('Team.Descriptor')
+   }
+
+   [string]ToString() {
+      return $this.Descriptor
+   }
+}

Source/Classes/VSTeamGitRepositoryPermissions.ps1

@@ -0,0 +1,20 @@
+# https://dev.azure.com/<organization>/_apis/securitynamespaces?api-version=5.0
+[flags()] Enum AzDGitRepositoryPermissions
+{
+    Administer = 1
+    GenericRead = 2
+    GenericContribute = 4
+    ForcePush = 8
+    CreateBranch = 16
+    CreateTag = 32
+    ManageNote = 64
+    PolicyExempt = 128
+    CreateRepository = 256
+    DeleteRepository = 512
+    RenameRepository = 1024
+    EditPolicies = 2048
+    RemoveOthersLocks = 4096
+    ManagePermissions = 8192
+    PullRequestContribute = 16384
+    PullRequestBypassPolicy = 32768
+}

Source/Classes/VSTeamGroup.ps1

@@ -0,0 +1,50 @@
+using namespace Microsoft.PowerShell.SHiPS
+
+[SHiPSProvider(UseCache = $true)]
+[SHiPSProvider(BuiltinProgress = $false)]
+class VSTeamGroup : VSTeamLeaf {
+
+   [string]$SubjectKind = $null
+   [string]$Description = $null
+   [string]$Domain = $null
+   [string]$PrincipalName = $null
+   [string]$MailAddress = $null
+   [string]$Origin = $null
+   [string]$OriginID = $null
+   [string]$DisplayName = $null
+   [string]$URL = $null
+   [string]$Descriptor = $null
+   [hashtable]$Links = $null
+
+   VSTeamGroup (
+      [object]$obj
+   ) : base($obj.displayName, $obj.descriptor, $null) {
+      $this.SubjectKind = $obj.subjectKind
+      $this.Description = $obj.description
+      $this.Domain = $obj.domain
+      $this.PrincipalName = $obj.principalName
+      $this.MailAddress = $obj.mailAddress
+      $this.Origin = $obj.origin
+      $this.OriginID = $obj.originId
+      $this.DisplayName = $obj.displayName
+      $this.ProjectName = $obj.principalName.Split('\')[0].Trim('[',']')
+
+      $this.Links = @{
+         'Self' = $obj._links.self.href;
+         'Memberships' = $obj._links.memberships.href;
+         'MembershipState'= $obj._links.membershipState.href;
+         'StorageKey'= $obj._links.storageKey.href;
+      }
+
+      $this.URL = $obj.url
+      $this.Descriptor = $obj.descriptor
+
+      $this._internalObj = $obj
+
+      $this.AddTypeName('Team.Group')
+   }
+
+   [string]ToString() {
+      return $this.PrincipalName
+   }
+}

Source/Classes/VSTeamIdentityPermissions.ps1

@@ -0,0 +1,10 @@
+# https://dev.azure.com/<organization>/_apis/securitynamespaces?api-version=5.0
+[flags()] Enum AzDIdentityPermissions
+{
+    Read = 1
+    Write = 2
+    Delete = 4
+    ManageMembership = 8
+    CreateScope = 16
+    RestoreScope = 32
+}

Source/Classes/VSTeamProjectPermissions.ps1

@@ -0,0 +1,28 @@
+# https://dev.azure.com/<organization>/_apis/securitynamespaces?api-version=5.0
+[flags()] Enum AzDProjectPermissions
+{
+    GENERIC_READ = 1
+    GENERIC_WRITE = 2
+    DELETE = 4
+    PUBLISH_TEST_RESULTS = 8
+    ADMINISTER_BUILD = 16
+    START_BUILD = 32
+    EDIT_BUILD_STATUS = 64
+    UPDATE_BUILD = 128
+    DELETE_TEST_RESULTS = 256
+    VIEW_TEST_RESULTS = 512
+    MANAGE_TEST_ENVIRONMENTS = 2048
+    MANAGE_TEST_CONFIGURATIONS = 4096
+    WORK_ITEM_DELETE = 8192
+    WORK_ITEM_MOVE = 16384
+    WORK_ITEM_PERMANENTLY_DELETE = 32768
+    RENAME = 65536
+    MANAGE_PROPERTIES = 131072
+    MANAGE_SYSTEM_PROPERTIES = 262144
+    BYPASS_PROPERTY_CACHE = 524288
+    BYPASS_RULES = 1048576
+    SUPPRESS_NOTIFICATIONS = 2097152
+    UPDATE_VISIBILITY = 4194304
+    CHANGE_PROCESS = 8388608
+    AGILETOOLS_BACKLOG = 16777216
+}

Source/Classes/VSTeamVersions.ps1

@@ -13,4 +13,5 @@ class VSTeamVersions {
    static [string] $ExtensionsManagement = ''
    static [string] $ServiceFabricEndpoint = ''
    static [string] $ModuleVersion = $null
+   static [string] $Graph = ''
 }

Source/Classes/VSTeamWorkItemAreaPermissions.ps1

@@ -0,0 +1,12 @@
+# https://dev.azure.com/<organization>/_apis/securitynamespaces?api-version=5.0
+[flags()] Enum AzDWorkItemAreaPermissions
+{
+    GENERIC_READ = 1
+    GENERIC_WRITE = 2
+    CREATE_CHILDREN = 4
+    DELETE = 8
+    WORK_ITEM_READ = 16
+    WORK_ITEM_WRITE = 32
+    MANAGE_TEST_PLANS = 64
+    MANAGE_TEST_SUITES = 128
+}

Source/Classes/VSTeamWorkItemIterationPermissions.ps1

@@ -0,0 +1,8 @@
+# https://dev.azure.com/<organization>/_apis/securitynamespaces?api-version=5.0
+[flags()] Enum AzDWorkItemIterationPermissions
+{
+    GENERIC_READ = 1
+    GENERIC_WRITE = 2
+    CREATE_CHILDREN = 4
+    DELETE = 8
+}

Source/Classes/classes.json

@@ -34,5 +34,17 @@
    "VSTeamProcess.ps1",
    "VSTeamRef.ps1",
    "VSTeamTeam.ps1",
-   "VSTeamAccount.ps1"
+   "VSTeamAccount.ps1",
+   "VSTeamGitRepositoryPermissions.ps1",
+   "VSTeamIdentityPermissions.ps1",
+   "VSTeamProjectPermissions.ps1",
+   "VSTeamWorkItemAreaPermissions.ps1",
+   "VSTeamWorkItemIterationPermissions.ps1",
+   "VSTeamGroup.ps1",
+   "VSTeamGitRepositoryPermissions.ps1",
+   "VSTeamIdentityPermissions.ps1",
+   "VSTeamProjectPermissions.ps1",
+   "VSTeamWorkItemAreaPermissions.ps1",
+   "VSTeamWorkItemIterationPermissions.ps1",
+   "VSTeamDescriptor.ps1"
 ]

Source/Private/common.ps1

@@ -6,6 +6,13 @@ $here = Split-Path -Parent $MyInvocation.MyCommand.Path
 $profilesPath = "$HOME/vsteam_profiles.json"
 
 # Not all versions support the name features.
+
+function _supportsGraph {
+   if (-not [VSTeamVersions]::Graph) {
+      throw 'This account does not support the graph API.'
+   }
+}
+
 function _supportsFeeds {
    if (-not [VSTeamVersions]::Packaging) {
       throw 'This account does not support packages.'