Category Archives: Set

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, Location, Set

Set-Location

NAME
    Set-Location

SYNOPSIS
    Sets the current working location to a specified location.

SYNTAX
    Set-Location [-LiteralPath] <string> [-PassThru] [-UseTransaction] [<CommonParameters>]

    Set-Location [[-Path] <string>] [-PassThru] [-UseTransaction] [<CommonParameters>]

    Set-Location [-StackName <string>] [-PassThru] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The Set-Location cmdlet sets the working location to a specified location. That location could be a directory, a sub-directory, a Registry location, or another location stack.

PARAMETERS
    -LiteralPath <string>
        Specifies a path to the location. The value of the LiteralPath parameter 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 location 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>
        This parameter is used to specify the path to a new working location.

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

    -StackName <string>
        The name of the stack to which the location is being set.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByPropertyName)
        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.String
        You can pipe a string that contains a path (but not a literal path) to Set-Location.

OUTPUTS
    None or System.Management.Automation.PathInfo
        When you use the PassThru parameter, Set-Location generates a System.Management.Automation.PathInfo object that represents the location. Otherwise, this cmdlet does not generate any output.

NOTES

        The Set-Location 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-Location HKLM:

    Description
    ———–
    This will set the current location to the one specified; in this case, it is the HKLM provider.

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

    C:\PS>Set-Location env: -PassThru

    Path
    —-
    Env:\

    Description
    ———–
    This will set the current location to the one specified; in this case, it is the Environment Variable provider.

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

    C:\PS>Set-Location C:

    Description
    ———–
    This will set the current location to the one specified; in this case, it is the C: drive in the file system provider.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113397
    about_providers
    Get-Location
    Pop-Location
    Push-Location

cmdlet, PSBreakpoint, Set

Set-PSBreakpoint

NAME
    Set-PSBreakpoint

SYNOPSIS
    Sets a breakpoint on a line, command, or Variable.

SYNTAX
    Set-PSBreakpoint -Command <string[]> [[-Script] <string[]>] [-Action <scriptblock>] [<CommonParameters>]

    Set-PSBreakpoint [-Script] <string[]> [-Line] <Int32[]> [[-Column] <int>] [-Action <scriptblock>] [<CommonParameters>]

    Set-PSBreakpoint -Variable <string[]> [[-Script] <string[]>] [-Mode {Read | Write | ReadWrite}] [-Action <scriptblock>] [<CommonParameters>]

DESCRIPTION
    The Set-PSBreakpoint cmdlet sets a breakpoint in a script or in any command run in the current session. You can use Set-PSBreakpoint to set a breakpoint before executing a script or running a command, or during debugging, when stopped at another breakpoint.

    Note: Set-PSBreakpoint cannot set a breakpoint on a remote computer. To debug a script on a remote computer, copy the script to the local computer and then debug it locally.

    Each Set-PSBreakpoint command creates one of the following three types of breakpoints:
     — Line breakpoint: Sets breakpoints at particular line and column coordinates.
     — Command breakpoint: Sets breakpoints on commands and Functions.
     — Variable breakpoint: Sets breakpoints on Variables.

    You can set a breakpoint on multiple lines, commands, or Variables in a single Set-PSBreakpoint command, but each Set-PSBreakpoint command sets only one type of breakpoint.

    At a breakpoint, Windows PowerShell temporarily stops executing and gives control to the debugger. The command prompt changes to “DBG>”, and a set of debugger commands become available for use. However, you can use the Action parameter to specify an alternate response, such as conditions for the breakpoint or instructions to perform additional tasks such as logging or diagnostics.

    The Set-PSBreakpoint cmdlet is one of several cmdlets designed for debugging Windows PowerShell scripts. For more information about the Windows PowerShell debugger, see about_debuggers.

PARAMETERS
    -Action <scriptblock>
        Specifies commands that run at each breakpoint instead of breaking. Enter a script block that contains the commands. You can use this parameter to set conditional breakpoints or to perform other tasks, such as testing or logging.

        If this parameter is omitted, or no action is specified, execution stops at the breakpoint, and the debugger starts.

        When the Action parameter is used, the Action script block runs at each breakpoint. Execution does not stop unless the script block includes the Break keyword. If you use the Continue keyword in the script block, execution resumes until the next breakpoint.

        For more information, see about_script_blocks, about_Break, and about_Continue.

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

    -Column <int>
        Specifies the column number of the column in the script file on which execution stops. Enter only one column number. The default is column 1.

        The Column value is used with the value of the Line parameter to specify the breakpoint. If the Line parameter specifies multiple lines, the Column parameter sets a breakpoint at the specified column on each of the specified lines. Windows PowerShell stops executing before the statement or expression that includes the character at the specified line and column position.

        Columns are counted from the top left margin beginning with column number 1 (not 0). If you specify a column that does not exist in the script, an error is not declared, but the breakpoint is never executed.

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

    -Command <string[]>
        Sets a command breakpoint. Enter command names, such as “Get-Process” or Function names. Wildcards are permitted.

        Execution stops just before each instance of each command is executed. If the command is a Function, execution stops each time the Function is called and at each BEGIN, PROCESS, and END section.

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

    -Line <Int32[]>
        Sets a line breakpoint in a script. Enter one or more line numbers, separated by commas. Windows PowerShell stops immediately before executing the statement that begins on each of the specified lines.

        Lines are counted from the top left margin of the script file beginning with line number 1 (not 0). If you specify a blank line, execution stops before the next non-blank line. If the line is out of range, the breakpoint is never hit.

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

    -Mode <VariableAccessMode>
        Determines the mode of access that triggers Variable breakpoints. The default is Write.

        This parameter is valid only when the Variable parameter is used in the command. The mode applies to all breakpoints set in the command.

        Valid values are:

        — Write: Stops execution immediately before a new value is written to the Variable.

        — Read: Stops execution when the Variable is read, that is, when its value is accessed, either to be assigned, displayed, or used. In read mode, execution does not stop when the value of the Variable changes.

        — ReadWrite: Stops execution when the Variable is read or written.

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

    -Script <string[]>
        Sets a breakpoint in each of the specified script files. Enter the paths and file names of one or more script files. If the files are in the current directory, you can omit the path. Wildcards are permitted.

        By default, Variable breakpoints and command breakpoints are set on any command that runs in the current session. This parameter is required only when setting a line breakpoint.

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

    -Variable <string[]>
        Sets a Variable breakpoint. Enter a comma-separated list of Variables without dollar signs ($).

        Use the Mode parameters to determine the mode of access that triggers the breakpoints. The default mode, Write, stops execution just before a new value is written to the Variable.

        Required?                    true
        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 Set-PSBreakpoint.

OUTPUTS
    Breakpoint object (System.Management.Automation.LineBreakpoint, System.Management.Automation.VariableBreakpoint, System.Management.Automation.CommandBreakpoint)
        Set-PSBreakpoint returns an object that represents each breakpoint that it sets.

NOTES

        Set-PSBreakpoint cannot set a breakpoint on a remote computer. To debug a script on a remote computer, copy the script to the local computer and then debug it locally.

        When you set a breakpoint on more than one line, command, or Variable, Set-PSBreakpoint generates a breakpoint object for each entry.

        When setting a breakpoint on a Function or Variable at the command prompt, you can set the breakpoint before or after you create the Function or Variable.

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

    C:\PS>Set-PSBreakpoint -Script sample.ps1 -Line 5

    Column     : 0
    Line     : 5
    Action     :
    Enabled    : True
    HitCount : 0
    Id         : 0
    Script     : C:\ps-test\sample.ps1
    ScriptName : C:\ps-test\sample.ps1

    Description
    ———–
    This command sets a breakpoint at line 5 in the Sample.ps1 script. As a result, when the script runs, execution stops immediately before line 5 would execute.

    When you set a new breakpoint by line number, the Set-PSBreakpoint cmdlet generates a line breakpoint object (System.Management.Automation.LineBreakpoint) that includes the breakpoint ID and hit count, as shown in the following sample output.

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

    C:\PS>Set-PSBreakpoint -command Increment -Script sample.ps1

    Command    : Increment
    Action     :
    Enabled    : True
    HitCount : 0
    Id         : 1
    Script     : C:\ps-test\sample.ps1
    ScriptName : C:\ps-test\sample.ps1

    Description
    ———–
    This command creates a command breakpoint on the Increment Function in the Sample.ps1 cmdlet. The script stops executing immediately before each call to the specified Function.

    The result is a command breakpoint object. Before the script runs, the value of the HitCount property is 0.

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

    C:\PS>Set-PSBreakpoint -Script sample.ps1 -variable Server -Mode ReadWrite

    Description
    ———–
    This command sets a breakpoint on the Server Variable in the Sample.ps1 script. It uses the Mode parameter with a value of ReadWrite to stop execution when the value of the Variable is read and just before the value changes.

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

    C:\PS>Set-PSBreakpoint -Script Sample.ps1 -command “write*”

    Description
    ———–
    This command sets a breakpoint on every command in the Sample.ps1 script that begins with “write”, such as “Write-Host“.

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

    C:\PS>Set-PSBreakpoint -Script test.ps1 -command DiskTest `
     -Action { (if $disk -gt 2) { break } }

    Description
    ———–
    This command stops execution at the DiskTest Function in the Test.ps1 script only when the value of the $disk Variable is greater than 2.

    It uses the Set-PSBreakpoint cmdlet to set a command breakpoint on the DiskTest Function. The value of the action is a script block that tests the value of the $disk Variable in the Function.

    The action uses the BREAK keyword to stop execution if the condition is met. The alternative (and the default) is CONTINUE.

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

    C:\PS>Set-PSBreakpoint -command Checkpoint-Computer

    Id     : 0
    Command : Checkpoint-Computer
    Enabled : True
    HitCount : 0
    Action :

    C:\PS> Function CheckLog {
    >> Get-Eventlog -log Application |
    >> where {($_.source -like “TestApp”) -and ($_.Message -like “*failed*”)}
    >>}
    >>
    C:\PS> Checklog
    DEBUG: Hit breakpoint(s)
    DEBUG: Function breakpoint on ‘prompt:Checklog’
    C:\PS>>>

    Description
    ———–
    This command sets a breakpoint on the CheckLog Function. Because the command does not specify a script, the breakpoint is set on anything that runs in the current session. The debugger breaks when the Function is called, not when it is declared.

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

    C:\PS>Set-PSBreakpoint -Script sample.ps1 -Line 1, 14, 19 -Column 2 -Action {&(log.ps1)}

    Column     : 2
    Line     : 1
    Action     :
    Enabled    : True
    HitCount : 0
    Id         : 6
    Script     : C:\ps-test\sample.ps1
    ScriptName : C:\ps-test\sample.ps1

    Column     : 2
    Line     : 14
    Action     :
    Enabled    : True
    HitCount : 0
    Id         : 7
    Script     : C:\ps-test\sample.ps1
    ScriptName : C:\ps-test\sample.ps1

    Column     : 2
    Line     : 19
    Action     :
    Enabled    : True
    HitCount : 0
    Id         : 8
    Script     : C:\ps-test\sample.ps1
    ScriptName : C:\ps-test\sample.ps1

    Description
    ———–
    This command sets three line breakpoints in the Sample.ps1 script. It sets one breakpoint at column 2 on each of the lines specified in the script. The action specified in the Action parameter applies to all breakpoints.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113449
    about_debuggers
    Get-PSBreakpoint
    Enable-PSBreakpoint
    Disable-PSBreakpoint
    Remove-PSBreakpoint
    Get-PSCallStack

cmdlet, PSDebug, Set

Set-PSDebug

NAME
    Set-PSDebug

SYNOPSIS
    Turns script debugging features on and off, sets the trace level, and toggles strict mode.

SYNTAX
    Set-PSDebug [-Off] [<CommonParameters>]

    Set-PSDebug [-Step] [-Strict] [-Trace <int>] [<CommonParameters>]

DESCRIPTION
    The Set-PSDebug cmdlet turns script debugging features on and off, sets the trace level, and toggles strict mode.

    When the Trace parameter is set to 1, each line of script is traced as it is executed. When the parameter is set to 2, Variable assignments, Function calls, and script calls are also traced. If the Step parameter is specified, you are prompted before each line of the script is executed.

PARAMETERS
    -Off [<SwitchParameter>]
        Turns off all script debugging features.

        Note: A “Set-StrictMode -off” command disables the verification set by a “Set-PSDebug -Strict” command. For more information, see Set-StrictMode.

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

    -Step [<SwitchParameter>]
        Turns on script stepping. Before each line is run, the user is prompted to stop, continue, or enter a new interpreter level to inspect the state of the script.

        Note: Specifying the Step parameter automatically sets a Trace level of 1.

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

    -Strict [<SwitchParameter>]
        Specifies that the interpreter should throw an exception if a Variable is referenced before a value is assigned to the Variable.

        Note: A “Set-StrictMode -off” command disables the verification set by a “Set-PSDebug -Strict” command. For more information, see Set-StrictMode.

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

    -Trace <int>
        Specifies the trace level:
         0 – Turn script tracing off
         1 – Trace script lines as they are executed
         2 – Trace script lines, Variable assignments, Function calls, and scripts.

        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 return any output.

NOTES

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

    C:\PS>Set-PSDebug -Trace 2; foreach ($i in 1..3) {$i}

    DEBUG:    1+ Set-PSDebug -Trace 2; foreach ($i in 1..3) {$i}
    DEBUG:    1+ Set-PSDebug -Trace 2; foreach ($i in 1..3) {$i}
    1
    DEBUG:    1+ Set-PSDebug -Trace 2; foreach ($i in 1..3) {$i}
    2
    DEBUG:    1+ Set-PSDebug -Trace 2; foreach ($i in 1..3) {$i}
    3

    Description
    ———–
    This command sets the trace level to 2, and then runs a script that displays the numbers 1, 2, and 3.

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

    C:\PS>Set-PSDebug -Step; foreach ($i in 1..3) {$i}

    DEBUG:    1+ Set-PSDebug -Step; foreach ($i in 1..3) {$i}
    Continue with this operation?
     1+ Set-PSDebug -Step; foreach ($i in 1..3) {$i}
    [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help
    (default is “Y”):a
    DEBUG:    1+ Set-PSDebug -Step; foreach ($i in 1..3) {$i}
    1
    2
    3

    Description
    ———–
    This command turns on stepping and then
    runs a script that displays the numbers 1, 2, and 3.

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

    C:\PS>Set-PSDebug -off; foreach ($i in 1..3) {$i}

    1
    2
    3

    Description
    ———–
    This command turns off all debugging features, and then runs a script that displays the numbers 1, 2, and 3.

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

    C:\PS>Set-PSDebug -Strict; $NewVar

    The Variable $NewVar cannot be retrieved because it has not been set yet.
    At line:1 char:28
    + Set-PSDebug -Strict;$NewVar <<<<

    Description
    ———–
    This command puts the interpreter in strict mode, and attempts to access a Variable that has not yet been set.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113398
    about_debuggers
    Debug-Process
    Set-PSBreakpoint
    Set-StrictMode
    Write-Debug

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

cmdlet, Service, Set

Set-Service

NAME
    Set-Service

SYNOPSIS
    Starts, stops, and suspends a service, and changes its properties.

SYNTAX
    Set-Service [-Name] <string> [-Description <string>] [-DisplayName <string>] [-PassThru] [-StartupType {Automatic | Manual | Disabled}] [-Status <string>] [-ComputerName <string[]>] [-Confirm] [-WhatIf] [<CommonParameters>]

    Set-Service [-Description <string>] [-DisplayName <string>] [-InputObject <ServiceController>] [-PassThru] [-StartupType {Automatic | Manual | Disabled}] [-Status <string>] [-ComputerName <string[]>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Set-Service cmdlet changes the properties of a local or remote service, including the status, description, display name, and start mode. You can use this cmdlet to start, stop, or suspend (pause) a service. To identify the service, enter its service name or submit a service object, or pipe a service name or service object to Set-Service.

PARAMETERS
    -ComputerName <string[]>
        Specifies one or more computers. The default is the local computer.

        Type the NetBIOS name, an IP address, or a fully qualified domain name of a remote computer. To specify the local computer, type the computer name, a dot (.), or “localhost”.

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

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

    -Description <string>
        Specifies a new description for the service.

        The service description appears in Services in Computer Management. Description is not a property of the ServiceController object that Get-Service gets. To see the service description, use Get-WmiObject to get a Win32_Service object that represents the service.

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

    -DisplayName <string>
        Specifies a new display name for the service.

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

    -InputObject <ServiceController>
        Specifies a ServiceController object that represents the service to be changed. Enter a Variable that contains the object, or type a command or expression that gets the object, such as a Get-Service command. You can also pipe a service object to Set-Service.

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

    -Name <string>
        Specifies the service name of the service to be changed. Wildcards are not permitted. You can also pipe a service name to Set-Service.

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

    -PassThru [<SwitchParameter>]
        Returns objects that represent the services that were changed. By default, this cmdlet does not generate any output.

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

    -StartupType <ServiceStartMode>
        Changes the start mode of the service. Valid values for StartupType are:

        — Automatic: Start when the system starts.
        — Manual: Starts only when started by a user or program.
        — Disabled: Cannot be started.

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

    -Status <string>
        Starts, stops, or suspends (pauses) the services. Valid values are:

        — Running: Starts the service.
        — Stopped: Stops the service.
        — Paused: Suspends the service.

        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 a service object or a string that contains a service name to Set-Service.

OUTPUTS
    None
        This cmdlet does not return any objects.

NOTES

        To use Set-Service on Windows Vista and later versions of Windows, start Windows PowerShell with the “Run as administrator” option.

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

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

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

    C:\PS>Set-Service -Name lanmanworkstation -DisplayName “LanMan Workstation”

    Description
    ———–
    This command changes the display name of the lanmanworkstation service to “LanMan Workstation”. (The default is “Workstation”.)

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

    C:\PS>Get-WmiObject win32_service -filter “name = ‘SysmonLog'”

    ExitCode : 0
    Name     : SysmonLog
    ProcessId : 0
    StartMode : Manual
    State     : Stopped
    Status    : OK

    C:\PS> Set-Service sysmonlog -StartupType automatic

    C:\PS> Get-WmiObject win32_service -filter “name = ‘SysmonLog'”

    ExitCode : 0
    Name     : SysmonLog
    ProcessId : 0
    StartMode : Auto
    State     : Stopped
    Status    : OK

    C:\PS> Get-WmiObject win32_service | Format-Table Name, StartMode -auto

    Name                                 StartMode
    —-                                 ———
    AdtAgent                             Auto
    Alerter                             Disabled
    ALG                                 Manual
    AppMgmt                             Manual
    …

    Description
    ———–
    These commands get the startup type of the Performance Logs and Alerts (SysmonLog) service, set the start mode to automatic, and then display the result of the change.

    These commands use the Get-WmiObject cmdlet to get the Win32_Service object for the service, because the ServiceController object that Get-Service returns does not include the start mode.

    The first command uses the Get-WmiObject cmdlet to get the Windows Management Instrumentation (WMI) object that represents the SysmonLog service. The default output of this command displays the start mode of the service.

    The second command uses Set-Service to change the start mode to automatic. Then, the first command is repeated to display the change.

    The final command displays the start mode of all services on the computer.

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

    C:\PS>Set-Service -Name Schedule -ComputerName S1 -Description “Configures and schedules tasks.”

    C:\PS> Get-WmiObject win32_service -ComputerName s1 | Where-Object {$_.Name -eq “Schedule”} | Format-List Name, Description

    Description
    ———–
    These commands change the description of the Task Scheduler service on the S1 remote computer and then display the result.

    These commands use the Get-WmiObject cmdlet to get the Win32_Service object for the service, because the ServiceController object that Get-Service returns does not include the service description.

    The first command uses a Set-Service command to change the description. It identifies the service by using the service name of the service, “Schedule”.

    The second command uses the Get-WmiObject cmdlet to get an instance of the WMI Win32_Service that represents the Task Scheduler service. The first element in the command gets all instances of the Win32_service class.

    The pipeline operator (|) passes the result to the Where-Object cmdlet, which selects instances with a value of “Schedule” in the Name property.

    Another pipeline operator sends the result to the Format-List cmdlet, which formats the output as a list with only the Name and Description properties.

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

    C:\PS>Set-Service winrm -Status Running -PassThru -ComputerName Server02

    Description
    ———–
    This command starts the WinRM service on the Server02 computer. The command uses the Status parameter to specify the desired status (“running”) and the PassThru parameter to direct Set-Service to return an object that represents the WinRM service.

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

    C:\PS>Get-Service schedule -ComputerName S1, S2 | Set-Service -Status paused

    Description
    ———–
    This command suspends the Schedule service on the S1 and S2 remote computers. It uses the Get-Service cmdlet to get the service. A pipeline operator (|) sends the service to the Set-Service cmdlet, which changes its status to “Paused”.

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

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

    C:\PS> Set-Service -inputobject $s -Status stopped

    Description
    ———–
    These commands stop the Schedule service on the local computer.

    The first command uses the Get-Service cmdlet to get the Schedule service. The command saves the service in the $s Variable.

    The second command uses the Set-Service cmdlet to change the status of the Schedule service to “Stopped”. It uses the InputObject parameter to submit the service stored in the $s Variable, and it uses the Status parameter to specify the desired status.

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

cmdlet, Set, StrictMode

Set-StrictMode

NAME
    Set-StrictMode

SYNOPSIS
    Establishes and enforces coding rules in expressions, scripts, and script blocks.

SYNTAX
    Set-StrictMode -Off [<CommonParameters>]

    Set-StrictMode -Version <Version> [<CommonParameters>]

DESCRIPTION
    The Set-StrictMode cmdlet configures strict mode for the current scope (and all child scopes) and turns it on and off. When strict mode is on, Windows PowerShell generates a terminating error when the content of an expression, script, or script block violates basic best-practice coding rules.

    Use the Version parameter to determine which coding rules are enforced.

    Unlike the Set-PSDebug cmdlet, Set-StrictMode affects only the current scope and its child scopes, so you can use it in a script or Function without affecting the global scope.

    When Set-StrictMode is off, uninitialized Variables (Version 1) are assumed to have a value of 0 (zero) or $null, depending on type. References to non-existent properties return $null, and the results of Function syntax that is not valid vary with the error. Unnamed Variables are not permitted.

PARAMETERS
    -Off [<SwitchParameter>]
        Turns strict mode off. This parameter also turns off “Set-PSDebug -Strict”.

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

    -Version <Version>
        Specifies the conditions that cause an error in strict mode. This parameter is required.

        The valid values are “1.0”, “2.0”, and “Latest”. The following list shows the effect of each value.

        1.0
        — Prohibits references to uninitialized Variables, except for uninitialized Variables in strings.

        2.0
        — Prohibits references to uninitialized Variables (including uninitialized Variables in strings).
        — Prohibits references to non-existent properties of an object.
        — Prohibits Function calls that use the syntax for calling methods.
        — Prohibits a Variable without a name (${}).

        Latest:
        –Selects the latest (most strict) version available. Use this value to assure that scripts use the strictest available version, even when new versions are added to Windows PowerShell.

        Required?                    true
        Position?                    named
        Default value                None
        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 return any output.

NOTES

        Set-StrictMode is similar to the Strict parameter of Set-PSDebug. “Set-StrictMode -Version 1″ is equivalent to “Set-PSDebug -strict”, except that Set-PSDebug is effective in all scopes. Set-StrictMode is effective only in the scope in which it is set and in its child scopes. For more information about scopes in Windows PowerShell, see about_scopes.

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

    C:\PS>Set-StrictMode -Version 1.0

    C:\PS> $a -gt 5
    False
    The Variable $a cannot be retrieved because it has not been set yet.
    At line:1 char:3
    + $a <<<< -gt 5
        + CategoryInfo         : InvalidOperation: (a:Token) [], RuntimeException
        + FullyQualifiedErrorId : VariableIsUndefined

    Description
    ———–
    This command turns strict mode on and sets it to version 1.0. As a result, attempts to reference Variables that are not initialized will fail.

    The sample output shows the effect of version 1.0 strict mode.

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

    C:\PS># Set-StrictMode -Version 2.0

    # Strict mode is off by default.

    C:\PS> Function add ($a, $b) {$a + $b}
    C:\PS> add 3 4
    7
    C:\PS> add(3,4)
    3
    4

    C:\PS> Set-StrictMode -Version 2.0

    C:\PS> add(3,4)

    The Function or command was called like a method. Parameters should be separated by spaces, as described in ‘Get-Help about_Parameter.’
    At line:1 char:4
    + add <<<< (3,4)
        + CategoryInfo         : InvalidOperation: (:) [], RuntimeException
        + FullyQualifiedErrorId : StrictModeFunctionCallWithParens

    C:\PS> Set-StrictMode -off

    C:\PS> $string = “This is a string”.
    C:\PS> $string.Month
    C:\PS>

    C:\PS> Set-StrictMode -Version 2.0

    C:\PS> $string = “This is a string”.
    C:\PS> $string.Month
    Property ‘month’ cannot be found on this object; make sure it exists.
    At line:1 char:9
    + $string. <<<< month
        + CategoryInfo         : InvalidOperation: (.:OperatorToken) [], RuntimeException
        + FullyQualifiedErrorId : PropertyNotFoundStrict

    Description
    ———–
    This command turns strict mode on and sets it to version 2.0. As a result, Windows PowerShell throws an error if you use method syntax (parentheses and commas) for a Function call or reference uninitialized Variables or non-existent properties.

    The sample output shows the effect of version 2.0 strict mode.

    Without version 2.0 strict mode, the “(3,4)” value is interpreted as a single array object to which nothing is added. With version 2.0 strict mode, it is correctly interpreted as faulty syntax for submitting two values.

    Without version 2.0, the reference to the non-existent Month property of a string returns only null. With version 2.0, it is interpreted correctly as a reference error.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113450
    about_debuggers
    about_scopes
    Set-PSDebug

cmdlet, Set, TraceSource

Set-TraceSource

NAME
    Set-TraceSource

SYNOPSIS
    Configures, starts, and stops a trace of Windows PowerShell components.

SYNTAX
    Set-TraceSource [[-Option] {None | Constructor | Dispose | Finalizer | Method | Property | Delegates | Events | Exception | Lock | Error | Errors | Warning | Verbose | WriteLine | Data | Scope | ExecutionFlow | Assert | All}] [-Debugger] [-FilePath <string>] [-Force] [-ListenerOption {None | LogicalOperationStack | DateTime | Timestamp | ProcessId | ThreadId | Callstack}] [-PassThru] [-PSHost] [-Name] <string[]> [<CommonParameters>]

    Set-TraceSource [-RemoveListener <string[]>] [-Name] <string[]> [<CommonParameters>]

    Set-TraceSource [-RemoveFileListener <string[]>] [-Name] <string[]> [<CommonParameters>]

DESCRIPTION
    The Set-TraceSource cmdlet configures, starts, and stops a trace of a Windows PowerShell component. You can use it to specify which components will be traced and where the tracing output is sent.

PARAMETERS
    -Debugger [<SwitchParameter>]
        Sends the trace output to the debugger. You can view the output in any user-mode or kernel mode debugger or in Microsoft Visual Studio. This parameter also selects the default trace listener.

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

    -FilePath <string>
        Sends the trace output to the specified file. This parameter also selects the file trace listener. If you use this parameter to start the trace, use the RemoveFileListener parameter to stop the trace.

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

    -Force [<SwitchParameter>]
        Allows the cmdlet to overwrite a read-only file. Use with the FilePath parameter.

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

    -ListenerOption <TraceOptions>
        Adds optional data to the prefix of each trace message in the output. The valid values are “None”, “LogicalOperationStack”, “DateTime”, “Timestamp”, “ProcessId”, “ThreadId”, and “Callstack”. “None” is the default.

        To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as “ProcessID,ThreadID”.

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

    -Name <string[]>
        Determines which components are traced. Enter the name of the trace source of each component. Wildcards are permitted.

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

    -Option <PSTraceSourceOptions>
        Determines the type of events that are traced.

        The valid values are: “None”, “Constructor”, “Dispose”, “Finalizer”, “Method”, “Property”, “Delegates”, “Events”, “Exception”, “Lock”, “Error”, “Errors”, “Warning”, “Verbose”, “WriteLine”, “Data”, “Scope”, “ExecutionFlow”, “Assert”, and “All”. “All” is the default.

        The following values are combinations of other values:

        — ExecutionFlow: (Constructor, Dispose, Finalizer, Method, Delegates, Events, and Scope)

        — Data: (Constructor, Dispose, Finalizer, Property, Verbose, and WriteLine)

        — Errors: (Error and Exception).

        To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as “Constructor,Dispose”.

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

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

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

    -PSHost [<SwitchParameter>]
        Sends the trace output to the Windows PowerShell host. This parameter also selects the PSHost trace listener.

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

    -RemoveFileListener <string[]>
        Stops the trace by removing the file trace listener associated with the specified file. Enter the path and file name of the trace output file.

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

    -RemoveListener <string[]>
        Stops the trace by removing the trace listener.

        Use the following values with RemoveListener:

        –To remove PSHost (console), type “Host”.
        –To remove Debugger, type “Debug”.
        –To remove all trace listeners, type “*”.

        To remove the file trace listener, use the RemoveFileListener parameter.

        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.String
        You can pipe a string that contains a name to Set-TraceSource.

OUTPUTS
    None or System.Management.Automation.PSTraceSource
        When you use the PassThru parameter, Set-TraceSource generates a System.Management.Automation.PSTraceSource object representing the trace session. Otherwise, this cmdlet does not generate any output.

NOTES

        Tracing is a method that developers use to debug and refine programs. When tracing, the program generates detailed messages about each step in its internal processing.

        The Windows PowerShell tracing cmdlets are designed to help Windows PowerShell developers, but they are available to all users. They let you monitor nearly every aspect of the Functionality of Windows PowerShell.

        A “trace source” is the part of each Windows PowerShell component that manages tracing and generates trace messages for the component. To trace a component, you identify its trace source.

        A “trace listener” receives the output of the trace and displays it to the user. You can elect to send the trace data to a user-mode or kernel-mode debugger, to the console, to a file, or to a custom listener derived from the System.Diagnostics.TraceListener class.

        To start a trace, use the Name parameter to specify a trace source (the component to be traced) and the FilePath, Debugger, or PSHost parameters to specify a listener (a destination for the output). Use the Options parameter to determine the types of events that are traced and the ListenerOptions parameter to configure the trace output.

        To change the configuration of a trace, enter a Set-TraceSource command as you would to start a trace. Windows PowerShell recognizes that the trace source is already being traced. It stops the trace, adds the new configuration, and starts or restarts the trace.

        To stop a trace, use the RemoveListener parameter. To stop a trace that uses the file listener (a trace started by using the -FilePath parameter), use the RemoveFileListener parameter. When you remove the listener, the trace stops.

        To determine which components can be traced, use Get-TraceSource. The trace sources for each module are loaded automatically when the component is in use, and they appear in the output of Get-TraceSource.

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

    C:\PS>Set-TraceSource -Name Parameterbinding -Option ExecutionFlow -PSHost ‘
    -ListenerOption “ProcessID,TimeStamp”

    Description
    ———–
    This command starts tracing for the ParameterBinding component of Windows PowerShell. It uses the Name parameter to specify the trace source, the Option parameter to select the ExecutionFlow trace events, and the PSHost parameter to select the Windows PowerShell host listener, which sends the output to the console. The ListenerOption parameter adds the “ProcessID” and “TimeStamp” values to the trace message prefix.

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

    C:\PS>Set-TraceSource -Name ParameterBinding -RemoveListener Host

    Description
    ———–
    This command stops the trace of the ParameterBinding component of Windows PowerShell. It uses the Name parameter to identify the component that was being traced and the RemoveListener parameter to identify the trace listener.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113400
    Get-TraceSource
    Trace-Command
    Set-PSDebug