functions/get-adopicklist.ps1
|
<# .SYNOPSIS Retrieves a picklist by its ID. .DESCRIPTION This function uses the `Invoke-ADOApiRequest` function to call the Azure DevOps REST API and retrieve a specific picklist by its ID. .PARAMETER Organization The name of the Azure DevOps organization. .PARAMETER Token The authentication token for accessing Azure DevOps. .PARAMETER ListId The ID of the picklist to retrieve. .PARAMETER ApiVersion The version of the Azure DevOps REST API to use. Default is "7.1". .EXAMPLE Get-ADOPickList -Organization "fabrikam" -Token "my-token" -ListId "661eb38e-6f0b-484a-bc53-27a57c2e2d50" Retrieves the specified picklist by its ID. .NOTES This function follows PSFramework best practices for logging and error handling. Author: Oleksandr Nikolaiev (@onikolaiev) #> function Get-ADOPickList { [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")] [CmdletBinding()] param ( [Parameter(Mandatory = $true)] [string]$Organization, [Parameter(Mandatory = $true)] [string]$Token, [Parameter(Mandatory = $true)] [string]$ListId, [Parameter()] [string]$ApiVersion = $Script:ADOApiVersion ) begin { Invoke-TimeSignal -Start # Log the start of the operation Write-PSFMessage -Level Verbose -Message "Starting retrieval of picklist with ID '$ListId' for Organization: $Organization" } process { if (Test-PSFFunctionInterrupt) { return } try { # Build the API URI $apiUri = "_apis/work/processes/lists/$ListId" # Log the request details Write-PSFMessage -Level Verbose -Message "API URI: $apiUri" # Call the Invoke-ADOApiRequest function $response = Invoke-ADOApiRequest -Organization $Organization ` -Token $Token ` -ApiUri $apiUri ` -Method "GET" ` -Headers @{"Content-Type" = "application/json"} ` -ApiVersion $ApiVersion # Log the successful response Write-PSFMessage -Level Verbose -Message "Successfully retrieved picklist with ID '$ListId' for Organization: $Organization" return $response.Results | Select-PSFObject * -TypeName "ADO.CORE.PickListObject" } catch { # Log the error Write-PSFMessage -Level Error -Message "Failed to retrieve picklist: $($_.ErrorDetails.Message)" -Exception $PSItem.Exception Stop-PSFFunction -Message "Stopping because of errors" return } } end { # Log the end of the operation Write-PSFMessage -Level Verbose -Message "Completed retrieval of picklist with ID '$ListId' for Organization: $Organization" Invoke-TimeSignal -End } } |