Share via

Create a Virtual Machine from a VM Template (SPF)

  • Article

This page is now retired and kept for archival purposes. This programming guide has been published on MSDN at http://msdn.microsoft.com/library/jj643273.aspx

This article is part of the [[Service Provider Foundation Programmers Guide (SPF)]].

Virtual machine (VM) templates are powerful because they allow you to create a new VM from a preconfigured VM, known as a template. The template provides settings like the hardware configuration and the virtual hard disks used. To create a VM in Service Provider Foundation you must know which stamp and cloud the virtual machine will be assigned to, as well as the identifier of the VM template that will be used to generate the VM.

Warning
The virtual hard disk (VHD) that is attached to the template must be bootable. If it is not bootable, Virtual Machine Manager (VMM) locks the newly created VM and you must reconfigure the VM by using VM host management software such as Microsoft Hyper-V.

The key properties you must set on the virtual machine object used with the Service Provider Foundation service are:

  • CloudId
  • StampId
  • VMTemplateId
  • Name

Depending on the operating system used, you most likely will need to set the ProductKey, LocalAdminUserName, and LocalAdminPassword properties. The values used for these properties will depend on the specific operating system image that is installed on the VHD.

To create a new virtual machine with .NET

  1. Connect to the Service Provider Foundation VMM service.

  2. Create a new instance of the SpfVMM.VirtualMachine class.

  3. Set the CloudId property of the virtual machine.

  4. Set the StampId property of the virtual machine.

  5. Set the VMTemplateId property to the System.Guid of the template.

  6. Set the Name property of the virtual machine.

  7. Provide the provisioning settings used by the template. Generally, these are set by the Organization, ProductKey, LocalAdminUserName, and LocalAdminPassword properties.

  8. Call the AddToVirtualMachines method on the VMM service object reference, and pass in the virtual machine reference.

  9. Call the SaveChanges method on the VMM service object reference.

To create a new virtual machine with HTTP

  1. Create a new HTTP Post operation.

  2. Set the URL to the appropriate URI: https:// server:30006/subscription-id/services/systemcenter/vmm/VirtualMachines

  3. Add the HTTP headers.

    Specifically, add the x-ms-principal-id header, which can be set to any value.

  4. Create the HTTP payload containing the virtual machine entity.

  5. Submit the HTTP request.

Example

The following example shows how to create a virtual machine using .NET. For more information, see Programming in Visual Studio with Service Provider Foundation Services.

SpfVMM.VMM vmmService = new SpfVMM.VMM(new Uri("https://wapserver:30006/97FD50F3-1DC0-41B6-A7C0-2B4FF4C3F7E3/services/systemcenter/vmm/"));
vmmService.Credentials = System.Net.CredentialCache.DefaultNetworkCredentials;
 
var template = vmmService.VMTemplates.Where(te => te.ID == new Guid("ed94037b-baab-4ce3-b57c-f4e3a00e585b"));
var cloud = vmmService.Clouds.Where(cl => cl.ID == new Guid("a5397df8-517c-4939-ba07-0a9a2c2c2d56"));
var stamp = template.First().StampId;
             
var vm = new SpfVMM.VirtualMachine();
vm.VMTemplateId = new Guid("ed94037b-baab-4ce3-b57c-f4e3a00e585b");
vm.CloudId  = new Guid("a5397df8-517c-4939-ba07-0a9a2c2c2d56");
vm.StampId = stamp;
 
vm.LocalAdminPassword = "abcdefg123!";
vm.LocalAdminUserName = "Administrator";
vm.Name = "Temp Machine Name";
vm.ComputerName = "Contoso1";
vm.StartVM = true;
 
vmmService.AddToVirtualMachines(vm);
vmmService.SaveChanges();

The following is an example HTTP request sent to the server:

POST https://wapserver:30006/97FD50F3-1DC0-41B6-A7C0-2B4FF4C3F7E3/services/systemcenter/vmm/VirtualMachines HTTP/1.1
DataServiceVersion: 3.0;NetFx
MaxDataServiceVersion: 3.0;NetFx
Accept: application/json;odata=minimalmetadata
Accept-Charset: UTF-8
DataServiceUrlConventions: KeyAsSegment
User-Agent: Microsoft ADO.NET Data Services
x-ms-principal-id: user@contoso.com
Content-Type: application/json;odata=minimalmetadata
Host: wapserver:30006
Content-Length: 3785
Expect: 100-continue

{
    "AddedTime": null,
    "Agent": null,
    "AllocatedGPU": null,
    "BackupEnabled": null,
    "BlockDynamicOptimization": null,
    "BlockLiveMigrationIfHostBusy": null,
    "CPUCount": null,
    "CPULimitForMigration": null,
    "CPULimitFunctionality": null,
    "CPUMax": null,
    "CPURelativeWeight": null,
    "CPUReserve": null,
    "CPUType": null,
    "CPUUtilization": null,
    "CanVMConnect": null,
    "CapabilityProfile": null,
    "CheckpointLocation": null,
    "CloudId": "a5397df8-517c-4939-ba07-0a9a2c2c2d56",
    "CloudVMRoleName": null,
    "ComputerName": "ContosoVM",
    "ComputerTierId": null,
    "CostCenter": null,
    "CreationSource": null,
    "CreationTime": null,
    "DataExchangeEnabled": null,
    "DelayStart": null,
    "DelayStartSeconds": null,
    "DeployPath": null,
    "DeploymentErrorInfo": {
        "CloudProblem": null,
        "Code": null,
        "DetailedCode": null,
        "DetailedErrorCode": null,
        "DetailedSource": null,
        "DisplayableErrorCode": null,
        "ErrorCodeString": null,
        "ErrorType": null,
        "ExceptionDetails": null,
        "IsConditionallyTerminating": null,
        "IsDeploymentBlocker": null,
        "IsMomAlert": null,
        "IsSuccess": null,
        "IsTerminating": null,
        "MessageParameters": null,
        "MomAlertSeverity": null,
        "Problem": null,
        "RecommendedAction": null,
        "RecommendedActionCLI": null,
        "ShowDetailedError": null,
        "odata.type": "VMM.ErrorInfo"
    },
    "Description": null,
    "DiskIO": null,
    "Dismiss": null,
    "Domain": null,
    "DynamicMemoryBufferPercentage": null,
    "DynamicMemoryDemandMB": null,
    "DynamicMemoryEnabled": null,
    "DynamicMemoryMaximumMB": null,
    "Enabled": null,
    "ExcludeFromPRO": null,
    "ExpectedCPUUtilization": null,
    "FailedJobID": null,
    "FullName": null,
    "GrantedToList": [],
    "GrantedToList@odata.type": "Collection(VMM.UserAndRole)",
    "HardwareProfileId": null,
    "HasPassthroughDisk": null,
    "HasSavedState": null,
    "HasVMAdditions": null,
    "HeartbeatEnabled": null,
    "HighlyAvailable": null,
    "ID": "00000000-0000-0000-0000-000000000000",
    "IsFaultTolerant": null,
    "IsHighlyAvailable": null,
    "IsRecoveryVM": null,
    "IsUndergoingLiveMigration": null,
    "LastRestoredCheckpointId": null,
    "LibraryGroup": null,
    "LimitCPUForMigration": null,
    "LimitCPUFunctionality": null,
    "LinuxAdministratorSSHKey": null,
    "LinuxAdministratorSSHKeyString": null,
    "LinuxDomainName": null,
    "LocalAdminPassword": "!!123abc",
    "LocalAdminRunAsAccountName": null,
    "LocalAdminUserName": "Administrator",
    "Location": null,
    "MarkedAsTemplate": null,
    "Memory": null,
    "MemoryAssignedMB": null,
    "MemoryAvailablePercentage": null,
    "MemoryWeight": null,
    "ModifiedTime": null,
    "MostRecentTaskId": null,
    "Name": "Temp Machine Name",
    "NetworkUtilization": null,
    "NewVirtualNetworkAdapterInput": [],
    "NewVirtualNetworkAdapterInput@odata.type": "Collection(VMM.NewVMVirtualNetworkAdapterInput)",
    "NumLock": null,
    "OSType": null,
    "OperatingSystem": null,
    "OperatingSystemId": null,
    "OperatingSystemShutdownEnabled": null,
    "Operation": null,
    "OrganizationName": null,
    "Owner": {
        "RoleID": null,
        "RoleName": null,
        "UserName": null,
        "odata.type": "VMM.UserAndRole"
    },
    "Password": null,
    "Path": null,
    "PerfCPUUtilization": null,
    "PerfDiskBytesRead": null,
    "PerfDiskBytesWrite": null,
    "PerfNetworkBytesRead": null,
    "PerfNetworkBytesWrite": null,
    "ProductKey": null,
    "Retry": null,
    "RunAsAccountUserName": null,
    "RunGuestAccount": null,
    "ServiceDeploymentErrorMessage": null,
    "ServiceId": null,
    "SharePath": null,
    "SourceObjectType": null,
    "StampId": "ba4146fa-fb41-4f59-a193-ad00c52a138c",
    "StartAction": null,
    "StartVM": true,
    "Status": null,
    "StatusString": null,
    "StopAction": null,
    "Tag": null,
    "TimeSynchronizationEnabled": null,
    "TimeZone": null,
    "TotalSize": null,
    "Undo": null,
    "UndoDisksEnabled": null,
    "UpgradeDomain": null,
    "UseCluster": null,
    "UseLAN": null,
    "UserName": null,
    "VMBaseConfigurationId": null,
    "VMCPath": null,
    "VMConfigResource": null,
    "VMHostName": null,
    "VMId": null,
    "VMNetworkAssignments": [],
    "VMNetworkAssignments@odata.type": "Collection(VMM.VMNetworkAssignment)",
    "VMResource": null,
    "VMResourceGroup": null,
    "VMTemplateId": "ed94037b-baab-4ce3-b57c-f4e3a00e585b",
    "VirtualHardDiskId": null,
    "VirtualMachineState": null,
    "VirtualizationPlatform": null,
    "WorkGroup": null,
    "odata.type": "VMM.VirtualMachine"
}

The following is an example HTTP response from the server:

HTTP/1.1 201 Created
Cache-Control: no-cache
Content-Length: 4066
Content-Type: application/json;odata=minimalmetadata;streaming=true;charset=utf-8
Location: https://wapserver:30006/97FD50F3-1DC0-41B6-A7C0-2B4FF4C3F7E3/services/systemcenter/vmm/VirtualMachines(ID=guid'2fa28d03-8d6d-486b-ae61-9694a2db5d6f',StampId=guid'ba4146fa-fb41-4f59-a193-ad00c52a138c')
Server: Microsoft-IIS/8.5
x-ms-request-id: 1f8a3a06-03d7-4b5d-ac04-a9a167068f0a
X-Content-Type-Options: nosniff
request-id: eda9bde6-834a-0000-e979-abed4a83ce01
DataServiceVersion: 3.0;
X-AspNet-Version: 4.0.30319
Persistent-Auth: true
X-Powered-By: ASP.NET
Date: Fri, 02 Aug 2013 22:12:56 GMT

{
    "AddedTime": "2013-08-02T15:12:54.2694809-07:00",
    "Agent": null,
    "AllocatedGPU": null,
    "BackupEnabled": false,
    "BlockDynamicOptimization": null,
    "BlockLiveMigrationIfHostBusy": null,
    "CPUCount": 1,
    "CPULimitForMigration": null,
    "CPULimitFunctionality": null,
    "CPUMax": 100,
    "CPURelativeWeight": null,
    "CPUReserve": 0,
    "CPUType": "3.60 GHz Xeon (2 MB L2 cache)",
    "CPUUtilization": 0,
    "CanVMConnect": null,
    "CapabilityProfile": "Hyper-V",
    "CheckpointLocation": null,
    "CloudId": "a5397df8-517c-4939-ba07-0a9a2c2c2d56",
    "CloudVMRoleName": null,
    "ComputerName": "ContosoVM",
    "ComputerTierId": null,
    "CostCenter": null,
    "CreationSource": "Temporary Template18a82ca1-df80-4c41-8b2c-e8400308c493",
    "CreationTime": "2013-08-02T15:12:54.2694809-07:00",
    "DataExchangeEnabled": false,
    "DelayStart": 0,
    "DelayStartSeconds": null,
    "DeployPath": null,
    "DeploymentErrorInfo": {
        "CloudProblem": null,
        "Code": null,
        "DetailedCode": null,
        "DetailedErrorCode": null,
        "DetailedSource": null,
        "DisplayableErrorCode": null,
        "ErrorCodeString": null,
        "ErrorType": null,
        "ExceptionDetails": null,
        "IsConditionallyTerminating": null,
        "IsDeploymentBlocker": null,
        "IsMomAlert": null,
        "IsSuccess": null,
        "IsTerminating": null,
        "MessageParameters": null,
        "MomAlertSeverity": null,
        "Problem": null,
        "RecommendedAction": null,
        "RecommendedActionCLI": null,
        "ShowDetailedError": null
    },
    "Description": "",
    "DiskIO": 0,
    "Dismiss": null,
    "Domain": null,
    "DynamicMemoryBufferPercentage": null,
    "DynamicMemoryDemandMB": 0,
    "DynamicMemoryEnabled": false,
    "DynamicMemoryMaximumMB": null,
    "Enabled": true,
    "ExcludeFromPRO": false,
    "ExpectedCPUUtilization": 20,
    "FailedJobID": "1f8a3a06-03d7-4b5d-ac04-a9a167068f0a",
    "FullName": null,
    "GrantedToList": [],
    "HardwareProfileId": null,
    "HasPassthroughDisk": false,
    "HasSavedState": false,
    "HasVMAdditions": false,
    "HeartbeatEnabled": false,
    "HighlyAvailable": null,
    "ID": "2fa28d03-8d6d-486b-ae61-9694a2db5d6f",
    "IsFaultTolerant": false,
    "IsHighlyAvailable": false,
    "IsRecoveryVM": false,
    "IsUndergoingLiveMigration": false,
    "LastRestoredCheckpointId": null,
    "LibraryGroup": "",
    "LimitCPUForMigration": false,
    "LimitCPUFunctionality": false,
    "LinuxAdministratorSSHKey": null,
    "LinuxAdministratorSSHKeyString": null,
    "LinuxDomainName": null,
    "LocalAdminPassword": null,
    "LocalAdminRunAsAccountName": null,
    "LocalAdminUserName": null,
    "Location": "",
    "MarkedAsTemplate": false,
    "Memory": 512,
    "MemoryAssignedMB": 0,
    "MemoryAvailablePercentage": null,
    "MemoryWeight": 5000,
    "ModifiedTime": "2013-08-02T15:12:55.4590593-07:00",
    "MostRecentTaskId": "1f8a3a06-03d7-4b5d-ac04-a9a167068f0a",
    "Name": "Temp Machine Name",
    "NetworkUtilization": 0,
    "NewVirtualNetworkAdapterInput": [],
    "NumLock": null,
    "OSType": null,
    "OperatingSystem": "64-bit edition of Windows Server 2008 R2 Enterprise",
    "OperatingSystemId": null,
    "OperatingSystemShutdownEnabled": false,
    "Operation": null,
    "OrganizationName": null,
    "Owner": {
        "RoleID": "97fd50f3-1dc0-41b6-a7c0-2b4ff4c3f7e3",
        "RoleName": "fred@fred.com_97fd50f3-1dc0-41b6-a7c0-2b4ff4c3f7e3",
        "UserName": "user@contoso.com"
    },
    "Password": null,
    "Path": null,
    "PerfCPUUtilization": -1,
    "PerfDiskBytesRead": "-1",
    "PerfDiskBytesWrite": "-1",
    "PerfNetworkBytesRead": "-1",
    "PerfNetworkBytesWrite": "-1",
    "ProductKey": null,
    "Retry": null,
    "RunAsAccountUserName": null,
    "RunGuestAccount": null,
    "ServiceDeploymentErrorMessage": null,
    "ServiceId": null,
    "SharePath": null,
    "SourceObjectType": "VM Template",
    "StampId": "ba4146fa-fb41-4f59-a193-ad00c52a138c",
    "StartAction": "NeverAutoTurnOnVM",
    "StartVM": null,
    "Status": "UnderCreation",
    "StatusString": "Creating...",
    "StopAction": "SaveVM",
    "Tag": "(none)",
    "TimeSynchronizationEnabled": false,
    "TimeZone": null,
    "TotalSize": "0",
    "Undo": null,
    "UndoDisksEnabled": false,
    "UpgradeDomain": null,
    "UseCluster": null,
    "UseLAN": null,
    "UserName": null,
    "VMBaseConfigurationId": null,
    "VMCPath": null,
    "VMConfigResource": null,
    "VMConnection@odata.mediaContentType": "application/x-rdp",
    "VMHostName": null,
    "VMId": null,
    "VMNetworkAssignments": [],
    "VMResource": null,
    "VMResourceGroup": null,
    "VMTemplateId": null,
    "VirtualHardDiskId": null,
    "VirtualMachineState": "PowerOff",
    "VirtualizationPlatform": "HyperV",
    "WorkGroup": null,
    "odata.metadata": "https://wapserver:30006/97FD50F3-1DC0-41B6-A7C0-2B4FF4C3F7E3/services/systemcenter/vmm/$metadata#VirtualMachines/@Element"