RequestStateChange-Methode der Msvm _ ComputerSystem-Klasse

Fordert an, dass der Status des virtuellen Computers in den angegebenen Wert geändert wird. Das mehrfache Aufrufen der RequestStateChange-Methode kann dazu führen, dass frühere Anforderungen überschrieben oder verloren gehen. Diese Methode wird nur für Instanzen der Msvm _ ComputerSystem-Klasse unterstützt, die einen virtuellen Computer darstellen.

Während der Zustandsänderung wird die RequestedState-Eigenschaft in den Wert des RequestedState-Parameters geändert.

Syntax

uint32 RequestStateChange(
  [in]  uint16              RequestedState,
  [out] CIM_ConcreteJob REF Job,
  [in]  datetime            TimeoutPeriod
);

Parameter

RequestedState [ In]

Typ: uint16

Der neue Zustand. Werte, die größer als 32767 sind, sind von DMTF vorgeschlagene Werte und können sich ändern.

Dies sind mögliche Werte:

Sonstige (1)

Entspricht CIM _ EnabledLogicalElement.EnabledState = Other.

Aktiviert (2)

Entspricht CIM _ EnabledLogicalElement.EnabledState = Enabled.

Deaktiviert (3)

Entspricht CIM _ EnabledLogicalElement.EnabledState = Disabled.

Herunterfahren (4)

Nur in Version 1 (V1) von Hyper-V gültig. Der virtuelle Computer wird über den Dienst zum Herunterfahren heruntergefahren. Entspricht CIM _ EnabledLogicalElement.EnabledState = ShuttingDown.

Offline (6)

Entspricht CIM _ EnabledLogicalElement.EnabledState = Aktiviert, aber offline.

Test (7)

Zurückern (8)

Ruhe (9)

Entspricht CIM _ EnabledLogicalElement.EnabledState = Quiesce, Enabled, but paused.

Neustart (10)

Statusübergang von Aus oder Gespeichert in Wird ausgeführt.

Zurücksetzen (11)

Setzen Sie den virtuellen Computer zurück. Entspricht CIM _ EnabledLogicalElement.EnabledState = Reset.

Speichern (32773)

In Version 1 (V1) von Hyper-V entspricht EnabledStateSaving.

Anhalten (32776)

In Version 1 (V1) von Hyper-V entspricht EnabledStatePausing.

Fortsetzen (32777)

In Version 1 (V1) von Hyper-V entspricht EnabledStateResuming. Statusübergang von Angehalten zu Wird ausgeführt.

FastSaved (32779)

Entspricht EnabledStateFastSuspend.

FastSaving (32780)

Entspricht EnabledStateFastSuspending. Statusübergang von Wird ausgeführt zu FastSaved.

Diese Werte stellen kritische Zustände dar:

RunningCritical (32781)

OffCritical (32782)

StoppingCritical (32783)

SavedCritical (32784)

PausedCritical (32785)

StartingCritical (32786)

ResetCritical (32787)

SavingCritical (32788)

PausingCritical (32789)

ResumingCritical (32790)

FastSavedCritical (32791)

FastSavingCritical (32792)

Auftrag [ out]

Typ: CIM _ ConcreteJob

Ein optionaler Verweis auf ein Msvm _ ConcreteJob-Objekt, das zurückgegeben wird, wenn der Vorgang asynchron ausgeführt wird. Falls vorhanden, kann der zurückgegebene Verweis verwendet werden, um den Fortschritt zu überwachen und das Ergebnis der -Methode zu erhalten.

TimeoutPeriod [ In]

Typ: datetime

Dieser Parameter wird nicht verwendet.

Rückgabewert

Typ: uint32

Diese Methode gibt einen der folgenden Werte zurück.

Rückgabecode/-wert Beschreibung
Abgeschlossen ohne Fehler
0
Erfolg.
Überprüfte Methodenparameter – Übergang gestartet
4096
Der Übergang ist asynchron.
Zugriff verweigert
32769
Zugriff verweigert:
32768
32770
32771
32772
32773
32774
Ungültiger Zustand für diesen Vorgang
32775
Der im RequestedState-Parameter angegebene Wert wird nicht unterstützt.
32776
32777
32778

Hinweise

Der Zugriff auf die Msvm _ ComputerSystem-Klasse kann durch UAC-Filterung eingeschränkt werden. Weitere Informationen finden Sie unter Benutzerkontensteuerung und WMI.

Beispiele

Im folgenden C#-Beispiel wird ein virtueller Computer gestartet oder deaktiviert. Die referenzierten Hilfsprogramme finden Sie unter Allgemeine Hilfsprogramme für die Virtualisierungsbeispiele (V2).

Wichtig

Damit der folgende Code ordnungsgemäß funktioniert, muss er auf dem Hostserver des virtuellen Computers und mit Administratorrechten ausgeführt werden.

using System;
using System.Management;

namespace HyperVSamples
{
    public class RequestStateChangeClass
    {
        public static void RequestStateChange(string vmName, string action)
        {
            ManagementScope scope = new ManagementScope(@"\\.\root\virtualization\v2", null);
            ManagementObject vm = Utility.GetTargetComputer(vmName, scope);

            if (null == vm)
            {
                throw new ArgumentException(
                    string.Format(
                    "The virtual machine '{0}' could not be found.", 
                    vmName));
            }

            ManagementBaseObject inParams = vm.GetMethodParameters("RequestStateChange");

            const int Enabled = 2;
            const int Disabled = 3;

            if (action.ToLower() == "start")
            {
                inParams["RequestedState"] = Enabled;
            }
            else if (action.ToLower() == "stop")
            {
                inParams["RequestedState"] = Disabled;
            }
            else
            {
                throw new Exception("Wrong action is specified");
            }

            ManagementBaseObject outParams = vm.InvokeMethod(
                "RequestStateChange", 
                inParams, 
                null);

            if ((UInt32)outParams["ReturnValue"] == ReturnCode.Started)
            {
                if (Utility.JobCompleted(outParams, scope))
                {
                    Console.WriteLine(
                        "{0} state was changed successfully.", 
                        vmName);
                }
                else
                {
                    Console.WriteLine("Failed to change virtual system state");
                }
            }
            else if ((UInt32)outParams["ReturnValue"] == ReturnCode.Completed)
            {
                Console.WriteLine(
                    "{0} state was changed successfully.", 
                    vmName);
            }
            else
            {
                Console.WriteLine(
                    "Change virtual system state failed with error {0}", 
                    outParams["ReturnValue"]);
            }

        }

        public static void Main(string[] args)
        {
            if (args != null && args.Length != 2)
            {
                Console.WriteLine("Usage: <application> vmName action");
                Console.WriteLine("action: start|stop");
                return;
            }

            RequestStateChange(args[0], args[1]);
        }

    }
}

Im folgenden beispiel Visual Basic Scripting Edition (VBScript) wird ein virtueller Computer gestartet oder deaktiviert.

Wichtig

Damit der folgende Code ordnungsgemäß funktioniert, muss er auf dem Hostserver des virtuellen Computers und mit Administratorrechten ausgeführt werden.

dim objWMIService
dim fileSystem

const JobStarting = 3
const JobRunning = 4
const JobCompleted = 7
const wmiStarted = 4096
const Enabled = 2
const Disabled = 3



Main()

'-----------------------------------------------------------------
' Main routine
'-----------------------------------------------------------------
Sub Main()
    set fileSystem = Wscript.CreateObject("Scripting.FileSystemObject")

    strComputer = "."
    set objWMIService = GetObject("winmgmts:\\" & strComputer & "\root\virtualization\v2")

    set objArgs = WScript.Arguments
    if WScript.Arguments.Count = 2 then
       vmName= objArgs.Unnamed.Item(0)
       action = objArgs.Unnamed.Item(1)
    else
       WScript.Echo "usage: cscript StartVM.vbs vmName start|stop"
       WScript.Quit
    end if
    
    set computerSystem = GetComputerSystem(vmName)

    if RequestStateChange(computerSystem, action) then

        WriteLog "Done"
        WScript.Quit(0)
    else
        WriteLog "RequestStateChange failed"
        WScript.Quit(1)
    end if

End Sub

'-----------------------------------------------------------------
' Retrieve Msvm_VirtualComputerSystem from base on its ElementName
' 
'-----------------------------------------------------------------
Function GetComputerSystem(vmElementName)
    On Error Resume Next
    query = Format1("select * from Msvm_ComputerSystem where ElementName = '{0}'", vmElementName)
    set GetComputerSystem = objWMIService.ExecQuery(query).ItemIndex(0)
    if (Err.Number <> 0) then
        WriteLog Format1("Err.Number: {0}", Err.Number)
        WriteLog Format1("Err.Description:{0}",Err.Description)
        WScript.Quit(1)
    end if
End Function


'-----------------------------------------------------------------
' Turn on a virtual machine
'-----------------------------------------------------------------
Function RequestStateChange(computerSystem, action)
    WriteLog Format2("RequestStateChange({0}, {1})", computerSystem.ElementName, action)

    RequestStateChange = false
    set objInParam = computerSystem.Methods_("RequestStateChange").InParameters.SpawnInstance_()
    
    if action = "start" then
        objInParam.RequestedState = Enabled
    else
        objInParam.RequestedState = Disabled
    end if

    set objOutParams = computerSystem.ExecMethod_("RequestStateChange", objInParam)

    if (WMIMethodStarted(objOutParams)) then
        if (WMIJobCompleted(objOutParams)) then
            WriteLog Format1("VM {0} was started successfully", computerSystem.ElementName)
            RequestStateChange = true
        end if
    end if

End Function


'-----------------------------------------------------------------
' Handle wmi return values
'-----------------------------------------------------------------
Function WMIMethodStarted(outParam)

    WMIMethodStarted = false

    if Not IsNull(outParam) then
        wmiStatus = outParam.ReturnValue

        if  wmiStatus = wmiStarted then
            WMIMethodStarted = true
        end if

    end if

End Function


'-----------------------------------------------------------------
' Handle wmi Job object
'-----------------------------------------------------------------
Function WMIJobCompleted(outParam)
    dim WMIJob

    set WMIJob = objWMIService.Get(outParam.Job)

    WMIJobCompleted = true

    jobState = WMIJob.JobState

    while jobState = JobRunning or jobState = JobStarting

        WScript.Sleep(1000)
        set WMIJob = objWMIService.Get(outParam.Job)
        jobState = WMIJob.JobState

    wend


    if (jobState <> JobCompleted) then
        WriteLog Format1("ErrorDescription:{0}", WMIJob.ErrorDescription)
        WMIJobCompleted = false
    end if

End Function

'-----------------------------------------------------------------
' Create the console log files.
'-----------------------------------------------------------------
Sub WriteLog(line)
    dim fileStream
    set fileStream = fileSystem.OpenTextFile(".\StartVM.log", 8, true)
    WScript.Echo line
    fileStream.WriteLine line
    fileStream.Close

End Sub


'------------------------------------------------------------------------------
' The string formatting functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format2(myString, arg0, arg1)
    Format2 = Format1(myString, arg0)
    Format2 = Replace(Format2, "{1}", arg1)
End Function

'------------------------------------------------------------------------------
' The string formatting functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format1(myString, arg0)
    Format1 = Replace(myString, "{0}", arg0)
End Function

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client)
[Windows 8 Nur Desktop-Apps]
Unterstützte Mindestversion (Server)
[Windows Server 2012 Nur Desktop-Apps]
Namespace
Root \ Virtualization \ V2
MOF
WindowsVirtualization.V2.mof
DLL
Vmms.exe

Weitere Informationen

Msvm _ ComputerSystem