Merge pull request #224518 from dknappettmsft/avd-uri-schemes

AVD URI schemes

Author: v-regandowner

articles/virtual-desktop/TOC.yml

@@ -159,6 +159,8 @@
         href: compare-remote-desktop-clients.md
       - name: Supported RDP properties
         href: rdp-properties.md
+      - name: Uniform Resource Identifier schemes
+        href: uri-scheme.md
     - name: Multimedia redirection
       href: multimedia-redirection-intro.md
     - name: Printing using Universal Print

articles/virtual-desktop/uri-scheme.md

@@ -0,0 +1,98 @@
+---
+title: Uniform Resource Identifier schemes with the Remote Desktop client for Azure Virtual Desktop (preview)
+description: Learn how to use Uniform Resource Identifier (URI) schemes with the Remote Desktop client to subscribe and connect to Azure Virtual Desktop
+ms.topic: conceptual
+author: dknappettmsft
+ms.author: daknappe
+ms.date: 01/19/2023
+---
+
+# Uniform Resource Identifier schemes with the Remote Desktop client for Azure Virtual Desktop (preview)
+
+> [!IMPORTANT]
+> The *ms-avd* Uniform Resource Identifier scheme for Azure Virtual Desktop is currently in PREVIEW.
+> See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+
+You can use Uniform Resource Identifier (URI) schemes to invoke the Remote Desktop client with specific commands, parameters, and values for use with Azure Virtual Desktop. For example, you can subscribe to a workspace or connect to a particular desktop or Remote App.
+
+This article details the available commands and parameters, along with some examples.
+
+## Supported clients
+
+The following table lists the supported clients for use with the URI schemes:
+
+| Client | Version |
+|--|--|
+| [Remote Desktop client for Windows](users/connect-windows.md) | 1.2.4065 and later |
+
+## Available URI schemes
+
+There are two URI schemes for supported Remote Desktop clients, *ms-avd* and *ms-rd*. With *ms-avd*, you can specify a particular Azure Virtual Desktop resource and user with which to connect. With *ms-rd*, you can automatically subscribe to a workspace in the Remote Desktop client, rather than having to manually add the workspace.
+
+The following sections detail the commands and parameters you can use with each URI scheme.
+
+### ms-avd
+
+Here's the list of currently supported commands for *ms-avd* and their corresponding parameters.
+
+#### ms-avd:connect
+
+`ms-avd:connect` locates a specified Azure Virtual Desktop resource and initiates the RDP session, directly connecting a specified user to that resource.
+
+> [!IMPORTANT]
+> The ms-avd:connect command is currently in preview and shouldn't be used in production.
+
+**Command name:** connect
+
+**Command parameters:**
+
+| Parameter | Values | Description |
+|--|--|--|
+| workspaceid | Object ID (GUID). | Specify the object ID of a valid workspace.<br /><br />To get the object ID value using PowerShell, see [Retrieve the object ID of a host pool, workspace, application group, or application](powershell-module.md#retrieve-the-object-id-of-a-host-pool-workspace-application-group-or-application). You can also use [Desktop Virtualization REST APIs](/rest/api/desktopvirtualization). |
+| resourceid | Object ID (GUID). | Specify the object ID of a published resource contained in the workspace. The value can be for a desktop or Remote App.<br /><br />To get the object ID value using PowerShell, see [Retrieve the object ID of a host pool, workspace, application group, or application](powershell-module.md#retrieve-the-object-id-of-a-host-pool-workspace-application-group-or-application). You can also use [Desktop Virtualization REST APIs](/rest/api/desktopvirtualization). |
+| user | User Principal Name (UPN), for example `[email protected]`. | Specify a valid user with access to specified resource. |
+| env *(optional)* | **avdarm** (commercial Azure)<br />**avdgov** (Azure Government) | Specify the Azure cloud where resources are located. |
+| version | **0** | Specify the version of the connect URI scheme to use. |
+| launchpartnerid *(optional)*| GUID. | Specify the partner or customer-provided ID that you can use with [Azure Virtual Desktop Diagnostics](diagnostics-log-analytics.md) to help with troubleshooting. We recommend using a GUID, which you can generate with the [New-Guid](/powershell/module/microsoft.powershell.utility/new-guid) PowerShell cmdlet. |
+| peeractivityid *(optional)*| GUID. | Specify the partner or customer-provided ID that you can use with [Azure Virtual Desktop Diagnostics](diagnostics-log-analytics.md) to help with troubleshooting. We recommend using a GUID, which you can generate with the [New-Guid](/powershell/module/microsoft.powershell.utility/new-guid) PowerShell cmdlet. |
+
+**Example:**
+```
+ms-avd:connect?workspaceId=1638e073-63b2-46d8-bd84-ea02ea905467&resourceid=c2f5facc-196f-46af-991e-a90f3252c185&[email protected]&version=0
+```
+
+### ms-rd
+
+Here's the list of currently supported commands for *ms-rd* and their corresponding parameters.
+
+> [!TIP]
+> Using `ms-rd:` without any commands launches the Remote Desktop client.
+
+#### ms-rd:subscribe
+
+`ms-rd:subscribe` launches the Remote Desktop client and starts the subscription process.
+
+**Command name:** subscribe
+
+**Command parameters:**
+
+| Parameter | Values | Description |
+|--|--|--|
+| url | A valid URL, such as <https://rdweb.wvd.microsoft.com>. | Specify a workspace URL. |
+
+**Example:**
+
+```
+ms-rd:subscribe?url=https://rdweb.wvd.microsoft.com
+```
+
+## Known Limitations
+
+Here are known limitations with the URI schemes:
+
+- Display properties cannot be configured via URI. You can configure display properties as an admin [on a host pool](customize-rdp-properties.md) or end users can configure display properties in the [Azure Virtual Desktop client](users/remote-desktop-clients-overview.md).
+
+
+## Next steps
+
+Learn how to [Connect to Azure Virtual Desktop with the Remote Desktop client for Windows](users/connect-windows.md?toc=%2Fazure%2Fvirtual-desktop%2Ftoc.json&bc=%2Fazure%2Fvirtual-desktop%2Fbreadcrumb%2Ftoc.json).

articles/virtual-desktop/users/client-features-windows.md

@@ -270,15 +270,9 @@ You can set the *AutomaticUpdates* registry key to one of the following values:
 
 ### URI to subscribe to a workspace
 
-The Remote Desktop client for Windows supports the *ms-rd* Uniform Resource Identifier (URI) scheme. This enables you to use a link that users can help to automatically subscribe to a workspace, rather than them having to manually add the workspace in the Remote Desktop client.
+The Remote Desktop client for Windows supports the *ms-rd* and *ms-avd* (preview) Uniform Resource Identifier (URI) schemes. This enables you to invoke the Remote Desktop client with specific commands, parameters, and values for use with Azure Virtual Desktop. For example, you can subscribe to a workspace or connect to a particular desktop or Remote App.
 
-To subscribe to a workspace with a link:
-
-1. Open the following link in a web browser: `ms-rd:subscribe?url=https://rdweb.wvd.microsoft.com`.
-
-1. If you see the prompt **This site is trying to open Microsoft Remote Desktop Connection Center**, select **Open**. The **Remote Desktop** application should open and automatically show a sign-in prompt.
-
-1. Enter your user account, then select **Sign in**. After a few seconds, your workspaces should show the desktops and applications that have been made available to you by your admin.
+For more information and the available commands, see [Uniform Resource Identifier schemes with the Remote Desktop client for Azure Virtual Desktop](../uri-scheme.md?toc=%2Fazure%2Fvirtual-desktop%2Fusers%2Ftoc.json)
 
 ## Azure Virtual Desktop (HostApp)