Category Archives: cmdlet

cmdlet, ModuleManifest, Test

Test-ModuleManifest

NAME
    Test-ModuleManifest

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

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

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

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

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

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

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

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

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

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

NOTES

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

cmdlet, Path, Test

Test-Path

NAME
    Test-Path

SYNOPSIS
    Determines whether all elements of a path exist.

SYNTAX
    Test-Path [-LiteralPath] <string[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Include <string[]>] [-IsValid] [-PathType {Any | Container | Leaf}] [-UseTransaction] [<CommonParameters>]

    Test-Path [-Path] <string[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Include <string[]>] [-IsValid] [-PathType {Any | Container | Leaf}] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The Test-Path cmdlet determines whether all elements of the path exist. It returns TRUE ($true) if all elements exist and FALSE ($false) if any are missing. It can also tell whether the path syntax is valid and whether the path leads to a container or a terminal (leaf) element.

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

    -Include <string[]>
        Tests only the specified paths. 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

    -IsValid [<SwitchParameter>]
        Determines whether the syntax of the path is correct, regardless of whether the elements of the path exist. This parameter returns TRUE if the path syntax is valid and FALSE if it is not.

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

    -LiteralPath <string[]>
        Specifies a path to be tested. Unlike Path, 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

    -Path <string[]>
        Specifies a path to be tested. Wildcards are permitted. If the path includes spaces, enclose it in quotation marks. The parameter name (“Path”) is optional.

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

    -PathType <TestPathType>
        Tells whether the final element in the path is of a particular type. This parameter returns TRUE if the element is of the specified type and FALSE if it is not.

        Valid values are:
        — Container: An element that contains other elements, such as a directory or Registry key.

        — Leaf: An element that does not contain other elements, such as a file.

        — Any: Either a container or a leaf.Tells whether the final element in the path is of a particular type. Returns TRUE if the element is of the specified type and FALSE if it is not.

        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.String
        You can pipe a string that contains a path (but not a literal path) to Test-Path.

OUTPUTS
    System.Boolean
        The cmdlet returns “True” when the path exists and “False” when it does not.

NOTES

        The cmdlets that contain the Path noun (the Path cmdlets) manipulate path names and return the names in a concise format that all Windows PowerShell providers can interpret. They are designed for use in programs and scripts where you want to display all or part of a path name in a particular format. Use them like you would use Dirname, Normpath, Realpath, Join, or other path manipulators.

         You can use the Path cmdlets with several providers, including the FileSystem, Registry, and Certificate providers.

        The Test-Path 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>Test-Path -Path “C:\Documents and Settings\NicoleH”

    Description
    ———–
    This command tells whether all elements in the path exist, that is, the C: directory, the Documents and Settings directory, and the NicoleH directory. If any are missing, the cmdlet returns FALSE. Otherwise, it returns TRUE.

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

    C:\PS>Test-Path -Path $profile

    C:\PS>Test-Path -Path $profile -IsValid

    Description
    ———–
    These commands test the path to the Windows PowerShell profile.

    The first command determines whether all elements in the path exist. The second command determines whether the syntax of the path is correct. In this case, the path is FALSE, but the syntax is correct (TRUE). These commands use $profile, the automatic Variable that points to the location for the profile, even if the profile does not exist.

    For more information about automatic Variables, see about_Automatic_Variables.

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

    C:\PS>Test-Path -Path “C:\CAD\Commercial Buildings\*” -Exclude *.dwg

    Description
    ———–
    This command tells whether there are any files in the Commercial Buildings directory other than .dwg files.

    The command uses the Path parameter to specify the path. Because it includes a space, the path is enclosed in quotes. The asterisk at the end of the path indicates the contents of the Commercial Building directory. (With long paths, like this one, type the first few letters of the path, and then use the TAB key to complete the path.)

    The command uses the Exclude parameter to specify files that will be omitted from the evaluation.

    In this case, because the directory contains only .dwg files, the result is FALSE.

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

    C:\PS>Test-Path -Path $profile -Pathtype leaf

    Description
    ———–
    This command tells whether the path stored in the $profile Variable leads to a file. In this case, because the Windows PowerShell profile is a .ps1 file, the cmdlet returns TRUE.

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

    C:\PS>Test-Path -Path HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell

    TRUE

    C:\PS> Test-Path -Path HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell\ExecutionPolicy
    FALSE

    Description
    ———–
    These commands use the Test-Path cmdlet with the Windows PowerShell Registry provider.

    The first command tests whether the Registry path to the Microsoft.PowerShell Registry key is correct on the system. If Windows PowerShell is installed correctly, the cmdlet returns TRUE.

    Test-Path does not work correctly with all Windows PowerShell providers. For example, you can use Test-Path to test the path to a Registry key, but if you use it to test the path to a Registry entry, it always returns FALSE, even if the Registry entry is present.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113418
    about_providers
    Convert-Path
    Split-Path
    Resolve-Path
    Join-Path

cmdlet, Test, WSMan

Test-WSMan

NAME
    Test-WSMan

SYNOPSIS
    Tests whether the WinRM service is running on a local or remote computer.

SYNTAX
    Test-WSMan [[-ComputerName] <string>] [-Authentication <Authentication>] [-Credential <PSCredential>] [<CommonParameters>]

DESCRIPTION
    The Test-WSMan cmdlet submits an identification request that determines whether the WinRM service is running on a local or remote computer. If the tested computer is running the service, the cmdlet displays the WS-Management identity schema, the protocol version, the product vendor, and the product version of the tested service.

PARAMETERS
    -Authentication <Authentication>
        Specifies the authentication mechanism to be used at the server. Possible values are:
        – Basic: Basic is a scheme in which the user name and password are sent in clear text to the server or proxy.
        – Default : Use the authentication method implemented by the WS-Management protocol.
        – Digest: Digest is a challenge-response scheme that uses a server-specified data string for the challenge.
        – Kerberos: The client computer and the server mutually authenticate by using Kerberos Certificates.
        – Negotiate: Negotiate is a challenge-response scheme that negotiates with the server or proxy to determine the scheme to use for authentication. For example, this parameter value allows negotiation to determine whether the Kerberos protocol or NTLM is used.
        – CredSSP: Use Credential Security Service Provider (CredSSP) authentication, which allows the user to delegate credentials. This option is designed for commands that run on one remote computer but collect data from or run additional commands on other remote computers.

        Caution: CredSSP delegates the user’s credentials from the local computer to a remote computer. This practice increases the security risk of the remote operation. If the remote computer is compromised, when credentials are passed to it, the credentials can be used to control the network session.

        Important: If the authentication parameter is not specified, then the Test-WSMan request will be sent to the remote machine anonymously (without using authentication). If the Test-WSMan request is made anonymously, it does not return any information that is specific to the operating-system version. Instead, Test-WSMan displays null values for the operating system version and service pack level (OS: 0.0.0 SP: 0.0).

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

    -ComputerName <string>
        Specifies the computer against which you want to run the management operation. The value can be a fully qualified domain name, a NetBIOS name, or an IP address. Use the local computer name, use localhost, or use a dot (.) to specify the local computer. The local computer is the default. When the remote computer is in a different domain from the user, you must use a fully qualified domain name must be used.

        Required?                    false
        Position?                    1
        Default value                localhost
        Accept pipeline input?     false
        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”, “Domain01\User01”, or User@Domain.com. Or, enter a PSCredential object, such as one returned by the Get-Credential cmdlet. When you type a user name, you will be prompted for a password.

        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
        This cmdlet does not accept any input.

OUTPUTS
    None
        This cmdlet does not generate any output object.

NOTES

        By default, the Test-WSMan cmdlet queries the WinRM service without using authentication, and it does not return any information that is specific to the operating-system version. Instead, it displays null values for the operating system version and service pack level (OS: 0.0.0 SP: 0.0).

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

    C:\PS>Test-WSMan

    wsmid         : http://schemas.dmtf.org/wbem/wsman/identity/1/wsmanidentity.xsd
    ProtocolVersion : http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd
    ProductVendor : Microsoft Corporation
    ProductVersion : OS: 0.0.0 SP: 0.0 Stack: 2.0

    Description
    ———–
    This command determines whether the WinRM service is running on the local computer or on a remote computer.

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

    C:\PS>Test-WSMan -ComputerName server01

    wsmid         : http://schemas.dmtf.org/wbem/wsman/identity/1/wsmanidentity.xsd
    ProtocolVersion : http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd
    ProductVendor : Microsoft Corporation
    ProductVersion : OS: 0.0.0 SP: 0.0 Stack: 2.0

    Description
    ———–
    This command determines whether the WinRM service is running on the server01 computer named.

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

    C:\PS>Test-WSMan -Authentication default

    wsmid         : http://schemas.dmtf.org/wbem/wsman/identity/1/wsmanidentity.xsd
    ProtocolVersion : http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd
    ProductVendor : Microsoft Corporation
    ProductVersion : OS: 6.0.6001 SP: 1.0 Stack: 2.0

    Description
    ———–
    This command tests to see if the WS-Management (WinRM) service is running on the local computer using the authentication parameter.

    Using the authentication parameter allows the Test-WSMan cmdlet to return the Operating System version.

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

    C:\PS>Test-WSMan -ComputerName server01 -Authentication default

    wsmid         : http://schemas.dmtf.org/wbem/wsman/identity/1/wsmanidentity.xsd
    ProtocolVersion : http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd
    ProductVendor : Microsoft Corporation
    ProductVersion : OS: 6.1.7021 SP: 0.0 Stack: 2.0

    Description
    ———–
    This command tests to see if the WS-Management (WinRM) service is running on the computer named server01 using the authentication parameter.

    Using the authentication parameter allows the Test-WSMan cmdlet to return the operating system version.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkId=141464
    Connect-WSMan
    Disable-WSManCredSSP
    Disconnect-WSMan
    Enable-WSManCredSSP
    Get-WSManCredSSP
    Get-WSManInstance
    Invoke-WSManAction
    New-WSManInstance
    New-WSManSessionOption
    Remove-WSManInstance
    Set-WSManInstance
    Set-WSManQuickConfig

cmdlet, Command, Trace

Trace-Command

NAME
    Trace-Command

SYNOPSIS
    Configures and starts a trace of the specified expression or command.

SYNTAX
    Trace-Command [-Command] <string> [-ArgumentList <Object[]>] [-Name] <string[]> [[-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] [-InputObject <psobject>] [-ListenerOption {None | LogicalOperationStack | DateTime | Timestamp | ProcessId | ThreadId | Callstack}] [-PSHost] [<CommonParameters>]

    Trace-Command [-Expression] <scriptblock> [-Name] <string[]> [[-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] [-InputObject <psobject>] [-ListenerOption {None | LogicalOperationStack | DateTime | Timestamp | ProcessId | ThreadId | Callstack}] [-PSHost] [<CommonParameters>]

DESCRIPTION
    The Trace-Command cmdlet configures and starts a trace of the specified expression or command. It works like Set-TraceSource, except that it applies only to the specified command.

PARAMETERS
    -ArgumentList <Object[]>
        Specifies the parameters and parameter values for the command being traced. The Alias for ArgumentList is Args. This feature is especially useful for debugging dynamic parameters.

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

    -Command <string>
        Specifies a command that is being processed during the trace.

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

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

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

    -Expression <scriptblock>
        Specifies the expression that is being processed during the trace. Enclose the expression in curly braces ({}).

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

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

    -Force [<SwitchParameter>]
        Allows the cmdlet to append trace information to a read-only file. Used with the FilePath parameter. 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

    -InputObject <psobject>
        Provides input to the expression that is being processed during the trace.

        You can enter a Variable that represents the input that the expression accepts, or pass an object through the pipeline.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        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 Windows PowerShell components are traced. Enter the name of the trace source of each component. Wildcards are permitted. To find the trace sources on your computer, type “Get-TraceSource“.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     false
        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?                    3
        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

    <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 that represent input to the expression to Trace-Command.

OUTPUTS
    System.Management.Automation.PSObject
        Returns the command trace in the debug stream.

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

        To find the Windows PowerShell components that are enabled for tracing, type “Get-Help Get-TraceSource.”

        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 host or console, to a file, or to a custom listener derived from the System.Diagnostics.TraceListener class.

        When you use the Command parameter set, Windows PowerShell processes the command just as it would be processed in a pipeline. For example, command discovery is not repeated for each incoming object.

        The names of the Name, Expression, Option, and Command parameters are optional. If you omit the parameter names, the unnamed parameter values must appear in this order: Name, Expression, Option or Name, Command,-Option . If you include the parameter names, the parameters can appear in any order.

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

    C:\PS>Trace-Command -Name metadata,parameterbinding,cmdlet -Expression {Get-Process notepad} -PSHost

    Description
    ———–
    This command starts a trace of metadata processing, parameter binding, and cmdlet creation and destruction of the “Get-Process notepad” expression. It uses the Name parameter to specify the trace sources, the Expression parameter to specify the command, and the PSHost parameter to send the output to the console. Because it does not specify any tracing options or listener options, the command uses the defaults, “All” for the tracing options, and “None” for the listener options.

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

    C:\PS>Trace-Command -Name commandprocessor,pipelineprocessor -command Get-Alias -argumentlist “ghy” -Option executionflow -ListenerOption “timestamp,callstack” -FilePath c:\test\debug.txt

    Description
    ———–
    This command starts a trace of the command processor and pipeline processor while processing the “Get-Alias cd” command.

    It uses the Name parameter to specify the trace sources, the Command parameter to specify the command, the ArgumentList parameter to specify the parameters of the Get-Alias command, the Option parameter to specify tracing options, and the ListenerOption parameter to specify the fields in the trace message prefix. The FilePath parameter sends the output to the C:\Test\Debug.txt file.

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

    C:\PS>$a = “i*”

    C:\PS> Trace-Command parameterbinding {Get-Alias $input} -PSHost -InputObject $a

    Description
    ———–
    These commands trace the actions of the ParameterBinding operations of Windows PowerShell while it processes a Get-Alias expression that takes input from the pipeline.

    In Trace-Command, the InputObject parameter passes an object to the expression that is being processed during the trace.

    The first command stores the string “i*” in the $a Variable. The second command uses the Trace-Command cmdlet with the ParameterBinding trace source. The PSHost parameter sends the output to the console.

    The expression being processed is “Get-Alias $input”, where the $input Variable is associated with the InputObject parameter. The InputObject parameter passes the Variable $a to the expression. In effect, the command being processed during the trace is “Get-Alias -InputObject $a” or “$a | Get-Alias“.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113419
    Get-TraceSource
    Set-TraceSource

cmdlet, Transaction, Undo

Undo-Transaction

NAME
    Undo-Transaction

SYNOPSIS
    Rolls back the active transaction.

SYNTAX
    Undo-Transaction [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Undo-Transaction cmdlet rolls back the active transaction. When you roll back a transaction, the changes made by the commands in the transaction are discarded and the data is restored to its original form.

    If the transaction includes multiple subscribers, an Undo-Transaction command rolls back the entire transaction for all subscribers.

    By default, transactions are rolled back automatically if any command in the transaction generates an error. However, transactions can be started with a different rollback preference and you can use this cmdlet to roll back the active transaction at any time.

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

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

NOTES

        You cannot roll back a transaction that has been committed.

        You cannot roll back any transaction other than the active transaction. To roll back a different, independent transaction, you must first commit or roll back the active transaction.

        Rolling back the transaction ends the transaction. To use a transaction again, you must start a new transaction.

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

    C:\PS>Undo-Transaction

    Description
    ———–
    This command rolls back the current (active) transaction.

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

    C:\PS>cd hkcu:\software

    PS HKCU:\Software> Start-Transaction
    PS HKCU:\Software> New-Item MyCompany -usetransaction
    PS HKCU:\Software> Undo-Transaction

    Description
    ———–
    This command starts a transaction and then rolls it back. As a result, no changes are made to the Registry.

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

    C:\PS>cd hkcu:\software

    PS HKCU:\Software> Start-Transaction
    PS HKCU:\Software> New-Item MyCompany -usetransaction
    PS HKCU:\Software> Get-Transaction

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

    PS HKCU:\Software> Start-Transaction
    PS HKCU:\Software> Get-Transaction

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

    PS HKCU:\Software> Undo-Transaction
    PS HKCU:\Software> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— —–
    Error                0                 RolledBack

    Description
    ———–
    This example demonstrates that when any subscriber rolls back a transaction, the entire transaction is rolled back for all subscribers.

    The first command changes the location to the HKCU:\Software Registry key.

    The second command starts a transaction.

    The third command uses the New-Item cmdlet to create a new Registry key. The command uses the UseTransaction parameter to include the change in the transaction.

    The fourth command uses the Get-Transaction cmdlet to get the active transaction. Notice that the status is Active and the subscriber count is 1.

    The fifth command uses the Start-Transaction command again. Typically,
    starting a transaction while another transaction is in progress occurs when a script used by the main transaction includes its own complete transaction. (This example is done interactively so that you can examine it in stages.)

    When you enter a Start-Transaction command while another transaction is in progress, the commands join the existing transaction as a new “subscriber” and the subscriber count is incremented.

    The sixth command uses the Get-Transaction cmdlet to get the active transaction. Notice that the subscriber count is now 2.

    The seventh command uses the Undo-Transaction cmdlet to roll back the transaction. This command does not return any objects.

    The final command is a Get-Transaction command that gets the active (or in this case, the most recently active) transaction. The results show that the transaction is rolled back, and that the subscriber count is 0, showing that the transaction was rolled back for all subscribers.

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

cmdlet, Event, Unregister

Unregister-Event

NAME
    Unregister-Event

SYNOPSIS
    Cancels an event subscription.

SYNTAX
    Unregister-Event [-SubscriptionId] <int> [-Force] [-Confirm] [-WhatIf] [<CommonParameters>]

    Unregister-Event [-SourceIdentifier] <string> [-Force] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Unregister-Event cmdlet cancels an event subscription that was created by using the Register-EngineEvent, Register-ObjectEvent, or Register-WmiEvent cmdlet.

    When an event subscription is canceled, the event subscriber is deleted from the session and the subscribed events are no longer added to the event queue. When you cancel a subscription to an event created by using the New-Event cmdlet, the new event is also deleted from the session.

    Unregister-Event does not delete events from the event queue. To delete events, use the Remove-Event cmdlet.

PARAMETERS
    -Force [<SwitchParameter>]
        Cancels all event subscriptions, including subscriptions that were hidden by using the SupportEvent parameter of Register-ObjectEvent, Register-WmiEvent, and Register-EngineEvent.

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

    -SourceIdentifier <string>
        Cancels event subscriptions that have the specified source identifier.

        A SourceIdentifier or SubscriptionId parameter must be included in every command.

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

    -SubscriptionId <int>
        Cancels event subscriptions that have the specified subscription identifier.

        A SourceIdentifier or SubscriptionId parameter must be included in every command.

        Required?                    true
        Position?                    1
        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.PSEventSubscriber
        You can pipe the output from Get-EventSubscriber to Unregister-Event.

OUTPUTS
    None
        This cmdlet does not return any output.

NOTES

        Events, event subscriptions, and the event queue exist only in the current session. If you close the current session, the event queue is discarded and the event subscription is canceled.

        Unregister-Event cannot delete events created by using the New-Event cmdlet unless you have subscribed to the event by using the Register-EngineEvent cmdlet. To delete a custom event from the session, you must remove it programmatically or close the session.

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

    C:\PS>Unregister-Event -SourceIdentifier ProcessStarted

    Description
    ———–
    This command cancels the event subscription that has a source identifier of “ProcessStarted”.

    To find the source identifier of an event, use the Get-Event cmdlet. To find the source identifier of an event subscription, use the Get-EventSubscriber cmdlet.

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

    C:\PS>Unregister-Event -subscriptionId 2

    Description
    ———–
    This command cancels the event subscription that has a subscription identifier of 2.

    To find the subscription identifier of an event subscription, use the Get-EventSubscriber cmdlet.

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

    C:\PS>Get-Eventsubscriber -Force | Unregister-Event -Force

    Description
    ———–
    This command cancels all event subscriptions in the session.

    The command uses the Get-EventSubscriber cmdlet to get all event subscriber objects in the session, including the subscribers that are hidden by using the SupportEvent parameter of the event registration cmdlets.

    It uses a pipeline operator (|) to send the subscriber objects to Unregister-Event, which deletes them from the session. To complete the task, the Force parameter is also required on Unregister-Event.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135269
    Register-ObjectEvent
    Register-EngineEvent
    Register-WmiEvent
    Unregister-Event
    Get-Event
    New-Event
    Remove-Event
    Wait-Event
    Get-EventSubscriber

cmdlet, PSSessionConfiguration, Unregister

Unregister-PSSessionConfiguration

NAME
    Unregister-PSSessionConfiguration

SYNOPSIS
    Deletes registered session configurations from the computer.

SYNTAX
    Unregister-PSSessionConfiguration [-Name] <string> [-Force] [-NoServiceRestart] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Unregister-PSSessionConfiguration cmdlet deletes registered session configurations from the computer. This is an advanced cmdlet that is designed to be used by system administrators to manage customized session configurations for their users.

    If you accidentally delete the default Microsoft.PowerShell or Microsoft.PowerShell32 session configurations, use the Enable-PSRemoting cmdlet to restore them.

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

    -Name <string>
        Specifies the names of session configurations to delete. Enter one or more configuration names. Wildcards are permitted. This parameter is required.

        You can also pipe a session configuration object to Unregister-PSSessionConfiguration.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        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 an Unregister-PSSessionConfiguration command, you are prompted to restart the WinRM service to make the change effective. Until the WinRM service is restarted, users can still use the unregistered session configuration, even though Get-PSSessionConfiguration does not find it.

        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

    -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.Commands.PSSessionConfigurationCommands#PSSessionConfiguration
        You can pipe a session configuration object from Get-PSSessionConfiguration to Unregister-PSSessionConfiguration.

OUTPUTS
    None
        This cmdlet does not return any objects.

NOTES

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

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

    C:\PS>Unregister-PSSessionConfiguration -Name MaintenanceShell

    Description
    ———–
    This command deletes the MaintenanceShell session configuration from the computer.

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

    C:\PS>Unregister-PSSessionConfiguration -maintenanceShell -Force

    Description
    ———–
    This command deletes the MaintenanceShell session configuration from the computer. The command uses the Force parameter to suppress all user messages and to restart the WinRM service without prompting.

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

    C:\PS>Unregister-PSSessionConfiguration -Name *

    C:\PS> Get-PSSessionConfiguration -Name * | Unregister-PSSessionConfiguration

    Description
    ———–
    These commands delete all of the session configurations on the computer. The commands have the same effect and can be used interchangeably.

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

    C:\PS>Unregister-PSSessionConfiguration -Name maintenanceShell -NoServiceRestart

    C:\PS> Get-PSSessionConfiguration -Name maintenanceShell

    Get-PSSessionConfiguration -Name maintenanceShell : No Session Configuration matches criteria “maintenanceShell”.
        + CategoryInfo         : NotSpecified: (:) [Write-Error], WriteErrorException
        + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException

    C:\PS> New-PSSession -configurationName MaintenanceShell

     Id Name     ComputerName    State    Configuration         Availability
     — —-     ————    —–    ————-         ————
     1 Session1 localhost     Opened MaintenanceShell     Available

    C:\PS> Restart-Service winrm

    C:\PS> New-PSSession -configurationName MaintenanceShell
    [localhost] Connecting to remote server failed with the following error message : The WS-Management service cannot process the request. The resource
    URI (http://schemas.microsoft.com/powershell/MaintenanceShell) was not found in the WS-Management catalog. The catalog contains the metadata that describes resour
    ces, or logical endpoints. For more information, see the about_remote_TroubleShooting Help topic.
        + CategoryInfo         : OpenError: (System.Manageme….RemoteRunspace:RemoteRunspace) [], PSRemotingTransportException
        + FullyQualifiedErrorId : PSSessionOpenFailed

    Description
    ———–
    This example shows the effect of using the NoServiceRestart parameter of Unregister-PSSessionConfiguration. This parameter is designed to prevent a service restart, which would disrupt any sessions on the computer.

    The first command uses the Unregister-PSSessionConfiguration cmdlet to deletes the MaintenanceShell session configuration. However, because the command uses the NoServiceRestart parameter, the WinRM service is not restarted and the change is not yet completely effective.

    The second command uses the Get-PSSessionConfiguration cmdlet to get the MaintenanceShell session. Because the session has been removed from the WS-Management resource table, Get-PSSession cannot return it.

    The third command uses the New-PSSession cmdlet to create a session on the local computer that uses the MaintenanceShell configuration. The command succeeds.

    The fourth command uses the Restart-Service cmdlet to restart the WinRM service.

    The fifth command again uses the New-PSSession cmdlet to create a session that uses the MaintenanceShell configuration. This time, the session fails because the MaintenanceShell configuration has been deleted.

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

cmdlet, FormatData, Update

Update-FormatData

NAME
    Update-FormatData

SYNOPSIS
    Updates the formatting data in the current session.

SYNTAX
    Update-FormatData [[-AppendPath] <string[]>] [-PrependPath <string[]>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Update-FormatData cmdlet reloads the formatting data from formatting files into the current session. This cmdlet lets you update the formatting data without restarting Windows PowerShell.

    Without parameters, Update-FormatData reloads the formatting files that it loaded previously. You can use the parameters of Update-FormatData to add new formatting files to the session.

    Formatting files are text files in XML format with the format.ps1xml file name extension. The formatting data in the files defines the display of Microsoft .NET Framework objects in the session.

    When Windows PowerShell starts, it loads the format data from the formatting files in the Windows PowerShell installation directory ($pshome) into the session. You can use Update-FormatData to reload the formatting data into the current session without restarting Windows PowerShell. This is useful when you have added or changed a formatting file, but do not want to interrupt the session.

    For more information about formatting files in Windows PowerShell, see about_Format.ps1xml.

PARAMETERS
    -AppendPath <string[]>
        Adds the specified formatting files to the session. The files are loaded after Windows PowerShell loads the built-in formatting files.

        When formatting .NET objects, Windows PowerShell uses the first formatting definition that it finds for each .NET type. If you use the AppendPath parameter, Windows PowerShell searches the data from the built-in files before it encounters the formatting data that you are adding.

        Use this parameter to add a file that formats a .NET object that is not referenced in the built-in formatting files.

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

    -PrependPath <string[]>
        Adds the specified formatting files to the session. The files are loaded before Windows PowerShell loads the built-in formatting files.

        When formatting .NET objects, Windows PowerShell uses the first formatting definition that it finds for each .NET type. If you use the PrependPath parameter, Windows PowerShell searches the data from the files that you are adding before it encounters the formatting data from the built-in files.

        Use this parameter to add a file that formats a .NET object that is also referenced in the built-in formatting files.

        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.String
        You can pipe a string that contains the append path to Update-FormatData.

OUTPUTS
    None
        The cmdlet does not return any output.

NOTES

        Update-FormatData also updates the formatting data for commands in the session that were imported from modules. If the formatting file for a module changes, you can run an Update-FormatData command to update the formatting data for imported commands. You do not need to import the module again.

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

    C:\PS>Update-FormatData

    Description
    ———–
    This command reloads the formatting files that it loaded previously.

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

    C:\PS>Update-FormatData -AppendPath trace.format.ps1xml, log.format.ps1xml

    Description
    ———–
    This command reloads the formatting files into the session, including two new files, Trace.format.ps1xml and Log.format.ps1xml.

    Because the command uses the AppendPath parameter, the formatting data in the new files is loaded after the formatting data from the built-in files.

    The AppendPath parameter is used because the new files contain formatting data for objects that are not referenced in the built-in files.

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

    C:\PS>Update-FormatData -PrependPath c:\test\NewFiles.format.ps1xml

    # Edit the NewFiles.format.ps1 file.

    C:\PS> Update-FormatData

    Description
    ———–
    This example shows how to reload a formatting file after you have edited it.

    The first command adds the NewFiles.format.ps1xml file to the session. It uses the PrependPath parameter because the file contains formatting data for objects that are referenced in the built-in files.

    After adding the NewFiles.format.ps1xml file and testing it in these session, the author edits the file.

    The second command uses the Update-FormatData cmdlet to reload the formatting files. Because the NewFiles.format.ps1xml file was previously loaded, Update-FormatData automatically reloads it without using parameters.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113420

cmdlet, List, Update

Update-List

NAME
    Update-List

SYNOPSIS
    Adds items to and removes items from a property value that contains a collection of objects.

SYNTAX
    Update-List [-Add <Object[]>] [-Remove <Object[]>] [[-Property] <string>] [-InputObject <psobject>] [<CommonParameters>]

    Update-List -Replace <Object[]> [[-Property] <string>] [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
    The Update-List cmdlet adds items to and removes items from a property value of an object, and then it returns the updated object. This cmdlet is designed for properties that contain collections of objects.

    The Add and Remove parameters add individual items to and remove them from the collection. The Replace parameter replaces the entire collection.

    If you do not specify a property in the command, Update-List returns an object that describes the update instead of updating the object. You can submit the update object to cmdlets that change objects, such as Set-* cmdlets.

    This cmdlet works only when the property that is being updated supports the IList interface that Update-List uses. Also, any Set-* cmdlets that accept an update must support the IList interface. The core cmdlets that are installed with Windows PowerShell do not support this interface. To determine whether a cmdlet supports Update-List, see the cmdlet Help topic.

PARAMETERS
    -Add <Object[]>
        Specifies the property values to be added to the collection. Enter the values in the order that they should appear in the collection.

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

    -InputObject <psobject>
        Specifies the objects to be updated. You can also pipe the object to be updated to Update-List.

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

    -Property <string>
        Identifies the property that contains the collection that is being updated. If you omit this parameter, Update-List returns an object that represents the change instead of changing the object.

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

    -Remove <Object[]>
        Specifies the property values to be removed from the collection.

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

    -Replace <Object[]>
        Specifies a new collection. This parameter replaces all items in the original collection with the items specified by this parameter.

        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
    System.Management.Automation.PSObject
        You can pipe the objects to be updated to Update-List.

OUTPUTS
    Objects or System.Management.Automation.PSListModifier
        Update-List returns the updated object, or it returns an object that represents the update action.

NOTES

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

    C:\PS>get-mailbox | Update-List -Property Aliases -Add “A”,”B” -Remove “X”,”Y” | set-mailbox

    Description
    ———–
    This command adds A and B and removes X and Y from the Aliases property of a mailbox.

    The command uses the Get-MailBox cmdlet from Microsoft Exchange Server to get the mailbox. A pipeline operator sends the mailbox object to the Update-List cmdlet.

    The Update-List command uses the Property parameter to indicate that the Aliases property of the mailbox is being updated, and it uses the Add and Remove parameters to specify the items that are being added and removed from the collection. The Aliases property fulfills the conditions of Update-List, because it stores a collection of Microsoft .NET Framework objects that have Add and Remove methods.

    The Update-List cmdlet returns the updated mailbox, which is piped to the Set-MailBox cmdlet, which changes the mailbox.

    For more information about Get-Mailbox, see http://go.microsoft.com/fwlink/?LinkId=111536.

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

    C:\PS>$m = get-mailbox

    C:\PS> Update-List -InputObject $m -Property Aliases -Add “A”,”B” -Remove “X”, “Y” | set-mailbox

    Description
    ———–
    This command adds A and B to the value of the Aliases property of a mailbox and removes X and Y. This command has the same effect as the previous command, although it has a slightly different format.

    The command uses the Get-MailBox cmdlet to get the mailbox, and it saves the mailbox in the $m Variable. This command uses the InputObject parameter of Update-List to specify the mailbox. The value of InputObject is the mailbox in the $m Variable. It uses the Property parameter to specify the Aliases property and the Add and Remove parameters to specify the items being added to and removed from the value of Aliases.

    The command uses a pipeline operator (|) to send the updated mailbox object to the Set-Mailbox cmdlet, which changes the mailbox.

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

    C:\PS>get-mailbox | set-mailbox -alias (Update-List -Add “A”, “B” -Remove “X”,”Y”)

    Description
    ———–
    This command adds A and B to the value of the Aliases property of a mailbox and removes X and Y. This command has the same effect as the two previous commands, but it uses a different procedure to perform the task.

    Instead of updating the Aliases property of the mailbox before sending it to Set-Mailbox, this command uses Update-List to create an object that represents the change. Then it submits the change to the Alias parameter of Set-Mailbox.

    The command uses the Get-MailBox cmdlet to get the mailbox. A pipeline operator sends the mailbox object to the Set-Mailbox cmdlet, which changes mailboxes.

    The command uses the Alias parameter of Set-Mailbox to change the Aliases property of the mailbox object. The value of the Alias parameter is an Update-List command that creates an object that represents the update. The Update-List command is enclosed in parentheses to ensure that it runs before the value of the Alias parameter is evaluated. When the Set-Mailbox command completes, the mailbox is changed.

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

    C:\PS>Update-List -InputObject $a -Property Aliases -replace “A”, “B” | set-mailbox

    Description
    ———–
    This command uses the Replace operator of Update-List to replace the collection in the Aliases property of the object in $a with a new collection.

    This command uses the InputObject parameter which, in this case, is equivalent to using a pipeline operator to pass $a to Update-List.

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

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