{"id":638,"date":"2022-04-01T07:06:22","date_gmt":"2022-04-01T14:06:22","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/powershell-community\/?p=638"},"modified":"2022-04-01T07:19:35","modified_gmt":"2022-04-01T14:19:35","slug":"how-to-have-more-control-of-preferences-in-functions-and-the-role-of-modules-on-inheritance","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell-community\/how-to-have-more-control-of-preferences-in-functions-and-the-role-of-modules-on-inheritance\/","title":{"rendered":"On Preferences and Scopes"},"content":{"rendered":"

Progress in PowerShell: a tale of Verbosity and other preferences with lessons in Scopes and Proxies thrown in<\/h2>\n

It started, as these things often do, with someone complaining. In PowerShell Version 7.2 the output of Invoke-WebRequest -Verbose<\/code> and Invoke-RestMethod -Verbose<\/code> look like this:<\/p>\n

VERBOSE: GET with 0-byte payload<\/code><\/pre>\n
In all the earlier versions they look like the version below, which is more helpful when you’re trying to debug code that builds URIs:<\/p>\n
VERBOSE: GET https:\/\/google.com\/ with 0-byte payload<\/code><\/pre>\n
A proxy function<\/em> will fix that. If two commands have the same name an alias beats a function, which beats a cmdlet, which beats an external program. You can specify the full path to an external program or cmdlet – for example Microsoft.PowerShell.UtilityInvoke-RestMethod<\/code> so an Invoke-RestMethod<\/code> function<\/em> can act as a proxy<\/em> for the cmdlet, anything which calls Invoke-RestMethod<\/code> will go to the function, which calls the cmdlet with its fully qualified name. PowerShell even has a mechanism to create the function’s code:<\/p>\n
$cmd      = Get-Command Invoke-RestMethod\n$MetaData = New-Object System.Management.Automation.CommandMetaData $cmd\n[System.Management.Automation.ProxyCommand]::create($MetaData) | clip<\/code><\/pre>\n
(I don’t carry those 3 lines in my head, when I need them I refer to a script Jeffrey Snover wrote long ago, a newer version is on the PowerShell Gallery<\/a>.)
\nI added extra Write-Verbose<\/code> calls and tidied up the autogenerated code and posted the result as a gist<\/a>.
\nA module I’m working has lots of calls to Invoke-RestMethod<\/code> but the proxy function wouldn’t see that I’d specified -Verbose<\/code>. So I needed to investigate.<\/p>\n
The -Verbose<\/code> switch sets the value of $VerbosePreference<\/code> in the function being called; if you thought setting the global $VerbosePreference<\/code> to continue<\/code> was the same as a running everything with -Verbose<\/code>, trying the following might surprise you:<\/p>\n
$VerbosePreference=\"Continue\"\nInvoke-WebRequest \"https:\/\/google.com\" -OutFile delete.me\nCopy-Item delete.me delete.too<\/code><\/pre>\n
Invoke-WebRequest<\/code> heeds the preference, but Copy-Item<\/code> only prints a message if the -Verbose<\/code> switch<\/em> is specified.<\/p>\n
My proxy function would print a verbose message if run with -Verbose<\/code>, it would<\/em> heed the global preference-variable but not the switch passed to the function that called it. The -Confirm<\/code>, -Debug<\/code>, -ErrorAction<\/code>, -InformationAction<\/code>, -Verbose<\/code>, -WarningAction<\/code>, and -WhatIf<\/code> switches all<\/em> set the corresponding preference-variable inside a function but that wasn’t being inherited when the functions in my module called the proxy function.
\nI could reproduce this with the two functions below. First, I loaded them from a single .PSM1<\/code> file (and things were the same if I pasted them in at a PowerShell prompt)<\/p>\n
function one {\n  [cmdletBinding()]\n  param()\n  Write-Verbose \"One calls two\"\n  two\n  Write-Verbose \"Two returned\"\n}\n\nfunction two {\n  [cmdletBinding()]\n  param()\n  Write-Verbose \"Two has a message\"\n}<\/code><\/pre>\n
If I load this, I get three messages:<\/p>\n
VERBOSE: One calls two\nVERBOSE: Two has a message\nVERBOSE: Two returned<\/code><\/pre>\n
Things change if One<\/code> is in its own module<\/p>\n
\"Screen<\/p>\n
One -verbose<\/code> now just produces two messages:<\/p>\n
VERBOSE: One calls two\nVERBOSE: two returned<\/code><\/pre>\n
Setting the global preference-variable at the prompt returns all 3 – because function two<\/code> sees it.
\nIt is common to assume that a function inherits the variables from whatever called it<\/em>; we can see that working with simpler functions<\/p>\n
function three {\n    $e=\"ewe\"\n    four\n}\n\nfunction four {\n    $e\n} <\/code><\/pre>\n
If I set $e<\/code> and run three<\/code> from the prompt<\/p>\n
> $e = \"eye\"  \n> three\newe<\/code><\/pre>\n
the assumption holds; and a lot of documentation stops there, but if I import three<\/code> from a module<\/p>\n
> three\neye<\/code><\/pre>\n
The inheritance assumption is qualified by a rule that says what happens in a module stays in the module<\/em>.
\nThe question is what can we do about it?<\/em><\/p>\n
Before it dawned on me that this was a scopes<\/em> thing and not just -Verbose<\/code>, a search brought me a clue<\/a>; the solution is to change function two<\/code> (or my proxy function) as follows:<\/p>\n
function two {\n  [cmdletBinding()]\n  param($VerbosePreference = $PSCmdlet.GetVariableValue('VerbosePreference')\n  Write-Verbose \"Two has a message\"\n}<\/code><\/pre>\n
We can only use $PSCmdlet<\/code> if we have either [cmdletBinding()]<\/code> or a [parameter()]<\/code> decoration – just a side note on that, if you paste in<\/p>\n
function five { param ($p) }\nfunction six  { param ([parameter()]$p) }<\/code><\/pre>\n
when you try to tab-complete parameters for five<\/code> and six<\/code>, you\u2019ll see six<\/code> gets all the common parameters but five<\/code> does not – [parameter()]<\/code> is an implicit [cmdletBinding()]<\/code>, although it’s still good to write the latter explicitly.<\/p>\n
$PSCmdlet<\/code> is available when the function is setting up its variables<\/em>. Inside the function we’d never replace $x<\/code> with the long-winded $PSCmdlet.GetVariableValue(\"x\")<\/code>, but in a parameter<\/em> it is \u201cuse the value from the scope that called you – even if that scope is<\/em> a module\u201d.<\/p>\n
Now<\/em> the called function inherits the preference from its caller. If we specify -Verbose<\/code> it takes precedence, so nothing breaks copying in $VerbosePreference<\/code>. The same thing applies to -Confirm<\/code> and -WhatIf<\/code>.<\/p>\n
function seven {\n  [cmdletBinding(SupportsShouldProcess=$true)]\n  param()\n  eight\n  Write-Host \"Something Safe \"\n}\n\nfunction eight {\n  [cmdletBinding(SupportsShouldProcess=$true)]\n  param()\n  if ($PSCmdlet.ShouldProcess(\"This\",\"Do you want to do\")) {\n    Write-Host \"Something dangerous\"\n  }\n}<\/code><\/pre>\n
If seven<\/code> and eight<\/code> are loaded from the same psm1 file<\/p>\n
seven -Confirm\n\nConfirm\nAre you sure you want to perform this action?\nPerforming the operation \"Do you want to do\" on target \"This\".\n[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is\"Y\"): n\n\nSomething Safe<\/code><\/pre>\n
But, if seven<\/code> loads from its own module \u2026<\/p>\n
seven -Confirm\nSomething dangerous\nSomething Safe<\/code><\/pre>\n
Modifying the parameters in eight<\/code> with the code below restores the confirmation<\/p>\n
param($ConfirmPreference = $PSCmdlet.GetVariableValue('ConfirmPreference'))<\/code><\/pre>\n
-confirm<\/code> sets $confirmPreference<\/code> to low<\/code> which triggers $PSCmdlet.ShouldProcess<\/code> to prompt the user. I treat -Force<\/code> as an extra preference and my functions typically have
\nif ($Force -or $PSCmdlet.ShouldProcess(...<\/code>
\nto ensure the a command can be run non-interactively, even if its impact is set higher than $ConfirmPreference<\/code>.<\/p>\n
The example above might lead you to think -Confirm<\/code> and -WhatIf<\/code> should<\/em> be inherited, but this would cause a problem with scopes at the script<\/code> level (which apply module-wide). Suppose the module that contained seven read like this:<\/p>\n
$ConfirmPreference = 'None'\n\nfunction seven {\n...\n}<\/code><\/pre>\n
Any cmdlet that would normally ask for confirmation inside seven<\/code> will run silently. But what if the module containing eight<\/code> sets that option to something different? If a function overrides something from its own script-scope, then only things which share that scope see the change, which seems logical. Thinking of functions’ scopes as children<\/em> of their module’s scope which in turn is usually a child of the global scope means we can say things pass down their branch of the scope \u201ctree\u201d but don’t jump between<\/em> branches.<\/p>\n
Before leaving $ConfirmPreference<\/code>, I have been think about changing it inside a function, so it drops to low<\/code> if many items are being updated. I\u2019m not sure that’s a great idea because coming to rely<\/em> on a prompt and which isn’t there reliably<\/em>, will lead to trouble.<\/p>\n
The title said this is about Progress<\/em>. PowerShell 7.2 has an optional new way of displaying the progress bar, but the things it relies on are a bit flaky in the Integrated-Shell in Visual Studio Code (things improve if you use Write-Progress -completed<\/code>) and Invoke-WebRequest<\/code> downloading 100 log files becomes a mess. There is no -Progress<\/code> common parameter, but the day before I started on the -Verbose<\/code> problem, I had found that adding $ProgressPreference<\/code> as a parameter worked, so it makes sense to do it the same way. I inserted the following parameter into the function that calls Invoke-WebRequest<\/code>. Unlike the examples above, which might be tagged with [Parameter(DontShow)]<\/code> I want this to tab-complete the possible values, so it is marked with the ActionPreference<\/code> type:<\/p>\n
[ActionPreference]$ProgressPreference = $PSCmdlet.GetVariableValue('ProgressPreference')<\/code><\/pre>\n
And I will also want that<\/em> to inherit into my proxy function.
\nWith that in place, I can use the code below to call my function and replace the byte-by-byte progress indicator that Invoke-WebRequest<\/code> displays with my own file-by-file one:<\/p>\n
$count = 0\nForEach ($f in $file) {\n  Write-Progress \"Downloading\" -PercentComplete ($count\/$file.Count)\n  Myfunction $f -ProgressPreference SilentlyContinue\n  $count += 100\n}\nWrite-Progress \"Downloading\" -Completed<\/code><\/pre>\n
Quick tip: adding 100 to the counter each time (instead of adding 1) removes the need to multiply by 100 for a percentage.<\/p>\n
Since I mentioned ErrorAction<\/code> above, before finishing I wanted to share one last tip about preferences:<\/p>\n
function nine {\n  [cmdletBinding()]\n  param ($Name)\n  if (-not $Name) {throw \"Name is required\"}\n  Write-Host \"Deleting $Name*\"\n}<\/code><\/pre>\n
The \u201cdangerous\u201d line in the example above never runs if $n<\/code> is empty, right? Wrong, actually.<\/p>\n
\"Screen<\/p>\n
Specifying -ErrorAction<\/code> prevents the throw<\/code> statement throwing so<\/p>\n
nine \"\" -ErrorAction SilentlyContinue<\/code> would mean the dangerous code is<\/em> run.<\/p>\n
When it is acting as a \u201cfence\u201d around dangerous code, it is worth putting a return<\/code> after throw<\/code>.<\/p>\n","protected":false},"excerpt":{"rendered":"
Progress in PowerShell: a tale of Verbosity and other preferences with lessons in Scopes and Proxies thrown in It started, as these things often do, with someone complaining. In PowerShell Version 7.2 the output of Invoke-WebRequest -Verbose and Invoke-RestMethod -Verbose look like this: VERBOSE: GET with 0-byte payload In all the earlier versions they look […]<\/p>\n","protected":false},"author":6479,"featured_media":77,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[13],"tags":[66,3,63,65,64],"class_list":["post-638","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell","tag-erroraction","tag-powershell","tag-preference-variables","tag-progress","tag-verbose"],"acf":[],"blog_post_summary":"
Progress in PowerShell: a tale of Verbosity and other preferences with lessons in Scopes and Proxies thrown in It started, as these things often do, with someone complaining. In PowerShell Version 7.2 the output of Invoke-WebRequest -Verbose and Invoke-RestMethod -Verbose look like this: VERBOSE: GET with 0-byte payload In all the earlier versions they look […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/posts\/638","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/users\/6479"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/comments?post=638"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/posts\/638\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/media\/77"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/media?parent=638"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/categories?post=638"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/tags?post=638"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}