Improving a syntax for the Outputs section

[alexandair]

ATM, we define the output values as:

Output 'hostname' -Type 'string' -Value (reference $publicIPName).dnsSettings.fqdn
Output 'deploymentTime' -Type string -Value $deploymentTime

My suggestion is to use a syntax similar to the hash table, (e.g. $PSDefaultParameterValues):

Output @{
    string:hostname = (reference $publicIPName).dnsSettings.fqdn
    string:deploymentTime = $deploymentTime
}

[kilasuit]

I feel that would fail when you output objects (which I do a lot)

Also the string:hostname syntax isn't very PowerShell like, which will make it harder for those used to PowerShell to get on board with this an

I think output definitions could allow for simple syntax like this

Output 'hostname' [string](reference $publicIPName).dnsSettings.fqdn
Output 'deploymentTime' [string]$deploymentTime
Output 'vnet' [object](reference $vnet)
Output 'nsgrules' [array]$nsgrules

using your hashtable like method I'd see that being like this
Output @{
hostname = [String](reference $publicIPName).dnsSettings.fqdn
deploymentTime = [String]$deploymentTime
}
reason being that's cleaner to understand

but for more complex output building I can see benefit in having dedicated object types that you can build like below

#Output as object with 2 properties
$ARMOutput1 = [ARMOutput]::new('Out1', @{
    hostname       = [string](reference $publicIPName).dnsSettings.fqdn
    deploymentTime = [string]$deploymentTime
}, [object])
#Output as String full type provided
$ARMOutput2 = [ARMOutput]::new('Hostname', [string](reference $publicIPName).dnsSettings.fqdn, [string])

#Output as String inferred from the value type
$ARMOutput3 = [ARMOutput]::new('deploymentTime', [string]$deploymentTime)

#Output as Array from the provided type
$ARMOutput4 = [ARMOutput]::new('nsgrules', [array]$nsgrules, [array])

#Output as Array inferred from the value's type
$ARMOutput5 = [ARMOutput]::new('nsgrules', [array]$nsgrules)

#Output as Array inferred from the value type
$ARMOutput6 = [ARMOutput]::new('deploymentTime', [string]$deploymentTime)


# Output of complex json object with sub objects, arrays and providing 
$ARMOutput7 = [ARMOutput]::new('Out2', @{
vnet     = [object](reference $vnet)
rg       = [string]$rg.resourceID
nsgrules = [array]$nsgules 
object   = [Object] $object 
}, [object])

which you could then build either like this

$outs = [ARMOutputArray]@($ARMOutput1, $ARMOutput2, $ARMOutput3, $ARMOutput4,$ARMOutput3, $ARMOutput4, $ARMOutput5, $ARMOutput6, $ARMOutput7)
Output $outs

or like this

Output @($ARMOutput1, $ARMOutput2, $ARMOutput3, $ARMOutput4,$ARMOutput3, $ARMOutput4, $ARMOutput5, $ARMOutput6, $ARMOutput7)

And before anyone says that's too much code - this was demonstrated as being the most defensive by forcing types on values on purpose, I expect many to use the simpler syntaxes but we also need to be mindful of the more complex usecases too.

[rjmholt]

Output 'hostname' [string](reference $publicIPName).dnsSettings.fqdn

This probably won't work as you expect; at runtime the [string] is (1) just going to cast the value to a string and (2) not going to parse in expression mode anyway. [object] won't do anything at all, since casting to an object in PowerShell is essentially meaningless.

If we want something that properly and reliably maintains the ARM type decoration, it needs to have a syntax that will preserve that information at runtime. In discussing a number of PSArm syntaxes, I've seen a lot of suggestions for syntaxes that don't actually work for PowerShell and would require special parsing. I want to avoid that pretty much everywhere because PSArm needs to be PowerShell rather than a language that looks like PowerShell but with different semantics. It currently succeeds pretty much everywhere with that, which means we can rely on PowerShell behaviour for everything, so that you can do strange and unexpected things with arbitrary PowerShell and we can reason about it easily. If you invent custom syntax and parsing, you lose that (and things get much much harder to maintain).

One way we could make the above work is with a generic type cast similar to the ArmParameter type:

Output 'hostname' ([ArmOutput[string]](reference $publicIPName).dnsSettings.fqdn)

But I'm not convinced that's more convenient or readable than what already exists

[rjmholt]

In fact, playing with the simple cast syntax we see some pretty weird behaviour (possibly a bug) from PowerShell:

PS> function Output { param($X) wait-debugger }

PS> output [string](@{ a = 1 }).a
Entering debug mode. Use h or ? for help.

At line:1 char:29
+ function Output { param($X) wait-debugger }
+  
                           ~~~~~~~~~~~~~
[DBG] PS> $X
[string]

[DBG] PS> $X.GetType()

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     String                                   System.Object

Certainly we don't get what we'd need to make the syntax above work

[rjmholt]

Output @{
   string:hostname = (reference $publicIPName).dnsSettings.fqdn
   string:deploymentTime = $deploymentTime
}

I like the parsimony of the keyword here. My only reservation is the way the colon in the key is a magical string format; there's no real reification of the output type in the object itself.

The only way to do that though is to make each entry a self-describing object (how all of PSArm works -- self-describing objects):

Outputs @{
    hostname = Output string (reference ...)
}

But at that point you may as well be back to:

Output hostname -Type string (reference ...)

[rjmholt]

One thing I've noticed that users so far have pushed back on is the idea of using functions to emit entries vs something like a hashtable, and that makes sense.

The two advantages of the function/keyword approach are:

• Full control of the objects at each level
• Loops are possible for dynamic additions -- not as nice to dynamically add hashtable keys