Adding new functions

[Dylan-Prins]

Summary of the new feature / enhancement

We are missing the following functions in our existing api's:

• Get-AzDoPullRequest
• Remove-AzDoPullRequest
• Remove-AzDoEnvironment
• Get-AzDoProjectSettings
• Get-AzDoPipelineBranchControl

Proposed technical implementation details (optional)

No response

[Dylan-Prins]

@baswijdenes Hi Bas, I made a list which you can cross-of. Let me know if you need any help

[baswijdenes]

Remove-AzDoPullRequest will become (without consultation with Dylan for now) Set-AzDoPullRequest with default values to abandon a pull request since a pull request cannot be deleted?.

[baswijdenes]

Get-AzDoPullRequest is finished. Added the synopsis in the function & will update the documentation with PlatyPS. A merge will follow later on.

[Manbearpiet]

Do note that I setup some change I've already implemented here in some commandlets:
https://github.com/WeAreInSpark/AzureDevOpsPowerShellAPI/pull/72/files

PowerShell

Generic

All functions in the module should be advanced functions.
Aliases should be expanded
If variables are used on only one location, the variable should be replaced with the value and the assignment removed.
Functions should support ShouldProcess showing what would happen if WhatIf is supplied. It should be implemented beneath the functioncode using an if statement.

Splatting should be used to functions with multiple or long arguments.

If a Get- function accepts filtering for a specific resourcename (ProjectName, RepoName, VariableGroupName) as an array, it should fetch all the resources and use Where-Object { -not $<ResourceName> -or $_.Name -in $<ResourceName> } for filtering.

Comment based help

The comment-based help block should be inside of the function at the top between the opening of the scriptblock and the CmdletBinding() statement.
All public functions require comment-based help.
The comment based help should contain a short synopsis and description.
The parameters of the function should be documented with # directly above the [Parameter( statement unless it's too much text. If the parameter is documented above the parameter, it shouldn't be in the comment-based help section.
The comment-based help should contain examples containing:

• Minimal input required to use the function using inline examples (no splatting or pipeline);
• Extensive input using splatting;
• If the command supports ValueFromPipeline parameter there should be an example how to use it;

Complex regex should be commented above with what it's regexing for.

ScriptAnalyzer

All PowerShell code should pass the built-in PSScriptAnalyzer rules (Warning and Error level).
Additionally all PowerShell code should pass the module Indented.ScriptAnalyzerRules it's rules, except the "UseSyntacticallyCorrectExamples".

Error-handling

If parameters support arrays, calling a different function within a loop over the parameter should be handled with a non-terminating error using:

Write-Error "Failed to do <action> to <resource> in <container> of <collection> Error: $_"

If the error happens within a foreach loop it should continue with the next object in the array.
If the error happens within a Foreach-Object loop it should utilize return. When there is no loop utilized it should use:

$PSCmdlet.ThrowTerminatingError((Write-AzDoError -Message "Failed to do <action> to <resource> in <container> of <collection> Error: $_"))

Output

The functions should output end results of Invoke-AzDoRestMethod directly to the pipeline in the process block, not in an end-block. It should just output the object without assigning it to a variable.
The output should be a PSCustomObject containing all the parameters required to pipe to a different function to the same resourcetype (Project, Repo, Workitem etc.) with the property names consistent, required for the ValueFromPipelineFromPropertyName.

[baswijdenes]

@Manbearpiet I've merged your branch in to mine. Do you want me to review your pull request?

[Manbearpiet]

I was busy with #72 or do you mean #61 ?

[baswijdenes]

Yes I mean 72, but I see that it's not yours ;-). Will you review that one?

[Manbearpiet]

I was busy with that one but couldn't find the time to proceed. I was fixing it to conform to the quote above. Each API represented in our functions should have at least CRUD support, IMHO. I was also fixing the begin/process/end pattern we started; it doesn't work as we thought it would. So when I find the time, I'll proceed with that one ☝️. For now, you can review mine, yes 👍.

[baswijdenes]

Unfortunately I cannot add a switch to Get-AzDoProject for the settings (or -Properties) because of the Where-Object filtering.
Ill create a seperate function for the settings / properties.

[baswijdenes]

Get-AzDoPipelineBranchControl: https://learn.microsoft.com/en-us/rest/api/azure/devops/git/policy-configurations/list?view=azure-devops-rest-5.0

[baswijdenes]

Created a PR and tagged reviewers