Méthode RequestStateChange de la classe Msvm_ComputerSystem

Demande que l’état de la machine virtuelle soit remplacé par la valeur spécifiée. L’appel de la méthode RequestStateChange plusieurs fois peut entraîner le remplacement ou la perte de requêtes antérieures. Cette méthode est uniquement prise en charge pour les instances de la classe Msvm_ComputerSystem qui représentent une machine virtuelle.

Pendant que le changement d’état est en cours, la propriété RequestedState est remplacée par la valeur du paramètre RequestedState .

Syntaxe

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

Paramètres

RequestedState [in]

Type : uint16

Nouvel état. Les valeurs supérieures à 32767 sont des valeurs proposées par DMTF et sont susceptibles d’être modifiées.

Voici les valeurs possibles :

Autre (1)

Correspond à CIM_EnabledLogicalElement.EnabledState = Autre.

Activé (2)

Correspond à CIM_EnabledLogicalElement.EnabledState = Enabled.

Désactivé (3)

Correspond à CIM_EnabledLogicalElement.EnabledState = Disabled.

Arrêter (4)

Valide dans la version 1 (V1) d’Hyper-V uniquement. La machine virtuelle s’arrête via le service d’arrêt. Correspond à CIM_EnabledLogicalElement.EnabledState = ShuttingDown.

Hors connexion (6)

Correspond à CIM_EnabledLogicalElement.EnabledState = Enabled mais hors connexion.

Test (7)

Report (8)

Quiesce (9)

Correspond à CIM_EnabledLogicalElement.EnabledState = Quiesce, Enabled mais en pause.

Redémarrage (10)

Transition de l’état de Désactivé ou Enregistré à En cours d’exécution.

Réinitialiser (11)

Réinitialisez la machine virtuelle. Correspond à CIM_EnabledLogicalElement.EnabledState = Reset.

Enregistrement (32773)

Dans la version 1 (V1) d’Hyper-V, correspond à EnabledStateSaving.

Suspension (32776)

Dans la version 1 (V1) d’Hyper-V, correspond à EnabledStatePausing.

Reprise (32777)

Dans la version 1 (V1) d’Hyper-V, correspond à EnabledStateResuming. Transition de l’état de Suspendu à En cours d’exécution.

FastSaved (32779)

Correspond à EnabledStateFastSuspend.

FastSaving (32780)

Correspond à EnabledStateFastSuspending. Transition de l’état de Running à FastSaved.

Ces valeurs représentent des états critiques :

Valeur retournée

Type : uint32

Cette méthode retourne l’une des valeurs suivantes.

Notes

L’accès à la classe Msvm_ComputerSystem peut être limité par le filtrage UAC. Pour plus d’informations, consultez Contrôle de compte d’utilisateur et WMI.

Exemples

L’exemple C# suivant démarre ou désactive une machine virtuelle. Les utilitaires référencés se trouvent dans Utilitaires communs pour les exemples de virtualisation (V2).

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]);
        }

    }
}

L’exemple visual Basic Scripting Edition (VBScript) suivant démarre ou désactive une machine virtuelle.

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

Spécifications

Voir aussi

Msvm_ComputerSystem