How should the PowerShell worker implement $returns (if at all)?

[TylerLeonhardt]

Background

In Azure Functions, there is a concept of "output bindings" which are essentially the output of your function. You define these outputs in the bindings section of the function.json. Here's an example function.json for an HttpTrigger and response:

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    }
  ]
}

notice the binding Response has a direction of out.

There exists a "special" output binding called $returns which would look like this:

    {
      "type": "http",
      "direction": "out",
      "name": "$returns"
    }

This, in every language that Azure Functions supports in V2, gives the user the ability to "return" the result. Rather than explicitly specifying that value X goes to the output binding of "Foo".

For example, in C# you would normally declare outputs using the out keyword in the function definition:

function.json

    {
      "type": "http",
      "direction": "out",
      "name": "output"
    }

run.cs

public static Run(string input, out string output)
{
    output = "Hello World";
}

But if you want to leverage $returns you would do:

function.json

    {
      "type": "http",
      "direction": "out",
      "name": "$returns"
    }

run.cs

public static Run(string input)
{
    return "Hello World";
}

Note the use of the return keyword.

The problem

PowerShell is different than most languages because it can return multiple things by leveraging the Pipeline.

In addition to that, a lot of folks write to the pipeline as a way to log something.

So implementing $returns for PowerShell is strange because it's not clear what the intended behavior should be.

The possible solutions

Solution 1: Take everything

Everything that gets thrown onto the pipeline, will be added to a list. That list will be set as the output for the output binding $returns. In addition to that, everything added to the pipeline can be logged to the host.

This idea comes from the fact that since PowerShell can "return" multiple things, a list of the things written to the pipeline would be the most "PowerShell-y" experience for $returns.

This does mean that the user would need to log using Write-Host or others instead of simply writing to the pipeline otherwise their log statements will be included in the $returns output.

Solution 2: Take one thing

Everything that gets thrown onto the pipeline will be logged, but the LAST item added to the pipeline will be the output for the output binding $returns.

This idea comes from wanting to align with other languages. It also gives the user the ability to use the pipeline for logging and "returning".

FWIW, AWS Lambda went with this approach - so I've heard.

Solution 3: Take nothing

This would mean that $returns doesn't make sense for PowerShell and the only way to specify output is by using the Push-OutputBinding command.

That said, everything added to the pipeline can be logged to the host.

[essentialexch]

Every single time I've used "write-output" for logging, I've ending up regretting it.

Just say no.

However, returning tuples from functions is useful, extremely useful. I would be very disappointed to see that capability gone from any implementation (I've taken to commonly using something I first saw in golang: $ret, $err = function-call).

So I vote for Solution 1.

[dfinke]

First blush, I like option 2.

[TylerLeonhardt]

Care to elaborate, @dfinke? 😊

[dfinke]

I like the notion that all the output in the function gets logged, and I'm guessing to the trace console, and no extra work on my part I can expect the last line to be returned to the caller.

I'm guessing a majority of functions can leverage that. Most of the http triggers I've built, I emit info to the pipeline for logging/tracing and then then the last statement I have is $result > $res.

For that pattern, my code wouldn't really change.

I'd like to play with it a bit, get a better feel.

[KirkMunro]

Would leveraging PowerShell classes be out of the question? Explicit return, and attributes to control bindings of functions to methods. Plus in C# functions I have an explicit way to log information I want logged, and would like the same in PowerShell. Lazier approaches (return everything), and return the last thing don't feel right to me.

[TylerLeonhardt]

Just to add some context:

In C# functions I have an explicit way to log information I want logged, and would like the same in PowerShell

We are planning on just leveraging PowerShell logging that already exists. All of the Write-* cmdlets will work out of the box and log to the respective log levels in Functions.

[rjmholt]

Not advocating these, but other possibilities might be a special variable:

$return = $outputForReturnVariable

Or even a cmdlet similar to the ones for output bindings:

Push-$Return $outputForReturnVariable

(That dollar in the function name would probably break things, but I thought it was a cute idea).

Neither of these strike me as great, but they might avoid some of the pipeline collection flattening problems...

[Jaykul]

@rjmholt oddly enough, Push-$Return is a perfectly legal function name:

${function:Push-$Return} = { $global:return = $args | % { $_ } }

Having said that, magic variables and extra functions *are not the answer. That's the problem we had before: dealing with weird/odd ways of getting values in and out (by reading and writing files) put me off using PowerShell in Azure functions completely (frankly, put me off Azure functions completely as something that was obviously and unashamedly sloppy and unfinished).

Personally I think Kirk's answer is the best: let azure functions have the exact same semantics of a method in a PowerShell class: Write-Output is not allowed (and not implied) and return is required, and only valid once, because then you're done.

As a bonus this means that you have an easy way of building a framework outside Azure functions that lets your tools help you write the right thing (i.e. just write a wrapper for your code in a class, and specify the return type you need to return, etc).

[essentialexch]

And what can return return? I'm strongly opposed to not being able to return a tuple.

[SteveL-MSFT]

In our team discussion, the logical PowerShell way of aligning with AzFunctions semantics for $returns is either only support it via classes which has a 1:1 mapping or return everything that is sent to the pipeline. Accepting everything sent to the pipeline has its own issues in terms of both usability and some technical challenges for serializing. However, we already have the need for a custom cmdlet to send output to any arbitrary output binding since you can have multiple output bindings in an AzFunction. So you would do something like: Push-OutputBinding -Name Request -Value .... We could re-use this for $return and it would look something like Push-OutputBinding -Name '$returns' -Value ... which is not great as $returns needs to be escaped. I think specifically to support $returns semantics, it makes the most sense to use a PowerShell class so that there aren't any surprises to the user.

For me, I think support of $returns overall is a lower priority pending customer feedback that it is something people want rather than just using Push-OutputBinding all the time.

[TimCurwick]

It should be easy to move code from one platform to another. It should be easy to move scripters from one platform to another.
Wherever possible, code should behave the same way wherever it runs. Moving a working script to Functions should largely be a matter of copy/paste.
So Solution 1.

[rjmholt]

@Jaykul, don’t worry I also think pipeline output is the way to go. It means that PowerShell concepts will support users everywhere, rather than having to relearn things. (And yes I thought that might be a legal function name, but it did break syntax highlighting already, and it would probably break a bunch of tooling).

While there is a risk of having to serialise a large number of pipeline objects, (1) serialisation to JSON is not the bottleneck in much of my PowerShell code, and (2) PowerShell users already have a best practice of not polluting the pipeline.

My only concern is that it’s sometimes a pain trying to prevent things from being written to the pipeline. Like why @BrucePayette advises not to use an ArrayList — because Add() returns ints.

[Jaykul]

@rjmholt which is why I suggested class semantics because in classes there's already no leaking output.

@SteveL-MSFT can OutputBindings be handled as simply as setting a $global:outputname variable, or is it actually something where you need to be able to call Push over and over for the same name?