feat: Added function New-PipelineRun

.gitignore

@@ -1,3 +1,4 @@
 # Don't check in the Output dir
 Output/
 site/
+.vs

AzureDevOpsPowerShell/Public/Api/Pipelines/Runs/Get-PipelineRun.ps1 → AzureDevOpsPowerShell/Public/Api/Pipelines/Runs/Get-AzDoPipelineRun.ps1

@@ -1,23 +1,40 @@
-function Get-PipelineRun {
+function Get-AzDoPipelineRun {
   <#
 .SYNOPSIS
   Retrieves pipeline run information from Azure DevOps for a specified pipeline within a project.
+
 .DESCRIPTION
-  The `Get-PipelineRun` function fetches details about one or more pipeline runs from an Azure DevOps project.
+  The `Get-AzDoPipelineRun` function fetches details about one or more pipeline runs from an Azure DevOps project.
   It requires the collection URI, project name, and pipeline ID. Optionally, specific run IDs can be provided
   to filter the results. The function uses the `Invoke-AzDoRestMethod` cmdlet to make the REST API call to
   Azure DevOps and returns the run details.
+
 .EXAMPLE
-  Get-PipelineRun -CollectionUri "https://dev.azure.com/YourOrg" -ProjectName "YourProject" -PipelineId 123
+  $getPipelineRunSplat = @{
+      CollectionUri = "https://dev.azure.com/YourOrg"
+      ProjectName = "YourProject"
+      PipelineId = 123
+  }
+
+  Get-AzDoPipelineRun @getPipelineRunSplat
 
   Retrieves all runs for the specified pipeline in the given project.
+
 .EXAMPLE
-  Get-PipelineRun -CollectionUri "https://dev.azure.com/YourOrg" -ProjectName "YourProject" -PipelineId 123 -RunId 456
+  $getPipelineRunSplat = @{
+      CollectionUri = "https://dev.azure.com/YourOrg"
+      ProjectName = "YourProject"
+      PipelineId = 123
+      RunId = 456
+  }
+
+  Get-AzDoPipelineRun @getPipelineRunSplat
 
   Retrieves the details of the specified run (with ID 456) for the given pipeline.
+
 .OUTPUTS
-  Returns an array of pipeline run objects. If specific run IDs are provided, only the matching runs are returned.
-.NOTES
+  System.Management.Automation.PSCustomObject
+
 #>
   [CmdletBinding(SupportsShouldProcess)]
   param (
@@ -53,13 +70,40 @@ function Get-PipelineRun {
       $runs = $response.value
 
       if (-not $RunId) {
-        return $runs
+        $runs | ForEach-Object {
+          [PSCustomObject]@{
+            PipelineId    = $_.pipeline.id
+            RunId         = $_.id
+            RunName       = $_.name
+            Result        = $_.result
+            State         = $_.state
+            CreatedAt     = $_.createdDate
+            FinishedAt    = $_.finishedDate
+            ProjectName   = $ProjectName
+            CollectionUri = $CollectionUri
+            URL           = $_.url
+          }
+        }
+        return
       }
 
-      $runs | Where-Object { $_.id -in $RunId }
+      @($runs | Where-Object { $_.id -in $RunId } | ForEach-Object {
+          [PSCustomObject]@{
+            PipelineId    = $_.pipeline.id
+            RunId         = $_.id
+            RunName       = $_.name
+            Result        = $_.result
+            State         = $_.state
+            CreatedAt     = $_.createdDate
+            FinishedAt    = $_.finishedDate
+            ProjectName   = $ProjectName
+            CollectionUri = $CollectionUri
+            URL           = $_.url
+          }
+        }
+      )
     } else {
       Write-Verbose "Calling Invoke-AzDoRestMethod with $($params| ConvertTo-Json -Depth 10)"
     }
   }
 }
-

AzureDevOpsPowerShell/Public/Api/Pipelines/Runs/New-AzDoPipelineRun.ps1

@@ -0,0 +1,128 @@
+function New-AzDoPipelineRun {
+  <#
+.SYNOPSIS
+  Initiates a new run of an Azure DevOps pipeline.
+
+.DESCRIPTION
+  The New-AzDoPipelineRun function starts a new run for a specified Azure DevOps pipeline.
+  It supports various parameters to customize the pipeline run, including the collection URI, project name, pipeline ID, branch, parameters, preview run flag, and stages to skip.
+  This function leverages the Azure DevOps REST API to trigger the pipeline run.
+
+.EXAMPLE
+  $newPipelineRunSplat = @{
+    CollectionUri = "https://dev.azure.com/organization"
+    ProjectName = "SampleProject"
+    PipelineId = 123
+    StagesToSkip = @("Stage1", "Stage2")
+  }
+
+  New-AzDoPipelineRun @newPipelineRunSplat
+  This command initiates a new run of the pipeline with ID 123 in the "SampleProject" project.
+
+.EXAMPLE
+  $newPipelineRunSplat = @{
+      CollectionUri = "https://dev.azure.com/organization"
+      ProjectName = "SampleProject"
+      PipelineId = 123
+      Branch = "dev"
+      Parameters = @{param1 = "value1"; param2 = "value2"}
+  }
+
+  New-AzDoPipelineRun @newPipelineRunSplat
+  This command initiates a new run of the pipeline with ID 123 in the "SampleProject" project, targeting the "dev" branch.
+
+.OUTPUTS
+  System.Management.Automation.PSCustomObject
+
+  Returns the response from the Azure DevOps REST API, which includes details of the pipeline run.
+#>
+  [CmdletBinding(SupportsShouldProcess)]
+  param (
+    # Collection Uri of the organization
+    [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
+    [ValidateScript({ Validate-CollectionUri -CollectionUri $_ })]
+    [string]
+    $CollectionUri,
+
+    # Project where the pipeline is defined
+    [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
+    [string]
+    $ProjectName,
+
+    # Pipeline ID of the pipeline to start the run for
+    [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
+    [int]$PipelineId,
+
+    # Parameters to pass to the pipeline
+    [Parameter(ValueFromPipelineByPropertyName)]
+    [object]$Parameters,
+
+    # If the run should be a preview run
+    [Parameter(ValueFromPipelineByPropertyName)]
+    [switch]$PreviewRun,
+
+    # Stages to skip in the pipeline run
+    [Parameter(ValueFromPipelineByPropertyName)]
+    [array]$StagesToSkip,
+
+    # Branch to run the pipeline for
+    [Parameter(ValueFromPipelineByPropertyName)]
+    [string]$Branch
+  )
+  process {
+    $body = @{}
+
+    if ($PreviewRun) {
+      $body.Add("previewRun", $PreviewRun)
+    }
+
+    if ($Branch) {
+      $resources = @{
+        repositories = @{
+          self = @{
+            refName = $Branch
+          }
+        }
+      }
+
+      $body.Add("resources", $resources)
+    }
+
+    if ($StagesToSkip) {
+      $body.Add("stagesToSkip", $StagesToSkip)
+    }
+
+    if ($Parameters) {
+      $body.Add("templateParameters", $Parameters)
+    } else {
+      $body.Add("templateParameters", @{})
+    }
+
+    $params = @{
+      Uri     = "$CollectionUri/$ProjectName/_apis/pipelines/$PipelineId/runs"
+      Version = "7.0"
+      Method  = 'POST'
+      Body    = $body
+    }
+
+    if ($PSCmdlet.ShouldProcess("PipelineId: $PipelineId", "Trigger a new run on pipeline")) {
+      try {
+        $output = Invoke-AzDoRestMethod @params
+        [PSCustomObject]@{
+          PipelineId    = $output.pipeline.id
+          RunId         = $output.id
+          RunName       = $output.name
+          CreatedAt     = $output.createdDate
+          ProjectName   = $ProjectName
+          CollectionUri = $CollectionUri
+          URL           = $output.url
+          Resources     = $output.resources
+        }
+      } catch {
+        Write-AzDoError -Message $_
+      }
+    } else {
+      Write-Verbose "Calling Invoke-AzDoRestMethod with $($params| ConvertTo-Json -Depth 10)"
+    }
+  }
+}

build.ps1

@@ -1,61 +1,61 @@
 [cmdletbinding(DefaultParameterSetName = 'Task')]
 param(
-    # Build task(s) to execute
-    [parameter(ParameterSetName = 'task', position = 0)]
-    [string[]]$Task = 'default',
-
-    # Bootstrap dependencies
-    [switch]$Bootstrap,
-
-    # Calculate version
-    [switch]$CalculateVersion,
-
-    # List available build tasks
-    [parameter(ParameterSetName = 'Help')]
-    [switch]$Help,
-
-    # Optional properties to pass to psake
-    [hashtable]$Properties,
-
-    # Optional parameters to pass to psake
-    [hashtable]$Parameters = @{
-        "PSRepository"          = 'PSGallery'
-        "PSRepositoryApiKey"    = ""
-        "ScriptAnalysisEnabled" = $true
-        "TestEnabled"           = $true
-    }
+  # Build task(s) to execute
+  [parameter(ParameterSetName = 'task', position = 0)]
+  [string[]]$Task = 'default',
+
+  # Bootstrap dependencies
+  [switch]$Bootstrap,
+
+  # Calculate version
+  [switch]$CalculateVersion,
+
+  # List available build tasks
+  [parameter(ParameterSetName = 'Help')]
+  [switch]$Help,
+
+  # Optional properties to pass to psake
+  [hashtable]$Properties,
+
+  # Optional parameters to pass to psake
+  [hashtable]$Parameters = @{
+    "PSRepository"          = 'PSGallery'
+    "PSRepositoryApiKey"    = ""
+    "ScriptAnalysisEnabled" = $true
+    "TestEnabled"           = $true
+  }
 )
 
 $ErrorActionPreference = 'Stop'
 
 # Bootstrap dependencies
 if ($Bootstrap.IsPresent) {
-    Get-PackageProvider -Name Nuget -ForceBootstrap | Out-Null
-    Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
-    if ((Test-Path -Path ./requirements.psd1)) {
-        if (-not (Get-Module -Name PSDepend -ListAvailable)) {
-            Install-Module -Name PSDepend -Repository PSGallery -Scope CurrentUser -Force
-        }
-        Import-Module -Name PSDepend -Verbose:$false
-        Invoke-PSDepend -Path './requirements.psd1' -Install -Import -Force -WarningAction SilentlyContinue
-    } else {
-        Write-Warning 'No [requirements.psd1] found. Skipping build dependency installation.'
+  Get-PackageProvider -Name Nuget -ForceBootstrap | Out-Null
+  Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
+  if ((Test-Path -Path ./requirements.psd1)) {
+    if (-not (Get-Module -Name PSDepend -ListAvailable)) {
+      Install-Module -Name PSDepend -Repository PSGallery -Scope CurrentUser -Force
     }
+    Import-Module -Name PSDepend -Verbose:$false
+    Invoke-PSDepend -Path './requirements.psd1' -Install -Import -Force -WarningAction SilentlyContinue
+  } else {
+    Write-Warning 'No [requirements.psd1] found. Skipping build dependency installation.'
+  }
 }
 
 # Execute psake task(s)
 $psakeFile = './psakeFile.ps1'
 if ($PSCmdlet.ParameterSetName -eq 'Help') {
-    Get-PSakeScriptTasks -buildFile $psakeFile |
-    Format-Table -Property Name, Description, Alias, DependsOn
+  Get-PSakeScriptTasks -buildFile $psakeFile |
+  Format-Table -Property Name, Description, Alias, DependsOn
 } else {
-    Set-BuildEnvironment -Force
-    Invoke-psake -buildFile $psakeFile -taskList $Task -nologo -properties $Properties -parameters $Parameters
-    if ($psake.build_success) {
-        "Build complete"
-        exit 0
-    } else {
-        Write-Error "Build not complete"
-        exit 1
-    }
+  Set-BuildEnvironment -Force
+  Invoke-psake -buildFile $psakeFile -taskList $Task -nologo -properties $Properties -parameters $Parameters
+  if ($psake.build_success) {
+    "Build complete"
+    exit 0
+  } else {
+    Write-Error "Build not complete"
+    exit 1
+  }
 }