[App Service] Docs and help text improvements for deploy, connection-string, and SSL commands

src/azure-cli/azure/cli/command_modules/appservice/_help.py

@@ -1578,12 +1578,33 @@
 helps['webapp config connection-string set'] = """
 type: command
 short-summary: Update a web app's connection strings.
-long-summary: Note that connection string values are now redacted in the result. Please use the `az webapp config connection-string list` command to view the values.
+long-summary: >
+    Note that connection string values are now redacted in the result. Please use the
+    `az webapp config connection-string list` command to view the values.
+
+
+    App Service exposes each connection string as an environment variable with a type-based
+    prefix:
+      SQLServer    → `SQLCONNSTR_<name>`
+      SQLAzure     → `SQLAZURECONNSTR_<name>`
+      MySQL        → `MYSQLCONNSTR_<name>`
+      PostgreSQL   → `POSTGRESQLCONNSTR_<name>`
+      Custom       → `CUSTOMCONNSTR_<name>`
+
+
+    .NET's Configuration.GetConnectionString() auto-maps only the SQLServer, SQLAzure, and
+    Custom prefixes. For MySQL and PostgreSQL connection strings, access the value directly
+    via `Configuration["MYSQLCONNSTR_<name>"]` or `Configuration["POSTGRESQLCONNSTR_<name>"]`
+    instead.
 examples:
   - name: Add a mysql connection string.
     text: >
         az webapp config connection-string set -g MyResourceGroup -n MyUniqueApp -t mysql \\
             --settings mysql1='Server=myServer;Database=myDB;Uid=myUser;Pwd=myPwd;'
+  - name: Add a PostgreSQL connection string (access in .NET via Configuration["POSTGRESQLCONNSTR_pg1"]).
+    text: >
+        az webapp config connection-string set -g MyResourceGroup -n MyUniqueApp -t postgresql \\
+            --settings pg1='Host=myHost;Database=myDB;Username=myUser;Password=myPwd;'
 """
 
 helps['webapp config container'] = """
@@ -1665,6 +1686,15 @@
   - name: set configuration through a JSON file called params.json
     text: >
         az webapp config set -g MyResourceGroup -n MyUniqueApp --generic-configurations "@.\\params.json"
+  - name: Set the linux runtime stack to Python 3.11 (format is RUNTIME|VERSION).
+    text: >
+        az webapp config set -g MyResourceGroup -n MyUniqueApp --linux-fx-version "PYTHON|3.11"
+  - name: Set the linux runtime stack to Node.js 18 LTS.
+    text: >
+        az webapp config set -g MyResourceGroup -n MyUniqueApp --linux-fx-version "NODE|18-lts"
+  - name: Set the linux runtime stack to .NET 8.0.
+    text: >
+        az webapp config set -g MyResourceGroup -n MyUniqueApp --linux-fx-version "DOTNETCORE|8.0"
 
 """
 
@@ -1910,6 +1940,9 @@
   - name: Create a web app with end-to-end encryption enabled and minimum TLS version 1.2
     text: >
         az webapp create -g MyResourceGroup -p MyPlan -n MyUniqueAppName --end-to-end-encryption-enabled true --min-tls-version 1.2
+  - name: Create a web app with a system-assigned managed identity and grant it access to a storage account.
+    text: >
+        az webapp create -g MyResourceGroup -p MyPlan -n MyUniqueAppName --assign-identity [system] --scope /subscriptions/{subscription}/resourceGroups/{resourceGroup}/providers/Microsoft.Storage/storageAccounts/{storageAccount} --role Contributor
 """
 
 helps['webapp create-remote-connection'] = """
@@ -3287,9 +3320,24 @@
 helps['webapp deploy'] = """
     type: command
     short-summary: Deploys a provided artifact to Azure Web Apps.
+    long-summary: |
+        Supports deploying from local files (--src-path) or remote URLs (--src-url).
+        When --track-status is enabled (the default for Linux web apps), the command monitors
+        application startup after deployment by polling health endpoints. If the app fails to
+        start within the expected window, the command returns a non-zero exit code. Use
+        --async false together with --track-status true to wait for full deployment completion
+        before tracking begins.
     examples:
-    - name: Deploy a war file asynchronously.
-      text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path SourcePath --type war --async true
-    - name: Deploy a static text file to wwwroot/staticfiles/test.txt
-      text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path SourcePath --type static --target-path staticfiles/test.txt
+    - name: Deploy a war file asynchronously from local path.
+      text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path app.war --type war --async true
+    - name: Deploy a zip file from a remote URL.
+      text: az webapp deploy --resource-group ResourceGroup --name AppName --src-url https://example.com/app.zip
+    - name: Deploy without cleaning the target directory.
+      text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path app.zip --clean false
+    - name: Deploy with runtime status tracking for Linux web app.
+      text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path app.zip --track-status true --async false
+    - name: Deploy to a specific slot.
+      text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path app.jar --type jar --slot staging
+    - name: Deploy a static text file to a custom path.
+      text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path file.txt --type static --target-path staticfiles/file.txt
 """

src/azure-cli/azure/cli/command_modules/appservice/_params.py

@@ -581,7 +581,7 @@ def load_arguments(self, _):
             c.argument('power_shell_version', help='The version used to run your function app if using PowerShell, e.g., 7.2', options_list=['--powershell-version'])
             c.argument('python_version', help='The version used to run your web app if using Python, e.g., 2.7, 3.4')
             c.argument('net_framework_version', help="The version used to run your web app if using .NET Framework, e.g., 'v4.0' for .NET 4.6 and 'v3.0' for .NET 3.5")
-            c.argument('linux_fx_version', help="The runtime stack used for your linux-based webapp, e.g., \"RUBY|2.5.5\", \"NODE|12LTS\", \"PHP|7.2\", \"DOTNETCORE|2.1\". See https://aka.ms/linux-stacks for more info.")
+            c.argument('linux_fx_version', help="The runtime stack used for your linux-based webapp, in the format 'RUNTIME|VERSION'. Common examples: \"PYTHON|3.11\", \"NODE|18-lts\", \"DOTNETCORE|8.0\", \"JAVA|17-java17\", \"PHP|8.2\". Use `az webapp list-runtimes --os linux` to see all supported values. See https://aka.ms/linux-stacks for more info.")
             c.argument('windows_fx_version', help="A docker image name used for your windows container web app, e.g., microsoft/nanoserver:ltsc2016")
             if scope == 'functionapp':
                 c.ignore('windows_fx_version')
@@ -591,7 +591,7 @@ def load_arguments(self, _):
                 c.ignore('reserved_instance_count')
                 c.argument('runtime', help="Canonicalized web runtime in the format of Framework:Version, e.g. \"PHP:7.2\"."
                                            "Use `az webapp list-runtimes` for available list")
-                c.argument('acr_use_identity', arg_type=get_three_state_flag(return_label=True), help="Enable or disable pull image from acr use managed identity")
+                c.argument('acr_use_identity', arg_type=get_three_state_flag(return_label=True), help="If not specified, managed identity will not be used for ACR image pull.")
                 c.argument('acr_identity', help="Accept system or user assigned identity which will be set for acr image pull. "
                                                 "Use \'[system]\' to refer system assigned identity, or a resource id to refer user assigned identity.")
             c.argument('java_version',
@@ -794,7 +794,11 @@ def load_arguments(self, _):
 
     with self.argument_context('webapp config connection-string') as c:
         c.argument('connection_string_type', options_list=['--connection-string-type', '-t'],
-                   help='connection string type', arg_type=get_enum_type(ConnectionStringType))
+                   help='Connection string type. App Service sets an env var prefix per type '
+                        '(e.g., SQLAZURECONNSTR_, POSTGRESQLCONNSTR_). .NET GetConnectionString() '
+                        'auto-maps SQLServer, SQLAzure, and Custom only; for MySQL/PostgreSQL, '
+                        'read the env var directly.',
+                   arg_type=get_enum_type(ConnectionStringType))
         c.argument('ids', options_list=['--ids'],
                    help="One or more resource IDs (space delimited). If provided no other 'Resource Id' arguments should be specified.",
                    required=True)
@@ -1007,9 +1011,9 @@ def load_arguments(self, _):
         c.argument('clean', help='If true, cleans the target directory prior to deploying the file(s). Default value is determined based on artifact type.', arg_type=get_three_state_flag())
         c.argument('ignore_stack', help='If true, any stack-specific defaults are ignored.', arg_type=get_three_state_flag())
         c.argument('reset', help='Reset Java apps to the default parking page if set to true with no type specified.', arg_type=get_three_state_flag())
-        c.argument('timeout', type=int, help='Timeout for the deployment operation in milliseconds. Ignored when using "--src-url" since synchronous deployments are not yet supported when using "--src-url"')
-        c.argument('slot', help="The name of the slot. Default to the productions slot if not specified.")
-        c.argument('track_status', help="If true, web app startup status during deployment will be tracked for linux web apps.",
+        c.argument('timeout', type=int, help='Timeout for the deployment operation in milliseconds. Default: 900000 (15 minutes). Ignored when using "--src-url".')
+        c.argument('slot', help="The name of the slot. Default to the production slot if not specified.")
+        c.argument('track_status', help="If not specified, the command will track app startup and runtime health. Default: true.",
                    arg_type=get_three_state_flag())
         c.argument('enable_kudu_warmup', help="If true, kudu will be warmed up before performing deployment for a linux webapp.",
                    arg_type=get_three_state_flag())