Azure-cli: az group deployment create --parameters documentation does not work in powershell shell

[jsturtevant]

If you follow the example from the documentation from the help output for az group deployment create -h in a powershell prompt you end with an error message splatting operator '@' cannot be used to reference variables in an expression

With example command:

az group deployment create --name acsenginedeploy -g sample-group --template-file azuredeploy.json --parameters @azuredeploy.parameters.json

you get the error message:

At line:1 char:114
+ ... in --template-file azuredeploy.json --parameters @azuredeploy.paramet ...
+                                                      ~~~~~~~~~~~~
The splatting operator '@' cannot be used to reference variables in an expression. '@azuredeploy' can be used only as an argument to a command. To reference variables in an expression use '$azuredeploy'.
    + CategoryInfo          : ParserError: (:) [], ParentContainsErrorRecordException
    + FullyQualifiedErrorId : SplattingNotPermitted

The help shows from az group deployment create -h shows to use the @ syntax which fails in powershell prompt

Command
    az group deployment create: Start a deployment.

Arguments
    --resource-group -g [Required]: Name of resource group. You can configure the default group
                                    using `az configure --defaults group=<name>`.
    --mode                        : Incremental (only add resources to resource group) or Complete
                                    (remove extra resources from resource group).  Allowed values:
                                    Complete, Incremental.  Default: Incremental.
    --name -n                     : The deployment name. Default to template file base name.
    --no-wait                     : Do not wait for the long-running operation to finish.
    --parameters                  : Supply deployment parameter values.
        Parameters may be supplied from a file using the `@{path}` syntax, a JSON string, or as
        <KEY=VALUE> pairs. Parameters are evaluated in order, so when a value is assigned twice, the
        latter value will be used. It is recommended that you supply your parameters file first, and
        then override selectively using KEY=VALUE syntax.
    --template-file               : A template file path in the file system.
    --template-uri                : A uri to a remote template file.

Global Arguments
    --debug                       : Increase logging verbosity to show all debug logs.
    --help -h                     : Show this help message and exit.
    --output -o                   : Output format.  Allowed values: json, jsonc, table, tsv.
                                    Default: json.
    --query                       : JMESPath query string. See http://jmespath.org/ for more
                                    information and examples.
    --verbose                     : Increase logging verbosity. Use --debug for full debug logs.

Examples
    Create a deployment from a remote template file, using parameters from a local JSON file.
        az group deployment create -g MyResourceGroup --template-uri
        https://myresource/azuredeploy.json --parameters @myparameters.json


    Create a deployment from a local template file, using parameters from a JSON string.
        az group deployment create -g MyResourceGroup --template-file azuredeploy.json --parameters
        '{
                "location": {
                    "value": "westus"
                }
            }'


    Create a deployment from a local template, using a parameter file and selectively overriding
    key/value pairs.
        az group deployment create -g MyResourceGroup --template-file azuredeploy.json \
            --parameters @params.json --parameters MyValue=This [email protected]

Is the @ symbol needed?

Can the documentation be updated to remove the @ symbol? It doesn't seem to be need in cmd or linux environment?

---

Environment summary

Install Method: MSI
OS version: Microsoft Windows [Version 10.0.16299.309]
Shell Type: Powershell

azure-cli (2.0.29)

acr (2.0.22)
acs (2.0.28)
advisor (0.5.0)
appservice (0.1.29)
backup (1.0.7)
batch (3.1.11)
batchai (0.1.6)
billing (0.1.7)
cdn (0.0.13)
cloud (2.0.12)
cognitiveservices (0.1.11)
command-modules-nspkg (2.0.1)
configure (2.0.14)
consumption (0.2.2)
container (0.1.19)
core (2.0.29)
cosmosdb (0.1.19)
dla (0.0.18)
dls (0.0.19)
eventgrid (0.1.11)
eventhubs (0.1.0)
extension (0.0.10)
feedback (2.1.0)
find (0.2.8)
interactive (0.3.17)
iot (0.1.18)
keyvault (2.0.20)
lab (0.0.17)
monitor (0.1.3)
network (2.0.25)
nspkg (3.0.2)
profile (2.0.20)
rdbms (0.1.0)
redis (0.2.11)
reservations (0.1.1)
resource (2.0.25)
role (2.0.20)
servicebus (0.1.0)
servicefabric (0.0.11)
sql (2.0.23)
storage (2.0.27)
vm (2.0.28)

Python location 'C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\python.exe'
Extensions directory 'C:\Users\jstur\.azure\cliextensions'

Python (Windows) 3.6.1 (v3.6.1:69c0db5, Mar 21 2017, 17:54:52) [MSC v.1900 32 bit (Intel)]

Legal docs and information: aka.ms/AzureCliLegal

[tjprescott]

Yes, the @ symbol is necessary. In CLI 2.0 it is used to load the contents of the file. It is effectively the same as supplying a JSON string by loading the file.

CLI 2.0 was not designed to be used with Powershell. The use of the @ symbol to load the contents of a file did not cause issues on bash or Windows but is used by Powershell and thus takes precedence. You will need to escape the @ symbol with backtick (`).

[satls]

I'm not sure that "CLI 2.0 was not designed to be used with Powershell." is correct, are you suggesting that the CLI 2.0 is not supported on PowerShell?

[tjprescott]

Many people regularly use CLI 2.0 on Powershell and it is available on the CloudShell via a PS terminal. However, the CLI's core mechanisms were designed initially without PS as an intended shell, and as a result, some of the design choices conflict with syntax already appropriated by PS. Long story short, it means you can use PS, but you have to appropriately quote the syntax to prevent PS from interpreting it, as this occurs before the input ever reaches the CLI.