Win32ShutdownTracker

Provides the same set of shutdown options supported by Win32Shutdown() but also allows you to specify comments, a reason for shutdown, or a timeout.

With this method, you can logoff, reboot or shutdown a system while logging the operation and providing a reason in the event log.

Example

Do not run below example code just to see what happens next. Many methods seriously affect your system. Always make sure you actually understand what the method and the code do.

param
(
  [Parameter(Mandatory)]
  [String]
  $Comment,

  [Parameter(Mandatory)]
  [int]
  $Flags,

  [Parameter(Mandatory)]
  [UInt32]
  $ReasonCode,

  [UInt32]
  $Timeout
)


$query = 'Select * From Win32_OperatingSystem'

Invoke-CimMethod -Query $query -MethodName Win32ShutdownTracker -Arguments $PSBoundParameters |
  Add-Member -MemberType ScriptProperty -Name ReturnValueFriendly -Passthru -Value {
  switch ([int]$this.ReturnValue)
  {
        0        {'Success'}
        default  {"Unknown Error $_"}
    }
}

To run this method on one or more remote systems, use New-CimSession:

param
(
  [Parameter(Mandatory)]
  [String]
  $Comment,

  [Parameter(Mandatory)]
  [int]
  $Flags,

  [Parameter(Mandatory)]
  [UInt32]
  $ReasonCode,

  [UInt32]
  $Timeout,

  [String[]]
  $ComputerName,

  [PSCredential]
  $Credential
)


$session = New-CimSession -ComputerName $ComputerName -Credential $Credential

$query = 'Select * From Win32_OperatingSystem'

Invoke-CimMethod -Query $query -MethodName Win32ShutdownTracker -Arguments $PSBoundParameters -CimSession $session |
  Add-Member -MemberType ScriptProperty -Name ReturnValueFriendly -Passthru -Value {
  switch ([int]$this.ReturnValue)
  {
        0        {'Success'}
        default  {"Unknown Error $_"}
    }
}


Remove-CimSession -CimSession $session

Learn more about Invoke-CimMethod and invoking WMI methods.

Syntax

uint32 Win32ShutdownTracker(
  [in]uint32 Timeout,
  [in]string Comment,
  [in]uint32 ReasonCode,
  [in]sint32 Flags
);

Parameters

Name Type Description
Comment String The Comment parameter specifies a message to display in the shutdown dialog box and also stored as a comment in the event log entry.
Flags SInt32 The Flags parameter contains a set of flags to shut the computer down. Setting this parameter to 0 is the command to logoff.
ReasonCode UInt32 The ReasonCode parameter specifies the reason for initiating the shutdown.
Timeout UInt32 The Timeout parameter is the time in seconds before shutdown take place. The default value is 0.

Flags

Bitmapped set of flags to shut the computer down.

To force a command, add the Force flag (4) to the command value.

Using Force in conjunction with Shutdown or Reboot on a remote computer immediately shuts down everything (including WMI, COM, and so on), or reboots the remote computer. This results in an indeterminate return value.

[Flags()]Enum OperatingSystemFlags
{
  Logoff     = 0        # Logs the user off the computer. Logging off stops all processes associated with the security context of the process that called the exit function, logs the current user off the system, and displays the logon dialog box.
  Shutdown   = 1        # Shuts down the computer to a point where it is safe to turn off the power. (All file buffers are flushed to disk, and all running processes are stopped.) Users see the message *It is now safe to turn off your computer.* During shutdown the system sends a message to each running application. The applications perform any cleanup while processing the message and return True to indicate that they can be terminated.
  Reboot     = 2        # Shuts down and then restarts the computer.
  Force      = 4        # When the flag *Force* is added, all services, including WMI, are shut down immediately. Because of this, you will not be able to receive a return value if you are running the script against a remote computer. When you specify only the flag *Force*, the user will immediately be logged off.
  PowerOff   = 8        # Shuts down the computer and turns off the power (if supported by the computer in question).
}

Return Value

Returns a value of type UInt32. Return values:

$returnValues = @{
    0    = 'Success'
}

See Also

Additional methods implemented by Win32_OperatingSystem:

Reboot()

Reboot() shuts down and then restarts the computer system.

SetDateTime()

SetDateTime() allows the computer date and time to be set.

Shutdown()

Shutdown() unloads programs and DLLs to the point where it is safe to turn off the computer.

Win32Shutdown()

Win32Shutdown() provides the full set of shutdown options supported by Windows operating systems.

Requirements

To use Win32_OperatingSystem, the following requirements apply:

PowerShell

Get-CimInstance was introduced with PowerShell Version 3.0, which in turn was introduced on clients with Windows 8 and on servers with Windows Server 2012.

If necessary, update Windows PowerShell to Windows PowerShell 5.1, or install PowerShell 7 side-by-side.

Operating System

Win32_OperatingSystem was introduced on clients with Windows Vista and on servers with Windows Server 2008.

Namespace

Win32_OperatingSystem lives in the Namespace Root/CIMV2. This is the default namespace. There is no need to use the -Namespace parameter in Get-CimInstance.

Implementation

Win32_OperatingSystem is implemented in CIMWin32.dll and defined in CIMWin32.mof. Both files are located in the folder C:\Windows\system32\wbem:

explorer $env:windir\system32\wbem
notepad $env:windir\system32\wbem\CIMWin32.mof