The Create Virtual Machine operation creates a new virtual machine (VM) on the Microsoft Hyper-V server. This topic illustrates the actor adapter request and response and describes the elements used in the request.
The following table describes the elements for the adapter request:
Adapter request elements for the Create Virtual Machine operation
| | |
|---|
| Specifies the name of the operation: create-virtual-machine | |
| Contains the elements that specify the details for the VM to be created | |
| Contains a dynamic target configuration or uses a predefined target configuration of the Hyper-V server on which the request is executed Note: If you do not specify a dynamic target in the adapter request, the default adapter configuration is used. The <target> element contains the following elements: - <host>
- <user-name>
- <password>
- <timeout-secs>
| Conditional; required if a target is referenced or defined in the request |
| Specifies the host name or the IP address of the Hyper-V server
The <host> element applies to a dynamic target. | Conditional; required when defining a dynamic target |
| Specifies the user name to be used to connect to the Hyper-V server
The <user-name> element applies to a dynamic target. | Conditional; required when defining a dynamic target |
| Specifies the password that corresponds to the <user-name>provided
The <password> element applies to a dynamic target.
The <password> element can contain an encryption-typeattribute that indicates whether the password specified is encrypted.
Valid values for encryption-type: base64, plain (default) | Conditional; required if <user-name> is provided |
| Specifies the time, in seconds, after which the attempt to connect to the Hyper-V server fails
Default value: 60 | |
| Specifies the name of the virtual machine to be created | |
| Specifies the location for saving the VM files, including the snapshots The Hyper-V server has a default location that is used if no path is specified. | |
| Specifies the generation, as an integer, for the virtual machine Valid values: 1, 2 | |
| Specifies the amount of memory, in bytes, to assign to the virtual machine Default value: 512 MB | |
| Specifies the friendly name of the virtual switch if you want to connect the new virtual machine to an existing virtual switch to provide connectivity to a network Hyper-V automatically creates a virtual machine with one virtual network adapter, however you can connect it to a virtual switch is optional. | |
| Specifies one or more Hyper-V hosts on which the virtual machine is to be created NetBIOS names, IP addresses, and fully-qualified domain names are allowed. The default is the local computer — use “localhost” or a dot (“.”) to specify the local computer explicitly. | |
The following figure shows a sample <items> XML element for the Create Virtual Machine operation.
Sample <items> XML element for the Create Virtual Machine operation
<items>
<item>
<target>
<host>localhost</host>
<user-name>admin</user-name>
<password encryption-type="Base64">YWRtaW4=</password>
<timeout-secs>120</timeout-secs>
</target>
<name>Test_Virtual_Machine</name>
<computer-name>test-server.domain.com</computer-name>
<path>C:\vmfiles</path>
<generation>2</generation>
<switch-name> Default External Network </<switch-name>>
<memory-startup-bytes>512MB</memory-startup-bytes>
</item>
<item>
<target>config2</target>
<name>Test_Virtual_Machine</name>
<path>C:\vmfiles</path>
<generation>2</generation>
<memory-startup-bytes>512MB</memory-startup-bytes>
</item>
</items>
The following figure shows a sample adapter request for the Create Virtual Machine operation:
Sample adapter request for the Create Virtual Machine operation
<ms-hyperv-request>
<operation-name>create-virtual-machine</operation-name>
<arguments>
<target>
<host>localhost</host>
<user-name>admin</user-name>
<password encryption-type="Base64">YWRtaW4=</password>
</target>
<name>Test_Virtual_Machine</name>
<computer-name>test-server.domain.com</computer-name>
<path>C:\vmfiles</path>
<generation>2</generation>
<switch-name> Default External Network </<switch-name>>
<memory-startup-bytes>512MB</memory-startup-bytes>
</arguments>
</ms-hyperv-request>
The following figure shows a sample adapter response for the Create Virtual Machine operation:
Sample adapter response for the Create Virtual Machine operation
<ms-hyperv-response>
<metadata>
<status>success</status>
<response-count>1</response-count>
</metadata>
<responses>
<CreateVirtualMachineResponse>
<metadata>
<target>BW-HOU-DCA-DV01</target>
<status>success</status>
<count>1</count>
</metadata>
<items>
<item>
<vm-name>Test_Virtual_Machine12</vm-name>
<vm-id>4ff9263c-e49e-4490-be9a-c50d671d5291</vm-id>
<ps-computer-name>BW-HOU-DCA-DV01</ps-computer-name>
<runspace-id>f19f7d8a-e6a1-4c1a-8f01-d00b977059d6</runspace-id>
<id>4ff9263c-e49e-4490-be9a-c50d671d5291</id>
<name>Test_Virtual_Machine12</name>
<state>Off</state>
<integration-services-state></integration-services-state>
<operational-status>{Ok}</operational-status>
<primary-operational-status>Ok</primary-operational-status>
<secondary-operational-status></secondary-operational-status>
<status-descriptions>{Operating normally}</status-descriptions>
<primary-status-description>Operating normally</primary-status-description>
<secondary-status-description></secondary-status-description>
<status>Operating normally</status>
<heartbeat></heartbeat>
<replication-state>Disabled</replication-state>
<replication-health>NotApplicable</replication-health>
<replication-mode>None</replication-mode>
<cpu-usage>0</cpu-usage>
<memory-assigned>0</memory-assigned>
<memory-demand>0</memory-demand>
<memory-status></memory-status>
<smart-paging-file-in-use>False</smart-paging-file-in-use>
<uptime>00:00:00</uptime>
<integration-services-version></integration-services-version>
<resource-metering-enabled>False</resource-metering-enabled>
<configuration-location>C:\vmfiles1\Test_Virtual_Machine12</configuration-location>
<snapshot-file-location>C:\vmfiles1\Test_Virtual_Machine12</snapshot-file-location>
<automatic-start-action>StartIfRunning</automatic-start-action>
<automatic-stop-action>Save</automatic-stop-action>
<automatic-start-delay>0</automatic-start-delay>
<smart-paging-file-path>C:\vmfiles1\Test_Virtual_Machine12</smart-paging-file-path>
<numa-aligned></numa-aligned>
<numa-nodes-count>1</numa-nodes-count>
<numa-socket-count>1</numa-socket-count>
<key>Microsoft.HyperV.PowerShell.VirtualMachineObjectKey</key>
<is-deleted>False</is-deleted>
<computer-name>BW-HOU-DCA-DV01</computer-name>
<version>5.0</version>
<notes></notes>
<generation>1</generation>
<path>C:\vmfiles1\Test_Virtual_Machine12</path>
<creation-time>12/1/2014 3:08:48 AM</creation-time>
<is-clustered>False</is-clustered>
<size-of-system-files>31786</size-of-system-files>
<parent-snapshot-id></parent-snapshot-id>
<parent-snapshot-name></parent-snapshot-name>
<memory-startup>536870912</memory-startup>
<dynamic-memory-enabled>False</dynamic-memory-enabled>
<memory-minimum>536870912</memory-minimum>
<memory-maximum>1099511627776</memory-maximum>
<processor-count>1</processor-count>
<remote-fx-adapter></remote-fx-adapter>
<network-adapters>{Microsoft.HyperV.PowerShell.VMNetworkAdapter}</network-adapters>
<fibre-channel-host-bus-adapters>{}</fibre-channel-host-bus-adapters>
<com-port1>Microsoft.HyperV.PowerShell.VMComPort</com-port1>
<com-port2>Microsoft.HyperV.PowerShell.VMComPort</com-port2>
<floppy-drive>Microsoft.HyperV.PowerShell.VMFloppyDiskDrive</floppy-drive>
<dvd-drives>{Microsoft.HyperV.PowerShell.DvdDrive}</dvd-drives>
<hard-drives>{}</hard-drives>
<vm-integration-service>{Microsoft.HyperV.PowerShell.VMIntegrationComponent, Microsoft.HyperV.PowerShell.VMIntegrationComponent, Microsoft.HyperV.PowerShell.DataExchangeComponent,Microsoft.HyperV.PowerShell.ShutdownComponent...}</vm-integration-service>
</item>
</items>
</CreateVirtualMachineResponse>
</responses>
</ms-hyperv-response>