All posts by Adam

Test-ModuleManifest

February 26, 2014 Adam

SYNOPSIS
Verifies that a module manifest file accurately describes the contents of a module.

SYNTAX
Test-ModuleManifest [-Path] <string> [<CommonParameters>]

DESCRIPTION
The Test-ModuleManifest cmdlet verifies that the files that are listed in the module manifest (.psd1) file actually exist in the specified paths.

This cmdlet is designed to help module authors test their manifest files. Module users can also use this cmdlet in scripts and commands to detect errors before running scripts that depend on the module.

The Test-ModuleManifest cmdlet returns an object that represents the module (the same type of object that Get-Module returns). If any files are not in the locations specified in the manifest, the cmdlet also generates an error for each missing file.

PARAMETERS
-Path <string>
Specifies the path to the module manifest file. Enter a path (optional) and the name of the module manifest file with the .psd1 file name extension. The default location is the current directory. This parameter is required. The parameter name (“Path”) is optional. You can also pipe a path to Test-ModuleManifest.

        Required?                    true
        Position?                    1
        Default value                None
        Accept pipeline input?     true (ByValue, ByPropertyName)
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
System.String
You can pipe the path to a module manifest to Test-ModuleManifest.

OUTPUTS
System.Management.Automation.PSModuleInfo
Test-ModuleManifest returns a PSModuleInfo object that represents the module. It returns this object even if the manifest has errors.

NOTES

————————– EXAMPLE 1 ————————–

C:\PS>Test-ModuleManifest -Path $pshome\Modules\TestModule.psd1

    Description
    ———–
    This command tests the TestModule.psd1 module manifest.

————————– EXAMPLE 2 ————————–

C:\PS>”$pshome\Modules\TestModule.psd1″ | Test-ModuleManifest

    Test-ModuleManifest : The specified type data file ‘C:\Windows\System32\Wi
    ndowsPowerShell\v1.0\Modules\TestModule\TestTypes.ps1xml’ could not be pro
    cessed because the file was not found. Please correct the path and try aga
    in.
    At line:1 char:34
    + “$pshome\Modules\TestModule.psd1” | Test-ModuleManifest <<<<
        + CategoryInfo         : ResourceUnavailable: (C:\Windows\System32\Win
    dowsPowerShell\v1.0\Modules\TestModule\TestTypes.ps1xml:String) [Test-Modul
    eManifest], FileNotFoundException
        + FullyQualifiedErrorId : Modules_TypeDataFileNotFound,Microsoft.
    PowerShell.Commands.TestModuleManifestCommandName

    Name             : TestModule
    Path             : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\Test
    Module\TestModule.psd1
    Description     :
    Guid             : 6f0f1387-cd25-4902-b7b4-22cff6aefa7b
    Version         : 1.0
    ModuleBase        : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\Test
    Module
    ModuleType        : Manifest
    PrivateData     :
    AccessMode        : ReadWrite
    ExportedAliases : {}
    ExportedCmdlets : {}
    ExportedFunctions : {}
    ExportedVariables : {}
    NestedModules     : {}

    Description
    ———–
    This command uses a pipeline operator (|) to send a path string to Test-ModuleManifest.

The command output shows that the test failed, because the TestTypes.ps1xml file, which was listed in the manifest, was not found.

————————– EXAMPLE 3 ————————–

C:\PS>function Bool-ModuleManifest ($path)
{$a = dir $path | Test-ModuleManifest -ErrorAction SilentlyContinue; $?}

    Description
    ———–
    This Function is like Test-ModuleManifest, but it returns a Boolean value; it returns “True” if the manifest passed the test and “False” otherwise.

The Function uses the Get-ChildItem cmdlet (alias = dir) to get the module manifest specified by the $path Variable. It uses a pipeline operator (|) to pass the file object to the Test-ModuleManifest cmdlet.

The Test-ModuleManifest command uses the ErrorAction common parameter with a value of SilentlyContinue to suppress the display of any errors that the command generates. It also saves the PSModuleInfo object that Test-ModuleManifest returns in the $a Variable, so the object is not displayed.

Then, in a separate command (the semi-colon [;] is the command separator), it displays the value of the $? automatic Variable, which returns “True” if the previous command generated no error and “False” otherwise.

You can use this Function in conditional statements, such as those that might precede an Import-Module command or a command that uses the module.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=141557
    Import-Module
    Get-Module
    New-Module
    Remove-Module
    Export-ModuleMember
    New-ModuleManifest
    about_modules

cmdlet, Connection, Test

Test-Connection

February 26, 2014 Adam

NAME
Test-Connection

SYNOPSIS
Sends ICMP echo request packets (“pings”) to one or more computers.

SYNTAX
Test-Connection [-ComputerName] <string[]> [[-Source] <string[]>] [-AsJob] [-Authentication {Default | None | Connect | Call | Packet | PacketIntegrity | PacketPrivacy | Unchanged}] [-BufferSize <int>] [-Count <int>] [-Credential <PSCredential>] [-Delay <int>] [-Impersonation {Default | Anonymous | Identify | Impersonate | Delegate}] [-Quiet] [-ThrottleLimit <int>] [-TimeToLive <int>] [<CommonParameters>]

DESCRIPTION
The Test-Connection cmdlet sends Internet Control Message Protocol (ICMP) echo request packets (“pings”) to one or more remote computers and returns the echo response replies. You can use this cmdlet to determine whether a particular computer can be contacted across an Internet Protocol (IP) network.

You can use the parameters of Test-Connection to specify both the sending and receiving computers, to run the command as a background job, to set a timeout and number of pings, and to configure the connection and authentication.

Unlike the traditional “ping” command, Test-Connection returns a Win32_PingStatus object that you can investigate in Windows PowerShell, but you can use the Quiet parameter to force it to return only a Boolean value.

PARAMETERS
-AsJob [<SwitchParameter>]
Runs the command as a background job.

Note: To use this parameter, the local and remote computers must be configured for remoting and, on Windows Vista and later versions of Windows, you must open Windows PowerShell with the “Run as administrator” option. For more information, see about_remote_requirements.

When you use the AsJob parameter, the command immediately returns an object that represents the background job. You can continue to work in the session while the job completes. The job is created on the local computer and the results from remote computers are automatically returned to the local computer. To get the job results, use the Receive-Job cmdlet.

For more information about Windows PowerShell background jobs, see about_jobs and about_remote_Jobs.

        Required?                    false
        Position?                    named
        Default value                False
        Accept pipeline input?     false
        Accept wildcard characters? false

-Authentication <AuthenticationLevel>
Specifies the authentication level that is used for the WMI connection. (Test-Connection uses WMI.)

Valid values are:

        Unchanged:     The authentication level is the same as the previous command.
        Default:         Windows Authentication.
        None:            No COM authentication.
        Connect:         Connect-level COM authentication.
        Call:            Call-level COM authentication.
        Packet:         Packet-level COM authentication.
        PacketIntegrity: Packet Integrity-level COM authentication.
        PacketPrivacy: Packet Privacy-level COM authentication.

        Required?                    false
        Position?                    named
        Default value                4
        Accept pipeline input?     false
        Accept wildcard characters? false

-BufferSize <int>
Specifies the size, in bytes, of the buffer sent with this command. The default value is 32.

        Required?                    false
        Position?                    named
        Default value                32
        Accept pipeline input?     false
        Accept wildcard characters? false

-ComputerName <string[]>
Specifies the computers to ping. Type the computer names or type IP addresses in IPv4 or IPv6 format. Wildcard characters are not permitted. This parameter is required.

This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter even if your computer is not configured to run remote commands.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Count <int>
Specifies the number of echo requests to send. The default value is 4.

        Required?                    false
        Position?                    named
        Default value                4
        Accept pipeline input?     false
        Accept wildcard characters? false

-Credential <PSCredential>
Specifies a user account that has permission to perform this action. Type a user name, such as “User01” or “Domain01\User01”, or enter a PSCredential object, such as one from the Get-Credential cmdlet.

        Required?                    false
        Position?                    named
        Default value                Current user
        Accept pipeline input?     false
        Accept wildcard characters? false

-Delay <int>
Specifies the interval between pings, in seconds.

        Required?                    false
        Position?                    named
        Default value                1 (second)
        Accept pipeline input?     false
        Accept wildcard characters? false

-Impersonation <ImpersonationLevel>
Specifies the impersonation level to use when calling WMI. (Test-Connection uses WMI.) The default value is “Impersonate”.

Valid values are:

        Default:     Default impersonation.
        Anonymous:    Hides the identity of the caller.
        Identify:     Allows objects to query the credentials of the caller.
        Impersonate: Allows objects to use the credentials of the caller.

        Required?                    false
        Position?                    named
        Default value                3
        Accept pipeline input?     false
        Accept wildcard characters? false

-Quiet [<SwitchParameter>]
Suppresses all errors and returns $True if any pings succeeded and $False if all failed.

-Source <string[]>
Specifies the names of the computers where the ping originates. Enter a comma-separated list of computer names. The default is the local computer.

        Required?                    false
        Position?                    2
        Default value                Local computer
        Accept pipeline input?     false
        Accept wildcard characters? false

-ThrottleLimit <int>
Specifies the maximum number of concurrent connections that can be established to run this command. If you omit this parameter or enter a value of 0, the default value, 32, is used.

The throttle limit applies only to the current command, not to the session or to the computer.

-TimeToLive <int>
Specifies the maximum time, in seconds, that each echo request packet (“pings”) is active. The default value is 80 (seconds). The Alias of the TimeToLive parameter is TTL.

        Required?                    false
        Position?                    named
        Default value                80
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
System.Management.ManagementObject#root\cimv2\Win32_PingStatus, System.Management.Automation.RemotingJob, System.Boolean
When you use the AsJob parameter, the cmdlet returns a job object. When you use the Quiet parameter, it returns a Boolean. Otherwise, this cmdlet returns a Win32_PingStatus object for each ping.

NOTES

This cmdlet uses the Win32_PingStatus class. A “get-wmiojbect win32_pingstatus” command is equivalent to a Test-Connection command.

————————– EXAMPLE 1 ————————–

C:\PS>Test-Connection server01

    Source        Destination     IPV4Address     IPV6Address Bytes    Time(ms)
    ——        ———–     ———–     ———– —–    ——–
    ADMIN1        Server01        157.59.137.44                32     0
    ADMIN1        Server01        157.59.137.44                32     0
    ADMIN1        Server01        157.59.137.44                32     0
    ADMIN1        Server01        157.59.137.44                32     1

    Description
    ———–
    This command sends echo request packets (“pings”) from the local computer to the Server01 computer. This command uses the ComputerName parameter to specify the Server01 computer, but omits the optional parameter name.

————————– EXAMPLE 2 ————————–

C:\PS>Test-Connection -ComputerName server01, server02, server12 -Credential domain01\user01

    Description
    ———–
    This command sends pings from the local computer to several remote computers. It uses the Credential parameter to specify a user account that has permission to ping all of the remote computers.

————————– EXAMPLE 3 ————————–

C:\PS>Test-Connection -Source Server02, Server 12, localhost -ComputerName Server01

    Description
    ———–
    This command sends pings from different source computers to a single remote computer, Server01. Use this command format to test the latency of connections from multiple points.

————————– EXAMPLE 4 ————————–

C:\PS>Test-Connection -ComputerName Server01 -Count 3 -Delay 2 -TTL 256 -BufferSize 256 -throttle 32

    Description
    ———–
    This command sends three pings from the local computer to the Server01 computer. It uses the parameters of Test-Connection to customize the command.

Use this command format when the ping response is expected to take longer than usual, either because of an extended number of hops or a high-traffic network condition.

————————– EXAMPLE 5 ————————–

C:\PS>$job = Test-Connection -ComputerName (Get-Content servers.txt) -AsJob

C:\PS> if ($job.jobstateinfo.state -ne “Running”) {$results = Receive-Job $job}

    Description
    ———–
    This example shows how to run a Test-Connection command as a Windows PowerShell background job.

The first command uses the Test-Connection cmdlet to ping many computers in an enterprise. The value of ComputerName parameter is a Get-Content command that reads a list of computer names from the Servers.txt file. The command uses the AsJob parameter to run the command as a background job.

The second command checks to see that the job is not still running, and if it is not, it uses a Receive-Job command to get the results and store them in the $results Variable.

————————– EXAMPLE 6 ————————–

C:\PS>Test-Connection Server55 -Credential domain55\user01 -Impersonation Identify

    Description
    ———–
    This command uses the Test-Connection cmdlet to ping a remote computer. The command uses the Credential parameter to specify a user account with permission to ping the remote computer and the Impersonation parameter to change the impersonation level to “Identify”.

————————– EXAMPLE 7 ————————–

C:\PS>if (Test-Connection -ComputerName Server01 -quiet) {New-PSSession Server01}

    Description
    ———–
    This command creates a PSSession on the Server01 only if at least one of the pings sent to the computer succeeds.

The command uses the Test-Connection cmdlet to ping the Server01 computer. The command uses the Quiet parameter, which returns a Boolean value, instead of a Win32_PingStatus object. The value is $True if any of the four pings succeed and is, otherwise, false.

If the Test-Connection command returns a value of $True, the command uses the New-PSSession cmdlet to create the PSSession.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135266
    Add-Computer
    Restart-Computer
    Stop-Computer

cmdlet, ComputerSecureChannel, Test

Test-ComputerSecureChannel

February 26, 2014 Adam

NAME
Test-ComputerSecureChannel

SYNOPSIS
Tests and repairs the secure channel between the local computer and its domain.

SYNTAX
Test-ComputerSecureChannel [-Repair] [-Server <string>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Test-ComputerSecureChannel cmdlet verifies that the secure channel between the local computer and its domain is working correctly by checking the status of its trust relationships. If a connection fails, you can use the Repair parameter to try to restore it.

Test-ComputerSecureChannel returns “True” if the secure channel is working correctly and “False” if it is not. This result lets you use the cmdlet in conditional statements in Functions and scripts. To get more detailed test results, use the Verbose parameter.

This cmdlet works much like NetDom.exe. Both NetDom and Test-ComputerSecureChannel use the NetLogon service to perform the actions.

PARAMETERS
-Repair [<SwitchParameter>]
Removes and then rebuilds the secure channel established by the NetLogon service. Use this parameter to try to restore a connection that has failed the test (returned “False”.)

To use this parameter, the current user must be a member of the Administrators group on the local computer.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

-Server <string>
Uses the specified domain controller to run the command. If this parameter is omitted, Test-ComputerSecureChannel selects a default domain controller for the operation.

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
System.Boolean
The cmdlet returns “True” when the connection is working correctly and “False” when it is not.

NOTES

To run a Test-ComputerSecureChannel command on Windows Vista and later versions of Windows, open Windows PowerShell with the “Run as administrator” option.

Test-ComputerSecureChannel is implemented by using the I_NetLogonControl2 Function, which controls various aspects of the Netlogon service.

————————– EXAMPLE 1 ————————–

C:\PS>Test-ComputerSecureChannel

True

    Description
    ———–
    This command tests the secure channel between the local computer and the domain to which it is joined.

————————– EXAMPLE 2 ————————–

C:\PS>Test-ComputerSecureChannel -Server DCName.fabrikam.com

True

    Description
    ———–
    This command specifies a preferred domain controller for the test.

————————– EXAMPLE 3 ————————–

C:\PS>Test-ComputerSecureChannel -Repair

True

    Description
    ———–
    This command resets the secure channel between the local computer and its domain.

————————– EXAMPLE 4 ————————–

C:\PS>Test-ComputerSecureChannel -Verbose

    VERBOSE: Performing operation “Test-ComputerSecureChannel” on Target “SERVER01”.
    True
    VERBOSE: “The secure channel between ‘SERVER01’ and ‘net.fabrikam.com’ is alive and working correctly.”

    Description
    ———–
    This command uses the Verbose common parameter to request detailed messages about the operation. For more information about the Verbose parameter, see about_CommonParameters.

————————– EXAMPLE 5 ————————–

C:\PS>Set-Alias tcsc Test-ComputerSecureChannel

    if (!(tcsc))
         {Write-Host “Connection failed. Reconnect and retry.”}
    else { &(.\get-Servers.ps1) }

    Description
    ———–
    This example shows how to use Test-ComputerSecureChannel to test a connection before running a script that requires the connection.

The first command uses the Set-Alias cmdlet to create an Alias for the cmdlet name. This saves space and prevents typing errors.

The If statement checks the value that Test-ComputerSecureChannel returns before running a script.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=137749
    Checkpoint-Computer
    Restart-Computer
    Stop-Computer
    Reset-ComputerMachinePassword

cmdlet, Object, Tee

Tee-Object

February 26, 2014 Adam

NAME
Tee-Object

SYNOPSIS
Saves command output in a file or Variable, and displays it in the console.

SYNTAX
Tee-Object [-FilePath] <string> [-InputObject <psobject>] [<CommonParameters>]

Tee-Object -Variable <string> [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
The Tee-Object cmdlet sends the output of a command in two directions (like the letter “T”). It stores the output in a file or Variable and also sends it down the pipeline. If Tee-Object is the last command in the pipeline, the command output is displayed in the console.

PARAMETERS
-FilePath <string>
Specifies the file where the cmdlet stores the object. Accepts wildcards that resolve to a single file.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-InputObject <psobject>
Specifies the object input to the cmdlet. Enter a Variable that contains the objects or type a command or expression that gets the objects.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? false

-Variable <string>
Assigns a reference to the input objects to the specified Variable.

        Required?                    true
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
System.Management.Automation.PSObject
You can pipe objects to be redirected to Tee-Object.

OUTPUTS
System.Management.Automation.PSObject
Tee-Object returns the object that it redirected.

NOTES

You can also use the Out-File cmdlet or the redirection operator, both of which save the output in a file but do not send it down the pipeline.

Tee-Object uses Unicode encoding when it writes to files. As a result, the output might not be formatted properly in files with a different encoding. To specify the encoding, use the Out-File cmdlet.

————————– EXAMPLE 1 ————————–

C:\PS>Get-Process | Tee-Object -FilePath C:\Test1\testfile2.txt

    Handles NPM(K)    PM(K)     WS(K) VM(M) CPU(s)    Id ProcessName
    ——- ——    —–     —– —– ——    — ———–
     83     4     2300     4520    39     0.30    4032 00THotkey
     272     6     1400     3944    34     0.06    3088 alg
     81     3     804     3284    21     2.45     148 ApntEx
     81     4     2008     5808    38     0.75    3684 Apoint
    …

    Description
    ———–
    This command gets a list of the processes running on the computer and sends the result to a file. Because a second path is not specified, the result will be displayed in the console.

————————– EXAMPLE 2 ————————–

C:\PS>Get-Process notepad | Tee-Object -variable proc | Select-Object processname,handles

    ProcessName                             Handles
    ———–                             ——-
    notepad                                 43
    notepad                                 37
    notepad                                 38
    notepad                                 38

    Description
    ———–
    This command gets a list of the processes running on the computer and sends the result to a Variable named “proc”. It then pipes the resulting objects along to Select-Object, which selects the ProcessName and Handles property. Note that the $proc Variable includes the default information returned by Get-Process.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113417
    about_Redirection
    Select-Object

cmdlet, Service, Suspend

Suspend-Service

February 26, 2014 Adam

NAME
Suspend-Service

SYNOPSIS
Suspends (pauses) one or more running services.

SYNTAX
Suspend-Service [-Name] <string[]> [-Exclude <string[]>] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Suspend-Service -DisplayName <string[]> [-Exclude <string[]>] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Suspend-Service [-InputObject <ServiceController[]>] [-Exclude <string[]>] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Suspend-Service cmdlet sends a suspend message to the Windows Service Controller for each of the specified services. While suspended, the service is still running, but its action is halted until resumed, such as by using Resume-Service. You can specify the services by their service names or display names, or you can use the InputObject parameter to pass a service object representing the services that you want to suspend.

PARAMETERS
-DisplayName <string[]>
Specifies the display names of the services to be suspended. Wildcards are permitted.

        Required?                    true
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Exclude <string[]>
Omits the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as “s*”. Wildcards are permitted.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Include <string[]>
Suspends only the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as “s*”. Wildcards are permitted.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-InputObject <ServiceController[]>
Specifies ServiceController objects representing the services to be suspended. Enter a Variable that contains the objects, or type a command or expression that gets the objects.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? false

-Name <string[]>
Specifies the service names of the services to be suspended. Wildcards are permitted.

The parameter name is optional. You can use “Name” or its Alias, “ServiceName”, or you can omit the parameter name.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByValue, ByPropertyName)
        Accept wildcard characters? false

-PassThru [<SwitchParameter>]
Returns an object representing the service. By default, this cmdlet does not generate any output.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
System.ServiceProcess.ServiceController or System.String
You can pipe a service object or a string that contains a service name to Suspend-Service.

OUTPUTS
None or System.ServiceProcess.ServiceController
When you use the PassThru parameter, Suspend-Service generates a System.ServiceProcess.ServiceController object representing the service. Otherwise, this cmdlet does not generate any output.

NOTES

Suspend-Service can control services only when the current user has permission to do so. If a command does not work correctly, you might not have the required permissions.

Also, Suspend-Service can suspend only services that support being suspended and resumed. To determine whether a particular service can be suspended, use the Get-Service cmdlet with the CanPauseAndContinue property. For example, “Get-Service wmi | Format-List name, canpauseandcontinue”. To find all services on the computer that can be suspended, type “Get-Service | Where-Object {$_.canpauseandcontinue -eq “True”}”.

To find the service names and display names of the services on your system, type “Get-Service“. The service names appear in the Name column, and the display names appear in the DisplayName column.

————————– EXAMPLE 1 ————————–

C:\PS>Suspend-Service -displayname “Telnet”

    Description
    ———–
    This command suspends the Telnet service (Tlntsvr) service on the local computer.

————————– EXAMPLE 2 ————————–

C:\PS>Suspend-Service -Name lanman* -WhatIf

    Description
    ———–
    This command tells what would happen if you suspended the services that have a service name that begins with “lanman”. To suspend the services, rerun the command without the WhatIf parameter.

————————– EXAMPLE 3 ————————–

C:\PS>Get-Service schedule | Suspend-Service

    Description
    ———–
    This command uses the Get-Service cmdlet to get an object that represents the Task Scheduler (Schedule) service on the computer. The pipeline operator (|) passes the result to the Suspend-Service cmdlet, which suspends the service.

————————– EXAMPLE 4 ————————–

C:\PS>Get-Service | Where-Object {$_.canpauseandcontinue -eq “True”} | Suspend-Service -Confirm

    Description
    ———–
    This command suspends all of the services on the computer that can be suspended. It uses the Get-Service cmdlet to get objects representing the services on the computer. The pipeline operator (|) passes the results to the Where-Object cmdlet, which selects only the services that have a value of “True” for the CanPauseAndContinue property. Another pipeline operator passes the results to the Suspend-Service cmdlet. The Confirm parameter prompts you for confirmation before suspending each of the services.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113416
    Get-Service
    Start-Service
    Stop-Service
    Restart-Service
    Resume-Service
    Set-Service
    New-Service

cmdlet, Stop, Transcript

Stop-Transcript

February 26, 2014 Adam

NAME
Stop-Transcript

SYNOPSIS
Stops a transcript.

SYNTAX
Stop-Transcript [<CommonParameters>]

DESCRIPTION
The Stop-Transcript cmdlet stops a transcript that was started by using the Start-Transcript cmdlet. You can also stop a transcript by ending the session.

PARAMETERS
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
System.String
Stop-Transcript returns a string that contains a status message and the path to the output file.

NOTES

If a transcript has not been started, the command fails.

————————– EXAMPLE 1 ————————–

C:\PS>Stop-Transcript

    Description
    ———–
    This command stops any running transcripts.

RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113415
Start-Transcript

cmdlet, Service, Stop

Stop-Service

February 26, 2014 Adam

NAME
Stop-Service

SYNOPSIS
Stops one or more running services.

SYNTAX
Stop-Service [-Name] <string[]> [-Exclude <string[]>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Stop-Service -DisplayName <string[]> [-Exclude <string[]>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Stop-Service [-InputObject <ServiceController[]>] [-Exclude <string[]>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Stop-Service cmdlet sends a stop message to the Windows Service Controller for each of the specified services. You can specify the services by their service names or display names, or you can use the InputObject parameter to pass a service object representing the services that you want to stop.

PARAMETERS
-DisplayName <string[]>
Specifies the display names of the services to be stopped. Wildcards are permitted.

        Required?                    true
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Exclude <string[]>
Omits the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as “s*”. Wildcards are permitted.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Force [<SwitchParameter>]
Allows the cmdlet to stop a service even if that service has dependent services.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Include <string[]>
Stops only the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as “s*”. Wildcards are permitted.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-InputObject <ServiceController[]>
Specifies ServiceController objects representing the services to be stopped. Enter a Variable that contains the objects, or type a command or expression that gets the objects.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? false

-Name <string[]>
Specifies the service names of the services to be stopped. Wildcards are permitted.

The parameter name is optional. You can use “Name” or its Alias, “ServiceName”, or you can omit the parameter name.

-PassThru [<SwitchParameter>]
Returns an object representing the service. By default, this cmdlet does not generate any output.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
System.ServiceProcess.ServiceController or System.String
You can pipe a service object or a string that contains the name of a service to Stop-Service.

OUTPUTS
None or System.ServiceProcess.ServiceController
When you use the PassThru parameter, Stop-Service generates a System.ServiceProcess.ServiceController object representing the service. Otherwise, this cmdlet does not generate any output.

NOTES

You can also refer to Stop-Service by its built-in Alias, “spsv”. For more information, see about_aliases.

Stop-Service can control services only when the current user has permission to do so. If a command does not work correctly, you might not have the required permissions.

To find the service names and display names of the services on your system, type “Get-Service“. The service names appear in the Name column and the display names appear in the DisplayName column.

————————– EXAMPLE 1 ————————–

C:\PS>Stop-Service sysmonlog

    Description
    ———–
    This command stops the Performance Logs and Alerts (SysmonLog) service on the local computer.

————————– EXAMPLE 2 ————————–

C:\PS>Get-Service -displayname telnet | Stop-Service

    Description
    ———–
    This command stops the Telnet service on the local computer. The command uses the Get-Service cmdlet to get an object representing the Telnet service. The pipeline operator (|) pipes the object to the Stop-Service cmdlet, which stops the service.

————————– EXAMPLE 3 ————————–

C:\PS>Get-Service iisadmin | Format-List -property name, dependentservices

C:PS>Stop-Service iisadmin -Force -Confirm

    Description
    ———–
    The Stop-Service command stops the IISAdmin service on the local computer. Because stopping this service also stops the services that depend on the IISAdmin service, it is best to precede the Stop-Service command with a command that lists the services that depend on the IISAdmin service.

The first command lists the services that depend on IISAdmin. It uses the Get-Service cmdlet to get an object representing the IISAdmin service. The pipeline operator (|) passes the result to the Format-List cmdlet. The command uses the Property parameter of Format-List to list only the Name and DependentServices properties of the service.

The second command stops the IISAdmin service. The Force parameter is required to stop a service that has dependent services. The command uses the Confirm parameter to request confirmation from the user before stopping each service.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113414
    Get-Service
    Suspend-Service
    Start-Service
    Restart-Service
    Resume-Service
    Set-Service
    New-Service

cmdlet, Process, Stop

Stop-Process

February 26, 2014 Adam

NAME
Stop-Process

SYNOPSIS
Stops one or more running processes.

SYNTAX
Stop-Process [-Id] <Int32[]> [-Force] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Stop-Process -InputObject <Process[]> [-Force] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Stop-Process -Name <string[]> [-Force] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Stop-Process cmdlet stops one or more running processes. You can specify a process by process name or process ID (PID), or pass a process object to Stop-Process. Stop-Process works only on processes running on the local computer.

On Windows Vista and later versions of Windows, to stop a process that is not owned by the current user, you must start Windows PowerShell with the “Run as administrator” option. Also, you are prompted for confirmation unless you use the Force parameter.

PARAMETERS
-Force [<SwitchParameter>]
Stops the specified processes without prompting for confirmation. By default, Stop-Process prompts for confirmation before stopping any process that is not owned by the current user.

To find the owner of a process, use the Get-WmiMethod cmdlet to get a Win32_Process object that represents the process, and then use the GetOwner method of the object.

-Id <Int32[]>
Specifies the process IDs of the processes to be stopped. To specify multiple IDs, use commas to separate the IDs. To find the PID of a process, type “Get-Process“. The parameter name (“Id”) is optional.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-InputObject <Process[]>
Stops the processes represented by the specified process objects. Enter a Variable that contains the objects, or type a command or expression that gets the objects.

        Required?                    true
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? false

-Name <string[]>
Specifies the process names of the processes to be stopped. You can type multiple process names (separated by commas) or use wildcard characters.

        Required?                    true
        Position?                    named
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-PassThru [<SwitchParameter>]
Returns an object representing the process. By default, this cmdlet does not generate any output.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
System.Diagnostics.Process
You can pipe a process object to Stop-Process.

OUTPUTS
None or System.Diagnostics.Process
When you use the PassThru parameter, Stop-Process returns a System.Diagnostics.Process object that represents the stopped process. Otherwise, this cmdlet does not generate any output.

NOTES

You can also refer to Stop-Process by its built-in Aliases, “kill” and “spps”. For more information, see about_aliases.

You can also use the properties and methods of the Windows Management Instrumentation (WMI) Win32_Process object in Windows PowerShell. For more information, see Get-WmiObject and the WMI SDK.

When stopping processes, be aware that stopping a process can stop process and services that depend on the process. In an extreme case, stopping a process can stop Windows.

————————– EXAMPLE 1 ————————–

C:\PS>Stop-Process -name notepad

    Description
    ———–
    This command stops all instances of the Notepad process on the computer. (Each instance of Notepad runs in its own process.) It uses the Name parameter to specify the processes, all of which have the same name. If you were to use the ID parameter to stop the same processes, you would have to list the process IDs of each instance of Notepad.

————————– EXAMPLE 2 ————————–

C:\PS>Stop-Process -Id 3952 -Confirm -PassThru

    Confirm
    Are you sure you want to perform this action?
    Performing operation “Stop-Process” on Target “notepad (3952)”.
    [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help
    (default is “Y”):y
    Handles NPM(K)    PM(K)     WS(K) VM(M) CPU(s)     Id ProcessName
    ——- ——    —–     —– —– ——     — ———–
         41     2     996     3212    31            3952 notepad

    Description
    ———–
    This command stops a particular instance of the Notepad process. It uses the process ID, 3952, to identify the process. The Confirm parameter directs Windows PowerShell to prompt the user before stopping the process. Because the prompt includes the process name, as well as its ID, this is best practice. The PassThru parameter passes the process object to the formatter for display. Without this parameter, there would be no display after a Stop-Process command.

————————– EXAMPLE 3 ————————–

C:\PS>calc

c:\PS>$p = Get-Process calc

c:\PS>Stop-Process -inputobject $p

c:\PS>Get-Process | Where-Object {$_.HasExited}

    Description
    ———–
    This series of commands starts and stops the Calc process and then detects processes that have stopped.

The first command (“calc”) starts an instance of the calculator. The second command (“$p = Get-Process calc”), uses the Get-Process cmdlet to get an object representing the Calc process and store it in the $p Variable. The third command (“Stop-Process -inputobject $p”) uses the Stop-Process cmdlet to stop the Calc process. It uses the InputObject parameter to pass the object to Stop-Process.

The last command gets all of the processes on the computer that were running but that are now stopped. It uses the Get-Process cmdlet to get all of the processes on the computer. The pipeline operator (|) passes the results to the Where-Object cmdlet, which selects the ones where the value of the HasExited property is TRUE. HasExited is just one property of process objects. To find all the properties, type “Get-Process | Get-Member“.

————————– EXAMPLE 4 ————————–

C:\PS>Get-Process lsass | Stop-Process

    Stop-Process : Cannot stop process ‘lsass (596)’ because of the following error: Access is denied
    At line:1 char:34
    + Get-Process lsass | Stop-Process <<<<

    [ADMIN]: C:\PS> Get-Process lsass | Stop-Process
    Warning!
    Are you sure you want to perform this action?
    Performing operation ‘Stop-Process‘ on Target ‘lsass(596)’
    [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is “Y”):

[ADMIN]: C:\PS> Get-Process lsass | Stop-Process -Force
[ADMIN]: C:\PS>

    Description
    ———–
    These commands show the effect of using the Force parameter to stop a process that is not owned by the user.

The first command uses the Get-Process cmdlet to get the Lsass process. A pipeline operator sends the process to the Stop-Process cmdlet to stop it. As shown in the sample output, the first command fails with an “Access denied” message, because this process can be stopped only by a member of the Administrator’s group on the computer.

When Windows PowerShell is opened with the “Run as administrator” option, and the command is repeated, Windows PowerShell prompts you for confirmation.

The second command uses the Force parameter to suppress the prompt. As a result, the process is stopped without confirmation.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113412
    Get-Process
    Start-Process
    Stop-Process
    Wait-Process
    Debug-Process

cmdlet, Job, Stop

Stop-Job

February 26, 2014 Adam

NAME
Stop-Job

SYNOPSIS
Stops a Windows PowerShell background job.

SYNTAX
Stop-Job [[-InstanceId] <Guid[]>] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Stop-Job [-Job] <Job[]> [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Stop-Job [[-Name] <string[]>] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Stop-Job [-Id] <Int32[]> [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Stop-Job [-State {NotStarted | Running | Completed | Failed | Stopped | Blocked}] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Stop-Job cmdlet stops Windows PowerShell background jobs that are in progress. You can use this cmdlet to stop all jobs or stop selected jobs based on their name, ID, instance ID, or state, or by passing a job object to Stop-Job.

You can use Stop-Job to stop jobs that were started by using Start-Job or the AsJob parameter of Invoke-Command. When you stop a background job, Windows PowerShell completes all tasks that are pending in that job queue and then ends the job. No new tasks are added to the queue after this command is submitted.

This cmdlet does not delete background jobs. To delete a job, use Remove-Job.

PARAMETERS
-Id <Int32[]>
Stops jobs with the specified IDs. The default is all jobs in the current session.

The ID is an integer that uniquely identifies the job within the current session. It is easier to remember and type than the InstanceId, but it is unique only within the current session. You can type one or more IDs (separated by commas). To find the ID of a job, type “Get-Job” without parameters.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-InstanceId <Guid[]>
Stops only jobs with the specified instance IDs. The default is all jobs.

An instance ID is a GUID that uniquely identifies the job on the computer. To find the instance ID of a job, use Get-Job.

        Required?                    false
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Job <Job[]>
Specifies the jobs to be stopped. Enter a Variable that contains the jobs or a command that gets the jobs. You can also use a pipeline operator to submit jobs to the Stop-Job cmdlet. By default, Stop-Job deletes all jobs that were started in the current session.

-Name <string[]>
Stops only the jobs with the specified friendly names. Enter the job names in a comma-separated list or use wildcard characters (*) to enter a job name pattern. By default, Stop-Job stops all jobs created in the current session.

Because the friendly name is not guaranteed to be unique, use the WhatIf and Confirm parameters when stopping jobs by name.

        Required?                    false
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? true

-PassThru [<SwitchParameter>]
Returns an object representing the new background job. By default, this cmdlet does not generate any output.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-State <JobState>
Stops only jobs within the specified state. Valid values are NotStarted, Running, Completed, Stopped, Failed, and Blocked.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
System.Management.Automation.RemotingJob
You can pipe a job object to Stop-Job.

OUTPUTS
None or System.Management.Automation.RemotingJob
When you use the PassThru parameter, Stop-Job returns a job object. Otherwise, this cmdlet does not generate any output.

NOTES

————————– EXAMPLE 1 ————————–

C:\PS>$s = New-PSSession -computername Server01 -credential domain01\admin02

C:\PS> $j = Invoke-Command -session $s -scriptblock {Start-Job -scriptblock {Get-Eventlog system}}

C:\PS> Invoke-Command -session $s -scriptblock {param($j) Stop-Job -job $j} -ArgumentList $j

    Description
    ———–
    This example shows how to use the Stop-Job cmdlet to stop a job that is running on a remote computer.

Because the job was started by using Invoke-Command to run a Start-Job command remotely, the job object is stored on the remote computer, and you must use another Invoke-Command command to run a Stop-Job command remotely. For more information about remote background jobs, see about_remote_Jobs.

The first command creates a Windows PowerShell session (PSSession) on the Server01 computer and saves the session object in the $s Variable. The command uses the credentials of a domain administrator.

The second command uses the Invoke-Command cmdlet to run a Start-Job command in the session. The command in the job gets all of the events in the System event log. The resulting job object is stored in the $j Variable.

The third command stops the job. It uses the Invoke-Command cmdlet to run a Stop-Job command in the PSSession on Server01. Because the job objects are stored in $j, which is a Variable on the local computer, the command uses the “param” keyword to declare the local Variables in the command, and it uses the ArgumentList parameter to supply values for the Variables.

When the command completes, the job is stopped and the PSSession in $s is available for use.

————————– EXAMPLE 2 ————————–

C:\PS>Stop-Job -state failed

    Description
    ———–
    This command stops all jobs with a State value of “Failed”.

————————– EXAMPLE 3 ————————–

C:\PS>Stop-Job -name job1

    Description
    ———–
    This command stops the Job1 background job.

————————– EXAMPLE 4 ————————–

C:\PS>Stop-Job -Id 1, 3, 4

    Description
    ———–
    This command stops three jobs. It identifies them by their IDs.

————————– EXAMPLE 5 ————————–

C:\PS>Get-Job | Stop-Job

    Description
    ———–
    This command stops all the background jobs in the current session.

————————– EXAMPLE 6 ————————–

C:\PS>Stop-Job -state blocked

    Description
    ———–
    This command stops all the jobs with a job status of “Blocked”.

————————– EXAMPLE 7 ————————–

C:\PS>Get-Job | Format-Table ID, Name, Command, @{Label=”State”;Expression={$_.jobstateinfo.state}}, I
nstanceID -auto

    Id Name Command                 State InstanceId
    — —- ——-                 —– ———-
     1 Job1 Start-Service schedule Running 05abb67a-2932-4bd5-b331-c0254b8d9146
     3 Job3 Start-Service schedule Running c03cbd45-19f3-4558-ba94-ebe41b68ad03
     5 Job5 Get-Service s*         Blocked e3bbfed1-9c53-401a-a2c3-a8db34336adf

C:\PS> Stop-Job -instanceid e3bbfed1-9c53-401a-a2c3-a8db34336adf

    Description
    ———–
    These commands show how to stop a job based on its instance ID.

The first command uses a Get-Job command to get the jobs in the current session. The command uses a pipeline operator (|) to send the jobs to a Format-Table command, which displays a table of the specified properties of each job. The table includes the Instance ID of each job. It uses a calculated property to display the job state.

The second command uses a Stop-Job command with the InstanceID parameter to stop a selected job.

————————– EXAMPLE 8 ————————–

C:\PS>$j = Invoke-Command -computername Server01 -scriptblock {Get-Eventlog system} -asjob

C:\PS> $j | Stop-Job -PassThru

    Id    Name    State     HasMoreData     Location         Command
    —    —-    —-     ———–     ——–         ——-
    5     Job5    Stopped    True            judithh-tablet Get-Eventlog system

    Description
    ———–
    This example shows how to use the Stop-Job cmdlet to stop a job that is running on a remote computer.

Because the job was started by using the AsJob parameter of Invoke-Command, the job object is located on the local computer, even though the job runs on the remote computer. As such, you can use a local Stop-Job command to stop the job.

The first command uses the Invoke-Command cmdlet to start a background job on the Server01 computer. The command uses the AsJob parameter to run the remote command as a background job.

This command returns a job object, which is the same job object that Start-Job returns. The command saves the job object in the $j Variable.

The second command uses a pipeline operator to send the job in the $j Variable to Stop-Job. The command uses the PassThru parameter to direct Stop-Job to return a job object. The job object display confirms that the State of the job is “Stopped”.

For more information about remote background jobs, see about_remote_Jobs.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113413
    about_jobs
    about_job_details
    about_remote_Jobs
    Start-Job
    Get-Job
    Receive-Job
    Wait-Job
    Remove-Job
    Invoke-Command

cmdlet, Computer, Stop

Stop-Computer

February 26, 2014 Adam

NAME
Stop-Computer

SYNOPSIS
Stops (shuts down) local and remote computers.

SYNTAX
Stop-Computer [[-ComputerName] <string[]>] [[-Credential] <PSCredential>] [-AsJob] [-Authentication {Default | None | Connect | Call | Packet | PacketIntegrity | PacketPrivacy | Unchanged}] [-Force] [-Impersonation {Default | Anonymous | Identify | Impersonate | Delegate}] [-ThrottleLimit <int>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Stop-Computer cmdlet shuts down computers remotely. It can also shut down the local computer.

You can use the parameters of Stop-Computer to run the shutdown operations as a background job, to specify the authentication levels and alternate credentials, to limit the concurrent connections that are created to run the command, and to force an immediate shut down.

This cmdlet does not require Windows PowerShell remoting unless you use the AsJob parameter.

PARAMETERS
-AsJob [<SwitchParameter>]
Runs the command as a background job.

For more information about Windows PowerShell background jobs, see about_jobs and see about_remote_Jobs.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Authentication <AuthenticationLevel>
Specifies the authentication level that is used for the WMI connection. (Stop-Computer uses WMI.) The default value is Packet.

Valid values are:

        Required?                    false
        Position?                    named
        Default value                4
        Accept pipeline input?     false
        Accept wildcard characters? false

-ComputerName <string[]>
Stops the specified computers. The default is the local computer.

Type the NETBIOS name, IP address, or fully qualified domain name of one or more computers in a comma-separated list. To specify the local computer, type the computername or “localhost”.

This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter even if your computer is not configured to run remote commands.

        Required?                    false
        Position?                    1
        Default value                .
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Credential <PSCredential>
Specifies a user account that has permission to perform this action. The default is the current user.

Type a user name, such as “User01” or “Domain01\User01”, or enter a PSCredential object, such as one from the Get-Credential cmdlet.

        Required?                    false
        Position?                    2
        Default value                Current user
        Accept pipeline input?     false
        Accept wildcard characters? false

-Force [<SwitchParameter>]
Forces an immediate shut down of the computers.

-Impersonation <ImpersonationLevel>
Specifies the impersonation level to use when calling WMI. (Stop-Computer uses WMI.) The default value is “Impersonate”.

Valid values are:

        Required?                    false
        Position?                    named
        Default value                Impersonate
        Accept pipeline input?     false
        Accept wildcard characters? false

The throttle limit applies only to the current command, not to the session or to the computer.

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
None or System.Management.Automation.RemotingJob
When you use the AsJob parameter, the cmdlet returns a job object (System.Management.Automation.RemotingJob). Otherwise, it does not generate any output.

NOTES

This cmdlet uses the Win32Shutdown method of the Win32_OperatingSystem WMI class.

————————– EXAMPLE 1 ————————–

C:\PS>Stop-Computer

    Description
    ———–
    This command shuts down the local computer.

————————– EXAMPLE 2 ————————–

C:\PS>Stop-Computer -ComputerName Server01, Server02, localhost

    Description
    ———–
    This command stops two remote computers, Server01 and Server02, and the local computer, identified as “localhost”.

————————– EXAMPLE 3 ————————–

C:\PS>$j = Stop-Computer -ComputerName Server01, Server02 -AsJob

C:\PS> $results = $j | Receive-Job

C:\PS> $results

    Description
    ———–
    These commands run a Stop-Computer command as a background job on two remote computers, and then get the results.

The first command uses the AsJob parameter to run the command as a background job. The command saves the resulting job object in the $j Variable.

The second command uses a pipeline operator to send the job object in $j to the Receive-Job cmdlet, which gets the job results. The command saves the results in the $results Variable.

The third command displays the result saved in the $results Variable.

Because the AsJob parameter creates the job on the local computer and automatically returns the results to the local computer, you can run the Receive-Job command as a local command.

————————– EXAMPLE 4 ————————–

C:\PS>Stop-Computer -comp Server01 -Impersonation anonymous -Authentication PacketIntegrity

    Description
    ———–
    This command restarts the Server01 remote computer. The command uses customized impersonation and authentication settings.

————————– EXAMPLE 5 ————————–

C:\PS>$s = Get-Content domain01.txt

C:\PS> $c = Get-Credential domain01\admin01

C:\PS> Stop-Computer -ComputerName $s -Force -ThrottleLimit 10 -Credential $c

    Description
    ———–
    These commands force an immediate shut down of all of the computers in Domain01.

The first command gets a list of computers in the domain and saves it in the $s Variable.

The second command gets the credentials of a domain administrator and saves them in the $c Variable.

The third command shuts down the computers. It uses ComputerName parameter to submit the list of computers in the $s Variable, the Force parameter to force an immediate shutdown, and the Credential parameter to submit the credentials saved in the $c Variable. It also uses the ThrottleLimit parameter to limit the command to 10 concurrent connections.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135263
    Add-Computer
    Checkpoint-Computer
    Remove-Computer
    Restart-Computer
    Restore-Computer
    Test-Connection