Add "Remove Agent" function (#70)

* added a function to remove agents * added test for removing agents * added docs for "remove agent" function * added -Force param and option to add multiple agents at once * Added test to cover the situation where it throws. * I decided to change the level to High. * Updated readme and psd1 for Version 3.0.5 * The pools are changing so fast it breaks our integration tests. I changed the condition to account for that. * Missed a - on Be
MethodsAndPractices · Aug 1, 2018 · eb9f93c · eb9f93c
1 parent 5f0e034
commit eb9f93c
Show file tree

Hide file tree

Showing 10 changed files with 238 additions and 9 deletions.
diff --git a/.docs/Remove-VSTeamAgent.md b/.docs/Remove-VSTeamAgent.md
@@ -0,0 +1,50 @@
+<!-- #include "./common/header.md" -->
+
+# Remove-VSTeamAgent
+
+## SYNOPSIS
+
+<!-- #include "./synopsis/Remove-VSTeamAgent.md" -->
+
+## SYNTAX
+
+## DESCRIPTION
+
+<!-- #include "./synopsis/Remove-VSTeamAgent.md" -->
+
+## EXAMPLES
+
+## PARAMETERS
+
+### -PoolId
+
+Id of the pool.
+
+```yaml
+Type: String
+Required: True
+Accept pipeline input: true (ByValue)
+```
+
+### -Id
+
+Id of the agent to remove.
+
+```yaml
+Type: int
+Aliases: AgentID
+Required: True
+Accept pipeline input: true (ByPropertyName)
+```
+
+<!-- #include "./params/force.md" -->
+
+## INPUTS
+
+### System.String
+
+## OUTPUTS
+
+## NOTES
+
+## RELATED LINKS
diff --git a/.docs/synopsis/Remove-VSTeamAgent.md b/.docs/synopsis/Remove-VSTeamAgent.md
@@ -0,0 +1 @@
+Removes an agent from a pool.
diff --git a/README.md b/README.md
@@ -12,6 +12,12 @@ The cases of every file is very important. This module is to be used on Windows,
 
 ## Release Notes
 
+### 3.0.5
+
+Merged [Pull Request](https://github.com/DarqueWarrior/vsteam/pull/70) from [Geert van der Cruijsen](https://github.com/Geertvdc) which included the following:
+
+Added a function to remove vsts agents from a pool. by calling Remove-Agent or Remove-VSTeamAgent
+
 ### 3.0.4
 
 The ProjectName dynamic parameter that enables Tab Complete of project names was getting called approximately 20 times when tab completing a function name. To reduce the number of calls a rudimentary cache was put in place.   

diff --git a/VSTeam.psd1 b/VSTeam.psd1
@@ -13,7 +13,7 @@
    RootModule        = ''
 
    # Version number of this module.
-   ModuleVersion     = '3.0.4'
+   ModuleVersion     = '3.0.5'
 
    # Supported PSEditions
    # CompatiblePSEditions = @()
@@ -202,7 +202,8 @@
       'Get-VSTeamWorkItem',
       'Show-VSTeamWorkItem',
       'Get-VSTeamGitRef',
-      'Get-VSTeamAgent')
+      'Get-VSTeamAgent',
+      'Remove-VSTeamAgent')
 
    # 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 = @()
@@ -302,7 +303,8 @@
       'Update-Policy', 
       'Remove-Policy',
       'Get-GitRef',
-      'Get-Agent')
+      'Get-Agent',
+      'Remove-Agent')
 
    # DSC resources to export from this module
    # DscResourcesToExport = @()

diff --git a/docs/Team.md b/docs/Team.md
@@ -223,6 +223,10 @@ Removes a team from a project.
 
 Clears your default project, account name and personal access token.
 
+### [Remove-VSTeamAgent](Remove-VSTeamAgent.md)
+
+Removes an agent from a pool.
+
 ### [Remove-VSTeamBuild](Remove-VSTeamBuild.md)
 
 Deletes the build.

diff --git a/docs/readme.md b/docs/readme.md
@@ -228,6 +228,10 @@ Removes a team from a project.
 
 Clears your default project, account name and personal access token.
 
+### [Remove-VSTeamAgent](Remove-VSTeamAgent.md)
+
+Removes an agent from a pool.
+
 ### [Remove-VSTeamBuild](Remove-VSTeamBuild.md)
 
 Deletes the build.

diff --git a/en-US/VSTeam-Help.xml b/en-US/VSTeam-Help.xml
@@ -8860,6 +8860,115 @@ Demo-CI           Demo-CI-45   notStarted</dev:code>
       </maml:navigationLink>
     </command:relatedLinks>
   </command:command>
+  <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
+    <command:details>
+      <command:name>Remove-VSTeamAgent</command:name>
+      <command:verb>Remove</command:verb>
+      <command:noun>VSTeamAgent</command:noun>
+      <maml:description>
+        <maml:para>Removes an agent from a pool.</maml:para>
+      </maml:description>
+    </command:details>
+    <maml:description>
+      <maml:para>Removes an agent from a pool.</maml:para>
+    </maml:description>
+    <command:syntax>
+      <command:syntaxItem>
+        <maml:name>Remove-VSTeamAgent</maml:name>
+        <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none">
+          <maml:name>PoolId</maml:name>
+          <maml:Description>
+            <maml:para>Id of the pool.</maml:para>
+          </maml:Description>
+          <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
+          <dev:type>
+            <maml:name>String</maml:name>
+            <maml:uri />
+          </dev:type>
+          <dev:defaultValue>None</dev:defaultValue>
+        </command:parameter>
+        <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="AgentID">
+          <maml:name>Id</maml:name>
+          <maml:Description>
+            <maml:para>Id of the agent to remove.</maml:para>
+          </maml:Description>
+          <command:parameterValue required="true" variableLength="false">int</command:parameterValue>
+          <dev:type>
+            <maml:name>int</maml:name>
+            <maml:uri />
+          </dev:type>
+          <dev:defaultValue>None</dev:defaultValue>
+        </command:parameter>
+        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none">
+          <maml:name>Force</maml:name>
+          <maml:Description>
+            <maml:para>Forces the command without confirmation</maml:para>
+          </maml:Description>
+          <dev:type>
+            <maml:name>SwitchParameter</maml:name>
+            <maml:uri />
+          </dev:type>
+          <dev:defaultValue>False</dev:defaultValue>
+        </command:parameter>
+      </command:syntaxItem>
+    </command:syntax>
+    <command:parameters>
+      <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none">
+        <maml:name>PoolId</maml:name>
+        <maml:Description>
+          <maml:para>Id of the pool.</maml:para>
+        </maml:Description>
+        <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
+        <dev:type>
+          <maml:name>String</maml:name>
+          <maml:uri />
+        </dev:type>
+        <dev:defaultValue>None</dev:defaultValue>
+      </command:parameter>
+      <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="AgentID">
+        <maml:name>Id</maml:name>
+        <maml:Description>
+          <maml:para>Id of the agent to remove.</maml:para>
+        </maml:Description>
+        <command:parameterValue required="true" variableLength="false">int</command:parameterValue>
+        <dev:type>
+          <maml:name>int</maml:name>
+          <maml:uri />
+        </dev:type>
+        <dev:defaultValue>None</dev:defaultValue>
+      </command:parameter>
+      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none">
+        <maml:name>Force</maml:name>
+        <maml:Description>
+          <maml:para>Forces the command without confirmation</maml:para>
+        </maml:Description>
+        <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
+        <dev:type>
+          <maml:name>SwitchParameter</maml:name>
+          <maml:uri />
+        </dev:type>
+        <dev:defaultValue>False</dev:defaultValue>
+      </command:parameter>
+    </command:parameters>
+    <command:inputTypes>
+      <command:inputType>
+        <dev:type>
+          <maml:name>System.String</maml:name>
+        </dev:type>
+        <maml:description>
+          <maml:para></maml:para>
+        </maml:description>
+      </command:inputType>
+    </command:inputTypes>
+    <command:returnValues />
+    <maml:alertSet>
+      <maml:alert>
+        <maml:para></maml:para>
+      </maml:alert>
+    </maml:alertSet>
+    <command:examples />
+    <command:relatedLinks />
+  </command:command>
   <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
     <command:details>
       <command:name>Remove-VSTeamBuild</command:name>

diff --git a/integration/test/010_projects.Tests.ps1 b/integration/test/010_projects.Tests.ps1
@@ -10,9 +10,11 @@ if ($null -eq $env:TEAM_CIBUILD) {
 ##############################################################
 # Before running these tests you must set the following
 # Environment variables.
-# $env:API_VERSION = TFS2017, TFS2018 or VSTS depending on the value used for ACCT
+# $env:API_VERSION = TFS2017, TFS2018 or VSTS depending on
+#                    the value used for ACCT
 # $env:EMAIL = Email of user to remove and re-add to account
-# $env:ACCT = VSTS Account Name or full TFS URL including collection
+# $env:ACCT = VSTS Account Name or full TFS URL including
+#             collection
 # $env:PAT = Personal Access token of ACCT
 ##############################################################
 #     THESE TEST ARE DESTRUCTIVE. USE AN EMPTY ACCOUNT.      #
@@ -169,7 +171,7 @@ Describe 'VSTeam Integration Tests' -Tag 'integration' {
             $actual.name | Should Be 'Default'
          }
          else {
-            $actual.Count | Should Be 6
+            $actual.Count | Should -Not -Be 0
          }
       }
    }
@@ -193,7 +195,7 @@ Describe 'VSTeam Integration Tests' -Tag 'integration' {
          }
          else {
             $global:queueId = $actual[0].id
-            $actual.Count | Should Be 6
+            $actual.Count | Should -Not -Be 0
          }
       }
 

diff --git a/src/agents.psm1 b/src/agents.psm1
@@ -43,8 +43,38 @@ function Get-VSTeamAgent {
    }
 }
 
+function Remove-VSTeamAgent {
+   [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = "High")]
+   param(      
+      [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 0)]
+      [int] $PoolId,
+
+      [parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, Position = 1)]
+      [Alias('AgentID')]
+      [int[]] $Id,
+
+      # Forces the command without confirmation
+      [switch] $Force
+   )
+
+   process {
+      foreach ($item in $Id) {
+         if ($force -or $pscmdlet.ShouldProcess($item,"Delete agent")) {
+            try {
+               _callAPI -Method Delete -Area "distributedtask/pools/$PoolId" -Resource agents -Id $item -Version $VSTeamVersionTable.DistributedTask | Out-Null
+               Write-Output "Deleted agent $item"
+            }
+            catch {
+               _handleException $_
+            }
+         }
+      }
+   }
+}
+
 Set-Alias Get-Agent Get-VSTeamAgent
+Set-Alias Remove-Agent Remove-VSTeamAgent
 
 Export-ModuleMember `
-   -Function Get-VSTeamAgent `
-   -Alias Get-Agent
+   -Function Get-VSTeamAgent, Remove-VSTeamAgent `
+   -Alias Get-Agent, Remove-Agent
diff --git a/unit/test/agents.Tests.ps1 b/unit/test/agents.Tests.ps1
@@ -66,5 +66,26 @@ InModuleScope agents {
             }
          }
       }
+
+      Context 'Remove-VSTeamAgent by ID' {
+         Mock Invoke-RestMethod
+
+         It 'should remove the agent with passed in Id' {
+            Remove-VSTeamAgent -Pool 36 -Id 950 -Force
+
+            Assert-MockCalled Invoke-RestMethod -Exactly -Scope It -Times 1 -ParameterFilter {
+               $Method -eq 'Delete' -and
+               $Uri -eq "https://test.visualstudio.com/_apis/distributedtask/pools/36/agents/950?api-version=$($VSTeamVersionTable.DistributedTask)"
+            }
+         }
+      }
+
+      Context 'Remove-VSTeamAgent throws' {
+         Mock Invoke-RestMethod { throw 'boom' }
+
+         It 'should remove the agent with passed in Id' {
+            { Remove-VSTeamAgent -Pool 36 -Id 950 -Force } | Should Throw
+         }
+      }
    }
 }