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
hostPoolName
path True

string

minLength: 3
maxLength: 64
pattern: ^[A-Za-z0-9@.\-_ ]*$

The name of the host pool within the specified resource group

resourceGroupName
path True

string

minLength: 1
maxLength: 90

The name of the resource group. The name is case insensitive.

subscriptionId
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

SessionHostConfigurationPatchProperties

Detailed properties for SessionHostConfiguration

Responses

Name Type Description
200 OK

SessionHostConfiguration

Azure operation completed successfully.

202 Accepted

Resource update request accepted.

Headers

  • Location: string
  • Retry-After: integer
Other Status Codes

ErrorResponse

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
ActiveDirectoryInfoPatchProperties

Active directory info. Only one should be populated based on the join type

ActiveDirectoryInfoProperties

Active directory info. Only one should be populated based on the join type.

AzureActiveDirectoryInfoProperties

Azure Active directory info. Only one should be populated based on the join type

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

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

createdByType

The type of identity that created the resource.

CustomInfoPatchProperties

Custom image information.

CustomInfoProperties

Custom image information.

DiffDiskOption

Specifies the ephemeral disk settings for operating system disk.

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'.

DiffDiskProperties

Specifies the ephemeral disk settings for the operating system disk used by the virtual machine.

DiskInfoProperties

Disk information.

DomainInfoPatchProperties

Domain configurations of session hosts.

DomainInfoProperties

Domain configurations of session hosts.

DomainJoinType

The type of domain join done by the virtual machine.

ErrorAdditionalInfo

The resource management error additional info.

ErrorDetail

The error detail.

ErrorResponse

Error response

ImageInfoPatchProperties

Image configurations of session host in a HostPool

ImageInfoProperties

Image configurations of session host in a HostPool

KeyVaultCredentialsPatchProperties

Credentials kept in the keyvault.

KeyVaultCredentialsProperties

Credentials kept in the keyvault.

ManagedDiskProperties

Managed Disk information.

MarketplaceInfoPatchProperties

Marketplace image information.

MarketplaceInfoProperties

Marketplace image information.

NetworkInfoPatchProperties

Network information.

NetworkInfoProperties

Network information.

ProvisioningStateSHC

Provisioning state of the Session Host Configuration.

SecurityInfoPatchProperties

Security Information.

SecurityInfoProperties

Security Information.

SessionHostConfiguration

Schema for SessionHostConfiguration properties.

SessionHostConfigurationPatch

SessionHostConfiguration properties that can be patched.

SessionHostConfigurationPatchProperties

Session host configurations of HostPool.

systemData

Metadata pertaining to creation and last modification of the resource.

type

The type of image session hosts use in the hostpool.

VirtualMachineDiskType

The disk type used by virtual machine in hostpool session host.

VirtualMachineSecurityType

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

KeyVaultCredentialsPatchProperties

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

KeyVaultCredentialsProperties

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.

If storageUri is not specified while enabling boot diagnostics, managed storage will be used.

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.

If storageUri is not specified while enabling boot diagnostics, managed storage will be used.

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

DiffDiskOption

Specifies the ephemeral disk settings for operating system disk.

placement

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'.

DiskInfoProperties

Disk information.

Name Type Description
diffDiskSettings

DiffDiskProperties

Specifies the ephemeral disk settings for the operating system disk used by the virtual machine.

managedDisk

ManagedDiskProperties

The managed disk parameters.

DomainInfoPatchProperties

Domain configurations of session hosts.

Name Type Description
activeDirectoryInfo

ActiveDirectoryInfoPatchProperties

Active directory info. Only one should be populated based on the join type.

DomainInfoProperties

Domain configurations of session hosts.

Name Type Description
activeDirectoryInfo

ActiveDirectoryInfoProperties

Active directory info. Only one should be populated based on the join type.

azureActiveDirectoryInfo

AzureActiveDirectoryInfoProperties

Azure active directory info. Only one should be populated based on the join type.

joinType

DomainJoinType

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

ErrorAdditionalInfo[]

The error additional info.

code

string

The error code.

details

ErrorDetail[]

The error details.

message

string

The error message.

target

string

The error target.

ErrorResponse

Error response

Name Type Description
error

ErrorDetail

The error object.

ImageInfoPatchProperties

Image configurations of session host in a HostPool

Name Type Description
customInfo

CustomInfoPatchProperties

The values to uniquely identify a custom image. Only one should be populated based on the image type.

marketplaceInfo

MarketplaceInfoPatchProperties

The values to uniquely identify a marketplace image. Only one should be populated based on the image type.

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

CustomInfoProperties

The values to uniquely identify a custom image. Only one should be populated based on the image type.

marketplaceInfo

MarketplaceInfoProperties

The values to uniquely identify a marketplace image. Only one should be populated based on the image type.

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

VirtualMachineDiskType

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

VirtualMachineSecurityType

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

VirtualMachineSecurityType

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

BootDiagnosticsInfoProperties

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

DiskInfoProperties

Disk Information

properties.domainInfo

DomainInfoProperties

Domain configurations of session hosts.

properties.friendlyName

string

maxLength: 260

Friendly name to describe this version of the SessionHostConfiguration.

properties.imageInfo

ImageInfoProperties

Image configurations of HostPool.

properties.networkInfo

NetworkInfoProperties

Network information.

properties.provisioningState

ProvisioningStateSHC

Provisioning state of the Session Host Configuration.

properties.securityInfo

SecurityInfoProperties

Security Information

properties.version

string (date-time)

The timestamp of the last update.

properties.vmAdminCredentials

KeyVaultCredentialsProperties

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

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

SessionHostConfigurationPatchProperties

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

BootDiagnosticsInfoPatchProperties

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

DiskInfoProperties

Disk Information

domainInfo

DomainInfoPatchProperties

Domain configurations of session hosts.

friendlyName

string

maxLength: 260

Friendly name to describe this version of the SessionHostConfiguration.

imageInfo

ImageInfoPatchProperties

Image configurations of HostPool.

networkInfo

NetworkInfoPatchProperties

Network information.

securityInfo

SecurityInfoPatchProperties

Security Information

vmAdminCredentials

KeyVaultCredentialsPatchProperties

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

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

createdByType

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