search

Azure / autorest.powershell

AutoRest PowerShell Generator
MIT License
112 stars 83 forks source link

Information level output has useless information #689

Closed dingmeng-xue closed 1 year ago

dingmeng-xue commented 4 years ago

Information level output doesn't make sense. We need to re-design information level output and debug level output.

Script 1.0.1 Az.Functions

PS /Users/xuedm> $InformationPreference="Continue"
PS /Users/xuedm> Get-AzFunctionApp                   
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
Microsoft.Azure.PowerShell.Cmdlets.Functions.Runtime.EventData
KirkMunro commented 4 years ago

I recently ran into this issue as well.

See the following issues and their discussions to understand the impacts of misusing Write-Information and System.Management.Automation.Cmdlet.WriteInformation:

There are several issues with the use of WriteInformation and Write-Information in this SDK that should be corrected, as follows:

  1. https://github.com/Azure/autorest.powershell/blob/a9da10f9e6bb63f2818854bbce34655f877a8d29/powershell/cmdlets/class.ts#L983

    Issue #1: This line uses System.Management.Automation.Cmdlet.WriteInformation incorrectly. The first parameter is the information that you want to capture, and the second parameter is the collection of tags that can be used to discover and/or categorize that information. This SDK is writing the message as a tag (which makes no sense whatsoever -- somebody clearly didn't read the docs when creating this logic), and a data object as the information to capture (except the message is the only important part).

    Issue #2: The Information stream should not be used to output verbose or debugging information. PowerShell has Verbose and Debug streams for that. Further, when outputting extra information from a cmdlet, it has to mean something. If you are trying to show progress, use WriteProgress -- that's what it's for. If you want to provide more information that would allow a scripter to diagnose why their invocation of a cmdlet might not be working, use the verbose stream and WriteVerbose. If you want to provide debugging information so that a cmdlet author can collect more detailed debug logs when needed, use WriteDebug.

    Recommendation: Replace the use of WriteInformation with WriteVerbose, and only output messages if they will be helpful for troubleshooting purposes. These messages must be kept to an absolute minimum. If it isn't essential for troubleshooting, don't write it into a stream. Anything that is not to help an end user but is still desired to be kept around should be written using WriteDebug.

  2. https://github.com/Azure/autorest.powershell/blob/0608ba1ca5447e9a0bd7e3d7195a96a93d713999/powershell/generators/psm1.ts#L30

    Issue: If this message is useful for troubleshooting purposes, keep it, but switch to using Write-Verbose instead. I don't believe this message is useful though.

    Recommendation: Remove the Write-Information message. If you want something for troubleshooting purposes, add an else clause that only fires if a profile does not load, and use Write-Verbose, Write-Warning, or Write-Error as appropriate in that else clause.

  3. https://github.com/Azure/autorest.powershell/blob/0608ba1ca5447e9a0bd7e3d7195a96a93d713999/powershell/generators/psm1.ts#L85

    and https://github.com/Azure/autorest.powershell/blob/0608ba1ca5447e9a0bd7e3d7195a96a93d713999/powershell/generators/psm1.ts#L139

    Issue: These messages add zero value. They aren't used for troubleshooting because they only appears at the end of the module load. They don't help a scripter (autoloading is supposed to be silent). There is zero value in outputting these messages.

    Recommendation: Remove both of them. They are entirely unnecessary, and do nothing but spam the logs.

dolauli commented 1 year ago

This issue should have been fixed.