IT:AD:PowerShell:HowTo:Gotchas/Function Returns [Notes]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
# IT:AD:PowerShell:HowTo:Gotchas/Function Returns #



* [[./|(UP)]]
{{indexmenu>.#2|nsort tsort}}



<panel title="Summary">

Not understanding Function returns is definitely going to cause you unnecessary pain.


</panel>


## Prefer Void Returns ##

<wrap tip>
 Prefer void returns, unless the function's point is to return a variable.
</wrap>

Powershell is a pipe mechanism where any unused variable created in one module is put made available to the next Module. This can drive you nuts.

<sxh powershell>
function Foo1(){
  return "Foo";
}
# Invoke it, and you get back "Foo", as one would expect from any language:
c:>Foo1
Foo
</sxh>

Let's chain two processors together, and try again:

<sxh powershell>
function Bar2(){
  return "Bar";
}
function Foo2(){
  $x = Bar2;
  return "Foo";
}
# Invoke it, and you get back "Foo", as one would expect from any language:
c:>Foo2
Foo
</sxh>  

This time, let's be totally flummoxed:
<sxh powershell>
function Bar3(){
  return "Bar";
}
function Foo3(){
  Bar3;
  return "Foo";
}
# Invoke it, and you get back "Foo", as one would expect from any language:
c:>Foo3
Foo
Bar
# say what?!? Two outputs?!?!!
</sxh>

That combined with the second fact that if the return value of an invoked method only has one item (eg: as string) the return value will be a single value, but if it finds more than one, the string will be wrapped in an array...and you quickly go nuts:

<sxh>
Write-Host Foo2
Write-Host Foo3
#shit, that's not right...maybe it's the second item I want
Write-Host Foo3[1]
# but that stinks...and is going to sooner or later trip up.
</sxh>

The reason is that Powershell is trying to be helpful (like a kick in the head!) and is packing the output with everything that was created, that you may need, further down the pipeline.

I'm sure it could be very useful. Except I haven't found a use for it.

Instead, just ensure that if your function is either an Action or a Function, and vigorously don't return a value if it is not going to be used. In other words:

<sxh>
  void Ensure-Directory($path){
     ...check the directory...and make it if not...
     
     #Do NOT do this. 
     #a) the value is already known by the invoker
     #b) as invoker already has it, it's not guaranteed
     #   it will use it. And if the response is not used
     #   (ie, put into a variable) 
     #   it will pack the pipeline uneccessariy, and turn
     #   the response of the invoker into an array...
     #NO!!!! return $path
  }
  void Get-DirectoryPAth($args){
     $result = ....calc something the invoker doesn't know...
     
     # on the other hand this will always be used
     # so go right ahead
     return $result;
  }
</sxh>

## Resources ##