Start-AlIpsPrepare
SYNOPSIS
Starts the App Layering Image Portability Service (IPS) preparation phase for a disk image on its target platform.
SYNTAX
Start-AlIpsPrepare -ConnectorConfigId <String> -ProvisioningType <ProvisioningType> -SourceDisk <String>
-OutputDiskName <String> [-DomainUnjoin] [-PvsInstallVersion <String>] [-InstallUpl]
[-UpdateLayerRepo <String>] [-Chkdsk] [-Defrag] [-EnableRdp] [-Misa <IpsInstallType>]
[-Mcsio <IpsInstallType>] [-Tags <Hashtable>] [-XdReconfigure <InstallerParameter[]>] [-Timeout <TimeSpan>]
[-DebugSettings <Hashtable>] [-ConnectionId <Guid>] [<CommonParameters>]
<!--NeedCopy-->
DESCRIPTION
The Start-AlIpsPrepare cmdlet initiates the ‘prepare’ phase of the App Layering Image Portability Service (IPS).
This phase operates on a disk image that has already been placed onto the target platform (e.g., after being exported and copied, or directly uploaded).
Preparation modifies the image to ensure it runs correctly and optimally in the target environment. Key actions performed during preparation include:
- Removing components specific to the original source hypervisor (if any).
- Installing necessary drivers and agents for the target platform and chosen provisioning method (e.g., PVS Target Device drivers, MCS IO drivers, MCS security agent).
- Configuring Citrix components like the Virtual Delivery Agent (VDA) within the image.
- Optionally performing tasks such as domain unjoin, disk maintenance (chkdsk, defrag), enabling RDP, or updating the App Layering repository URL.
To run this command, you must provide:
- The platform-specific identifier for the source disk to be prepared (
-SourceDisk). - A desired name for the output disk (
-OutputDiskName). - The identifier of the connector configuration (
-ConnectorConfigId) that defines how to access the source platform environment where the disk resides. - The target Citrix provisioning method (Mcs or Pvs) (
-ProvisioningType).
This command initiates an asynchronous task that may run for a significant amount of time, depending on the disk size and environment.
You may need to use other cmdlets (e.g., Wait-AlTask) to monitor the progress and completion status of the prepare task.
EXAMPLES
Example 1
PS C:\> $xdReconfigure = @( @{ ParameterName = "controllers"; ParameterValue = "cloudy-cc1.wse2edev.cloudy cloudy-cc2.wse2edev.cloudy" }, @{ ParameterName = "portnumber"; ParameterValue = "80" } )
PS C:\> $tags = @{ MyTagName = "MyTagValue" }
PS C:\> Start-AlIpsPrepare -ConnectorConfigId '47251663-6710-4f76-854a-2385e3fe002d' -ProvisioningType Mcs -SourceDisk '/subscriptions/a874f766-6f7b-4367-9f3e-07e2458f83b8/resourceGroups/CloudyTargetDisks/providers/Microsoft.Compute/disks/w10-al-mcs' -OutputDiskName 'w10-al-mcs-out' -XdReconfigure $xdReconfigure -Tags $tags
<!--NeedCopy-->
This example first starts with creating an xdReconfigure with the value of @{ ParameterName = "controllers"; ParameterValue = "cloudy-cc1.wse2edev.cloudy cloudy-cc2.wse2edev.cloudy" }, @{ ParameterName = "portnumber"; ParameterValue = "80" }.
Then the user creates tags with the value of { MyTagName = "MyTagValue" } to add to the created disk.
The final command starts an IPS prepare task on the appliance using a connector with config Id '47251663-6710-4f76-854a-2385e3fe002d' using 'Mcs' as the provisioning type. It identifies the source disk as '/subscriptions/a874f766-6f7b-4367-9f3e-07e2458f83b8/resourceGroups/CloudyTargetDisks/providers/Microsoft.Compute/disks/w10-al-mcs' and setting the output disk name as 'w10-al-mcs-out'. The values xdReconfigure and tags created by the first two commands are also passed in as part of this command.
Example 2
PS C:\> Start-AlIpsPrepare -ConnectorConfigId '47251663-6710-4f76-854a-2385e3fe002d' -ProvisioningType Pvs -SourceDisk '/subscriptions/a874f768-6f7b-5368-9f3e-07e2452f83b9/resourceGroups/CLOUDYTARGETDISKS/providers/Microsoft.Compute/snapshots/Windows-Server2022' -OutputDiskName 'Windows-Server2022OUT' -PvsInstallVersion '2308' -Defrag
<!--NeedCopy-->
The above command will start an IPS prepare task on the appliance using a connector with config Id '47251663-6710-4f76-854a-2385e3fe002d' using 'Pvs' as the provisioning type. Since the provisioning type is 'Pvs', -PvsInstallVersion is provided and given the value '2308'. It identifies the source disk as '/subscriptions/a874f768-6f7b-5368-9f3e-07e2452f83b9/resourceGroups/CLOUDYTARGETDISKS/providers/Microsoft.Compute/snapshots/Windows-Server2022' and setting the output disk name as 'Windows-Server2022OUT'. The -Defrag flag is provided and will run the Windows Disk Defragmenter utility on the image’s filesystem during preparation.
Example 3
PS C:\> $DebugSettings = @{PreserveCeOnError = $true}
PS C:\> Start-AlIpsPrepare -ConnectorConfigId '47251663-6710-4f76-854a-2385e3fe002d' -ProvisioningType Mcs -SourceDisk '/subscriptions/a874f766-6f7b-4367-9f3e-07e2458f83b8/resourceGroups/CloudyTargetDisks/providers/Microsoft.Compute/disks/w10-al-mcs' -OutputDiskName 'w10-al-mcs-out' -Chkdsk -DomainUnjoin -DebugSettings $DebugSettings
<!--NeedCopy-->
This example first starts with creating debug settings with the value of @{PreserveCeOnError = $true}.
The second command starts an IPS prepare task on the appliance using a connector with config Id '47251663-6710-4f76-854a-2385e3fe002d' using 'Mcs' as the provisioning type. It identifies the source disk as '/subscriptions/a874f766-6f7b-4367-9f3e-07e2458f83b8/resourceGroups/CloudyTargetDisks/providers/Microsoft.Compute/disks/w10-al-mcs' and sets the output disk name as 'w10-al-mcs-out'. The -Chkdsk parameter will run the Windows Check Disk utility on the image’s filesystem during preparation to verify and attempt to fix integrity issues. The -DomainUnjoin parameter means the image will be actively removed from its current Active Directory domain during the preparation process. The debug settings from the first command are passed in, allowing the user to preserve the CE if an error occurs for troubleshooting purposes.
PARAMETERS
-Chkdsk
If specified, runs the Windows Check Disk utility on the image’s filesystem during preparation to verify and attempt to fix integrity issues.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-ConnectionId
Specifies the connection to the App Layering Appliance to use for this operation.
This is the GUID returned by Connect-AlAppliance.
If omitted, the command uses the current connection automatically if it’s the only one active. When multiple sessions are active, the GUID of the most recently used connection is used.
Type: Guid
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-ConnectorConfigId
Specifies the unique identifier (Id) of the App Layering connector configuration.
This configuration defines the source environment (e.g., hypervisor or cloud platform) where the disk specified by -SourceDisk is located and how to access it.
This parameter is mandatory.
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-DebugSettings
Provides advanced debugging options for the Image Portability Service prepare operation, specified as a PowerShell hashtable (e.g., @{ Setting1 = ‘Value1’; Setting2 = $True }). Use only when directed by specific troubleshooting guides or support personnel.
Type: Hashtable
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-Defrag
If specified, runs the Windows Disk Defragmenter utility on the image’s filesystem during preparation.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-DomainUnjoin
If specified, the image will be actively removed from its current Active Directory domain during the preparation process.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-EnableRdp
If specified, enables the Remote Desktop Protocol (RDP) feature within the Windows image during preparation, configuring the firewall and service to allow RDP connections after deployment.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-InstallUpl
If specified, installs the Citrix User Personalization Layer (UPL) feature into the image during preparation.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-Mcsio
Controls the installation behavior for the MCS Storage Optimization driver (MCSIO). Valid values:
- None: The driver will not be installed or modified. (Default)
- Install: Installs the driver version that matches the VDA found on the image.
- Force: Installs the latest available driver version known to IPS, potentially upgrading an existing one.
Type: IpsInstallType
Parameter Sets: (All)
Aliases:
Accepted values: None, Install, Force
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-Misa
Controls the installation behavior for the MCS security agent (MISA). Valid values:
- None: The agent will not be installed or modified. (Default)
- Install: Installs the driver version that matches the VDA found on the image.
- Force: Installs the latest available driver version known to IPS, potentially upgrading an existing one.
Type: IpsInstallType
Parameter Sets: (All)
Aliases:
Accepted values: None, Install, Force
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-OutputDiskName
Specifies the desired name for the new disk that will be created by IPS, containing the fully prepared image.
This parameter is mandatory.
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-ProvisioningType
Specifies the target Citrix provisioning method for which the image should be prepared. Valid values are:
- Mcs: Prepares the image for deployment via Machine Creation Services.
- Pvs: Prepares the image for deployment via Provisioning Services.
This choice influences component installation and configuration.
This parameter is mandatory.
Type: ProvisioningType
Parameter Sets: (All)
Aliases:
Accepted values: Pvs, Mcs
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-PvsInstallVersion
Required only when -ProvisioningType is Pvs.
Specifies the exact version of the PVS Target Device driver to install within the image during preparation.
The version string should match the target PVS server version (e.g., ‘2206’, ‘7.33’, ‘2203cu1’).
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-SourceDisk
Specifies the platform-specific identifier, path, or name of the disk image as it exists on the target platform that requires preparation.
The required format depends on the target platform defined by -ConnectorConfigId.
This parameter is mandatory.
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-Tags
Applies specified labels or tags to the primary output disk resource created during the prepare operation on supported cloud platforms. Provide tags as a hashtable.
Example: @{ Environment = 'Production'; CostCenter = '12345' }
Type: Hashtable
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-Timeout
Sets an optional time limit for the entire prepare operation. Specify the maximum duration (e.g., “02:00:00” for 2 hours, or use New-TimeSpan). If the prepare task exceeds this time limit, it fails with a timeout error. By default, there is no time limit.
Type: TimeSpan
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-UpdateLayerRepo
If specified, the App Layering layer repository URL in the image will be updated to the given value during preparation.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-XdReconfigure
Provides options to reconfigure an existing Citrix Virtual Delivery Agent (VDA) within the image using 'XenDesktopVdaSetup.exe /reconfigure'.
Supply parameters as an array of strings, each corresponding to a valid argument.
Example: @(\"/controllers=controller.domain.local\", \"/portnumber=8080\", \"/enable_hdx_ports\")
Supported options currently include /controllers, /portnumber, and /enable_hdx_ports.
Type: InstallerParameter[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS
None
OUTPUTS
[IpsPrepareResult]
Returns a task object representing the image preparation operation. This object contains a TaskId/WorkTicketId and can be piped to Wait-AlTask to monitor progress and await completion.
- WorkTicketId [Int64]
- Warning [String]
- WarningDetail [String]
- Error [ApplicationError]