This document tells you how to use Studio to perform the operation you want to script (in this case, to create a catalog for a set of Machine Creation Services machines) and collect the log of SDK operations that Studio made to perform the task. This output can then be customized to produce a script for automating catalog creation.

Note

To ensure you always get the latest enhancements and fixes, Citrix recommends you follow the procedure described in this document, rather than copying and pasting the example script. Line numbers and line breaks have been added to the script for readability.

Understand the script

The following section explains what each part of the script produced by Studio is doing. This
will help you with the customization of your own script. Line numbers have been added for readability.

Creates a provisioning scheme object. This is a template for the machines that are to be created. It specifies the hypervisor, network, storage, memory, number of CPUs to be used etc. It takes parameters from the system already set up, such as the HostingUnit name and the path to the VM snapshot to be used for the machines to be created. This command makes a 'consolidated' copy of the VM snapshot being used and, as a result, the process can take time to complete.

In this example, the Studio script specified the -RunAsyncronous flag on this command. This means the command will return control to the administrator before it has completed, so you must wait for it to finish before performing any operations that require it to be complete. If this flag is not specified, the command runs synchronously in-line and control is not returned until the command completes (successfully or otherwise). You can check the status of an asynchronous task using the Get-ProvTask cmdlet. Supply the task ID returned from the operation that started the task; in this case, the New-ProvScheme cmdlet.

Adds a set of controller addresses to the provisioning scheme object. This is a list of addresses that the machines created can use to register with a Controller (broker) when deployed. The machines' registration addresses can be supplied in many ways; however, this information is required if the administrator wants to use the 'Allow Machine Creation Service to supply this' in the VDA installer. Changes to this list affect only machines created after the change, not existing machines.

Studio gets a list of available Machine Identities from the Identity Pool so that, if existing accounts have been created in the past but are unused, these can be consumed instead of creating new accounts. Note that this is not required in a script because new accounts can be created instead, provided the script is running in a context that has permissions to do this. However, if the script does not have permissions to create accounts, change the script to consume available accounts (a separate process will be required to provide a pool of accounts into the Identity Pool, before running the script).

Creates the required AD computer accounts in Active Directory. The script creates one account
but, if required, it can create more using the 'Count' parameter of the command. The accounts are created into the OU defined in the provisioning scheme created above.

Locks the provisioned virtual machines and prevents accidental modification of the virtual
machine. Consumers of the SDK can use this to indicate that the virtual machine is in use and why it is locked. The script locks the VM with a tag of 'Brokered' to indicate the virtual machine is created and added to a Broker catalog and must not be deleted without first being removed from the catalog. You can set the Tag name to whatever is required.

Stops the logged operation begun in the first step and indicates it was successful.

Customize the script

The following section shows how to convert and adapt the Studio output into a script that is
more consumable. In addition to using variables and removing commands that are not required, it shows how to add machine creation into a loop so that you can control the number of machines created. Line numbers have been added for readability.

1[CmdletBinding()]param([Parameter(Mandatory=$true)][string]$hostingUnitPath,[Parameter(Mandatory=$true)][string]$catalogName,[string]$catalogDescription,[Parameter(Mandatory=$true)][int]$numVmsToCreate,[string]$adminAddress,[Parameter(Mandatory=$true)][string]$namingScheme,[string]$OU,[Parameter(Mandatory=$true)][string]$domain,[Parameter(Mandatory=$true)][string]$masterImagePath)2.Set-HypAdminConnection-AdminAddress$adminAddress3.$hostingUnit=get-item$hostingUnitPath4.$hostConnection=$hostingUnit.hypervisorConnection5.$brokerHypConnection=Get-BrokerHypervisorConnection-HypHypervisorConnectionUid$hostConnection.HypervisorConnectionUid6.# Start logged operation7.$loggingOp=Start-LogHighLevelOperation-AdminAddress$adminAddress-Source'Scripted'-Text"Create Machine Catalog `'$catalogName`'"8.$loggingId=$loggingOp.Id9.# Create the broker catalog and the AD Identity account pool10.$catalog=New-BrokerCatalog-AllocationType'Permanent'-Description$catalogDescription-IsRemotePC$False-MinimumFunctionalLevel'L7'-Name$catalogName-PersistUserChanges'OnPvd'-ProvisioningType'MCS'-Scope@()-SessionSupport'SingleSession'-LoggingId$loggingId-AdminAddress$adminAddress11.$adPool=New-AcctIdentityPool-IdentityPoolName$catalogName-NamingScheme$namingScheme-NamingSchemeType'Numeric'-OU$OU-Domain$domain-AllowUnicode-LoggingId$loggingId-AdminAddress$adminAddress12.Set-BrokerCatalogMetadata-CatalogId$catalog.Uid-Name'Citrix_DesktopStudio_IdentityPoolUid'-Value$adPool.IdentityPoolUid-LoggingId$loggingId-AdminAddress$adminAddress13.###################################################################14.#create the ProvisioningScheme and wait for it to complete (reporting progress)15.$provSchemeTaskID=New-ProvScheme-ProvisioningSchemeName$catalogName-HostingUnitUID$hostingUnit.HostingUnitUID-IdentityPoolUID$adpool.IdentityPoolUid-CleanOnBoot-MasterImageVM$masterImagePath-UsePersonalVDiskStorage-PersonalVDiskDriveLetterP-PersonalVDiskDriveSize10-RunAsynchronously-LoggingId$loggingId-AdminAddress$adminAddress16.$ProvTask=get-provTask-TaskID$provSchemeTaskID-AdminAddress$adminAddress17.$taskProgress=018.write-host"Creating New ProvScheme"19.while($provTask.Active-eq$true)20.{21.# catch an uninitialized task progress, this occurs until the product initialized the value22.try{$totalPercent=if($provTask.TaskProgress){$provTask.TaskProgress}else{0}}catch{}23.Write-Progress-activity"Creating Provisioning Scheme:"-status"$totalPercent% Complete:"-percentcomplete$totalPercent24.sleep3025.$ProvTask=get-provTask-TaskID$provSchemeTaskID-AdminAddress$adminAddress26.}27.write-host"New ProvScheme Creation Finished"28.$provScheme=get-provScheme-ProvisioningSchemeUID$provTask.ProvisioningSchemeUid29.$controllers=Get-BrokerController|selectDNSName30.Add-ProvSchemeControllerAddress-ProvisioningSchemeUID$provScheme.ProvisioningSchemeUID-ControllerAddress$controllers-LoggingId$loggingId-AdminAddress$adminAddress31.###################################################################32.# Set the provisioning scheme id for the broker catalog33.Set-BrokerCatalog-InputObject$catalog-ProvisioningSchemeId$provTask.ProvisioningSchemeUid-LoggingId$loggingId-AdminAddress$adminAddress34.###################################################################35.# create the AD accounts required and then create the Virtual machines (reporting progress)36.$accts=New-AcctADAccount-IdentityPoolUid$adPool.IdentityPoolUid-Count$numVMsToCreate-LoggingId$loggingId-AdminAddress$adminAddress37.$provVMTaskID=New-ProvVM-ProvisioningSchemeUID$provScheme.ProvisioningSchemeUID-ADAccountName$accts.SuccessfulAccounts-RunAsynchronously-LoggingId$loggingId-AdminAddress$adminAddress38.# wait for the VMS to finish Provisioning39.$ProvTask=get-provTask-TaskID$provVMTaskID-AdminAddress$adminAddress40.while($provTask.Active-eq$true)41.{42.# catch an uninitialized task progress, this occurs until the product initialized the value43.try{$totalPercent=if($provTask.TaskProgress){$provTask.TaskProgress}else{0}}catch{}44.Write-Progress-activity"Creating Machines:"-status"$totalPercent% Complete:"-percentcomplete$totalPercent45.sleep546.$ProvTask=get-provTask-TaskID$provVMTaskID-AdminAddress$adminAddress47.}48.write-host"VM Creation Finished"49.# Lock the VMs and add them to the broker Catalog50.$provisionedVMs=get-ProvVM-ProvisioningSchemeUID$provScheme.ProvisioningSchemeUID-AdminAddress$adminAddress51.$provisionedVMs|Lock-ProvVM-ProvisioningSchemeUID$provScheme.ProvisioningSchemeUID-Tag'Brokered'-LoggingId$loggingId-AdminAddress$adminAddress52.$provisionedVMs|ForEach-Object{New-BrokerMachine-CatalogUid$catalog.UID-HostedMachineId$_.VMId-HypervisorConnectionUid$brokerHypConnection.UID-MachineName$_.ADAccountSid-LoggingId$loggingId-AdminAddress$adminAddress}53.Stop-LogHighLevelOperation-IsSuccessful$true-HighLevelOperationId$loggingId-AdminAddress$adminAddress