Adds a new function Stop-VSTeamBuild

.docs/Stop-VSTeamBuild.md

@@ -0,0 +1,60 @@
+<!-- #include "./common/header.md" -->
+
+# Stop-VSTeamBuild
+
+## SYNOPSIS
+
+<!-- #include "./synopsis/Stop-VSTeamBuild.md" -->
+
+## SYNTAX
+
+## DESCRIPTION
+
+Stop-VSTeamBuild will cancel a build using the build id.
+
+## EXAMPLES
+
+### -------------------------- EXAMPLE 1 --------------------------
+
+```PowerShell
+PS C:\> Set-VSTeamDefaultProject Demo
+PS C:\> Stop-VSTeamBuild -id 1
+```
+
+This example cancels the build with build id 1.
+
+### -------------------------- EXAMPLE 3 --------------------------
+
+```PowerShell
+PS C:\> Set-VSTeamDefaultProject Demo
+PS C:\> $buildsToCancel = Get-VSTeamBuild -StatusFilter "inProgress" | where-object definitionName -eq Build-Defenition-Name
+PS C:\> ForEach($build in $buildsToCancel) { Stop-VSTeamBuild -id $build.id }
+```
+
+This example will find all builds with a status of "inProgress" and a defenitionName of "Build-Defenition-Name" and then cancel each of these builds.
+
+## PARAMETERS
+
+<!-- #include "./params/projectName.md" -->
+
+<!-- #include "./params/BuildId.md" -->
+
+<!-- #include "./params/confirm.md" -->
+
+<!-- #include "./params/whatIf.md" -->
+
+## INPUTS
+
+### System.String
+
+ProjectName
+
+### System.Int32
+
+BuildId
+
+## OUTPUTS
+
+## NOTES
+
+## RELATED LINKS

.docs/synopsis/Stop-VSTeamBuild.md

@@ -0,0 +1 @@
+Allows you to cancel a running build.

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 6.5.1
+
+Merged [Pull Request](https://github.com/DarqueWarrior/vsteam/pull/317) from [Brittan DeYoung](https://github.com/brittandeyoung) which included the following:
+
+- Adds a new function Stop-VSTeamBuild which allows cancelling a build using the build id.
+
 ## 6.5.0
 
 Requires Pester 5.x

Source/Public/Stop-VSTeamBuild.ps1

@@ -0,0 +1,35 @@
+function Stop-VSTeamBuild {
+   [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = "Medium")]
+   param(
+      [parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
+      [Alias('BuildID')]
+      [Int] $Id,
+
+      [Parameter(Mandatory = $true, Position = 0, ValueFromPipelineByPropertyName = $true)]
+      [ProjectValidateAttribute()]
+      [ArgumentCompleter([ProjectCompleter])]
+      [string] $ProjectName
+   )
+
+   process {
+      if ($pscmdlet.ShouldProcess($Id, "Stop-VSTeamBuild")) {
+
+       try {
+
+          $body = @{
+             "status" = "Cancelling"
+          }
+
+         $bodyAsJson = $body | ConvertTo-Json -Compress -Depth 50
+
+         # Call the REST API
+         _callAPI -ProjectName $ProjectName -Area 'build' -Resource 'builds' -Id $Id `
+            -Method Patch -ContentType 'application/json' -body $bodyAsJson -Version $(_getApiVersion Build) | Out-Null
+       }
+
+       catch {
+         _handleException $_
+       }
+     }
+   }
+ }

unit/test/Stop-VSTeamBuild.Tests.ps1

@@ -0,0 +1,54 @@
+Set-StrictMode -Version Latest
+
+Describe 'VSTeamBuild' {
+   BeforeAll {
+      $sut = (Split-Path -Leaf $PSCommandPath).Replace(".Tests.", ".")
+
+      . "$PSScriptRoot/../../Source/Classes/VSTeamVersions.ps1"
+      . "$PSScriptRoot/../../Source/Classes/VSTeamProjectCache.ps1"
+      . "$PSScriptRoot/../../Source/Classes/ProjectCompleter.ps1"
+      . "$PSScriptRoot/../../Source/Classes/ProjectValidateAttribute.ps1"
+      . "$PSScriptRoot/../../Source/Private/common.ps1"
+      . "$PSScriptRoot/../../Source/Public/$sut"
+
+      Mock Invoke-RestMethod
+
+      # Mock the call to Get-Projects by the dynamic parameter for ProjectName
+      Mock Invoke-RestMethod { return @() } -ParameterFilter {
+         $Uri -like "*_apis/projects*"
+      }
+   }
+
+   Context 'Update Build status' {
+      BeforeAll {
+         # Set the account to use for testing. A normal user would do this
+         # using the Set-VSTeamAccount function.
+         Mock _getInstance { return 'https://dev.azure.com/test' } -Verifiable
+
+
+      }
+
+      It 'should post changes' {
+         Stop-VSTeamBuild -projectName project -id 1
+
+         Should -Invoke Invoke-RestMethod -Exactly -Times 1 -ParameterFilter {
+            $Method -eq 'Patch' -and
+            $Body -eq '{"status":"Cancelling"}' -and
+            $Uri -eq "https://dev.azure.com/test/project/_apis/build/builds/1?api-version=$(_getApiVersion Build)" }
+      }
+
+      It 'should process pipeline with multiple ids' {
+
+         $idArr = (1..3)
+
+         $idArr | Stop-VSTeamBuild -projectName project
+
+         Should -Invoke Invoke-RestMethod -Exactly -Times $idArr.Count -ParameterFilter {
+            $Method -eq 'Patch' -and
+            $Body -eq '{"status":"Cancelling"}' -and
+            $Uri -like "https://dev.azure.com/test/project/_apis/build/builds/*" -and
+            $Uri -like "*api-version=$(_getApiVersion Build)*"
+          }
+      }
+   }
+}