Msvm_ComputerSystem クラスの RequestStateChange メソッド
仮想マシンの状態を指定した値に変更するように要求します。 RequestStateChange メソッドを複数回呼び出すと、以前の要求が上書きされたり失われたりする可能性があります。 このメソッドは、仮想マシンを表す Msvm_ComputerSystem クラスのインスタンスでのみサポートされます。
状態の変更が進行中の間、 RequestedState プロパティは RequestedState パラメーターの値に変更されます。
構文
uint32 RequestStateChange(
[in] uint16 RequestedState,
[out] CIM_ConcreteJob REF Job,
[in] datetime TimeoutPeriod
);
パラメーター
-
RequestedState [in]
-
型: uint16
新しい状態です。 32767 より大きい値は DMTF 提案値であり、変更される可能性があります。
使用可能な値を次に示します。
-
その他 (1)
-
CIM_EnabledLogicalElement.EnabledState = Other に対応します。
-
有効 (2)
-
CIM_EnabledLogicalElement.EnabledState = Enabled に対応します。
-
無効 (3)
-
CIM_EnabledLogicalElement.EnabledState = Disabled に対応します。
-
シャットダウン (4)
-
Hyper-V のバージョン 1 (V1) でのみ有効です。 仮想マシンはシャットダウン サービスを介してシャットダウンしています。 CIM_EnabledLogicalElement.EnabledState = ShuttingDown に対応します。
-
オフライン (6)
-
CIM_EnabledLogicalElement.EnabledState = Enabled に対応しますが、オフラインです。
-
テスト (7)
-
延期 (8)
-
休止 (9)
-
CIM_EnabledLogicalElement.EnabledState = 休止、有効、一時停止に対応します。
-
再起動 (10)
-
状態が [オフ] または [保存済み] から [実行中] に切り替わります。
-
リセット (11)
-
仮想マシンをリセットします。 CIM_EnabledLogicalElement.EnabledState = Reset に対応します。
-
保存 (32773)
-
Hyper-V のバージョン 1 (V1) では、 は EnabledStateSaving に対応しています。
-
一時停止 (32776)
-
Hyper-V のバージョン 1 (V1) では、 は EnabledStatePausing に対応しています。
-
再開 (32777)
-
Hyper-V のバージョン 1 (V1) では、 は EnabledStateResuming に対応しています。 状態が [一時停止] から [実行中] に切り替 わります。
-
FastSaved (32779)
-
EnabledStateFastSuspend に対応します。
-
FastSaving (32780)
-
EnabledStateFastSuspending に対応します。 状態が [実行中] から [FastSaved] に切り替わります。
これらの値は、重大な状態を表します。
RunningCritical (32781)
OffCritical (32782)
StoppingCritical (32783)
SavedCritical (32784)
PausedCritical (32785)
StartingCritical (32786)
ResetCritical (32787)
SavingCritical (32788)
PausingCritical (32789)
ResumingCritical (32790)
FastSavedCritical (32791)
FastSavingCritical (32792)
ジョブ [出力]
種類: CIM_ConcreteJob
操作が非同期に実行された場合に返される Msvm_ConcreteJob オブジェクトへの省略可能な参照。 存在する場合は、返された参照を使用して進行状況を監視し、メソッドの結果を取得できます。
TimeoutPeriod [in]
種類: datetime
このパラメーターは使用されません。
戻り値
型: uint32
このメソッドは、次のいずれかの値を返します。
| リターン コード/値 | Description |
|---|---|
|
正常終了しました。 |
|
遷移は非同期です。 |
|
アクセスが拒否されました。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
RequestedState パラメーターで指定された値はサポートされていません。 |
|
|
|
|
|
解説
MSVM_COMPUTERSYSTEM クラスへのアクセスは、UAC フィルター処理によって制限される場合があります。 詳細については、「 ユーザー アカウント制御と WMI」を参照してください。
例
次の C# の例では、仮想マシンを起動または無効にします。 参照されるユーティリティについては、「 仮想化サンプルの一般的なユーティリティ (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]);
}
}
}
次の Visual Basic Scripting Edition (VBScript) の例では、仮想マシンを起動または無効にします。
重要
正しく機能するには、次のコードを仮想マシン ホスト サーバーで実行し、管理者特権で実行する必要があります。
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
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント |
Windows 8 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー |
Windows Server 2012 [デスクトップ アプリのみ] |
| 名前空間 |
Root\Virtualization\V2 |
| MOF |
|
| [DLL] |
|