Tag Archives: Confirm

cmdlet, Service, Start

Start-Service

NAME
    Start-Service

SYNOPSIS
    Starts one or more stopped services.

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

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

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

DESCRIPTION
    The Start-Service cmdlet sends a start message to the Windows Service Controller for each of the specified services. If a service is already running, the message is ignored without error. You can specify the services by their service names or display names, or you can use the InputObject parameter to supply a service object representing the services that you want to start.

PARAMETERS
    -DisplayName <string[]>
        Specifies the display names of the services to be started. 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[]>
        Starts 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 started. 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 for the service to be started.

        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

    <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.ServiceProcess.ServiceController, System.String
        You can pipe objects that represent the services or strings that contain the service names to Start-Service.

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

NOTES

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

        Start-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.

        You can start only the services that have a start type of “Manual” or “Automatic”. You cannot start the services with a start type of “Disabled”. If a Start-Service command fails with the message “Cannot start service <service-Name> on computer,” use a Get-WmiObject command to find the start type of the service and, if necessary, use a Set-Service command to change the start type of the service.

        Some services, such as Performance Logs and Alerts (SysmonLog) stop automatically if they have no work to do. When Windows PowerShell starts a service that stops itself almost immediately, it displays the following message: “Service <display-Name> start failed.”

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

    C:\PS>Start-Service -Name eventlog

    Description
    ———–
    This command starts the EventLog service on the local computer. It uses the Name parameter to identify the service by its service name.

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

    C:\PS>Start-Service -displayname *remote* -WhatIf

    Description
    ———–
    This command tells what would happen if you started the services with a display name that includes “remote”. It uses the DisplayName parameter to specify the services by their display name instead of by their service name. And, it uses the WhatIf parameter to tell what would happen if the command were executed instead of executing the command.

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

    C:\PS>$s = Get-Service wmi

    C:\PS>Start-Service -InputObject $s -PassThru | Format-List >> services.txt

    Description
    ———–
    These commands start the Windows Management Instrumentation (WMI) service on the computer and add a record of the action to the services.txt file. The first command uses the Get-Service cmdlet to get an object representing the WMI service and store it in the $s Variable.

    The second command uses the Start-Service cmdlet to start the WMI service. It identifies the service by using the InputObject parameter to pass the $s Variable containing the WMI service object to Start-Service. Then, it uses the PassThru parameter to create an object that represents the starting of the service. Without this parameter, Start-Service does not create any output.

    The pipeline operator (|) passes the object that Start-Service creates to the Format-List cmdlet, which formats the object as a list of its properties. The append redirection operator (>>) redirects the output to the services.txt file, where it is added to the end of the existing file.

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

    C:\PS># Start-Service

    Description
    ———–
    This series of commands shows how to start a service when the start type of the service is “Disabled”. The first command, which uses the Start-Service cmdlet to start the Telnet service (tlntsvr), fails.

    C:\PS>Start-Service tlntsvr

    Start-Service : Service ‘Telnet (TlntSvr)’ cannot be started due to the    following error: Cannot start service TlntSvr on computer ‘.’.
    At line:1 char:14
    + Start-Service <<<< tlntsvr

    The second command uses the Get-WmiObject cmdlet to get the Tlntsvr service. This command retrieves an object with the start type property in the StartMode field. The resulting display reveals that the start type of the Tlntsvr service is “Disabled”.

    C:\PS> Get-WmiObject win32_service | Where-Object {$_.Name -eq “tlntsvr”}

    ExitCode : 0
    Name     : TlntSvr
    ProcessId : 0
    StartMode : Disabled
    State     : Stopped
    Status    : OK

    The next command uses the Set-Service cmdlet to change the start type of the Tlntsvr service to “Manual”.

    C:\PS> Set-Service tlntsvr -startuptype manual

    Now, we can resubmit the Start-Service command. This time, the command succeeds.

    C:\PS> Start-Service tlntsvr

    To verify that the command succeeded, use Get-Service.

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

cmdlet, Start, Transaction

Start-Transaction

NAME
    Start-Transaction

SYNOPSIS
    Starts a transaction.

SYNTAX
    Start-Transaction [-Independent] [-RollbackPreference {Error | TerminatingError | Never}] [-Timeout <int>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Start-Transaction cmdlet starts a transaction, which is a series of commands that are managed as a unit. A transaction can be completed (“committed”), or it can be completely undone (“rolled back”) so that any data changed by the transaction is restored to its original state. Because the commands in a transaction are managed as a unit, either all commands are committed or all commands are rolled back.

    By default, transactions are rolled back automatically if any command in the transaction generates an error, but you can use the RollbackPreference parameter to change this behavior.

    The cmdlets used in a transaction must be designed to support transactions. Cmdlets that support transactions have a UseTransaction parameter. To perform transactions in a provider, the provider must support transactions. The Windows PowerShell Registry provider in Windows Vista and later versions of Windows supports transactions. You can also use the Microsoft.PowerShell.Commands.Management.TransactedString class to include expressions in transactions on any version of Windows that supports Windows PowerShell. Other Windows PowerShell providers can also support transactions.

    Only one transaction can be active at a time. If you start a new, independent transaction while a transaction is in progress (neither completed nor undone), the new transaction becomes the active transaction, and you must commit or roll back the new transaction before making any changes to the original transaction.

    The Start-Transaction cmdlet is one of a set of cmdlets that support the transactions feature in Windows PowerShell. For more information, see about_transactions.

PARAMETERS
    -Independent [<SwitchParameter>]
        Starts a transaction that is independent of any transactions in progress. By default, if you use Start-Transaction while another transaction is in progress, a new subscriber is added to the transaction in progress. This parameter has an effect only when a transaction is already in progress in the session.

        By default, if you use Start-Transaction while a transaction is in progress, the existing transaction object is reused and the subscriber count is incremented. The effect is much like joining the original transaction. An Undo-Transaction command rolls back the entire the transaction. To complete the transaction, you must enter a Complete-Transaction command for each subscriber. Because most transactions that are in progress at the same time are related, the default is sufficient for most uses.

        If you use the Independent parameter, a new transaction is created that can be completed or undone without affecting the original transaction. However, because only one transaction can be active at a time, you must complete or roll back the new transaction before resuming work on the original transaction.

        Required?                    false
        Position?                    named
        Default value                Reuse the original transaction object.
        Accept pipeline input?     false
        Accept wildcard characters? false

    -RollbackPreference <RollbackSeverity>
        Specifies the conditions under which a transaction is automatically rolled back. The default value is “Error”.

        Valid values are:

        — Error: The transaction is rolled back automatically if a terminating or non-terminating error occurs. “Error” is the default.
        — Terminating error: The transaction is rolled back automatically if a terminating error occurs.
        — Never: The transaction is never rolled back automatically.

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

    -Timeout <int>
        Specifies the maximum time, in minutes, that the transaction is active. When the time-out expires, the transaction is automatically rolled back.

        By default, there is no time-out for transactions that are started at the command line. When transactions are started by a script, the default time-out is 30 minutes.

        Required?                    false
        Position?                    named
        Default value                No timeout (infinite)
        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

    <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
    None
        This cmdlet does not generate any output.

NOTES

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

    C:\PS>cd hkcu:\software

    PS HKCU:\software> Start-Transaction

    PS HKCU:\software> New-Item MyCompany -UseTransaction

    PS HKCU:\software> New-Itemproperty MyCompany -name MyKey -value 123 -UseTransaction

    PS HKCU:\software> Undo-Transaction

    Description
    ———–
    These commands start and then roll back a transaction. Because the transaction is rolled back, no changes are made to the Registry.

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

    C:\PS>cd hkcu:\software

    PS HKCU:\software> Start-Transaction

    PS HKCU:\software> New-Item MyCompany -UseTransaction

    PS HKCU:\software> New-Itemproperty MyCompany -name MyKey -value 123 -UseTransaction

    PS HKCU:\software> Complete-Transaction

    Description
    ———–
    These commands start and then complete a transaction. No changes are made to the Registry until the Complete-Transaction command is used.

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

    C:\PS>cd HKCU:\software
    PS HKCU:\software> Start-Transaction
    PS HKCU:\software> New-Item -path NoPath -name MyCompany -UseTransaction
    PS HKCU:\software> New-Item -path . -name MyCompany -UseTransaction

    PS HKCU:\software> Start-Transaction -RollbackPreference never
    PS HKCU:\software> New-Item -path NoPath -name MyCompany -UseTransaction
    PS HKCU:\software> New-Item -path . -name MyCompany -UseTransaction

    # Start-Transaction (-RollbackPreference error)

    PS HKCU:\software> Start-Transaction
    PS HKCU:\software> New-Item -path NoPath -Name MyCompany -UseTransaction
    New-Item : The Registry key at the specified path does not exist.
    At line:1 char:9
    + New-Item <<<< -path NoPath -Name MyCompany -UseTransaction

    PS HKCU:\software> New-Item -path . -name MyCompany -UseTransaction
    New-Item : Cannot use transaction. The transaction has been rolled back or has timed out.
    At line:1 char:9
    + New-Item <<<< -path . -name MyCompany -UseTransaction

    # Start-Transaction (-RollbackPreference never)
    PS HKCU:\software> Start-Transaction -RollbackPreference never
    PS HKCU:\software> New-Item -path NoPath -name MyCompany -UseTransaction
    New-Item : The Registry key at the specified path does not exist.
    At line:1 char:9
    + New-Item <<<< -path NoPath -name MyCompany -UseTransaction

    PS HKCU:\software> New-Item -path . -name MyCompany -UseTransaction
     Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     0 0 MyCompany                     {}

    PS HKCU:\Software> Complete-Transaction
    # Succeeds

    Description
    ———–
    This example demonstrates the effect of changing the RollbackPreference parameter value.

    In the first set of commands, the Start-Transaction command does not use the RollbackPreference parameter. As a result, the default value (“Error”) is used. When an error occurs in a transaction command (the specified path does not exist), the transaction is automatically rolled back.

    In the second set of commands, the Start-Transaction command uses the RollbackPreference parameter with a value of “Never”. As a result, when an error occurs in a transaction command, the transaction is still active and can be completed successfully.

    Because most transactions must be performed without error, the default value of the RollbackPreference parameter is typically preferred.

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

    C:\PS>cd HKCU:\software

    PS HKCU:\software> Start-Transaction
    PS HKCU:\software> New-Item MyCompany -UseTransaction

    PS HKCU:\software> Start-Transaction
    PS HKCU:\software> Get-Transaction
    PS HKCU:\software> New-Item MyCompany2 -UseTransaction

    PS HKCU:\software> Complete-Transaction
    PS HKCU:\software> Complete-Transaction

    PS HKCU:\Software> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— ——
    Error                2                 Active

    Description
    ———–
    This example shows the effect of using the Start-Transaction command while a transaction is in progress. The effect is much like joining the transaction in progress.

    Although this is a simplified command, this scenario commonly occurs when the transaction involves running a script that includes a complete transaction.

    The first Start-Transaction command starts the transaction. The first New-Item command is part of the transaction.

    The second Start-Transaction command adds a new subscriber to the transaction. The Get-Transaction command now returns a transaction with a subscriber count of 2. The second New-Item command is part of the same transaction.

    No changes are made to the Registry until the entire transaction is completed. To complete the transaction, you must enter two Complete-Transaction commands, one for each subscriber. If you were to roll back the transaction at any point, the entire transaction would be rolled back for both subscribers.

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

    C:\PS>cd HKCU:\software
    PS HKCU:\software> Start-Transaction
    PS HKCU:\software> New-Item MyCompany -UseTransaction

    PS HKCU:\software> Start-Transaction -Independent
    PS HKCU:\software> Get-Transaction
    PS HKCU:\software> Undo-Transaction

    PS HKCU:\software> New-Itemproperty -path MyCompany -name MyKey -value 123 -UseTransaction
    PS HKCU:\software> Complete-Transaction
    PS HKCU:\software> dir my*

    PS HKCU:\Software> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— ——
    Error                1                 Active

    PS HKCU:\software> Undo-Transaction
    PS HKCU:\software> New-Itemproperty -path MyCompany -name MyKey -value 123 -UseTransaction

    MyKey
    —–
    123

    PS HKCU:\software> Complete-Transaction
    PS HKCU:\software> dir my*

     Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     0 1 MyCompany                     {MyKey}

    Description
    ———–
    This example shows the effect of using the Independent parameter of Start-Transaction to start a transaction while another transaction is in progress. In this case, the new transaction is rolled back without affecting the original transaction.

    Although the transactions are logically independent, because only one transaction can be active at a time, you must roll back or commit the newest transaction before resuming work on the original transaction.

    The first set of commands starts a transaction. The New-Item command is part of the first transaction.

    In the second set of commands, the Start-Transaction command uses the Independent parameter. The Get-Transaction command that follows shows the transaction object for the active transaction (the newest one). The subscriber count is equal to 1, showing that the transactions are unrelated.

    When the active transaction is rolled back by using an Undo-Transaction command, the original transaction becomes active again.

    The New-ItemProperty command, which is part of the original transaction, completes without error, and the original transaction can be completed by using the Complete-Transaction command. As a result, the Registry is changed.

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

    C:\PS>cd hkcu:\software

    PS HKCU:\software> Start-Transaction
    PS HKCU:\software> New-Item MyCompany1 -UseTransaction
    PS HKCU:\software> New-Item MyCompany2
    PS HKCU:\software> New-Item MyCompany3 -UseTransaction

    PS HKCU:\software> dir my*

    PS HKCU:\software> Complete-Transaction
    PS HKCU:\software> dir my*

    PS HKCU:\Software> dir my*

     Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     0 0 MyCompany2                     {}

    PS HKCU:\Software> Complete-Transaction

    PS HKCU:\Software> dir my*

     Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     0 0 MyCompany1                     {}
     0 0 MyCompany2                     {}
     0 0 MyCompany3                     {}

    Description
    ———–
    This example demonstrates that commands that are submitted while a transaction is in progress can be included in the transaction or not included. Only commands that use the UseTransaction parameter are part of the transaction.

    The first and third New-Item commands use the UseTransaction parameter. These commands are part of the transaction. Because the second New-Item command does not use the UseTransaction parameter, it is not part of the transaction.

    The first “dir” command shows the effect. The second New-Item command is completed immediately, but the first and third New-Item commands are not effective until the transaction is committed.

    The Complete-Transaction command commits the transaction. As a result, the second “dir” command shows that all of the new items are added to the Registry.

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

    C:\PS>Start-Transaction -Timeout 2

    # Wait two minutes…

    C:\PS> Get-Transaction

    C:\PS> New-Item HKCU:\Software\MyCompany -UseTransaction

    C:\PS> Start-Transaction -Timeout 2

    # Wait two minutes…

    C:\PS>> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— ———–
    Error                1                 RolledBack

    C:\PS> New-Item HKCU:\Software\MyCompany -UseTransaction
    New-Item : Cannot use transaction. The transaction has been rolled back or has timed out.
    At line:1 char:9
    + New-Item <<<< MyCompany -UseTransaction

    Description
    ———–
    This command uses the Timeout parameter of Start-Transaction to start a transaction that must be completed within two minutes. If the transaction is not complete when the timeout expires, it is rolled back automatically.

    When the timeout expires, you are not notified, but the Status property of the transaction object is set to RolledBack and commands that use the UseTransaction parameter fail.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135262
    about_transactions
    Get-Transaction
    Complete-Transaction
    Undo-Transaction
    Use-Transaction

cmdlet, Start, Transcript

Start-Transcript

NAME
    Start-Transcript

SYNOPSIS
    Creates a record of all or part of a Windows PowerShell session in a text file.

SYNTAX
    Start-Transcript [[-Path] <string>] [-Append] [-Force] [-NoClobber] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Start-Transcript cmdlet creates a record of all or part of a Windows PowerShell session in a text file. The transcript includes all command that the user types and all output that appears on the console.

PARAMETERS
    -Append [<SwitchParameter>]
        Adds the new transcript to the end of an existing file. Use the Path parameter to specify the file.

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

    -Force [<SwitchParameter>]
        Allows the cmdlet to append the transcript to an existing read-only file. When used on a read-only file, the cmdlet changes the file permission to read-write. Even using the Force parameter, the cmdlet cannot override security restrictions.

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

    -NoClobber [<SwitchParameter>]
        Will not overwrite (replace the contents) of an existing file. By default, if a transcript file exists in the specified path, Start-Transcript overwrites the file without warning.

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

    -Path <string>
        Specifies a location for the transcript file. Enter a path to a .txt file. Wildcards are not permitted.

        If you do not specify a path, Start-Transcript uses the path in the value of the $Transcript global Variable. If you have not created this Variable, Start-Transcript stores the transcripts in the $Home\My Documents directory as \PowerShell_transcript.<time-stamp>.txt files.

        If any of the directories in the path do not exist, the command fails.

        Required?                    false
        Position?                    1
        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

    <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 objects to this cmdlet.

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

NOTES

        To stop a transcript, use the Stop-Transcript cmdlet.

        To record an entire session, add the Start-Transcript command to your profile. For more information, see about_profiles.

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

    C:\PS>Start-Transcript

    Description
    ———–
    This command starts a transcript in the default file location.

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

    C:\PS>Start-Transcript -Path c:\transcripts\transcript0.txt -NoClobber

    Description
    ———–
    This command starts a transcript in the Transcript0.txt file in C:\transcripts. The NoClobber parameter prevents any existing files from being overwritten. If the Transcript0.txt file already exists, the command fails.

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

cmdlet, Computer, Stop

Stop-Computer

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.

        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 manage the job, use the Job cmdlets. To get the job results, use the Receive-Job cmdlet.

        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:

        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

    -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.

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

    -Impersonation <ImpersonationLevel>
        Specifies the impersonation level to use when calling WMI. (Stop-Computer 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                Impersonate
        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.

        Required?                    false
        Position?                    named
        Default value                32
        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

    <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
    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

cmdlet, Job, Stop

Stop-Job

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.

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

    -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

    <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.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, Process, Stop

Stop-Process

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.

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

    -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

    <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.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, ExecutionPolicy, Set

Set-ExecutionPolicy

NAME
    Set-ExecutionPolicy

SYNOPSIS
    Changes the user preference for the Windows PowerShell execution policy.

SYNTAX
    Set-ExecutionPolicy [-ExecutionPolicy] {Unrestricted | RemoteSigned | AllSigned | Restricted | Default | Bypass | Undefined} [[-Scope] {Process | CurrentUser | LocalMachine | UserPolicy | MachinePolicy}] [-Force] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Set-ExecutionPolicy changes the user preference for the Windows PowerShell execution policy.

    To run this command on Windows Vista, Windows Server 2008, and later versions of Windows, you must start Windows PowerShell with the “Run as administrator” option, even if you are a member of the Administrators group on the computer.

    The execution policy is part of the security strategy of Windows PowerShell. It determines whether you can load configuration files (including your Windows PowerShell profile) and run scripts, and it determines which scripts, if any, must be digitally signed before they will run.

    For more information, see about_execution_policies.

PARAMETERS
    -ExecutionPolicy <ExecutionPolicy>
        Specifies a new execution policy for the shell. The parameter name (“Name”) is optional.

        Valid values are:

        — Restricted: Does not load configuration files or run scripts. “Restricted” is the default.

        — AllSigned: Requires that all scripts and configuration files be signed by a trusted publisher, including scripts that you write on the local computer.

        — RemoteSigned: Requires that all scripts and configuration files downloaded from the Internet be signed by a trusted publisher.

        — Unrestricted: Loads all configuration files and runs all scripts. If you run an unsigned script that was downloaded from the Internet, you are prompted for permission before it runs.

        — Bypass: Nothing is blocked and there are no warnings or prompts.

        — Undefined: Removes the currently assigned execution policy from the current scope. This parameter will not remove an execution policy that is set in a Group Policy scope.

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

    -Force [<SwitchParameter>]
        Suppresses all prompts. By default, Set-ExecutionPolicy displays a warning whenever you change the execution policy.

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

    -Scope <ExecutionPolicyScope>
        Specifies the scope of the execution policy. The default is LocalMachine.

        Valid values are:

        — Process: The execution policy affects only the current Windows PowerShell process.
        — CurrentUser: The execution policy affects only the current user.
        — LocalMachine: The execution policy affects all users of the computer.

        To remove an execution policy from a particular scope, set the execution policy for that scope to Undefined.

        Required?                    false
        Position?                    2
        Default value                LocalMachine
        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

    <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
    Microsoft.PowerShell.ExecutionPolicy, System.String
        You can pipe an execution policy object or a string that contains the name of an execution policy to Set-ExecutionPolicy.

OUTPUTS
    None
        This cmdlet does not return any output.

NOTES

        When you use Set-ExecutionPolicy, the new user preference is written to the Registry and remains unchanged until you change it.

        However, if the “Turn on Script Execution” Group Policy is enabled for the computer or user, the user preference is written to the Registry, but it is not effective, and Windows PowerShell displays a message explaining the conflict. You cannot use Set-ExecutionPolicy to override a Group Policy, even if the user preference is more restrictive than the policy.

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

    C:\PS>Set-ExecutionPolicy remotesigned

    Description
    ———–
    This command sets the user preference for the shell execution policy to RemoteSigned.

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

    C:\PS>Set-ExecutionPolicy Restricted

    Set-ExecutionPolicy : Windows PowerShell updated your local preference successfully, but the setting is overridden by the group policy applied to your system. Due to the override, your shell will retain its current effective execution policy of “AllSigned”. Contact your group policy administrator for more information.
    At line:1 char:20
    + Set-ExecutionPolicy <<<< restricted

    Description
    ———–
    This command attempts to set the execution policy for the shell to “Restricted.” The “Restricted” setting is written to the Registry, but because it conflicts with a Group Policy, it is not effective, even though it is more restrictive than the policy.

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

    C:\PS>Invoke-Command -computername Server01 -scriptblock {Get-ExecutionPolicy} | Set-ExecutionPolicy -Force

    Description
    ———–
    This command gets the execution policy from a remote computer and applies that execution policy to the local computer.

    The command uses the Invoke-Command cmdlet to send the command to the remote computer. Because you can pipe an ExecutionPolicy (Microsoft.PowerShell.ExecutionPolicy) object to Set-ExecutionPolicy, the Set-ExecutionPolicy command does not need an ExecutionPolicy parameter.

    The command does have a Force parameter, which suppresses the user prompt.

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

    C:\PS>Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy AllSigned -Force

    C:\PS> Get-ExecutionPolicy -list

            Scope ExecutionPolicy
            —– —————
    MachinePolicy         Undefined
     UserPolicy         Undefined
         Process         Undefined
     CurrentUser         AllSigned
     LocalMachine     RemoteSigned

    C:\PS> Get-ExecutionPolicy
    AllSigned

    Description
    ———–
    This example shows how to set an execution policy for a particular scope.

    The first command uses the Set-ExecutionPolicy cmdlet to set an execution policy of AllSigned for the current user. It uses the Force parameter to suppress the user prompts.

    The second command uses the List parameter of Get-ExecutionPolicy to get the execution policies set in each scope. The results show that the execution policy that is set for the current user differs from the execution policy set for all users of the computer.

    The third command uses the Get-ExecutionPolicy cmdlet without parameters to get the effective execution policy for the current user on the local computer. The result confirms that the execution policy that is set for the current user takes precedence over the one set for all users.

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

    C:\PS>Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Undefined

    Description
    ———–
    This command uses an execution policy value of Undefined to effectively remove the execution policy that is set for the current user scope. As a result, the execution policy that is set in Group Policy or in the LocalMachine (all users) scope is effective.

    If you set the execution policy in all scopes to Undefined and the Group Policy is not set, the default execution policy, Restricted, is effective for all users of the computer.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113394
    Get-ExecutionPolicy
    Set-AuthenticodeSignature
    Get-AuthenticodeSignature
    about_execution_policies
    about_Signing

cmdlet, Item, Set

Set-Item

NAME
    Set-Item

SYNOPSIS
    Changes the value of an item to the value specified in the command.

SYNTAX
    Set-Item [-LiteralPath] <string[]> [[-Value] <Object>] [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

    Set-Item [-Path] <string[]> [[-Value] <Object>] [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The Set-Item cmdlet changes the value of an item, such as a Variable or Registry key, to the value specified in the command.

PARAMETERS
    -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 generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.

        This parameter is not supported by any providers installed with Windows PowerShell.

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

    -Exclude <string[]>
        Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as “*.txt”. Wildcards are permitted.

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

    -Filter <string>
        Specifies a filter in the provider’s format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.

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

    -Force [<SwitchParameter>]
        Allows the cmdlet to set items that cannot otherwise be changed, such as read-only Alias or Variables. The cmdlet cannot change constant Aliases or Variables. Implementation varies from provider to provider. For more information, see about_providers. Even using the Force parameter, the cmdlet cannot override security restrictions.

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

    -Include <string[]>
        Changes only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as “*.txt”. Wildcards are permitted.

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

    -LiteralPath <string[]>
        Specifies a path to the location of the new items. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.

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

    -PassThru [<SwitchParameter>]
        Passes an object representing the item to the pipeline. By default, this cmdlet does not generate any output.

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

    -Path <string[]>
        Specifies a path to the location of the new items. Wildcards are permitted.

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

    -Value <Object>
        Specifies a new value for the item.

        Required?                    false
        Position?                    2
        Default value
        Accept pipeline input?     true (ByValue, 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

    -UseTransaction [<SwitchParameter>]
        Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_transactions.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        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.Object
        You can pipe an object that represents the new value of the item to Set-Item.

OUTPUTS
    None or an object representing the new or changed item.
        When you use the Passthru parameter, Set-Item generates an object representing the item. Otherwise, this cmdlet does not generate any output.

NOTES

        You can also refer to Set-Item by its built-in Alias, “si”. For more information, see about_aliases.

        The Set-Item cmdlet is not supported by the Windows PowerShell FileSystem provider. To change the values of items in the file system, use Set-Content.

        In the Registry drives, HKLM: and HKCU:, Set-Item changes the data in the (Default) value of a Registry key. To create and change the names of Registry keys, use New-Item and Rename-Item. To change the names and data in Registry values, use New-ItemProperty, Set-ItemProperty, and Rename-ItemProperty.

        The Set-Item cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type “Get-PSProvider“. For more information, see about_providers.

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

    C:\PS>Set-Item -Path Alias:np -Value c:\windows\notepad.exe

    Description
    ———–
    This command creates an Alias of “np” for Notepad.

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

    C:\PS>Set-Item -Path env:UserRole -Value Administrator

    Description
    ———–
    This command uses the Set-Item cmdlet to change the value of the “UserRole” Environment Variable to “Administrator”.

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

    C:\PS>Set-Item -Path Function:prompt -Value {‘PS ‘+ $(Get-Date -format t) + ” ” + $(Get-Location) + ‘> ‘}

    Description
    ———–
    This command uses the Set-Item cmdlet to change the “prompt” Function so that it displays the time before the path.

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

    C:\PS>Set-Item -Path Function:prompt -options “AllScope,ReadOnly”

    Description
    ———–
    This command sets the AllScope and ReadOnly options for the “prompt” Function. This command uses the Options dynamic parameter of the Set-Item cmdlet. The Options parameter is available in Set-Item only when you use it with the Alias or Function provider.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113395
    about_providers
    Get-Item
    New-Item
    Remove-Item
    Clear-Item
    Invoke-Item
    Rename-Item
    Move-Item
    Copy-Item

cmdlet, ItemProperty, Set

Set-ItemProperty

NAME
    Set-ItemProperty

SYNOPSIS
    Creates or changes the value of a property of an item.

SYNTAX
    Set-ItemProperty [-LiteralPath] <string[]> -InputObject <psobject> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

    Set-ItemProperty [-Path] <string[]> -InputObject <psobject> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

    Set-ItemProperty [-LiteralPath] <string[]> [-Name] <string> [-Value] <Object> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

    Set-ItemProperty [-Path] <string[]> [-Name] <string> [-Value] <Object> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The Set-ItemProperty cmdlet changes the value of the property of the specified item. You can use the cmdlet to establish or change the properties of items. For example, you can use Set-ItemProperty to set the value of the IsReadOnly property of a file object to true.

    You also use Set-ItemProperty to create and change Registry values and data. For example, you can add a new Registry entry to a key and establish or change its value.

PARAMETERS
    -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 generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.

        This parameter is not supported by any providers installed with Windows PowerShell.

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

    -Exclude <string[]>
        Specifies those items upon which the cmdlet is not to act, and includes all others.

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

    -Filter <string>
        Specifies a filter in the provider’s format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.

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

    -Force [<SwitchParameter>]
        Allows the cmdlet to set a property on items that cannot otherwise be accessed by the user. Implementation varies from provider to provider. For more information, see about_providers.

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

    -Include <string[]>
        Specifies only those items upon which the cmdlet will act, excluding all others.

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

    -InputObject <psobject>
        Specifies the object that has the properties that you want to change. Enter a Variable that contains the object or a command that gets the object.

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

    -LiteralPath <string[]>
        Specifies a path to the item property. The value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.

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

    -Name <string>
        Specifies the name of the property.

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

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

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

    -Path <string[]>
        Specifies the path to the items with the property to be set.

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

    -Value <Object>
        Specifies the value of the property.

        Required?                    true
        Position?                    3
        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

    -UseTransaction [<SwitchParameter>]
        Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_transactions.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        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.Management.Automation.PSObject
        You can pipe objects to Set-ItemProperty.

OUTPUTS
    None or System.Management.Automation.PSCustomObject
        When you use the PassThru parameter, Set-ItemProperty generates a PSCustomObject object that represents the item that was changed and its new property value. Otherwise, this cmdlet does not generate any output.

NOTES

        The Set-ItemProperty cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type “Get-PSProvider“. For more information, see about_providers.

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

    C:\PS>Set-Itemproperty -Path c:\GroupFiles\final.doc -Name IsReadOnly -Value $true

    Description
    ———–
    This command sets the value of the IsReadOnly property of the final.doc file to true.

    The command uses the Set-ItemProperty cmdlet to change the value of the property of the final.doc file. It uses the Path parameter to specify the file. It uses the Name parameter to specify the name of the property and the Value parameter to specify the new value.

    The $true automatic Variable represents a value of TRUE. For more information, see about_Automatic_Variables.

    The file is a System.IO.FileInfo object and IsReadOnly is just one of its properties. To see all of the properties and methods of a FileInfo object, pipe the file to the Get-Member cmdlet. For example, “final.doc | Get-Member“.

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

    C:\PS>Set-Itemproperty -Path HKLM:\Software\MyCompany -Name NoOfEmployees -Value 823

    C:\PS>Get-Itemproperty -Path HKLM:\Software\MyCompany

    PSPath        : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany
    PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software
    PSChildName : mycompany
    PSDrive     : HKLM
    PSProvider    : Microsoft.PowerShell.Core\Registry
    NoOfLocations : 2
    NoOfEmployees : 823

    C:\PS>Set-Itemproperty -Path HKLM:\Software\MyCompany -Name NoOfEmployees -Value 824
    C:\PS>Get-Itemproperty -Path HKLM:\Software\MyCompany

    PSPath        : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany
    PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software
    PSChildName : mycompany
    PSDrive     : HKLM
    PSProvider    : Microsoft.PowerShell.Core\Registry
    NoOfLocations : 2
    NoOfEmployees : 824

    Description
    ———–
    This example shows how to use Set-ItemProperty to create a new Registry entry and to assign a value to the entry. It creates the NoOfEmployees entry in the MyCompany key in HKLM\Software key and sets its value to 823.

    Because Registry entries are considered to be properties of the Registry keys (which are items), you use Set-ItemProperty to create Registry entries, and to establish and change their values.

    The first command uses the Set-ItemProperty cmdlet to create the Registry entry. It uses the Path parameter to specify the path to the HKLM: drive and the Software\MyCompany key. It uses the Name parameter to specify the entry name and the Value parameter to specify a value.

    The second command uses the Get-ItemProperty cmdlet to see the new Registry entry. If you use the Get-Item or Get-ChildItem cmdlets, the entries do not appear because they are properties of a key, not items or child items.

    The third command changes the value of the NoOfEmployees entry to 824.

    You can also use the New-ItemProperty cmdlet to create the Registry entry and its value and then use Set-ItemProperty to change the value.

    For more information about the HKLM: drive, type “Get-Help Get-PSDrive“. For more information about using Windows PowerShell to manage the Registry, type “Get-Help Registry“.

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

    C:\PS>Get-ChildItem weekly.txt | Set-Itemproperty -Name IsReadOnly -Value $true

    Description
    ———–
    These commands show how to use a pipeline operator (|) to send an item to Set-ItemProperty.

    The first part of the command uses the Get-ChildItem cmdlet to get an object that represents the Weekly.txt file. The command uses a pipeline operator to send the file object to Set-ItemProperty. The Set-ItemProperty command uses the Name and Value parameters to specify the property and its new value.

    This command is equivalent to using the InputObject parameter to specify the object that Get-ChildItem gets.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113396
    about_providers
    Get-ItemProperty
    New-ItemProperty
    Clear-ItemProperty
    Remove-ItemProperty
    Rename-ItemProperty
    Move-ItemProperty
    Copy-ItemProperty

cmdlet, PSSessionConfiguration, Set

Set-PSSessionConfiguration

NAME
    Set-PSSessionConfiguration

SYNOPSIS
    Changes the properties of a registered session configuration.

SYNTAX
    Set-PSSessionConfiguration [-AssemblyName] <string> [-ConfigurationTypeName] <string> [-Name] <string> [-ApplicationBase <string>] [-Force] [-MaximumReceivedDataSizePerCommandMB <double>] [-MaximumReceivedObjectSizeMB <double>] [-NoServiceRestart] [-SecurityDescriptorSddl <string>] [-ShowSecurityDescriptorUI] [-StartupScript <string>] [-ThreadApartmentState {STA | MTA | Unknown}] [-ThreadOptions {Default | UseNewThread | ReuseThread | UseCurrentThread}] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Set-PSSessionConfiguration cmdlet changes the properties of the registered session configurations on the local computer. This is an advanced cmdlet that is designed to be used by system administrators to manage customized session configurations for their users.

    Use the Name parameter to identify the configuration that you want to change. Use the other parameters to specify new values for the properties of the session configuration. To delete a property value from the configuration (and use the default value), enter an empty string (“”) or a value of $null for the corresponding parameter.

    To see the properties of a session configuration, use the Get-PSSessionConfiguration cmdlet or the WS-Management Provider. For more information about the WS-Management Provider, type “Get-Help WSMan“.

PARAMETERS
    -ApplicationBase <string>
        Changes the path to the assembly file (*.dll) that is specified in the value of the AssemblyName parameter.

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

    -AssemblyName <string>
        Specifies a different assembly file for the configuration. Enter the path (optional) and file name of an assembly (.dll) file that defines the configuration type.

        If you enter only the name, you can enter the path in the value of the ApplicationBase parameter.

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

    -ConfigurationTypeName <string>
        Specifies a different configuration type for the configuration. The type that you specify must implement the System.Management.Automation.Remoting.PSSessionConfiguration class.

        If you enter “$null” or an empty string, the DefaultRemotePowerShellConfiguration class is used for the session configuration.

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

    -Force [<SwitchParameter>]
        Suppresses all user prompts, and restarts the WinRM service without prompting. Restarting the service makes the configuration change effective.

        To prevent a restart and suppress the restart prompt, use the NoServiceRestart parameter.

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

    -MaximumReceivedDataSizePerCommandMB <double>
        Changes the limit on the amount of data that can be sent to this computer in any single remote command. Enter the data size in megabytes (MB). The default is 50 MB.

        If a data size limit is defined in the configuration type that is specified in the ConfigurationTypeName parameter, the limit in the configuration type is used and the value of this parameter is ignored.

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

    -MaximumReceivedObjectSizeMB <double>
        Changes the limits on the amount of data that can be sent to this computer in any single object. Enter the data size in megabytes (MB). The default is 10 MB.

        If an object size limit is defined in the configuration type that is specified in the ConfigurationTypeName parameter, the limit in the configuration type is used and the value of this parameter is ignored.

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

    -Name <string>
        Specifies the name of the session configuration that you want to change.

        You cannot use this parameter to change the name of the session configuration.

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

    -NoServiceRestart [<SwitchParameter>]
        Does not restart the WinRM service, and suppresses the prompt to restart the service.

        By default, when you enter a Set-PSSessionConfiguration command, you are prompted to restart the WinRM service to make the new session configuration effective. Until the WinRM service is restarted, the new session configuration is not effective.

        To restart the WinRM service without prompting, use the Force parameter. To restart the WinRM service manually, use the Restart-Service cmdlet.

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

    -SecurityDescriptorSddl <string>
        Specifies a different Security Descriptor Definition Language (SDDL) string for the configuration.

        This string determines the permissions that are required to use the new session configuration. To use a session configuration in a session, users must have at least “Execute(Invoke)” permission for the configuration.

        To use the default security descriptor for the configuration, enter an empty string (“”) or a value of $null. The default is the root SDDL in the WSMan: drive.

        If the security descriptor is complex, consider using the ShowSecurityDescriptorUI parameter instead of this one. You cannot use both parameters in the same command.

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

    -ShowSecurityDescriptorUI [<SwitchParameter>]
        Displays a property sheet that helps you to create a new SDDL for the session configuration. The property sheet appears after you enter the Set-PSSessionConfiguration command and then restart the WinRM service.

        When setting the permissions to the configuration, remember that users must have at least “Execute(Invoke)” permission to use the session configuration in a session.

        You cannot use the SecurityDescriptorSDDL parameter and this parameter in the same command.

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

    -StartupScript <string>
        Adds or changes the startup script for the configuration. Enter the fully qualified path to a Windows PowerShell script. The specified script runs in the new session that uses the session configuration.

        To delete a startup script from a session configuration, enter an empty string (“”) or a value of $null.

        You can use a startup script to further configure the user’s session. If the script generates an error (even a non-terminating error), the session is not created and the user’s New-PSSession command fails.

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

    -ThreadApartmentState <ApartmentState>
        Changes the apartment state setting for the threads in the session. Valid values are STA, MTA and Unknown. Unknown is the default.

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

    -ThreadOptions <PSThreadOptions>
        Changes the thread options setting in the configuration. This setting defines how threads are created and used when a command is executed in the session. Valid values are Default, ReuseThread, UseCurrentThread, and UseNewThread. UseCurrentThread is the default.

        Required?                    false
        Position?                    named
        Default value                PSThreadOptions.UserCurrentThread
        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

    <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
    Microsoft.WSMan.Management.WSManConfigLeafElement

NOTES

        To run this cmdlet on Windows Vista, Windows Server 2008, and later versions of Windows, you must open Windows PowerShell with the “Run as administrator” option.

        The Set-PSSessionConfiguration cmdlet does not change the configuration name and the WS-Management provider does not support the Rename-Item cmdlet. To change the name of a configuration, use the Unregister-PSSessionConfiguration cmdlet to delete the configuration and then use the Register-PSSessionConfiguration cmdlet to create and register a new session configuration.

        You can use the Set-PSSessionConfiguration cmdlet to change the default Microsoft.PowerShell and Microsoft.PowerShell32 session configurations. They are not protected. To revert to the original version of a default session configuration, use the Unregister-PSSessionConfiguration cmdlet to delete the default session configuration and then use the Enable-PSRemoting cmdlet to restore it.

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

    C:\PS>Set-PSSessionConfiguration -Name MaintenanceShell -ThreadApartmentState STA

    Description
    ———–
    This command changes the thread apartment state in the MaintenanceShell configuration to STA. The change is effective when you restart the WinRM service.

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

    C:\PS>Register-PSSessionConfiguration -Name AdminShell -assemblyName c:\shells\AdminShell.dll -configurationType AdminClass

    C:\PS> Set-PSSessionConfiguration -Name AdminShell -StartupScript AdminConfig.ps1

    C:\PS> Set-PSSessionConfiguration -Name AdminShell -StartupScript $null

    Description
    ———–
    This example shows how to create and then change a session configuration.

    The first command uses the Register-PSSessionConfiguration cmdlet to create the AdminShell configuration.

    The second command uses the Set-PSSessionConfiguration cmdlet to add the AdminConfig.ps1 script to the configuration. The change is effective when you restart WinRM.

    The third command removes the AdminConfig.ps1 script from the configuration. It uses the Set-PSSessionConfiguration cmdlet with a value of $null for the StartupScript parameter.

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

    C:\PS>Set-PSSessionConfiguration -Name foo -MaximumReceivedObjectSizeMB 20

     WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\foo\InitializationParameters

    ParamName                     ParamValue
    ———                     ———-
    psmaximumreceivedobjectsizemb 20

    “Restart WinRM service”
    WinRM service need to be restarted to make the changes effective. Do you want to run the command “Restart-Service winrm”?
    [Y] Yes [N] No [S] Suspend [?] Help (default is “Y”): y

    Description
    ———–
    This example show sample output from the Set-PSSessionConfiguration cmdlet.

    The Set-PSSessionConfiguration command in this example increases the value of the MaximumReceivedObjectSizeMB property to 20.

    The Set-PSSessionConfiguration command returns a Microsoft.WSMan.Management.WSManConfigLeafElement object that shows the parameter name and new value.

    It also prompts you to restart the WinRM service. The Set-PSSessionConfiguration change is not effective until the WinRM service is restarted.

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

    C:\PS>Set-PSSessionConfiguration -Name MaintenanceShell -StartupScript c:\ps-test\Maintenance.ps1

     WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell\InitializationParameters

    ParamName            ParamValue
    ———            ———-
    startupscript        c:\ps-test\Mainte…

    “Restart WinRM service”
    WinRM service need to be restarted to make the changes effective. Do you want to run the command “Restart-Service winrm”?
    [Y] Yes [N] No [S] Suspend [?] Help (default is “Y”): y

    C:\PS> Get-PSSessionConfiguration maintenanceshell | Format-List -property *

    xmlns            : http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration
    Name             : MaintenanceShell
    Filename         : %windir%\system32\pwrshplugin.dll
    SDKVersion     : 1
    XmlRenderingType : text
    lang             : en-US
    PSVersion        : 2.0
    startupscript    : c:\ps-test\Maintenance.ps1
    ResourceUri     : http://schemas.microsoft.com/powershell/MaintenanceShell
    SupportsOptions : true
    ExactMatch     : true
    Capability     : {Shell}
    Permission     :

    C:\PS> dir WSMan:\localhost\plugin\MaintenanceShell\InitializationParameters

    ParamName     ParamValue
    ———     ———-
    PSVersion     2.0
    startupscript c:\ps-test\Maintenance.ps1

    Description
    ———–
    This command shows different ways of viewing the results of a Set-PSSessionConfiguration command.

    The first command uses the Set-PSSessionConfiguration cmdlet to change the startup script in the MaintenanceShell configuration to Maintenance.ps1. The output of this command shows the change and prompts you to restart the WinRM service. The response is “y” (yes).

    The second command uses the Get-PSSessionConfiguration cmdlet to get the MaintenanceShell session configuration. The command uses a pipeline operator (|) to send the results of the command to the Format-List cmdlet, which displays all of the properties of the session configuration object in a list.

    The third command uses the WS-Management provider to view the initialization parameters for the MaintenanceShell configuration. The command uses the Get-ChildItem cmdlet (alias = dir) to get the child items in the InitializationParameters node for the MaintenanceShell plug-in.

    For more information about the WS-Management provider, type “Get-Help WSMan“.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=144307
    about_Session_Configurations
    Disable-PSSessionConfiguration
    Enable-PSSessionConfiguration
    Get-PSSessionConfiguration
    Register-PSSessionConfiguration
    Unregister-PSSessionConfiguration
    WS-Management Provider