3.10.2 Delete virtual server
Function
This service template deletes virtual servers in a Hyper-V environment.
This service template requires the following servers:
- Hyper-V server
A server on which Hyper-V is installed
- Virtual server
A virtual server managed by Hyper-V
The following is an overview of the processing:
(1) The task obtains the status of the virtual server.
(2) The task confirms that the virtual server is not running.
If the virtual server is not running, the task continues processing. In all other cases, the task executes the User-Response Wait plug-in to check whether the virtual server is to be shut down.
If you select "Shutdown" from the GUI of the User-Response Wait plug-in, the running virtual server is shut down. If you select "Shutdown" for a virtual server that is not running, the task terminates abnormally without performing any operations on the virtual server.
If you select "Cancel" or the wait for a user response times out, the task terminates abnormally without performing any operations on the virtual server.
(3) The task deletes the virtual server.
The virtual server is deleted from the Hyper-V server. At this time, all snapshots for that virtual server are also deleted.
If you select "yes" from the selection list for the property hyperv.vHardDiskDeletePermanently, the task deletes all (dynamic, fixed, and differential) virtual disk files that are allocated to the virtual server that is to be deleted. The task does not delete disks or files that are allocated to pass-through (physical) disks, floppy disks, CDs or DVDs. If differential virtual disks are allocated to the virtual server, the task does not delete the virtual disks that are used as the parents of those differential virtual disks.
If the attempt to delete virtual disk files on the virtual server fails, the file deletion processing stops, and the task terminates abnormally.
(4) The task outputs a list of virtual disk files on the virtual server.
If the properties hyperv.vhdListOutputFileNameRemote and hyperv.vhdListOutputFileNameLocal are specified, the task outputs a CSV file that lists the paths of the virtual disk files allocated to the virtual server that is to be deleted from the Hyper-V server. The task then transfers the CSV file to the local PC and deletes the CSV file from the remote PC. If differential virtual disks are allocated to the virtual server, the virtual disks that are used as the parents of those differential virtual disks are not included in the CSV file.
If only the property hyperv.vhdListOutputFileNameRemote is specified, the task outputs a CSV file that lists the paths of the virtual disk files, but does not transfer the CSV file to the local PC.
The following items are output to the file in CSV (comma-separated value) format:
(a) Whether virtual disk files exist (header name: Existence)
Depending on whether virtual disk files are allocated to the virtual server when the server is deleted, one of the following values is output:
Found: Existence of virtual disk files was confirmed.
NotFound: Virtual disk files were set up, but their existence could not be confirmed.
(b) File deletion result (header name: DeleteResult)
If you select "yes" from the selection list for the property hyperv.vHardDiskDeletePermanently, the task outputs the result of deleting the virtual disk files. If you select "no", "Skipped" is output. For the deletion result, one of the following values is output:
Completed: File deletion finished successfully.
Failed: File deletion failed.
Skipped: File deletion was not performed.
(c) File path (header name: FilePath)
The paths of the virtual disk files set for the Hyper-V server are output, regardless of the values in (a) and (b).
Prerequisites
For the most recent information about the prerequisite products for the system, prerequisite products for the system executing the service templates, and the supported OSs for the prerequisite products for the system executing the service templates, see the Release Notes.
Prerequisite product for the system:
JP1/Automatic Operation 12-00 or later
Prerequisite products in the system executing the service template:
(1) Prerequisite product for the Hyper-V server
- Windows Server 2016 Hyper-V
Supported OSs for the prerequisite products in the system executing the service template:
(1) OS of the Hyper-V server
- Windows Server 2016 Standard/Datacenter
Note: Environments where Server Core/Nano Server is installed are excluded.
(2) OS of the virtual server
- Windows Server 2012 Standard/Datacenter, Windows Server 2012 R2 Standard/Datacenter
- Windows Server 2016 Standard/Datacenter
Note: Environments where Server Core/Nano Server is installed are excluded.
Conditions for using the prerequisite products on the system executing the service template:
(1) The name of each virtual server on the Hyper-V server must be unique.
(2) The following service of Hyper-V Integration Services must be enabled on the target virtual server:
- Operating System Shutdown
Cautions
(1) Do not concurrently execute multiple instances of this service on the same virtual server.
(2) If you previously performed an operation (such as a snapshot-related operation) to make the path of a virtual disk file invisible in the virtual server settings, this service will not delete that virtual disk file. In such a case, manually delete the virtual disk file.
(3) You can specify HTML tags for the property UserResponseplugin.dialogText. The specifiable tags and attributes are the same as those for the User-Response Wait plug-in. For details, see the topic about the User-Response Wait plug-in in this product manual.
(4) If you specify an existing file for the property hyperv.vhdListOutputFileNameRemote or hyperv.vhdListOutputFileNameLocal, the existing file is overwritten. In addition, the file on the remote PC will be deleted, so make sure the specified file name is correct.
(5) If you specify a path that includes non-existent folders for the property hyperv.vhdListOutputFileNameRemote, those folders are automatically created but not automatically deleted. Periodically delete these folders if they are unnecessary.
(6) If you specify the property hyperv.vhdListOutputFileNameRemote, a file is output to the remote PC even if the property hyperv.vhdListOutputFileNameLocal is not specified or if an error occurs during the deletion of the virtual server or virtual disk file. Because this service does not delete the output file, manually delete the file if it is unnecessary.
(7) This service does not delete the registration information of virtual servers from any services and applications of the failover cluster manager. Manually delete the registration information based on the user operational requirements.
(8) If you select "Shutdown" from the GUI of the User-Response Wait plug-in, the OS of the virtual server is forcibly shut down. Data in files that are being edited on the virtual server will not be saved.
Version
03.00.00
Tags
Delete VM,Hyper-V 2016
Property list
The following shows the list of the property groups set in the property:
|
Property group |
Description |
Initial display |
|---|---|---|
|
Virtual system environment information |
Specify Hyper-V information. |
Y |
|
Virtual server information |
Specify information about the virtual server to be deleted. |
Y |
|
Output file storage information |
If necessary, specify the storage destination for the file to be output. |
N |
|
User-response wait option |
This option is used when user response is required after a virtual server is started. Change the settings of this option as necessary. |
N |
The following shows the list of the properties to be displayed in the "Service Definition" window:
- (Legend)
-
R: The property must be specified.
O: The property can be omitted. However, the property might be mandatory depending on what is specified for other properties. See the Description of each property.
|
Property key |
Property name |
Description |
I/O type |
Shared |
Required |
Property group |
|---|---|---|---|---|---|---|
|
hyperv.targetHost |
Hyper-V server host name |
Specifies the host name or IP address of the Hyper-V server. IPv6 addresses are not supported. |
Input |
Disabled |
R |
Virtual system environment information |
|
UserResponsePlugin.toAddress |
TO addresses |
Specify the email addresses to enter in the TO field of notification emails sent when the service is waiting for a user response. Separate multiple addresses with commas. Example: mailA,mailB |
Input |
Disabled |
O |
User-response wait option |
|
UserResponsePlugin.ccAddress |
CC addresses |
Specify the email addresses to enter in the CC field of notification emails sent when the service is waiting for a user response. Separate multiple addresses with commas. Example: mailA,mailB |
Input |
Disabled |
O |
User-response wait option |
|
UserResponsePlugin.bccAddress |
BCC addresses |
Specify the email addresses to enter in the BCC field of notification emails sent when the service is waiting for a user response. Separate multiple addresses with commas. Example: mailA,mailB |
Input |
Disabled |
O |
User-response wait option |
|
UserResponsePlugin.mailSubject |
Subject line |
Specify the subject line of notification emails sent when the service is waiting for a user response. |
Input |
Disabled |
O |
User-response wait option |
|
UserResponsePlugin.mailBody |
Email text |
Specify the body text of notification emails sent when the service is waiting for a user response. |
Input |
Disabled |
O |
User-response wait option |
|
UserResponsePlugin.encodeType |
Encoding |
Specify the encoding of notification emails sent when the service is waiting for a user response. The encodings you can specify are us-ascii, iso-2022-jp, shift_jis, euc-jp, and utf-8. If you omit this property, utf-8 is set. |
Input |
Disabled |
O |
User-response wait option |
|
UserResponsePlugin.dialogText |
Additional dialog box text |
Enter additional text to appear in the response input dialog box, in text or HTML format. Supported HTML tags are anchor tags, bold tags, break tags, font tags, italics tags, and underline tags. |
Input |
Disabled |
O |
User-response wait option |
|
UserResponsePlugin.responseTimeOut |
Response timeout time (minutes) |
Specify how long (in minutes) the service waits for a user response before timing out. In the event of a response timeout, the service will terminate abnormally. |
Input |
Disabled |
R |
User-response wait option |
The following shows the list of the properties to be displayed on the "Service Definition" window and the "Submit Service" window:
|
Property key |
Property name |
Description |
I/O type |
Shared |
Required |
Property group |
|---|---|---|---|---|---|---|
|
hyperv.vmName |
Virtual server name |
Specifies the name of the virtual server. (This is the name of the virtual server as it is displayed in Hyper-V. This is not the host name in the OS.) |
Input |
Disabled |
R |
Virtual server information |
|
hyperv.vHardDiskDeletePermanently |
Deletion of virtual disk file required |
Specifies whether to delete virtual disk file used for the virtual server. |
Input |
Disabled |
R |
Virtual server information |
|
hyperv.vhdListOutputFileNameRemote |
Output file name (remote) |
Specifies, as a full path, the temporary file name for when the virtual disk file list used by the virtual server is output to the Hyper-V server. |
Input |
Disabled |
O |
Output file storage information |
|
hyperv.vhdListOutputFileNameLocal |
Output file name (local) |
Specifies the name of the file (in full-path format) that contains the list of virtual disk files to be saved to the local server. |
Input |
Disabled |
O |
Output file storage information |
The following shows the restrictions on inputs to the properties displayed in the "Service Definition" window:
|
Property key |
Characters that can be input |
|---|---|
|
hyperv.targetHost |
Enter up to 256 halfwidth alphanumeric characters. You can also use periods (.) and hyphens (-). |
|
UserResponsePlugin.toAddress |
A maximum of 1024 characters can be entered. Characters that can be used include alphanumeric characters and symbols. |
|
UserResponsePlugin.ccAddress |
A maximum of 1024 characters can be entered. Characters that can be used include alphanumeric characters and symbols. |
|
UserResponsePlugin.bccAddress |
A maximum of 1024 characters can be entered. Characters that can be used include alphanumeric characters and symbols. |
|
UserResponsePlugin.mailSubject |
A character string of no more than 256 characters can be entered. |
|
UserResponsePlugin.mailBody |
A character string of no more than 1024 characters can be entered. |
|
UserResponsePlugin.encodeType |
Select one of the following values: us-ascii,iso-2022-jp,shift_jis,euc-jp,utf-8 |
|
UserResponsePlugin.dialogText |
A character string of no more than 512 characters can be entered. |
|
UserResponsePlugin.responseTimeOut |
Integer between 1 and 9999 can be entered. |
The following shows the restrictions on inputs to the property displayed on the "Service Definition" window and the "Submit Service" window:
|
Property key |
Characters that can be input |
|---|---|
|
hyperv.vmName |
Enter a character string of up to 100 characters. The character string must not start with a space, end with a space or period (.), or contain the following characters: < > | ; & ' " * ? [ ] ` , % \ / : |
|
hyperv.vHardDiskDeletePermanently |
Select one of the following values: yes,no |
|
hyperv.vhdListOutputFileNameRemote |
Enter a character string of up to 256 characters. The character string must not end with a backslash (\) or contain the following characters: < > | ; & * ? " % / ' [ ] ` |
|
hyperv.vhdListOutputFileNameLocal |
Enter no more than 256 characters. Do not include the following characters: < > | ; & * ? " % or a trailing \ or / |
Flow specification details
The following table shows the detailed specification of the flow:
|
Hierarchy |
Display name |
Plug-in |
||
|---|---|---|---|---|
|
Plug-in name |
Description |
Error recovery method |
||
|
1 |
hyperv2016CheckVMState |
Flow Plug-in |
Checks the status of a virtual server. If the virtual server is running, this plug-in asks the user whether the virtual server is to be stopped. |
-- |
|
1-2 |
Obtain virtual server status |
Obtains the status of the specified virtual server. |
After removing the cause of the error, run the service again. |
|
|
1-3 |
Judge Value Plug-in |
Checks whether a virtual server has stopped. |
After removing the cause of the error, run the service again. |
|
|
1-4 |
Flow Plug-in |
Asks the user whether the virtual server is to be stopped. If the user chooses to stop it, this plug-in shuts down the virtual server. |
-- |
|
|
1-4-1 |
User-Response Wait Plug-in |
Asks the user whether the virtual server is to be stopped, and then waits for the user's response. |
After removing the cause of the error, run the service again. |
|
|
1-4-2 |
Obtain virtual server status |
Obtains the status of the specified virtual server. |
After removing the cause of the error, run the service again. |
|
|
1-4-3 |
Judge Value Plug-in |
Checks whether a virtual server has stopped. |
After removing the cause of the error, run the service again. |
|
|
1-4-4 |
Shut down virtual server |
Shuts down a virtual server. |
After removing the cause of the error, run the service again. |
|
|
2 |
hyperv2016DeleteVM |
Delete virtual server |
Deletes a virtual server. |
If the virtual server has not been deleted, remove the cause of the error, and then run the service again. If the virtual server has been deleted, check whether virtual disk files exist. If a list of virtual disk files was output, check the files on the Hyper-V server. If necessary, manually delete the virtual disk files. |
|
3 |
outputFileTransfer |
Flow Plug-in |
Forwards a list of virtual disk files. |
-- |
|
3-1 |
Judge Value Plug-in |
Checks whether the name of the file (remote) where the list of virtual disk files is to be output is specified. |
If a list of virtual disk files was output, this list remains on the Hyper-V server. Manually delete this list. |
|
|
3-2 |
Flow Plug-in |
Forwards a list of virtual disk files. |
-- |
|
|
3-2-1 |
Judge Value Plug-in |
Checks whether the name of the file (local) where the list of virtual disk files is to be output is specified. |
If a list of virtual disk files was output, this list remains on the Hyper-V server. Manually delete this list. |
|
|
3-2-2 |
Flow Plug-in |
Forwards a list of virtual disk files. |
-- |
|
|
3-2-2-1 |
File-Forwarding Plug-in |
Forwards the remote temporary file to the specified local output file. |
A list of virtual disk files remains on the Hyper-V server. Manually delete this list. |
|
|
3-2-2-2 |
Delete file |
Deletes the remote temporary file. |
A list of virtual disk files remains on the Hyper-V server. Manually delete this list. |
|