Feature planning: first class PowerShell support

This is a tracking item for First Class PowerShell support. We’ll be tracking the requirements and issues for first class PowerShell support via this item. Feel free to leave comments about features/design patterns.

Function format

For the Azure Function PowerShell format, we’ll keep the existing “scripting” model and limit the run file to the .ps1 format. A future feature will address .psm1 support with a proper “function” model.

This means we use the existing pattern of communicating data via files & environment variables. It also means that we don’t “cache” the environment that we run the script from. This will mean an inherent performance overhead, but this is likely acceptable for the scenarios where PowerShell scripting will be used. For more advanced scenarios, we’ll need to address those issues with psm1 support.

The scripting format, as is looks as so:

$in = Get-Content $Env:input

[Console]::WriteLine("Powershell script processed queue message '$in'")

$output = $Env:output
$json = $in | ConvertFrom-Json
$entity = [string]::Format('{{ "timestamp": "{0}", "status": 0, "title": "Powershell Table Entity for message {1}" }}', $(get-date -f MM-dd-yyyy_HH_mm_ss), $json.id)
$entity | Out-File -Encoding Ascii $output

Breaking this down, data coming in (via triggers and input bindings) is passed along via files which are communicated via environment variables, the names of which derive from the name property of the corresponding binding in the function.json. Data out works the same way. Any data being sent to output bindings is output to a local file specified via the environment variable corresponding to the name parameter in the function.json for the corresponding output bindings.

Data Type formats

All data is transferred via files. This means that it’s up to the user to parse the file to the right format.

Assuming the user knows which format the data in the file is in, all formats should be supportable.

• String
  • File contents as is, assuming UTF-8 encoding
  • input example: [string]$str = Get-Contents $Env:input
  • output example: $str > $Env:output
• Int
  • File contents, assuming file only contains a number
  • input example: [int]$int = Get-Contents $Env:input
  • output example: $int > $Env:output
• Bool
  • File contents, assuming file only contains 0 or 1
  • input example: [bool]$bool = [int](Get-Contents $Env:input)
  • output example: $bool > $Env:output
• Object/JSON
  • File contents, assuming its valid JSON
  • input exampe: $json = Get-Content $Env:input | ConvertFrom-Json
  • output example: $json | ConvertTo-Json > output.txt
• Binary/Buffer
  • File contents
  • input example: [byte[]] $byte = Get-Content .$Env:input -Encoding Byte
  • output example $byte | Set-Content $Env:output -Encoding Byte
• Stream (via file stream)
  • File contents
  • input example: $reader = [System.IO.File]::OpenText($Env:input)
  • output example $writer = [System.IO.StreamWriter] $Env:output
• HTTP
  • TBD

Version & Package management

TBD

Testing/CI

TBD

Change log

• 5/5 - Initial plan

[Jaykul]

I was thinking more about azure doing the C# part, and letting people write PowerShell functions that would, to quote you:

mimic as close as possible the command-line and scripting workflows on the PowerShell.exe console.

As a general rule, when people are writing functions for the PowerShell console, it would be an anti-pattern to use file IO for parameters or output. Instead, functions should take parameters and output objects.

In my ideal world, your sample PowerShell template function would look more like this:

param($request)
Write-Verbose "PowerShell HTTP trigger function processed a request. RequestUri=$($req.RequestUri)"
<# ... do stuff #>
$name = $request.GetQueryNameValuePairs().Where({$_.Key -eq "Name" }).Value

return $req.CreateResponse("OK". "Hello $name");

But obviously that requires some code a little like what you wrote in your C# example – I don’t think people should have to write that themselves nor settle for having to serialize and deserialize through JSon on disk …

[tohling]

@Jaykul, thank you for the clarification. I understand now that your expectation was that the user experience would be more akin to a PowerShell function. The term “PowerShell function” has a plural context at this point. We will keep this in mind and update our documentation to make the distinction clearer.

Unfortunately, the ideal workflow you suggested is not a supported scenario at this ‘Experimental’ stage. We appreciate this feedback and will add it as a consideration for our future planning.