Merge pull request #193613 from baanders/3-31-shell

ADT: Info for CLI special chars

Author: laurabren

articles/digital-twins/TOC.yml

@@ -154,7 +154,9 @@
       - name: Error 404 (Sub-Domain not found)
         href: troubleshoot-error-404.md
       - name: Azure Digital Twins Explorer authentication error
-        href: troubleshoot-error-azure-digital-twins-explorer-authentication.md  
+        href: troubleshoot-error-azure-digital-twins-explorer-authentication.md
+      - name: CLI parsing failures
+        href: troubleshoot-error-cli-parse.md  
 - name: Reference
   items:
   - name: REST API reference

articles/digital-twins/concepts-cli.md

@@ -5,7 +5,7 @@ titleSuffix: Azure Digital Twins
 description: Learn about the Azure Digital Twins CLI command set.
 author: baanders
 ms.author: baanders # Microsoft employees only
-ms.date: 02/28/2022
+ms.date: 03/31/2022
 ms.topic: conceptual
 ms.service: digital-twins
 
@@ -17,7 +17,7 @@ ms.service: digital-twins
 
 # Azure Digital Twins CLI command set
 
-Apart from managing your Azure Digital Twins instance in the Azure portal, Azure Digital Twins also has a command set for the [Azure CLI](/cli/azure/what-is-azure-cli) that you can use to do most major actions with the service. This article covers the [Azure CLI](/cli/azure/what-is-azure-cli) in terms of its uses, how to get it, and the requirements for using it.
+Apart from managing your Azure Digital Twins instance in the Azure portal, Azure Digital Twins also has a command set for the [Azure CLI](/cli/azure/what-is-azure-cli) that you can use to do most major actions with the service. This article covers the Azure CLI command set for Azure Digital twins including its uses, how to get it, and the requirements for using it.
 
 Some of the actions you can do using the command set include:
 * Managing an Azure Digital Twins instance
@@ -61,6 +61,67 @@ Otherwise, you can use the following command to install the extension yourself a
 az extension add --upgrade --name azure-iot
 ```
 
+## Use special characters in different shells
+
+Some `az dt` commands use special characters that may have to be escaped for proper parsing in certain shell environments. Use the tips in this section to help you know when to do this in your shell of choice.
+
+### Bash
+
+Use these special character tips for Bash environments.
+
+#### Queries
+
+In many twin queries, the `$` character is used to reference the `$dtId` property of a twin. When using the [az dt twin query](/cli/azure/dt/twin#az-dt-twin-query) command to query in the Cloud Shell Bash environment, escape the `$` character with a backslash (`\`).
+
+Here is an example of querying for a twin with a CLI command in the Cloud Shell Bash environment:
+
+```azurecli
+az dt twin query -n <instance-name> -q "SELECT * FROM DigitalTwins T Where T.\$dtId = 'room0'"
+```
+
+### PowerShell
+
+Use these special character tips for PowerShell environments.
+
+#### Inline JSON
+
+Some commands, like [az dt twin create](/cli/azure/dt/twin#az-dt-twin-create), allow you to enter twin information in the form of inline JSON. When entering inline JSON in the PowerShell environment, escape double quote characters (`"`) inside the JSON with a backslash (`\`). 
+
+Here is an example of creating a twin with a CLI command in PowerShell:
+
+```azurecli
+az dt twin create  --dt-name <instance-name> --dtmi "dtmi:contosocom:DigitalTwins:Thermostat;1" --twin-id thermostat67 --properties '{\"Temperature\": 0.0}'
+```
+
+>[!TIP]
+>Many of the commands that support inline JSON also support input as a file path, which can help you avoid shell-specific text requirements.
+
+#### Queries
+
+In many twin queries, the `$` character is used to reference the `$dtId` property of a twin. When using the [az dt twin query](/cli/azure/dt/twin#az-dt-twin-query) command to query in a PowerShell environment, escape the `$` character with a backtick character.
+
+Here is an example of querying for a twin with a CLI command in PowerShell:
+```azurecli
+az dt twin query -n <instance-name> -q "SELECT * FROM DigitalTwins T Where T.`$dtId = 'room0'"
+```
+
+### Windows CMD
+
+Use these special character tips for the local Windows CMD.
+
+#### Inline JSON
+
+Some commands, like [az dt twin create](/cli/azure/dt/twin#az-dt-twin-create), allow you to enter twin information in the form of inline JSON. When entering inline JSON in a local Windows CMD window, enclose the parameter value with double quotes (`"`) instead of single quotes (`'`), and escape double quote characters inside the JSON with a backslash (`\`). 
+
+Here is an example of creating a twin with a CLI command in the local Windows CMD:
+
+```azurecli
+az dt twin create  --dt-name <instance-name> --dtmi "dtmi:contosocom:DigitalTwins:Thermostat;1" --twin-id thermostat67 --properties "{\"Temperature\": 0.0}"
+```
+
+>[!TIP]
+>Many of the commands that support inline JSON also support input as a file path, which can help you avoid shell-specific text requirements.
+
 ## Next steps
 
 Explore the CLI and its full set of commands through the reference docs:

articles/digital-twins/how-to-ingest-iot-hub-data.md

@@ -57,9 +57,14 @@ To create a thermostat-type twin, you'll first need to upload the thermostat [mo
 You'll then need to create one twin using this model. Use the following command to create a thermostat twin named thermostat67, and set 0.0 as an initial temperature value.
 
 ```azurecli-interactive
-az dt twin create  --dt-name <instance-name> --dtmi "dtmi:contosocom:DigitalTwins:Thermostat;1" --twin-id thermostat67 --properties '{"Temperature": 0.0,}'
+az dt twin create  --dt-name <instance-name> --dtmi "dtmi:contosocom:DigitalTwins:Thermostat;1" --twin-id thermostat67 --properties '{"Temperature": 0.0}'
 ```
 
+>[!NOTE]
+>If you're using anything other than Cloud Shell in the Bash environment, you may need to escape certain characters in the inline JSON so that it's parsed correctly. 
+>
+>For more information, see [Use special characters in different shells](concepts-cli.md#use-special-characters-in-different-shells).
+
 When the twin is created successfully, the CLI output from the command should look something like this:
 ```json
 {

articles/digital-twins/troubleshoot-error-cli-parse.md

@@ -0,0 +1,44 @@
+---
+title: "Troubleshoot CLI parsing failures"
+titleSuffix: Azure Digital Twins
+description: Learn how to diagnose and resolve parsing failures with the Azure Digital Twins CLI command set.
+ms.service: digital-twins
+author: baanders
+ms.author: baanders
+ms.topic: troubleshooting
+ms.date: 03/31/2022
+---
+
+# Troubleshoot parsing failures with Azure Digital Twins CLI commands
+
+This article describes causes and resolution steps for various "parse failed" errors while running [az dt](/cli/azure/dt) commands in the Azure CLI.
+
+## Symptoms
+
+While attempting to run select `az dt` commands in an Azure CLI environment, you receive an error indicating that the command wasn't parsed correctly. The error message might include the words *parse failed* or *failed to parse*, or partial text from your command may be marked as *unrecognized arguments.*
+
+## Causes
+
+### Cause #1
+
+Some `az dt` commands use special characters that have to be escaped for proper parsing in certain shell environments. It is possible that some special character in your CLI command needs to be escaped for it to be parsed in the shell that you're using.
+
+## Solutions
+
+### Solution #1
+
+Use the full error message text to help you determine which character is causing an issue. Then, try escaping instances of this character with a backslash or a backtick. For a list of some specific characters that need to be escaped in certain shells, see [Use special characters in different shells](concepts-cli.md#use-special-characters-in-different-shells).
+
+### Solution #2
+
+If you're encountering the parsing issue while passing inline JSON into a command (like [az dt model create](/cli/azure/dt/model#az-dt-model-create) or [az dt twin create](/cli/azure/dt/twin#az-dt-twin-create)), check whether the command allows you to pass in a file instead. Many of the commands that support inline JSON also support input as a file path, which can help you avoid shell-specific text requirements.
+
+### Solution #3
+
+Not all shells have the same special character requirements, so you can try running the command in a different shell type (some options are the [Cloud Shell](https://shell.azure.com) Bash environment, [Cloud Shell](https://shell.azure.com) PowerShell environment, local Windows CMD, local Bash window, or local PowerShell window).
+
+## Next steps
+
+Read more about the CLI for Azure Digital Twins:
+* [Azure Digital Twins CLI command set](concepts-cli.md)
+* [az dt command reference](/cli/azure/dt)

articles/digital-twins/tutorial-command-line-cli.md

@@ -143,7 +143,9 @@ To create a digital twin, you use the [az dt twin create](/cli/azure/dt/twin#az-
     ```
 
     >[!NOTE]
-    > It's recommended to use the CLI in the Bash environment for this tutorial. If you're using the PowerShell environment, you may need to escape the quotation mark characters in order for the `--properties` JSON value to be parsed correctly.
+    >If you're using anything other than Cloud Shell in the Bash environment, you may need to escape certain characters in the inline JSON so that it's parsed correctly. 
+    >
+    >For more information, see [Use special characters in different shells](concepts-cli.md#use-special-characters-in-different-shells).
     
     The output from each command will show information about the successfully created twin (including properties for the room twins that were initialized with them).