Build-PSArmTemplate Alias for Publish-PSArmTemplate

[JustinGrote]

Publish to most powershell people means "do a deployment" e.g. Publish-Module. If the command isn't renamed directly, it should at least be aliased to Build-PSArmTemplate to be more instinctive and follow the typical lexicon:

❯ get-verb build,publish | fl

Verb        : Publish
AliasPrefix : pb
Group       : Data
Description : Makes a resource available to others

Verb        : Build
AliasPrefix : bd
Group       : Lifecycle
Description : Creates an artifact (usually a binary or document) out of some set of input files (usually source code
              or declarative documents)

[rjmholt]

In Windows PowerShell 5.1, I think these are our options:

> get-verb |sort -Property Verb

Verb        Group
----        -----
Add         Common
Approve     Lifecycle
Assert      Lifecycle
Backup      Data
Block       Security
Checkpoint  Data
Clear       Common
Close       Common
Compare     Data
Complete    Lifecycle
Compress    Data
Confirm     Lifecycle
Connect     Communications
Convert     Data
ConvertFrom Data
ConvertTo   Data
Copy        Common
Debug       Diagnostic
Deny        Lifecycle
Disable     Lifecycle
Disconnect  Communications
Dismount    Data
Edit        Data
Enable      Lifecycle
Enter       Common
Exit        Common
Expand      Data
Export      Data
Find        Common
Format      Common
Get         Common
Grant       Security
Group       Data
Hide        Common
Import      Data
Initialize  Data
Install     Lifecycle
Invoke      Lifecycle
Join        Common
Limit       Data
Lock        Common
Measure     Diagnostic
Merge       Data
Mount       Data
Move        Common
New         Common
Open        Common
Optimize    Common
Out         Data
Ping        Diagnostic
Pop         Common
Protect     Security
Publish     Data
Push        Common
Read        Communications
Receive     Communications
Redo        Common
Register    Lifecycle
Remove      Common
Rename      Common
Repair      Diagnostic
Request     Lifecycle
Reset       Common
Resize      Common
Resolve     Diagnostic
Restart     Lifecycle
Restore     Data
Resume      Lifecycle
Revoke      Security
Save        Data
Search      Common
Select      Common
Send        Communications
Set         Common
Show        Common
Skip        Common
Split       Common
Start       Lifecycle
Step        Common
Stop        Lifecycle
Submit      Lifecycle
Suspend     Lifecycle
Switch      Common
Sync        Data
Test        Diagnostic
Trace       Diagnostic
Unblock     Security
Undo        Common
Uninstall   Lifecycle
Unlock      Common
Unprotect   Security
Unpublish   Data
Unregister  Lifecycle
Update      Data
Use         Other
Wait        Lifecycle
Watch       Common
Write       Communications

[rjmholt]

I'd say my top candidates in order are:

• Build
• Export
• Invoke
• New
• Write
• Out

[JustinGrote]

I think I would opt for New over Publish, or even Invoke-BuildPSArmTemplate if you want to get really silly.

I'm mostly thinking of existing conventions that people are used to for these verbs (that's why they exist after all)

• Export makes kind of sense sense but normally when you're dealing with an object residing in PS memory and not pointing it at a script. e.g. export-csv, export-excel
• Out and Write are the same way, you don't normally point these to a Path without piping something to them.
• Invoke has become kind of a catch-all when there's not a more suitable verb.

My vote is new for 5.1 compatibilty, with Build available as an alias for 7:

New-PSArmTemplate -Path Myscript.arm.ps1 -OutFile MyOutputFolder

It lines up nicely with New-AzDeployment as well

[rjmholt]

Invoke is more transparent about the fact that we're actually running something user-provided under the hood

[rjmholt]

Anyway, I'll let this discussion play out without me now that I've added my 2 cents — I know how verb discussions go.

[kilasuit]

ConvertTo & ConvertFrom would be my choices though that said we don't usually output a file from those commands

[JustinGrote]

@kilasuit I agree, a lot of these are tricky because some "de-facto" conventions have evolved that the action being done here doesn't quite fit into the column. For instance the Convert verbs are almost exclusively used by piping and output an object.

[rjmholt]

Just found out that Build actually isn't valid in PS 7.0 unfortunately (VerbsLifecycle.Build doesn't compile against the 7.0 SDK) — it seemed like the most appropriate choice to me, but not sure if this rules it out entirely

[iSazonov]

Just found out that Build actually isn't valid in PS 7.0 unfortunately (VerbsLifecycle.Build doesn't compile against the 7.0 SDK) — it seemed like the most appropriate choice to me, but not sure if this rules it out entirely

I an very wonder, it presents in 7.*. Bug in SDK?

[bjompen]

While I agree Build would be best yet undoable if ps5 compatibility is the case, I would also argue that according to the descriptions "export" would be most fitting.

Encapsulates the primary input into a persistent data store, such as a file, or into an interchange format sounds to me, non native, like it fits pretty well.

[JustinGrote]

Export is my leading 5.1-compatible verb vote, since it is typically used with a path in other situations. The Build alias could be conditional on a 7.1 version check.

[rdbartram]

Convert, Export, merge or new.

the publish keyword really isn’t right in my opinion.

invoke could be an option but the noun afterwards would have to change to invoke-psarmtemplateconversion or invoke-psarm templatebuild. Saying invoke-psarmtemplate would imply to me we are actually running/deploying the template. if you were just to say that to me, that’s what I would think.

convert-psarmtojson or something like that would be my preference and is most clear to someone not knowing the semantics of what is going on

[rdbartram]

I guess the end goal is to avoid this all together right and have the new-azresourcegroupdeployment command accept psarm.ps1 files natively

[JustinGrote]

@rdbartram that would be ideal of course once it gets to a rc status I was planning to raise an issue or PR. There's precedent for it since they now accept Bicep files (even if all they do is just run bicep and then submit the json).