(#2591) Add headers to limit output commands

[corbob]

Description Of Changes

When a user asks for limited output from Chocolatey, it is not uncommon to pipe that output to ConvertFrom-String or ConvertFrom-Csv and manually add headers to get back an object. This allows for getting a header row back so that the end user doesn't need to add their own headers and discern what they are.

Adds a new feature that allows the user to always display the headers if desired. This defaults to off so that we don't break any existing scripts.

Motivation and Context

Reduce the amount of work end users need to do in order to consume limited output.

Testing

Ran through the tests in the Vagrant test environment. This resulted in two failures that appear unrelated to my changes. I will investigate those further before marking this PR as ready.

NOTE: This will require Chocolatey Licensed Extension changes.

Change Types Made

• Bug fix (non-breaking change)
• Feature / Enhancement (non-breaking change)
• Breaking change (fix or feature that could cause existing functionality to change)
• PowerShell code changes.

Related Issue

Fixes #2591

Change Checklist

• Requires a change to the documentation
• Documentation has been updated
• Tests to cover my changes, have been added
• All new and existing tests passed.
• PowerShell v2 compatibility checked.

[coveralls]

Coverage remained the same at 27.719% when pulling 46e4a2d on corbob:add_headers into e35fe2b on chocolatey:develop.

[corbob]

The tests added here failed on the pin output with a header due to it being overloaded I think... It might require some further investigation, and perhaps we should do that before merging this in?

For completeness this is the Test Kitchen output:

         Context Outputs headers for pin
           [+] Exits success (0) 4ms (2ms|2ms)
           [-] Displays appropriate header 5ms (4ms|1ms)
            Expected 'PackageID|Version', but got $null.
            at $ActualOutput | Should -Be $ExpectedHeaders, C:\Users\vagrant\AppData\Local\Temp\verifier\suites\chocolatey-licensed-tests\chocolatey-tests\features\Headers.Tests.ps1:129
            at <ScriptBlock>, C:\Users\vagrant\AppData\Local\Temp\verifier\suites\chocolatey-licensed-tests\chocolatey-tests\features\Headers.Tests.ps1:129

[corbob]

Converting this back to draft as it requires quite a bit of rework and validation.

[gep13]

@corbob I may have taken this for a quick spin, and rebased on the head of the develop branch. Just wanted to give you a heads up, so that you weren't surprised.

[gep13]

@corbob I have taken the liberty of rebasing this PR onto the head of the develop branch.

[gep13]

I have a number of local changes on my machine that I will push up here when I get a chance. This includes the outcomes from a chat with @pauby and a few additional changes after doing some testing of things.

[gep13]

During a discussion with @pauby the decision was made to:

• name the common option to --include-headers
• name the feature alwaysIncludeHeaders
• only show the header row if, and only if, there is something to be output (this is consistent with what the likes of PowerShell does)
• to be consistent with the names of the column headers for the new row, and have them match what the "things" are in for example the chocolatey.config file, or how they are named in the various commands that they are associated with. The header rows are best "seen" in the Header.Tests.ps1 file, where they are all asserted at the top of the file.

[gep13]

@AdmiringWorm I have run the Test-Kitchen tests for this PR, and they have all passed.

[gep13]

@AdmiringWorm this is now ready for a review. Thanks

[AdmiringWorm]

Some minor nitpicks.

[AdmiringWorm]

LGTM