Start-AlIpsExport
SYNOPSIS
Initiates the export of a source disk image using the App Layering Image Portability Service (IPS).
SYNTAX
Start-AlIpsExport -ConnectorConfigId <String> -SourceDisk <String> -OutputDiskName <String>
[-Timeout <TimeSpan>] [-Force] [-DebugSettings <Hashtable>] [-ConnectionId <Guid>] [<CommonParameters>]
<!--NeedCopy-->
DESCRIPTION
The Start-AlIpsExport cmdlet begins the process of exporting a specified source disk image into a portable VHD or VHDX format using the App Layering Image Portability Service (IPS).
This functionality is key to migrating virtual machine images between different virtualization or cloud platforms by creating a standardized disk file compatible with various environments.
To run this command, you must provide:
- The platform-specific identifier for the source disk to be exported (
-SourceDisk). - A desired name for the output VHD(X) file (
-OutputDiskName). - The identifier of the connector configuration (
-ConnectorConfigId) that defines how to access the source platform environment where the disk resides.
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 export task.
EXAMPLES
Example 1
PS C:\> Start-AlIpsExport -ConnectorConfigId "063A0697-ACDF-43BB-969B-AA69F1419757" -SourceDisk "[DatastoreName] VMFolder/disk.vmdk" -OutputDiskName "MyExportedDisk" -Timeout 02:00 -Force -DebugSettings @{PreserveCe = $true, PreserveCeOnError = $true}
<!--NeedCopy-->
The above command will start an IPS export task on the appliance. It uses the connector with config Id '063A0697-ACDF-43BB-969B-AA69F1419757' to export disk '[DatastoreName] VMFolder/disk.vmdk'. The -Force parameter will cause the operation to overwrite any existing file in the location specified by the connector with the same name as the specified output disk name plus extension (MyExportedDisk.vhd or MyExportedDisk.vhdx depending on connector settings). It has a timeout of two hours with debug settings to preserve the CE for troubleshooting.
PARAMETERS
-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 as well as the export location 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 export operation, specified as a PowerShell hashtable (e.g., @{ Setting1 = 'Value1'; Setting2 = $True }).
Use this parameter 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-->
-Force
Allows the operation to overwrite the output disk file (specified by -OutputDiskName) if it already exists in the target location managed by IPS.
Without this switch, the command will fail if the target output file name is already present.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-OutputDiskName
Specifies the desired name for the resulting VHD or VHDX file that will be created by the export process in the location defined by the connector configuration -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-->
-SourceDisk
Specifies the platform-specific identifier, path, or name of the disk image to be exported.
The required format for this value depends on the source platform defined by the associated -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-->
-Timeout
Sets an optional time limit for the entire export operation. Specify the maximum duration (e.g., “02:00:00” for 2 hours, or use New-TimeSpan). If the export 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-->
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
[IpsExportResult]
Returns a task object representing the export 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]
NOTES
PowerShell includes the following aliases for Start-AlIpsExport:
Start-AlIpsPublish