Rebooting Computers Using PowerShell

Understanding Set-ComputerState.ps1
Set-ComputerState.ps1 uses WMI to perform the specified actions on computers. Specifically, it uses the Win32Shutdown method of WMI's Win32_OperatingSystem class. This method requires a parameter that tells it what to do. Table 2 shows the valid parameter values for the Win32Shutdown method. (Test isn't a valid action for the Win32Shutdown method, but Set-ComputerState.ps1 uses the value 16 to represent the Test action.)

Set-ComputerState.ps1 assigns the Win32Shutdown method's parameter values to a series of variables representing the various actions, as callout A in Listing 2 shows. It then uses a hash table to associate the variables with the first letter of each action (callout B). The script checks the first character of the specified action against the hash table's keys. If there isn't a match (i.e., the specified action isn't valid), the script throws an error.

Listing 2: Set-ComputerState.ps1 Code That Associates the -action Parameter Values with the Win32Shutdown Parameter Method Values

Set-ComputerState.ps1 also uses the hash table to obtain the numeric value for the Win32Shutdown method and stores it in the $flags variable. If the -force parameter was entered on the command line, the script uses the -bor operator to obtain the value for the forced version of the action (provided that the action wasn't Test).

Next, the script creates a ManagementObjectSearcher object using PowerShell's [WMISearcher] type accelerator in a query that selects all properties from the Win32_OperatingSystem class. It then configures the ManagementObjectSearcher object's options to enable all WMI privileges and set the WMI impersonation level. (This is why Set-ComputerState.ps1 uses the ManagementObjectSearcher object instead of the Get-WMIObject cmdlet; the Get-WMIObject cmdlet doesn't support enabling all privileges.)

Set-ComputerState.ps1 uses a foreach loop to iterate through the computers specified with the -computername parameter. For each computer, the script creates a custom output object and configures its name. If the -ping parameter is present, the script calls the testIPHost function. The testIPHost function uses WMI's Win32_PingStatus class to check whether the computer responds to a ping. If the ping fails (i.e., the testIPHost function returns a non-zero value), the script updates the output object's Action and Result properties, outputs the object, and continues to the next computer.

In the code in Listing 3, Set-ComputerState.ps1 uses the PowerShell trap statement to capture exceptions.

Listing 3: The trap Script Block in Set-ComputerState.ps1

If an exception occurs, the trap script block updates the $ok variable in the parent scope to $FALSE, then attempts to retrieve the exception's ErrorCode property. Not all exceptions have an ErrorCode property, so the trap script block uses a regular expression to check if the exception's message contains a hex error code. If the exception message contains a hex error code, the script block updates the output object's Result property with the hex error code; otherwise, it updates the output object's Result property with the error message. The trap script block then uses the continue statement to continue to the statement following the one that caused the exception.

Finally, Set-ComputerState.ps1 points ManagementObjectSearcher to the root\cimv2 WMI namespace on the requested computer, then calls ManagementObjectSearcher's Get method to execute the query as a part of a foreach loop. If the $ok variable contains $TRUE, an exception didn't occur and the script checks whether Test was the requested action. If so, it updates the output object with a zero code (indicating success); otherwise, it calls the Win32Shutdown method and updates the output object's properties with the action and the result. The script uses the decodeFlags function to return a string representation of the $flags variable. After this, the script outputs the custom object and continues to the next computer.

Because Set-ComputerState.ps1 outputs objects, not just text, you can use PowerShell's formatting cmdlets to customize the script's output. For example, if you want to omit the Action property from the output, you can use the Format-Table cmdlet to select only the Computer and Result properties.

Exploiting PowerShell's Capabilities
The Get-EnabledComputerCN.ps1 and Set-ComputerState.ps1 scripts demonstrate how PowerShell makes it relatively easy to combine separate scripts to accomplish a single goal. If you add them to your toolbox, you'll be able to easily reboot computers whenever needed. You can download these scripts by clicking the Download the Code Here button near the top of the page. You can execute these PowerShell scripts on any machine that has PowerShell installed, but the computers on which you're performing the actions don't have to have PowerShell installed. You don't need to customize the scripts before you use them.