Win32Shutdown

For more efficient management of computers in an organization, administrators need the ability to remotely shut down or restart a computer, or to remotely log off a user.

The ability to carry out these tasks allows administrators to install software, reconfigure computer settings, remove computers from the network, and perform other tasks without having to manually shut down or restart each computer.

• For example, to perform a network upgrade, you might need to shut down all the computers running on a particular network segment.

• To force a Group Policy upgrade, you need to log users off their computers.

• If a computer virus is present anywhere in your organization, you might want to shut down as many computers as possible, before the virus has an opportunity to spread.

The ability to shut down and restart computers and to log off users programmatically instead of manually can be an enormous time-saver. The calling process must have the SE_SHUTDOWN_NAME privilege.

The Win32ShutdownTracker method provides the same set of shutdown options supported by the Win32Shutdown method in Win32_OperatingSystem but it also allows you to specify comments, a reason for shutdown, or a timeout.

The Win32Shutdown method does not have a parameter for locking a workstation, leaving the user logged on. However, workstations can be locked from the command line by using the following command: rundll32.exe user32.dll,LockWorkStation.

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)]
  [int]
  $Flags
)


$query = 'Select * From Win32_OperatingSystem'

Invoke-CimMethod -Query $query -MethodName Win32Shutdown -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)]
  [int]
  $Flags,

  [String[]]
  $ComputerName,

  [PSCredential]
  $Credential
)


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

$query = 'Select * From Win32_OperatingSystem'

Invoke-CimMethod -Query $query -MethodName Win32Shutdown -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 Win32Shutdown(
  [in]int32 Flags,
  [in]sint32 Reserved = 
);

Parameters

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.

Win32ShutdownTracker()

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.

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