Session Host Configurations - Update
Update a SessionHostConfiguration.
PATCH https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DesktopVirtualization/hostPools/{hostPoolName}/sessionHostConfigurations/default?api-version=2026-01-01-preview
URI Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
|
host
|
path | True |
string minLength: 3maxLength: 64 pattern: ^[A-Za-z0-9@.\-_ ]*$ |
The name of the host pool within the specified resource group |
|
resource
|
path | True |
string minLength: 1maxLength: 90 |
The name of the resource group. The name is case insensitive. |
|
subscription
|
path | True |
string (uuid) |
The ID of the target subscription. The value must be an UUID. |
|
api-version
|
query | True |
string minLength: 1 |
The API version to use for this operation. |
Request Body
| Name | Type | Description |
|---|---|---|
| properties |
Detailed properties for SessionHostConfiguration |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK |
Azure operation completed successfully. |
|
| 202 Accepted |
Resource update request accepted. Headers
|
|
| Other Status Codes |
An unexpected error response. |
Security
azure_auth
Azure Active Directory OAuth2 Flow.
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Scopes
| Name | Description |
|---|---|
| user_impersonation | impersonate your user account |
Examples
SessionHostConfigurations_Update
Sample request
PATCH https://management.azure.com/subscriptions/daefabc0-95b4-48b3-b645-8a753a63c4fa/resourceGroups/resourceGroup1/providers/Microsoft.DesktopVirtualization/hostPools/hostPool1/sessionHostConfigurations/default?api-version=2026-01-01-preview
{
"properties": {
"friendlyName": "Second Version, Updated Location",
"vmTags": {
"Department": "myDepartment",
"Team": "myTeam"
},
"vmLocation": "eastus2",
"vmResourceGroup": "myResourceGroup",
"vmNamePrefix": "westus2-vm",
"availabilityZones": [
1,
3
],
"networkInfo": {
"subnetId": "/subscriptions/.../resourceGroups/.../providers/Microsoft.Network/virtualNetworks/.../subnets/subnet1",
"securityGroupId": "/subscriptions/.../resourceGroups/.../provider s/Microsoft.Network/networkSecurityGroups/nsg1"
},
"vmSizeId": "Standard_D2s_v3",
"diskInfo": {
"diffDiskSettings": {
"option": "Local",
"placement": "CacheDisk"
}
},
"customConfigurationScriptUrl": "https://storageaccountname.blob.core.windows.net/blobcontainer/file",
"imageInfo": {
"type": "Marketplace",
"marketplaceInfo": {
"offer": "Windows-10",
"publisher": "MicrosoftWindowsDesktop",
"sku": "19h2-ent",
"exactVersion": "2019.0.20190115"
},
"customInfo": {
"resourceId": "/subscriptions/daefabc0-95b4-48b3-b645-8a753a63c4fa/resourceGroups/resourceGroup1/providers/Microsoft.Compute/images/imageName"
}
},
"domainInfo": {
"activeDirectoryInfo": {
"domainCredentials": {
"usernameKeyVaultSecretUri": "https://myvault.vault.azure.net/secrets/myusername",
"passwordKeyVaultSecretUri": "https://myvault.vault.azure.net/secrets/mysecretname"
}
}
},
"securityInfo": {
"type": "TrustedLaunch",
"secureBootEnabled": true,
"vTpmEnabled": true
},
"vmAdminCredentials": {
"usernameKeyVaultSecretUri": "https://myvault.vault.azure.net/secrets/myusername",
"passwordKeyVaultSecretUri": "https://myvault.vault.azure.net/secrets/mysecretname"
},
"bootDiagnosticsInfo": {
"enabled": true,
"storageUri": "https://myStorageAccountName.blob.core.windows.net"
}
}
}
Sample response
Azure-AsyncOperation: https://management.azure.com/subscriptions/daefabc0-95b4-48b3-b645-8a753a63c4fa/resourceGroups/resourceGroup1/providers/Microsoft.DesktopVirtualization/hostPools/hostPool1/sessionHostConfigurations/default/operationStatuses/ed5d502c-acaa-42ec-ad61-0d8488a9fd1d
{
"name": "default",
"id": "/subscriptions/daefabc0-95b4-48b3-b645-8a753a63c4fa/resourceGroups/resourceGroup1/providers/Microsoft.DesktopVirtualization/hostPools/hostPool1/sessionHostConfigurations/default",
"type": "Microsoft.DesktopVirtualization/hostPools/sessionHostConfigurations",
"systemData": {
"createdBy": "user1",
"createdByType": "User",
"createdAt": "2020-01-01T17:18:19.1234567Z",
"lastModifiedBy": "user2",
"lastModifiedByType": "User",
"lastModifiedAt": "2020-01-02T17:18:19.1234567Z"
},
"properties": {
"version": "2022-10-21T17:18:19.1234567Z",
"friendlyName": "InitialConfiguration",
"provisioningState": "Provisioning",
"vmTags": {
"Department": "myDepartment",
"Team": "myTeam"
},
"vmLocation": "eastus2",
"vmResourceGroup": "myResourceGroup",
"vmNamePrefix": "westus2-vm",
"availabilityZones": [
1,
3
],
"networkInfo": {
"subnetId": "/subscriptions/.../resourceGroups/.../providers/Microsoft.Network/virtualNetworks/.../subnets/subnet1",
"securityGroupId": "/subscriptions/.../resourceGroups/.../provider s/Microsoft.Network/networkSecurityGroups/nsg1"
},
"vmSizeId": "Standard_D2s_v3",
"diskInfo": {
"diffDiskSettings": {
"option": "Local",
"placement": "CacheDisk"
}
},
"customConfigurationScriptUrl": "https://storageaccountname.blob.core.windows.net/blobcontainer/file",
"imageInfo": {
"type": "Marketplace",
"marketplaceInfo": {
"offer": "Windows-10",
"publisher": "MicrosoftWindowsDesktop",
"sku": "19h2-ent",
"exactVersion": "2019.0.20190115"
},
"customInfo": {
"resourceId": "/subscriptions/daefabc0-95b4-48b3-b645-8a753a63c4fa/resourceGroups/resourceGroup1/providers/Microsoft.Compute/images/imageName"
}
},
"domainInfo": {
"joinType": "ActiveDirectory",
"activeDirectoryInfo": {
"domainCredentials": {
"usernameKeyVaultSecretUri": "https://myvault.vault.azure.net/secrets/myusername",
"passwordKeyVaultSecretUri": "https://myvault.vault.azure.net/secrets/mysecretname"
},
"ouPath": "OU=testOU,DC=domain,DC=Domain,DC=com",
"domainName": "wvdarmtest1.net"
},
"azureActiveDirectoryInfo": {
"mdmProviderGuid": "bdefabc0-95b4-48b3-b645-8a753a63c4fa"
}
},
"securityInfo": {
"type": "TrustedLaunch",
"secureBootEnabled": true,
"vTpmEnabled": true
},
"vmAdminCredentials": {
"usernameKeyVaultSecretUri": "https://myvault.vault.azure.net/secrets/myusername",
"passwordKeyVaultSecretUri": "https://myvault.vault.azure.net/secrets/mysecretname"
},
"bootDiagnosticsInfo": {
"enabled": true,
"storageUri": "https://myStorageAccountName.blob.core.windows.net"
}
}
}
Location: https://management.azure.com/subscriptions/daefabc0-95b4-48b3-b645-8a753a63c4fa/resourceGroups/resourceGroup1/providers/Microsoft.DesktopVirtualization/hostPools/hostPool1/sessionHostConfigurations/default/operationResults/ed5d502c-acaa-42ec-ad61-0d8488a9fd1d
Azure-AsyncOperation: https://management.azure.com/subscriptions/daefabc0-95b4-48b3-b645-8a753a63c4fa/resourceGroups/resourceGroup1/providers/Microsoft.DesktopVirtualization/hostPools/hostPool1/sessionHostConfigurations/default/operationStatuses/ed5d502c-acaa-42ec-ad61-0d8488a9fd1d
Retry-After: 60
Definitions
| Name | Description |
|---|---|
|
Active |
Active directory info. Only one should be populated based on the join type |
|
Active |
Active directory info. Only one should be populated based on the join type. |
|
Azure |
Azure Active directory info. Only one should be populated based on the join type |
|
Boot |
Boot Diagnostics is a debugging feature which allows you to view Console Output and Screenshot to diagnose VM status. |
|
Boot |
Boot Diagnostics is a debugging feature which allows you to view Console Output and Screenshot to diagnose VM status. |
|
created |
The type of identity that created the resource. |
|
Custom |
Custom image information. |
|
Custom |
Custom image information. |
|
Diff |
Specifies the ephemeral disk settings for operating system disk. |
|
Diff |
Gets or sets specifies the ephemeral disk placement for operating system disk. The defaulting behavior is: CacheDisk if one is configured for the VM size otherwise ResourceDisk is used. Refer to the VM size documentation for Windows VM at https://docs.microsoft.com/azure/virtual-machines/windows/sizes and Linux VM at https://docs.microsoft.com/azure/virtual-machines/linux/sizes to check which VM sizes exposes a cache disk. Possible values include: 'CacheDisk', 'ResourceDisk'. |
|
Diff |
Specifies the ephemeral disk settings for the operating system disk used by the virtual machine. |
|
Disk |
Disk information. |
|
Domain |
Domain configurations of session hosts. |
|
Domain |
Domain configurations of session hosts. |
|
Domain |
The type of domain join done by the virtual machine. |
|
Error |
The resource management error additional info. |
|
Error |
The error detail. |
|
Error |
Error response |
|
Image |
Image configurations of session host in a HostPool |
|
Image |
Image configurations of session host in a HostPool |
|
Key |
Credentials kept in the keyvault. |
|
Key |
Credentials kept in the keyvault. |
|
Managed |
Managed Disk information. |
|
Marketplace |
Marketplace image information. |
|
Marketplace |
Marketplace image information. |
|
Network |
Network information. |
|
Network |
Network information. |
|
Provisioning |
Provisioning state of the Session Host Configuration. |
|
Security |
Security Information. |
|
Security |
Security Information. |
|
Session |
Schema for SessionHostConfiguration properties. |
|
Session |
SessionHostConfiguration properties that can be patched. |
|
Session |
Session host configurations of HostPool. |
|
system |
Metadata pertaining to creation and last modification of the resource. |
| type |
The type of image session hosts use in the hostpool. |
|
Virtual |
The disk type used by virtual machine in hostpool session host. |
|
Virtual |
The security type used by virtual machine in hostpool session host. Default is Standard. |
ActiveDirectoryInfoPatchProperties
Active directory info. Only one should be populated based on the join type
| Name | Type | Description |
|---|---|---|
| domainCredentials |
Credentials needed to create the virtual machine. |
ActiveDirectoryInfoProperties
Active directory info. Only one should be populated based on the join type.
| Name | Type | Description |
|---|---|---|
| domainCredentials |
Credentials needed to create the virtual machine. |
|
| domainName |
string |
The domain a virtual machine connected to a hostpool will join. |
| ouPath |
string |
The organizational unit(OU) path. |
AzureActiveDirectoryInfoProperties
Azure Active directory info. Only one should be populated based on the join type
| Name | Type | Description |
|---|---|---|
| mdmProviderGuid |
string |
The Mobile Device Management(MDM) guid. |
BootDiagnosticsInfoPatchProperties
Boot Diagnostics is a debugging feature which allows you to view Console Output and Screenshot to diagnose VM status.
You can easily view the output of your console log.
Azure also enables you to see a screenshot of the VM from the hypervisor
| Name | Type | Description |
|---|---|---|
| enabled |
boolean |
Whether boot diagnostics should be enabled on the Virtual Machine. |
| storageUri |
string (uri) |
Uri of the storage account to use for placing the console output and screenshot. |
BootDiagnosticsInfoProperties
Boot Diagnostics is a debugging feature which allows you to view Console Output and Screenshot to diagnose VM status.
You can easily view the output of your console log.
Azure also enables you to see a screenshot of the VM from the hypervisor
| Name | Type | Description |
|---|---|---|
| enabled |
boolean |
Whether boot diagnostics should be enabled on the Virtual Machine. |
| storageUri |
string (uri) |
Uri of the storage account to use for placing the console output and screenshot. |
createdByType
The type of identity that created the resource.
| Value | Description |
|---|---|
| User | |
| Application | |
| ManagedIdentity | |
| Key |
CustomInfoPatchProperties
Custom image information.
| Name | Type | Description |
|---|---|---|
| resourceId |
string (arm-id) |
The resource ID of the image. |
CustomInfoProperties
Custom image information.
| Name | Type | Description |
|---|---|---|
| resourceId |
string (arm-id) |
The resource ID of the image. |
DiffDiskOption
Specifies the ephemeral disk settings for operating system disk.
| Value | Description |
|---|---|
| Local |
Operating system disk local setting. |
DiffDiskPlacement
Gets or sets specifies the ephemeral disk placement for operating system disk. The defaulting behavior is: CacheDisk if one is configured for the VM size otherwise ResourceDisk is used. Refer to the VM size documentation for Windows VM at https://docs.microsoft.com/azure/virtual-machines/windows/sizes and Linux VM at https://docs.microsoft.com/azure/virtual-machines/linux/sizes to check which VM sizes exposes a cache disk. Possible values include: 'CacheDisk', 'ResourceDisk'.
| Value | Description |
|---|---|
| CacheDisk |
Cache disk placement |
| ResourceDisk |
Resource disk placement |
DiffDiskProperties
Specifies the ephemeral disk settings for the operating system disk used by the virtual machine.
| Name | Type | Description |
|---|---|---|
| option |
Specifies the ephemeral disk settings for operating system disk. |
|
| placement |
Gets or sets specifies the ephemeral disk placement for operating system disk. The defaulting behavior is: CacheDisk if one is configured for the VM size otherwise ResourceDisk is used. Refer to the VM size documentation for Windows VM at https://docs.microsoft.com/azure/virtual-machines/windows/sizes and Linux VM at https://docs.microsoft.com/azure/virtual-machines/linux/sizes to check which VM sizes exposes a cache disk. Possible values include: 'CacheDisk', 'ResourceDisk'. |
DiskInfoProperties
Disk information.
| Name | Type | Description |
|---|---|---|
| diffDiskSettings |
Specifies the ephemeral disk settings for the operating system disk used by the virtual machine. |
|
| managedDisk |
The managed disk parameters. |
DomainInfoPatchProperties
Domain configurations of session hosts.
| Name | Type | Description |
|---|---|---|
| activeDirectoryInfo |
Active directory info. Only one should be populated based on the join type. |
DomainInfoProperties
Domain configurations of session hosts.
| Name | Type | Description |
|---|---|---|
| activeDirectoryInfo |
Active directory info. Only one should be populated based on the join type. |
|
| azureActiveDirectoryInfo |
Azure active directory info. Only one should be populated based on the join type. |
|
| joinType |
The type of domain join done by the virtual machine. |
DomainJoinType
The type of domain join done by the virtual machine.
| Value | Description |
|---|---|
| ActiveDirectory |
Using microsoft active directory. |
| AzureActiveDirectory |
Using microsoft azure active directory. |
ErrorAdditionalInfo
The resource management error additional info.
| Name | Type | Description |
|---|---|---|
| info |
object |
The additional info. |
| type |
string |
The additional info type. |
ErrorDetail
The error detail.
| Name | Type | Description |
|---|---|---|
| additionalInfo |
The error additional info. |
|
| code |
string |
The error code. |
| details |
The error details. |
|
| message |
string |
The error message. |
| target |
string |
The error target. |
ErrorResponse
Error response
| Name | Type | Description |
|---|---|---|
| error |
The error object. |
ImageInfoPatchProperties
Image configurations of session host in a HostPool
| Name | Type | Description |
|---|---|---|
| customInfo |
The values to uniquely identify a custom image. Only one should be populated based on the image type. |
|
| marketplaceInfo |
The values to uniquely identify a marketplace image. Only one should be populated based on the image type. |
|
| type |
The type of image session hosts use in the hostpool. |
ImageInfoProperties
Image configurations of session host in a HostPool
| Name | Type | Description |
|---|---|---|
| customInfo |
The values to uniquely identify a custom image. Only one should be populated based on the image type. |
|
| marketplaceInfo |
The values to uniquely identify a marketplace image. Only one should be populated based on the image type. |
|
| type |
The type of image session hosts use in the hostpool. |
KeyVaultCredentialsPatchProperties
Credentials kept in the keyvault.
| Name | Type | Description |
|---|---|---|
| passwordKeyVaultSecretUri |
string (uri) |
The uri to access the secret that the password is stored in. |
| usernameKeyVaultSecretUri |
string (uri) |
The uri to access the secret that the username is stored in. |
KeyVaultCredentialsProperties
Credentials kept in the keyvault.
| Name | Type | Description |
|---|---|---|
| passwordKeyVaultSecretUri |
string (uri) |
The uri to access the secret that the password is stored in. |
| usernameKeyVaultSecretUri |
string (uri) |
The uri to access the secret that the username is stored in. |
ManagedDiskProperties
Managed Disk information.
| Name | Type | Description |
|---|---|---|
| type |
Managed Disk information. |
MarketplaceInfoPatchProperties
Marketplace image information.
| Name | Type | Description |
|---|---|---|
| exactVersion |
string |
The version of the image. |
| offer |
string |
The offer of the image. |
| publisher |
string |
The publisher of the image. |
| sku |
string |
The SKU of the image. |
MarketplaceInfoProperties
Marketplace image information.
| Name | Type | Description |
|---|---|---|
| exactVersion |
string |
The version of the image. |
| offer |
string |
The offer of the image. |
| publisher |
string |
The publisher of the image. |
| sku |
string |
The SKU of the image. |
NetworkInfoPatchProperties
Network information.
| Name | Type | Description |
|---|---|---|
| securityGroupId |
string |
The resource ID of the security group. Any allowable/open ports should be specified in the Network Security Group(NSG). |
| subnetId |
string (arm-id) |
The resource ID of the subnet. |
NetworkInfoProperties
Network information.
| Name | Type | Description |
|---|---|---|
| securityGroupId |
string |
The resource ID of the security group. Any allowable/open ports should be specified in the Network Security Group(NSG). |
| subnetId |
string (arm-id) |
The resource ID of the subnet. |
ProvisioningStateSHC
Provisioning state of the Session Host Configuration.
| Value | Description |
|---|---|
| Succeeded |
Provisioning Successful |
| Failed |
Provisioning Failed |
| Canceled |
Provisioning was Canceled |
| Provisioning |
Provisioning in Progress |
SecurityInfoPatchProperties
Security Information.
| Name | Type | Description |
|---|---|---|
| secureBootEnabled |
boolean |
Whether to use secureBoot on the virtual machine. |
| type |
The security type used by virtual machine in hostpool session host. Default is Standard. |
|
| vTpmEnabled |
boolean |
Whether to use vTpm on the virtual machine. |
SecurityInfoProperties
Security Information.
| Name | Type | Default value | Description |
|---|---|---|---|
| secureBootEnabled |
boolean |
Whether to use secureBoot on the virtual machine. |
|
| type | Standard |
The security type used by virtual machine in hostpool session host. Default is Standard. |
|
| vTpmEnabled |
boolean |
Whether to use vTpm on the virtual machine. |
SessionHostConfiguration
Schema for SessionHostConfiguration properties.
| Name | Type | Description |
|---|---|---|
| id |
string (arm-id) |
Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}" |
| name |
string |
The name of the resource |
| properties.availabilityZones |
integer[] (int32) |
Value for availability zones to be used by the session host. Should be from [1,2,3]. |
| properties.bootDiagnosticsInfo |
Boot Diagnostics Information |
|
| properties.customConfigurationScriptUrl |
string (uri) |
The uri to the storage blob containing the arm template to be run on the virtual machine after provisioning. |
| properties.diskInfo |
Disk Information |
|
| properties.domainInfo |
Domain configurations of session hosts. |
|
| properties.friendlyName |
string maxLength: 260 |
Friendly name to describe this version of the SessionHostConfiguration. |
| properties.imageInfo |
Image configurations of HostPool. |
|
| properties.networkInfo |
Network information. |
|
| properties.provisioningState |
Provisioning state of the Session Host Configuration. |
|
| properties.securityInfo |
Security Information |
|
| properties.version |
string (date-time) |
The timestamp of the last update. |
| properties.vmAdminCredentials |
Local Admin credentials for session hosts." |
|
| properties.vmLocation |
string |
The Location for the session host to be created in. It will default to the location of the hostpool if not provided |
| properties.vmNamePrefix |
string maxLength: 11 |
The prefix that should be associated with session host names |
| properties.vmResourceGroup |
string |
The ResourceGroup for the session hosts to be created in. It will default to the ResourceGroup of the hostpool if not provided. |
| properties.vmSizeId |
string |
The id of the size of a virtual machine connected to a hostpool. Example: Standard_D2as_v6 |
| properties.vmTags |
object |
Hashtable that lists key/value pair tags to apply to the VMs |
| systemData |
Azure Resource Manager metadata containing createdBy and modifiedBy information. |
|
| type |
string |
The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts" |
SessionHostConfigurationPatch
SessionHostConfiguration properties that can be patched.
| Name | Type | Description |
|---|---|---|
| properties |
Detailed properties for SessionHostConfiguration |
SessionHostConfigurationPatchProperties
Session host configurations of HostPool.
| Name | Type | Description |
|---|---|---|
| availabilityZones |
integer[] (int32) |
Value for availability zones to be used by the session host. Should be from [1,2,3]. |
| bootDiagnosticsInfo |
Boot Diagnostics Information |
|
| customConfigurationScriptUrl |
string (uri) |
The uri to the storage blob containing the arm template to be run on the virtual machine after provisioning. |
| diskInfo |
Disk Information |
|
| domainInfo |
Domain configurations of session hosts. |
|
| friendlyName |
string maxLength: 260 |
Friendly name to describe this version of the SessionHostConfiguration. |
| imageInfo |
Image configurations of HostPool. |
|
| networkInfo |
Network information. |
|
| securityInfo |
Security Information |
|
| vmAdminCredentials |
Local Admin credentials for session hosts." |
|
| vmLocation |
string |
The Location for the session host to be created in. It will default to the location of the hostpool if not provided |
| vmNamePrefix |
string maxLength: 11 |
The prefix that should be associated with session host names |
| vmResourceGroup |
string |
The ResourceGroup for the session hosts to be created in. It will default to the ResourceGroup of the hostpool if not provided. |
| vmSizeId |
string |
The id of the size of a virtual machine connected to a hostpool. Example: Standard_D2as_v6 |
| vmTags |
object |
Hashtable that lists key/value pair tags to apply to the VMs |
systemData
Metadata pertaining to creation and last modification of the resource.
| Name | Type | Description |
|---|---|---|
| createdAt |
string (date-time) |
The timestamp of resource creation (UTC). |
| createdBy |
string |
The identity that created the resource. |
| createdByType |
The type of identity that created the resource. |
|
| lastModifiedAt |
string (date-time) |
The timestamp of resource last modification (UTC) |
| lastModifiedBy |
string |
The identity that last modified the resource. |
| lastModifiedByType |
The type of identity that last modified the resource. |
type
The type of image session hosts use in the hostpool.
| Value | Description |
|---|---|
| Marketplace |
Using default marketplace images offered by Azure Marketplace. |
| Custom |
Using a custom image. |
VirtualMachineDiskType
The disk type used by virtual machine in hostpool session host.
| Value | Description |
|---|---|
| Standard_LRS |
Standard HDD locally redundant storage. Best for backup, non-critical, and infrequent access. |
| Premium_LRS |
Premium SSD locally redundant storage. Best for production and performance sensitive workloads. |
| StandardSSD_LRS |
Standard SSD locally redundant storage. Best for web servers, lightly used enterprise applications and dev/test. |
VirtualMachineSecurityType
The security type used by virtual machine in hostpool session host. Default is Standard.
| Value | Description |
|---|---|
| Standard |
Standard security protocol. No additional parameters |
| TrustedLaunch |
TrustedLaunch allows for secure boot and vTpm |
| ConfidentialVM |
Confidential Virtual Machine security protocol |