Return behavior in PowerShell All Versions

Examples

• 2

  Early exit
  2

  function earlyexit {
      "Hello"
      return
      "World"
  }
  

  "Hello" will be placed in the output pipeline, "World" will not

  created Jul 31 '16 at 13:10

  
  discuss
• 1

  Gotcha! Return in the pipeline
  1

  get-childitem | foreach-object { if ($_.IsReadOnly) { return } } 
  

  Pipeline cmdlets (ex: ForEach-Object, Where-Object, etc) operate on closures. The return here will only move to the next item on the pipeline, not exit processing. You can use break instead of return if you want to exit processing.

  get-childitem | foreach-object { if ($_.IsReadOnly) { break } } 
  

  edited Oct 12 '16 at 17:20

  

  
  discuss
• 1

  Return with a value
  1

  (paraphrased from about_return)

  The following methods will have the same values on the pipeline

  function foo {
      $a = "Hello"
      return $a
  }
  
  function bar {
      $a = "Hello"
      $a
      return
  } 
  
  function quux {
      $a = "Hello"
      $a
  } 
  

  created Jul 31 '16 at 13:10

  
  discuss

• Improvements requested:

  • This was posted as an example, but it does not attempt to illustrate the topic. It should possibly be an edit to the topic, a separate topic, or deleted altogether. –  Ranadip Dutta Mar 11 at 17:05

    This example doesn't show anything with respect to function. It more indicates about suppressing output which is very much generic to PS. Incorporating the same in PS Function does not change the effectiveness for the same.

    1. I am not sure what is the problem? I think it is related to topic - Return behvior - without these fixes, user will face incorrect return value from the function.

       –  jumbo Mar 12 at 18:24
    2. I think this is related, it shows how return behavior works!

       –  Bert Levrau Mar 14 at 7:48
    3. This is definitely related. Add() methods in .NET are notorious for fouling up PowerShell functions, and it's precisely because of PowerShell's technique for determining function output.

       –  Mike Shepard Apr 12 at 1:10
    4. I would argue that it's not related, as it's not (to half-borrow a phrase) PowerShell-esque. Why use .NET methods in PowerShell if unrequired? Better served in these cases by something like $MyVariable += "a", which handily has no rogue output.

       –  James Ruskin May 26 at 11:15

  We are no longer accepting contributions to Documentation. Improvement requests can no longer be handled.

  0

  Gotcha! Ignoring unwanted output
  0

  Inspired by

  • PowerShell: Function doesn't have proper return value

  function bar {
   [System.Collections.ArrayList]$MyVariable = @()
   $MyVariable.Add("a") | Out-Null
   $MyVariable.Add("b") | Out-Null
   $MyVariable
  }
  

  The Out-Null is necessary because the .NET ArrayList.Add method returns the number of items in the collection after adding. If omitted, the pipeline would have contained 1, 2, "a", "b"

  There are multiple ways to omit unwanted output:

  function bar
  {
      # New-Item cmdlet returns information about newly created file/folder
      New-Item "test1.txt" | out-null
      New-Item "test2.txt" > $null
      [void](New-Item "test3.txt")
      $tmp = New-Item "test4.txt"
  }
  

  Note: to learn more about why to prefer > $null, see [topic not yet created].

  edited Sep 5 '16 at 20:12

  

  
  discuss
• 0

  How to work with functions returns
  0

  A function returns everything that is not captured by something else.
  If u use the return keyword, every statement after the return line will not be executed!

  Like this:

  Function Test-Function
  {
      Param
      (
          [switch]$ExceptionalReturn
      )
      "Start"
      if($ExceptionalReturn){Return "Damn, it didn't work!"}
      New-ItemProperty -Path "HKCU:\" -Name "test" -Value "TestValue" -Type "String"
      Return "Yes, it worked!"
  }
  

  Test-Function
  Will return:

  • Start
  • The newly created registry key (this is because there are some statements that create output that you may not be expecting)
  • Yes, it worked!

  Test-Function -ExceptionalReturn Will return:

  • Start
  • Damn, it didn't work!

  If you do it like this:

  Function Test-Function
  {
      Param
      (
          [switch]$ExceptionalReturn
      )
      . {
         "Start"
          if($ExceptionalReturn)
          {
              $Return = "Damn, it didn't work!"
              Return
          }
          New-ItemProperty -Path "HKCU:\" -Name "test" -Value "TestValue" -Type "String"
          $Return = "Yes, it worked!"
          Return 
      } | Out-Null
      Return $Return
  }
  

  Test-Function
  Will return:

  • Yes, it worked!

  Test-Function -ExceptionalReturn Will return:

  • Damn, it didn't work!

  With this trick you can control the returned output even if you are not sure what will each statement will spit out.

  It works like this

  .{<Statements>} | Out-Null
  

  the . makes the following scriptblock included in the code
  the {} marks the script block
  the | Out-Null pipes any unexpected output to Out-Null (so it is gone!)
  Because the scriptblock is included it gets the same scope as the rest of the function.
  So you can access variables who were made inside the scriptblock.

  created Dec 30 '16 at 0:49

  
  discuss