From f1dedfeaadf91d4be7534bf3760c2acaf2cdb36a Mon Sep 17 00:00:00 2001
From: Eike Hirdes <eike.hirdes@aitgmbh.de>
Date: Thu, 6 Apr 2023 15:35:19 +0200
Subject: [PATCH] Allow to destroy work items (permanent delete)

---
 Functions/AzureDevOps/Remove-ADOWorkItem.ps1 | 12 ++++++++--
 docs/Remove-ADOWorkItem.md                   | 25 ++++++++++++++++----
 2 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/Functions/AzureDevOps/Remove-ADOWorkItem.ps1 b/Functions/AzureDevOps/Remove-ADOWorkItem.ps1
index 84a13eb6..b0734558 100644
--- a/Functions/AzureDevOps/Remove-ADOWorkItem.ps1
+++ b/Functions/AzureDevOps/Remove-ADOWorkItem.ps1
@@ -8,7 +8,7 @@
     .Example
         Remove-ADOWorkItem -Organization StartAutomating -Project PSDevOps -ID 10
     .Example
-        Remove-ADOWorkItem -Organization StartAutomating -Project PSDevOps -Query "Select [System.ID] from WorkItems Where [System.Title] = 'Test-WorkItem'" -PersonalAccessToken $pat -Confirm:$false
+        Remove-ADOWorkItem -Organization StartAutomating -Project PSDevOps -Query "Select [System.ID] from WorkItems Where [System.Title] = 'Test-WorkItem'" -PersonalAccessToken $pat -Confirm:$false -Destroy
     .Link
         Invoke-ADORestAPI
     .Link
@@ -54,7 +54,11 @@
     # If targeting TFS, this will need to change to match your server version.
     # See: https://docs.microsoft.com/en-us/azure/devops/integrate/concepts/rest-api-versioning?view=azure-devops
     [string]
-    $ApiVersion = "5.1")
+    $ApiVersion = "5.1",
+    
+    # If set, the work item is deleted permanently. Please note: the destroy action is PERMANENT and cannot be undone.
+    [switch]
+    $Destroy)
 
     dynamicParam { . $GetInvokeParameters -DynamicParameter }
     begin {
@@ -81,6 +85,10 @@
                 if ($ApiVersion) {
                     "api-version=$ApiVersion"
                 }
+            $uri +=
+                if ($Destroy) {
+                    "&destroy=true"
+                }
 
             $invokeParams.Uri = $uri
             $invokeParams.Method = 'DELETE'
diff --git a/docs/Remove-ADOWorkItem.md b/docs/Remove-ADOWorkItem.md
index d3c49fbb..5e2b4968 100644
--- a/docs/Remove-ADOWorkItem.md
+++ b/docs/Remove-ADOWorkItem.md
@@ -27,7 +27,7 @@ Remove-ADOWorkItem -Organization StartAutomating -Project PSDevOps -ID 10
 
 #### EXAMPLE 2
 ```PowerShell
-Remove-ADOWorkItem -Organization StartAutomating -Project PSDevOps -Query "Select [System.ID] from WorkItems Where [System.Title] = 'Test-WorkItem'" -PersonalAccessToken $pat -Confirm:$false
+Remove-ADOWorkItem -Organization StartAutomating -Project PSDevOps -Query "Select [System.ID] from WorkItems Where [System.Title] = 'Test-WorkItem'" -PersonalAccessToken $pat -Confirm:$false -Destroy
 ```
 
 ---
@@ -153,6 +153,23 @@ See: https://docs.microsoft.com/en-us/azure/devops/integrate/concepts/rest-api-v
 
 
 
+---
+#### **Destroy**
+
+If set, the work item is deleted permanently. Please note: the destroy action is PERMANENT and cannot be undone.
+
+
+
+> **Type**: ```[SwitchParameter]```
+
+> **Required**: false
+
+> **Position**: named
+
+> **PipelineInput**:false
+
+
+
 ---
 #### **WhatIf**
 -WhatIf is an automatic variable that is created when a command has ```[CmdletBinding(SupportsShouldProcess)]```.
@@ -179,12 +196,12 @@ If the command sets a ```[ConfirmImpact("Medium")]``` which is lower than ```$co
 ---
 ### Syntax
 ```PowerShell
-Remove-ADOWorkItem -Organization <String> -Project <String> -ID <String> [-Server <Uri>] [-ApiVersion <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
+Remove-ADOWorkItem -Organization <String> -Project <String> -ID <String> [-Server <Uri>] [-ApiVersion <String>] [-Destroy] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 ```PowerShell
-Remove-ADOWorkItem -Organization <String> -Project <String> -Query <String> [-Server <Uri>] [-ApiVersion <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
+Remove-ADOWorkItem -Organization <String> -Project <String> -Query <String> [-Server <Uri>] [-ApiVersion <String>] [-Destroy] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 ```PowerShell
-Remove-ADOWorkItem -Organization <String> -Project <String> -QueryID <String> [-Server <Uri>] [-ApiVersion <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
+Remove-ADOWorkItem -Organization <String> -Project <String> -QueryID <String> [-Server <Uri>] [-ApiVersion <String>] [-Destroy] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 ---