New-SCVMCheckpoint
Creates a checkpoint for a virtual machine deployed on a host managed by VMM.
Syntax
New-SCVMCheckpoint
[-VM] <VM>
[-VMMServer <ServerConnection>]
[-Description <String>]
[-Name <String>]
[-RunAsynchronously]
[-PROTipID <Guid>]
[-JobVariable <String>]
[-WhatIf]
[-Confirm]
[-OnBehalfOfUser <String>]
[-OnBehalfOfUserRole <UserRole>]
[<CommonParameters>]Description
The New-SCVMCheckpoint cmdlet creates a checkpoint for a virtual machine deployed on a host managed by Virtual Machine Manager (VMM). You can use a checkpoint to restore a virtual machine to a previous state.
A typical use is to create a checkpoint before you install an update to the operating system or to an application on the virtual machine so that, if the update fails or adversely affects the virtual machine, you can use the Restore-SCVMCheckpoint cmdlet to revert the virtual machine to its previous state.
For virtual machines deployed on a Hyper-V host, VMware ESX host, or Citrix XenServer host, VMM creates the checkpoint without stopping the virtual machine, so no interruption in service occurs.
It is important to back up data files on a virtual machine before you restore the virtual machine to a checkpoint. When you restore the virtual machine, user data files on its virtual hard disks are returned to their previous state.
Although checkpoints let you restore a virtual machine to a previous state after a change such as a system or application update, checkpoints do not provide a permanent backup of the operating system, applications, or files. Checkpoints are stored with the virtual machine on the host. Therefore, if the host fails, checkpoints for virtual machines deployed on that host are lost.
To provide data protection for your virtual machines, you can use the Volume Shadow Copy Service (VSS). You can use a backup application such as Data Protection Manager (DPM) to back up virtual machines on any type of host to external storage.
You can grant self-service users permission to create and manage checkpoints for their virtual machines.
For more information, type Get-Help Set-VMMUserRole -Detailed.
Examples
Example 1: Create a virtual machine checkpoint for virtual machines that have the same name but reside on different hosts
PS C:\> $Checkpoints = Get-SCVirtualMachine -Name "VM01" | New-SCVMCheckpoint
PS C:\> $CheckpointsThe first command gets the virtual machine objects named VM01 (this example assumes that more than one host contains a virtual machine named VM01), creates a checkpoint for each virtual machine object, and then stores the checkpoint objects in the $Checkpoints object array.
The second command displays information about each checkpoint object stored in $Checkpoints to the user.
Example 2: Create a virtual machine checkpoint for a virtual machine asynchronously
PS C:\> Get-SCVirtualMachine -Name "VM02" | New-SCVMCheckpoint -RunAsynchronously -JobVariable "NewCheckpiontJob"
PS C:\> Write-Host $NewCheckpointJobThis example creates checkpoints in the same manner as Example 1 except that this command uses the RunAsynchronously parameter to return control to the command shell immediately, and uses the JobVariable parameter to track job progress and store a record of the progress in the NewCheckpointJob variable. When you use the JobVariable parameter, you do not use the dollar sign ($) to create the variable.
The second command displays the contents of $NewCheckpointJob.
Parameters
-Confirm
Prompts you for confirmation before running the cmdlet.
| Type: | SwitchParameter |
| Aliases: | cf |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Description
Specifies a description for the checkpoint.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-JobVariable
Specifies that job progress is tracked and stored in the variable named by this parameter.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Name
Specifies the name of a VMM object.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-OnBehalfOfUser
Specifies the name of a user. This cmdlet sets the on behalf of user as the user that this parameter specifies.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-OnBehalfOfUserRole
Specifies a user role. To obtain a user role, use the Get-SCUserRole cmdlet. This cmdlet operates on behalf of the user role that this parameter specifies.
| Type: | UserRole |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PROTipID
Specifies the ID of the Performance and Resource Optimization tip (PRO tip) that triggered this action. This parameter lets you audit PRO tips.
| Type: | Guid |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-RunAsynchronously
Indicates that the job runs asynchronously so that control returns to the command shell immediately.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-VM
Specifies a virtual machine object.
| Type: | VM |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-VMMServer
Specifies a VMM server object.
| Type: | ServerConnection |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet is not run.
| Type: | SwitchParameter |
| Aliases: | wi |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Outputs
VMCheckpoint
This cmdlet returns a VMCheckpoint object.