All posts by Adam

cmdlet, Item, Remove

Remove-Item

NAME
    Remove-Item

SYNOPSIS
    Deletes the specified items.

SYNTAX
    Remove-Item [-LiteralPath] <string[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-Recurse] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

    Remove-Item [-Path] <string[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-Recurse] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The Remove-Item cmdlet deletes one or more items. Because it is supported by many providers, it can delete many different types of items, including files, directories, Registry keys, Variables, Aliases, and Functions.

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 remove items that cannot otherwise be changed, such as hidden or read-only files or read-only Aliases or Variables. The cmdlet cannot remove 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[]>
        Deletes 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 items being removed. 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

    -Path <string[]>
        Specifies a path to the items being removed. Wildcards are permitted. The parameter name (“-Path“) is optional.

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

    -Recurse [<SwitchParameter>]
        Deletes the items in the specified locations and in all child items of the locations.

        The Recurse parameter in this cmdlet does not work properly.

        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

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

OUTPUTS
    None
        This cmdlet does not return any output.

NOTES

        You can also refer to Remove-Item by any of its built-in Aliases, “del”, “erase”, “rmdir”, “rd”, “ri”, or “rm”. For more information, see about_aliases.

        The Remove-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>Remove-Item C:\Test\*.*

    Description
    ———–
    This command deletes all of the files with names that include a dot (.) from the C:\Test directory. Because the command specifies a dot, the command does not delete directories or files with no file name extension.

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

    C:\PS>Remove-Item * -Include *.doc -Exclude *1*

    Description
    ———–
    This command deletes from the current directory all files with a .doc file name extension and a name that does not include “1”. It uses the wildcard character (*) to specify the contents of the current directory. It uses the Include and Exclude parameters to specify the files to delete.

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

    C:\PS>Remove-Item -Path C:\Test\hidden-RO-file.txt -Force

    Description
    ———–
    This command deletes a file that is both hidden and read-only. It uses the Path parameter to specify the file. It uses the Force parameter to give permission to delete it. Without Force, you cannot delete read-only or hidden files.

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

    C:\PS>Get-ChildItem * -Include *.csv -Recurse | Remove-Item

    Description
    ———–
    This command deletes all of the CSV files in the current directory and all subdirectories recursively.

    Because the Recurse parameter in this cmdlet is faulty, the command uses the Get-ChildItem cmdlet to get the desired files, and it uses the pipeline operator to pass them to the Remove-Item cmdlet.

    In the Get-ChildItem command, the Path parameter has a value of *, which represents the contents of the current directory. It uses the Include parameter to specify the CSV file type, and it uses the Recurse parameter to make the retrieval recursive.

    If you try to specify the file type in the path, such as “-Path *.csv”, the cmdlet interprets the subject of the search to be a file that has no child items, and Recurse fails.

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

    C:\PS>Remove-Item hklm:\software\mycompany\OldApp -Recurse

    Description
    ———–
    This command deletes the OldApp Registry key and all of its subkeys and values. It uses the Remove-Item cmdlet to remove the key. The path is specified, but the optional parameter name (Path) is omitted.

    The Recurse parameter deletes all of the contents of the OldApp key recursively. If the key contains subkeys and you omit the Recurse parameter, you are prompted to confirm that you want to delete the contents of the key.

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

cmdlet, EventLog, Remove

Remove-EventLog

NAME
    Remove-EventLog

SYNOPSIS
    Deletes an event log or unregisters an event source.

SYNTAX
    Remove-EventLog [-LogName] <string[]> [[-ComputerName] <string[]>] [-Confirm] [-WhatIf] [<CommonParameters>]

    Remove-EventLog [[-ComputerName] <string[]>] [-Source <string[]>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Remove-EventLog cmdlet deletes an event log file from a local or remote computer and unregisters all of its event sources for the log. You can also use this cmdlet to unregister event sources without deleting any event logs.

    The cmdlets that contain the EventLog noun (the EventLog cmdlets) work only on classic event logs. To get events from logs that use the Windows Event Log technology in Windows Vista and later versions of Windows, use Get-WinEvent.

PARAMETERS
    -ComputerName <string[]>
        Specifies a remote computer. The default is the local computer.

        Type the NetBIOS name, an Internet Protocol (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 Remove-EventLog even if your computer is not configured to run remote commands.

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

    -LogName <string[]>
        Specifies the event logs. Enter the log name (the value of the Log property; not the LogDisplayName) of one or more event logs , separated by commas. Wildcard characters are not permitted. This parameter is required.

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

    -Source <string[]>
        Unregisters the specified event sources. Enter the source names (not the executable name), separated by commas.

        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
    None
        You cannot pipe input to this cmdlet.

OUTPUTS
    None
        This cmdlet does not return any output.

NOTES

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

        If you remove an event log and then re-create the log, you will not be able to register the same event sources. Applications that used the events sources to write entries to the original log will not be able to write to the new log.

        When you unregister an event source for a particular log, the event source might be prevented from writing entries in other event logs.

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

    C:\PS>Remove-Eventlog -LogName MyLog

    Description
    ———–
    This command deletes the MyLog event log from the local computer and unregisters its event sources.

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

    C:\PS>Remove-Eventlog -LogName MyLog, TestLog -ComputerName Server01, Server02, localhost

    Description
    ———–
    This command deletes the MyLog and TestLog event logs from the local computer (“localhost”) and the Server01 and Server02 remote computers. The command also unregisters the event sources for these logs.

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

    C:\PS>Remove-Eventlog -source MyApp

    Description
    ———–
    This command deletes the MyApp event source from the logs on the local computer. When the command completes, the MyApp program cannot write to any event logs.

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

    C:\PS>Get-Eventlog -list

     Max(K) Retain OverflowAction        Entries Log
     —— —— ————–        ——- —
     15,168     0 OverwriteAsNeeded     22,923 Application
     15,168     0 OverwriteAsNeeded         53 DFS Replication
         512     7 OverwriteOlder             0 Directory Service
     15,168     7 OverwriteOlder             0 Hardware Events
         512     7 OverwriteOlder             0 Internet Explorer
     20,480     0 OverwriteAsNeeded         0 Key Management Service
     30,016     0 OverwriteAsNeeded     50,060 Security
     15,168     0 OverwriteAsNeeded     27,592 System
     15,360     0 OverwriteAsNeeded     18,355 Windows PowerShell
     15,168     7 OverwriteAsNeeded         12 ZapLog

    C:\PS> Remove-Eventlog -LogName ZapLog

    C:\PS> Get-Eventlog -list

     Max(K) Retain OverflowAction        Entries Log
     —— —— ————–        ——- —
     15,168     0 OverwriteAsNeeded     22,923 Application
     15,168     0 OverwriteAsNeeded         53 DFS Replication
         512     7 OverwriteOlder             0 Directory Service
     15,168     7 OverwriteOlder             0 Hardware Events
         512     7 OverwriteOlder             0 Internet Explorer
     20,480     0 OverwriteAsNeeded         0 Key Management Service
     30,016     0 OverwriteAsNeeded     50,060 Security
     15,168     0 OverwriteAsNeeded     27,592 System
     15,360     0 OverwriteAsNeeded     18,355 Windows PowerShell

    Description
    ———–
    These commands show how to list the event logs on a computer and verify that a Remove-EventLog command was successful.

    The first command lists the event logs on the local computer.

    The second command deletes the ZapLog event log.

    The third command lists the event logs again. The ZapLog event log no longer appears in the list.

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

    C:\PS>Get-WmiObject win32_nteventlogfile -filter “logfilename=’TestLog'” | foreach {$_.sources}

    MyApp
    TestApp

    C:\PS> Remove-Eventlog -source MyApp

    C:\PS> Get-WmiObject win32_nteventlogfile -filter “logfilename=’TestLog’} | foreach {$_.sources}
    TestApp

    Description
    ———–
    These commands use the Get-WmiObject cmdlet to list the event sources on the local computer. You can these commands to verify the success of a command or to delete an event source.

    The first command gets the event sources of the TestLog event log on the local computer. MyApp is one of the sources.

    The second command uses the Source parameter of Remove-EventLog to delete the MyApp event source.

    The third command is identical to the first. It shows that the MyApp event source was deleted.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135248
    Clear-EventLog
    Get-EventLog
    Limit-EventLog
    New-EventLog
    Remove-EventLog
    Show-EventLog
    Write-EventLog
    Get-WinEvent

cmdlet, Event, Remove

Remove-Event

NAME
    Remove-Event

SYNOPSIS
    Deletes events from the event queue.

SYNTAX
    Remove-Event [-EventIdentifier] <int> [-Confirm] [-WhatIf] [<CommonParameters>]

    Remove-Event [-SourceIdentifier] <string> [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Remove-Event cmdlet deletes events from the event queue in the current session.

    This cmdlet deletes only the events currently in the queue. To cancel event registrations or unsubscribe, use the Unregister-Event cmdlet.

PARAMETERS
    -EventIdentifier <int>
        Deletes only the event with the specified event identifier. An EventIdentifier or SourceIdentifier parameter is required in every command.

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

    -SourceIdentifier <string>
        Deletes only the events with the specified source identifier. Wildcards are not permitted. An EventIdentifier or SourceIdentifier parameter is required in every command.

        Required?                    true
        Position?                    1
        Default value                None
        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.Management.Automation.PSEventArgs
        You can pipe events from Get-Event to Remove-Event.

OUTPUTS
    None
        The cmdlet does not generate 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.

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

    C:\PS>Remove-Event -SourceIdentifier “ProcessStarted”

    Description
    ———–
    This command deletes events with a source identifier of “Process Started” from the event queue.

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

    C:\PS>Remove-Event -eventIdentifier 30

    Description
    ———–
    This command deletes the event with an event ID of 30 from the event queue.

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

    C:\PS>Get-Event | Remove-Event

    Description
    ———–
    This command deletes all events from the event queue.

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

cmdlet, Computer, Remove

Remove-Computer

NAME
    Remove-Computer

SYNOPSIS
    Remove the local computer from a workgroup or domain.

SYNTAX
    Remove-Computer [[-Credential] <PSCredential>] [-Force] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Remove-Computer cmdlet removes the local computer from its current workgroup or domain.

    When you remove a computer from a domain, Remove-Computer also disables the computer’s domain account.

    When the computer is in a domain, you must provide credentials, even when they are the credentials of the current user, and you must restart the computer to make the change effective.

    To get the results of the command, use the Verbose and PassThru parameters.

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.

        To remove a computer from a domain, you must use the Credential parameter, even when you are using the credentials of the current user.

        Required?                    false
        Position?                    2
        Default value                The credentials of the current user
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Force [<SwitchParameter>]

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

    -PassThru [<SwitchParameter>]
        Returns the results of the command. Otherwise, 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
    None
        You cannot pipe input to this cmdlet

OUTPUTS
    Microsoft.PowerShell.Commands.ComputerChangeInfo
        When you use the PassThru parameter, Remove-Computer returns a ComputerChangeInfo object. Otherwise, this cmdlet does not generate any output.

NOTES

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

    C:\PS>Remove-Computer

    Description
    ———–
    This command removes the computer from a workgroup.

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

    C:\PS>Remove-Computer -Credential domain01\admin01 -PassThru -Verbose; Restart-Computer

    Description
    ———–
    These commands remove the local computer from the domain to which it is joined.

    The first command removes the computer from the domain. The command uses the Credential parameter to supply the credentials of a domain administrator. It uses the PassThru parameter and the Verbose common parameter to display information about the success or failure of the command.

    The second command uses the Restart-Computer cmdlet to restart the computer, which is required to complete the remove operation.

    The semi-colon (;) separates the two commands.

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

cmdlet, Register, WmiEvent

Register-WmiEvent

NAME
    Register-WmiEvent

SYNOPSIS
    Subscribes to a Windows Management Instrumentation (WMI) event.

SYNTAX
    Register-WmiEvent [-Class] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-Namespace <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

    Register-WmiEvent [-Query] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-Namespace <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

DESCRIPTION
    The Register-WmiEvent cmdlet subscribes to WMI events on the local computer or on a remote computer.

    When the subscribed WMI event is raised, it is added to the event queue in your local session even if the event occurs on a remote computer. To get events in the event queue, use the Get-Event cmdlet.

    You can use the parameters of Register-WmiEvent to subscribe to events on remote computers and to specify the property values of the events that can help you to identify the event in the queue. You can also use the Action parameter to specify actions to take when a subscribed event is raised.

    When you subscribe to an event, an event subscriber is added to your session. To get the event subscribers in the session, use the Get-EventSubscriber cmdlet. To cancel the subscription, use the Unregister-Event cmdlet, which deletes the event subscriber from the session.

PARAMETERS
    -Action <scriptblock>
        Specifies commands that handle the events. The commands in the Action parameter run when an event is raised instead of sending the event to the event queue. Enclose the commands in braces ( { } ) to create a script block.

        The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $SourceEventArgs, and $SourceArgs automatic Variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables.

        When you specify an action, Register-WmiEvent returns an event job object that represents that action. You can use the cmdlets that contain the Job noun (the Job cmdlets) to manage the event job.

        Required?                    false
        Position?                    102
        Default value                The event is added to the event queue.
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Class <string>
        Specifies the event to which you are subscribing. Enter the WMI class that generates the events. A Class or Query parameter is required in every command.

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

    -ComputerName <string>
        Specifies a remote computer. The default is the local computer. Enter a NetBIOS name, an IP address, or a fully qualified domain name.

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

    -Credential <PSCredential>
        Specifies a user account that has permission to perform this action. Type a user name, such as “User01” or “Domain01\User01”. Or, enter a PSCredential object, such as one from the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.

        Required?                    false
        Position?                    named
        Default value                The credentials of the current user
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Forward [<SwitchParameter>]
        Sends events for this subscription to the session on the local computer. Use this parameter when you are registering for events on a remote computer or in a remote session.

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

    -MessageData <psobject>
        Specifies any additional data to be associated with this event subscription. The value of this parameter appears in the MessageData property of all events associated with this subscription.

        Required?                    false
        Position?                    named
        Default value                None. The MessageData property is NULL.
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Namespace <string>
        Specifies the namespace of the WMI class.

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

    -Query <string>
        Specifies a query in WMI Query Language (WQL) that identifies the WMI event class, such as “select * from __InstanceDeletionEvent”.

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

    -SourceIdentifier <string>
        Specifies a name that you select for the subscription. The name that you select must be unique in the current session. The default value is the GUID that Windows PowerShell assigns.

        The value of this parameter appears in the value of the SourceIdentifier property of the subscriber object and of all event objects associated with this subscription.

        Required?                    false
        Position?                    101
        Default value                GUID
        Accept pipeline input?     false
        Accept wildcard characters? false

    -SupportEvent [<SwitchParameter>]
        Hides the event subscription. Use this parameter when the current subscription is part of a more complex event registration mechanism and it should not be discovered independently.

        To view or cancel a subscription that was created with the SupportEvent parameter, use the Force parameter of the Get-EventSubscriber and Unregister-Event cmdlets.

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

    -Timeout <Int64>
        Determines how long Windows PowerShell waits for this command to complete.

        The default value, 0 (zero), means that there is no time-out, and it causes Windows PowerShell to wait indefinitely.

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

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

INPUTS
    None
        You cannot pipe objects to Register-WmiEvent.

OUTPUTS
    None
        This cmdlet does not generate any output.

NOTES

        To use this cmdlet in Windows Vista or a later version of Windows, start Windows PowerShell with the “Run as administrator” option.

        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.

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

    C:\PS>Register-WmiEvent -Class ‘Win32_ProcessStartTrace’ -SourceIdentifier “ProcessStarted”

    Description
    ———–
    This command subscribes to the events generated by the Win32_ProcessStartTrace class. This class raises an event whenever a process starts.

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

    C:\PS>Register-WmiEvent -query “select * from __instancecreationevent within 5 where targetinstance isa ‘win32_process'” -SourceIdentifier “WMIProcess” -MessageData “Test 01” -Timeout 500

    Description
    ———–
    This command uses a query to subscribe to Win32_process instance creation events.

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

    C:\PS>$action = { Get-History | where { $_.commandline -like “*Start-Process*” } | Export-Clixml “commandHistory.clixml” }

    C:\PS> Register-WmiEvent -Class ‘Win32_ProcessStartTrace’ -SourceIdentifier “ProcessStarted” -Action $action

    Id    Name            State     HasMoreData Location Command
    —    —-            —–     ———– ——– ——-
    1     ProcessStarted NotStarted False                 Get-History | where {…

    Description
    ———–
    This example shows how to use an action to respond to an event. In this case, when a process starts, any Start-Process commands in the current session are written to an XML file.

    When you use the Action parameter, Register-WmiEvent returns a background job that represents the event action. You can use the Job cmdlets, such as Get-Job and Receive-Job, to manage the event job.

    For more information, see about_jobs.

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

    C:\PS>Register-WmiEvent -Class ‘Win32_ProcessStartTrace’ -SourceIdentifier “Start” -ComputerName Server01

    C:\PS> Get-Event -SourceIdentifier “Start”

    Description
    ———–
    This example registers for events on the Server01 remote computer.

    WMI returns the events to the local computer and stores them in the event queue in the current session. To retrieve the events, run a local Get-Event command.

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

cmdlet, PSSessionConfiguration, Register

Register-PSSessionConfiguration

NAME
    Register-PSSessionConfiguration

SYNOPSIS
    Creates and registers a new session configuration.

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

DESCRIPTION
    The Register-PSSessionConfiguration cmdlet creates and registers a new session configuration 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.

    Every Windows PowerShell remote session uses a session configuration. When users create a session that connects to the computer, they can select a configuration or use the default configurations that are registered when you enable Windows PowerShell remoting. Users can also set the $PSSessionConfigurationName preference Variable, which specifies a default configuration for sessions created in the current session.

    The session configuration configures the Environment for the session. You can define the configuration by using an assembly that implements a new configuration class and by using a script that runs in the session. The configuration can determine which commands are available in the session, and it can include settings that protect the computer, such as those that limit the amount of data that the session can receive remotely in a single object or command. You can also specify a security descriptor that determines the permissions that are required to use the configuration.

PARAMETERS
    -ApplicationBase <string>
        Specifies the path to the assembly file (*.dll) that is specified in the value of the AssemblyName parameter. Use this parameter when the value of the AssemblyName parameter does not include a path. The default is the current directory.

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

    -AssemblyName <string>
        Specifies the name of an assembly file (*.dll) in which the configuration type is defined. You can specify the path to the .dll in this parameter or in the value of the ApplicationBase parameter.

        This parameter is required when the ConfigurationTypeName parameter is specified.

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

    -ConfigurationTypeName <string>
        Specifies the fully qualified name of the Microsoft .NET Framework type that is used for this configuration. The type that you specify must implement the System.Management.Automation.Remoting.PSSessionConfiguration class.

        To specify the assembly file (.dll) that implements the configuration type, use the AssemblyName and AssemblyBase parameters.

        Creating a type allows you to control more aspects of the session configuration, such as exposing or hiding certain parameters of cmdlets, or setting data size and object size limits that users cannot override.

        If you omit this parameter, the DefaultRemotePowerShellConfiguration class is used for the session configuration.

        Required?                    true
        Position?                    3
        Default value                System.Management.Automation.Remoting.PSSessionConfiguration
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Force [<SwitchParameter>]
        Suppresses all users 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>
        Limits 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>
        Limits 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 a name for the session configuration. This parameter is required.

        Required?                    true
        Position?                    1
        Default value                None
        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 Register-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                False
        Accept pipeline input?     false
        Accept wildcard characters? false

    -ProcessorArchitecture <string>
        Specifies a processor architecture for the configuration. This value determines whether a 32-bit or 64-bit version of the process that hosts Windows PowerShell is started when the configuration is used. Valid values are x86, AMD64, and IA64.

        The default is determined by the processor architecture of the computer that hosts the session configuration.

        Required?                    false
        Position?                    named
        Default value                The processor architecture of the host computer.
        Accept pipeline input?     false
        Accept wildcard characters? false

    -SecurityDescriptorSddl <string>
        Specifies a 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.

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

        If you omit this parameter, the root SDDL for the WinRM service is used for this configuration. To view or change the root SDDL, use the WS-Management provider. For example “Get-Item WSMan:\localhost\service\rootSDDL”. For more information about the WS-Management provider, type “Get-Help WSMan“.

        Required?                    false
        Position?                    named
        Default value                The value of the root SDDL
        Accept pipeline input?     false
        Accept wildcard characters? false

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

        When setting the permissions for 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>
        Specifies the fully qualified path to a Windows PowerShell script. The specified script runs in the new session that uses the session configuration.

        You can use the script to further configure the 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>
        Determines the apartment state of the threads in the session. Valid values are STA, MTA, and Unknown. Unknown is the default.

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

    -ThreadOptions <PSThreadOptions>
        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                UseCurrentThread
        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.WSManConfigContainerElement

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.

        This cmdlet generates XML that represents a Web Services for Management (WS-Management) plug-in configuration and sends the XML to WS-Management, which registers the plug-in on the local computer (“New-Item WSMan:\localhost\plugin”).

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

    C:\PS>Register-PSSessionConfiguration -Name NewShell -ApplicationBase c:\MyShells\ -assemblyName MyShell.dll -configurationTypeName MyClass

    Description
    ———–
    This command registers the NewShell session configuration. It uses the ApplicationName and ApplicationBase parameters to specify the location of the MyShell.dll file, which specifies the cmdlets and providers in the session configuration. It also uses the ConfigurationTypeName parameter to specify a new class that further configures the session.

    To use this configuration, users would type “New-PSSession -configurationname newshell”.

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

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

    Description
    ———–
    This command registers the MaintenanceShell configuration on the local computer. The command uses the StartupScript parameter to specify the Maintenance.ps1 script.

    When a user uses a New-PSSession command and selects the MaintenanceShell configuration, the Maintenance.ps1 script runs in the new session. The script can configure the session, including importing modules, adding Windows PowerShell snap-ins, and setting the execution policy for the session. If the script generates any errors, including non-terminating errors, the New-PSSession command fails.

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

    C:\PS>$sddl = “O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)”

    C:\PS> Register-PSSessionConfiguration -Name AdminShell -SecurityDescriptorSddl $sddl -MaximumReceivedObjectSizeMB 20 -StartupScript c:\scripts\AdminShell.ps1

    Description
    ———–
    This example registers the AdminShell session configuration.

    The first command saves a custom SDDL in the $sddl Variable.

    The second command registers the new shell. The command uses the SecurityDescritorSDDL parameter to specify the SDDL in the value of the $sddl Variable and the MaximumReceivedObjectSizeMB parameter to increase the object size limit. It also uses the StartupScript parameter to specify a script that configures the session.

    As an alternative to using the SecurityDescriptorSDDL parameter, you can use the ShowSecurityDescriptorUI parameter, which displays a property sheet that you can use to set permissions for the session configuration. When you click “OK” in the property sheet, the tool generates an SDDL for the session configuration.

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

    C:\PS>$s = Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript c:\ps-test\Maintenance.ps1

    C:\PS> $s

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

    Name                     Type                 Keys
    —-                     —-                 —-
    MaintenanceShell         Container            {Name=MaintenanceShell}

    C:\PS> $s.getType().fullname
    TypeName: Microsoft.WSMan.Management.WSManConfigContainerElement

    C:\PS> $s | Format-List -property *

    PSPath            : Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell
    PSParentPath     : Microsoft.WSMan.Management\WSMan::localhost\Plugin
    PSChildName     : MaintenanceShell
    PSDrive         : WSMan
    PSProvider        : Microsoft.WSMan.Management\WSMan
    PSIsContainer     : True
    Keys             : {Name=MaintenanceShell}
    Name             : MaintenanceShell
    TypeNameOfElement : Container

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

    Name                     Type                 Keys
    —-                     —-                 —-
    MaintenanceShell         Container            {Name=MaintenanceShell}
    microsoft.powershell     Container            {Name=microsoft.powershell}
    microsoft.powershell32    Container            {Name=microsoft.powershell32}

    Description
    ———–
    This example shows that a Register-PSSessionConfiguration command returns a WSManConfigContainerElement. It also shows how to find the container elements in the WSMan: drive.

    The first command uses the Register-PSSessionConfiguration cmdlet to register the MaintenanceShell configuration. It saves the object that the cmdlet returns in the $s Variable.

    The second command displays the contents of the $s Variable.

    The third command uses the GetType method and its FullName property to display the type name of the object that Register-PSSessionConfiguration returns.

    The fourth command uses the Format-List cmdlet to display all the properties of the object that Register-PSSessionConfiguration returns in a list. The PSPath property shows that the object is stored in a directory of the WSMan: drive.

    The fifth command uses the Get-ChildItem cmdlet to display the items in the WSMan:\LocalHost\PlugIn path. These include the new MaintenanceShell configuration and the two default configurations that come with Windows PowerShell.

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

    C:\PS>Register-PSSessionConfiguration -Name WithProfile -StartupScript add-profile.ps1

    # Add-Profile.ps1

    . c:\users\admin01\documents\windowspowershell\profile.ps1

    Description
    ———–
    This command creates and registers the WithProfile session configuration on the local computer. The command uses the StartupScript parameter to direct Windows PowerShell to run the specified script in any session that uses the session configuration.

    The content of the specified script, Add-Profile.ps1, is also displayed. The script contains a single command that uses dot sourcing to run the user’s CurrentUserAllHosts profile in the current scope of the session.

    For more information about profiles, see about_profiles. For more information about dot sourcing, see about_scopes.

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

cmdlet, ObjectEvent, Register

Register-ObjectEvent

NAME
    Register-ObjectEvent

SYNOPSIS
    Subscribes to the events that are generated by a Microsoft .NET Framework object.

SYNTAX
    Register-ObjectEvent [-InputObject] <psobject> [-EventName] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]

DESCRIPTION
    The Register-ObjectEvent cmdlet subscribes to events that are generated by .NET Framework objects on the local computer or on a remote computer.

    When the subscribed event is raised, it is added to the event queue in your session. To get events in the event queue, use the Get-Event cmdlet.

    You can use the parameters of Register-ObjectEvent to specify property values of the events that can help you to identify the event in the queue. You can also use the Action parameter to specify actions to take when a subscribed event is raised and the Forward parameter to send remote events to the event queue in the local session.

    When you subscribe to an event, an event subcriber is added to your session. To get the event subscribers in the session, use the Get-EventSubscriber cmdlet. To cancel the subscription, use the Unregister-Event cmdlet, which deletes the event subscriber from the session.

PARAMETERS
    -Action <scriptblock>
        Specifies commands to handle the events. The commands in the Action run when an event is raised, instead of sending the event to the event queue. Enclose the commands in braces ( { } ) to create a script block.

        The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $SourceEventArgs, and $SourceArgs automatic Variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables.

        When you specify an action, Register-ObjectEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.

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

    -EventName <string>
        Specifies the event to which you are subscribing. Enter the event name. This parameter is required.

        The value of this parameter is not a name that you select for the event subscription. It is the name of an event that the .NET Framework object exposes. For example, the ManagementEventWatcher class has events named “EventArrived” and “Stopped.” To find the event name of an event, use the Get-Member cmdlet.

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

    -Forward [<SwitchParameter>]
        Sends events for this subscription to a remote session. Use this parameter when you are registering for events on a remote computer or in a remote session.

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

    -InputObject <psobject>
        Specifies the .NET Framework object that generates the events. Enter a Variable that contains the object, or type a command or expression that gets the object. This parameter is required.

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

    -MessageData <psobject>
        Specifies any additional data to be associated with this event subscription. The value of this parameter appears in the MessageData property of all events associated with this subscription.

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

    -SourceIdentifier <string>
        Specifies a name that you select for the subscription. The name that you select must be unique in the current session. The default value is the GUID that Windows PowerShell assigns.

        The value of this parameter appears in the value of the SourceIdentifier property of the subcriber object and of all event objects associated with this subscription.

        Required?                    false
        Position?                    101
        Default value                GUID
        Accept pipeline input?     false
        Accept wildcard characters? false

    -SupportEvent [<SwitchParameter>]
        Hides the event subscription. Use this parameter when the current subscription is part of a more complex event registration mechanism and it should not be discovered independently.

        To view or cancel a subscription that was created with the SupportEvent parameter, use the Force parameter of the Get-EventSubscriber and Unregister-Event cmdlets.

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

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

INPUTS
    None
        You cannot pipe objects to Register-ObjectEvent.

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

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

    C:\PS>$query = New-Object System.Management.WqlEventQuery “__InstanceCreationEvent”, (New-Object TimeSpan 0,0,1), “TargetInstance isa ‘Win32_Process'”

    C:\PS> $processWatcher = New-Object System.Management.ManagementEventWatcher $query

    C:\PS> Register-ObjectEvent -InputObject $processWatcher -EventName “EventArrived”

    Description
    ———–
    This example subscribes to events generated when a new process starts.

    The command uses the ManagementEventWatcher object to get EventArrived events. A query object specifies that the events are instance creation events for the Win32_Process class.

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

    C:\PS>$query = New-Object System.Management.WqlEventQuery “__InstanceCreationEvent”, (New-Object TimeSpan 0,0,1), “TargetInstance isa ‘Win32_Process'”

    C:\PS> $processWatcher = New-Object System.Management.ManagementEventWatcher $query

    C:\PS> $action = { New-Event “PowerShell.ProcessCreated” -Sender $sender -EventArguments $SourceEventArgs.NewEvent.TargetInstance }

    C:\PS> Register-ObjectEvent -InputObject $processWatcher -EventName “EventArrived” -Action $action

    Id    Name            State     HasMoreData     Location             Command
    —    —-            —–     ———–     ——–             ——-
    2     422cfe5a-65e… Running    True                                 New-Event “PowerShe…

    Description
    ———–
    This example shows how to specify an action to respond to an event. When you specify an action, events that are raised are not added to the event queue. Instead, the action responds to the event.

    In this example, when an instance creation event is raised indicating that a new process is started, a new ProcessCreated event is raised.

    The action uses the $Sender and $SourceEventArgs automatic Variables which are populated only for event actions.

    The Register-ObjectEvent command returns a job object that represents the action, which runs as a background job. You can use the Job cmdlets, such as Get-Job and Receive-Job, to manage the background job.

    For more information, see about_jobs.

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

    C:\PS>$s = New-PSSession -computername Server01, Server02

    C:\PS> Invoke-Command -session $s -filepath ProcessCreationEvent.ps1

    C:\PS> Invoke-Command -session $s { Get-Event }

    # ProcessCreationEvent.ps1

    Function Enable-ProcessCreationEvent
    {
     $query = New-Object System.Management.WqlEventQuery “__InstanceCreationEvent”, `
         (New-Object TimeSpan 0,0,1), `
         “TargetInstance isa ‘Win32_Process'”
     $processWatcher = New-Object System.Management.ManagementEventWatcher $query

     $identifier = “WMI.ProcessCreated”
     Register-ObjectEvent -input $processWatcher -EventName “EventArrived” `
         -SourceIdentifier $identifier -MessageData “Test” -Forward
     }
    }

    EnableProcessCreationEvent

    Description
    ———–
    This example shows how to subscribe to object events on remote computers.

    The first command creates PSSessions on two remote computers and saves them in the $s Variable.

    The second command uses the FilePath parameter of the Invoke-Command cmdlet to run the ProcessCreationEvent.ps1 script in the each of the PSSessions in $s.

    The script includes a Register-ObjectEvent command that subscribes to instance creation events on the Win32_Process object through the ManagementEventWatcher object and its EventArrived event.

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

    C:\PS>$timer = New-Object Timers.Timer

    C:\PS> $timer.Interval = 500

    C:\PS> $job = Register-ObjectEvent -InputObject $timer -EventName Elapsed -SourceIdentifier Timer.Random -Action {$random = Get-Random -Min 0 -Max 100}

    C:\PS> $job.gettype().fullname
    System.Management.Automation.PSEventJob

    C:\PS> $job | Format-List -property *

    State         : Running
    Module        : __DynamicModule_6b5cbe82-d634-41d1-ae5e-ad7fe8d57fe0
    StatusMessage :
    HasMoreData : True
    Location     :
    Command     : $random = Get-Random -Min 0 -Max 100
    JobStateInfo : Running
    Finished     : System.Threading.ManualResetEvent
    InstanceId    : 88944290-133d-4b44-8752-f901bd8012e2
    Id            : 1
    Name         : Timer.Random
    ChildJobs     : {}
    …

    C:\PS> $timer.Enabled = $true

    C:\PS> & $job.module {$random}
    60

    C:\PS> & $job.module {$random}
    47

    Description
    ———–
    This example shows how to use the dynamic module in the PSEventJob object that is created when you include an Action in a event registration.

    The first command uses the New-Object cmdlet to create a timer object. The second command sets the interval of the timer to 500 (milliseconds).

    The third command uses the Register-ObjectEvent cmdlet to register the Elapsed event of the timer object. The command includes an action that handles the event. Whenever the timer interval elapses, an event is raised and the commands in the action run. In this case, the Get-Random cmdlet generates a random number between 0 and 100 and saves it in the $random Variable.

    When you use an Action parameter in a Register-ObjectEvent command, the command returns a PSEventJob object that represents the action. The command saves the job object in the $job Variable.

    The PSEventJob object that the Register-ObjectEvent cmdlet returns is also available in the Action property of the event subscriber. For more information, see Get-EventSubscriber.

    The fourth command shows that the $job Variable contains a PSEventJob object. The fifth command uses the Format-List cmdlet to display all of the properties of the PSEventJob object in a list.

    The PSEventJob has a Module property that contains a dynamic script module that implements the action.

    The sixth command enables the timer.

    The remaining commands use the call operator (&) to invoke the command in the module and display the value of the $random Variable. You can use the call operator to invoke any command in a module, including commands that are not exported. In this case, the commands show the random number that is being generated when the Elapsed event occurs.

    For more information about modules, see about_modules.

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

cmdlet, EngineEvent, Register

Register-EngineEvent

NAME
    Register-EngineEvent

SYNOPSIS
    Subscribes to events that are generated by the Windows PowerShell engine and by the New-Event cmdlet.

SYNTAX
    Register-EngineEvent [-SourceIdentifier] <string> [[-Action] <scriptblock>] [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]

DESCRIPTION
    The Register-EngineEvent cmdlet subscribes to events that are generated by the Windows PowerShell engine and the New-Event cmdlet. Use the SourceIdentifier parameter to specify the event.

    You can use this cmdlet to subscribe to the “Exiting” engine event and events generated by the New-Event cmdlet. These events are automatically added to your event queue in your session without subscribing. However, subscribing lets you forward the events, specify an action to respond to the events, and cancel the subscription.

    When the subscribed event is raised, it is added to the event queue in your session. To get events in the event queue, use the Get-Event cmdlet.

    When you subscribe to a event, an event subcriber is added to your session. To get the event subscribers in the session, use the Get-EventSubscriber cmdlet. To cancel the subscription, use the Unregister-Event cmdlet, which deletes the event subscriber from the session.

PARAMETERS
    -Action <scriptblock>
        Specifies commands to handle the events. The commands in the Action run when an event is raised, instead of sending the event to the event queue. Enclose the commands in braces ( { } ) to create a script block.

        The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $SourceEventArgs, and $SourceArgs automatic Variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables.

        When you specify an action, Register-EngineEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.

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

    -Forward [<SwitchParameter>]
        Sends events for this subscription to the session on the local computer. Use this parameter when you are registering for events on a remote computer or in a remote session.

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

    -MessageData <psobject>
        Specifies additional data associated with the event. The value of this parameter appears in the MessageData property of the event object.

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

    -SourceIdentifier <string>
        Specifies the source identifier of the event to which you are subscribing. The source identifier must be unique in the current session. This parameter is required.

        The value of this parameter appears in the value of the SourceIdentifier property of the subscriber object and of all event objects associated with this subscription.

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

    -SupportEvent [<SwitchParameter>]
        Hides the event subscription. Use this parameter when the current subscription is part of a more complex event registration mechanism and it should not be discovered independently.

        To view or cancel a subscription that was created with the SupportEvent parameter, use the Force parameter of the Get-EventSubscriber and Unregister-Event cmdlets.

        Required?                    false
        Position?                    named
        Default value                False
        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 Register-EngineEvent.

OUTPUTS
    None or System.Management.Automation.PSEventJob
        If you use the Action parameter, Register-EngineEvent returns a System.Management.Automation.PSEventJob object. Otherwise, it does not generate 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.

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

    C:\PS>$s = New-PSSession -computername Server01, Server02

    C:\PS> Invoke-Command -session $s { Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward }

    Description
    ———–
    This command registers for a Windows PowerShell engine event on two remote computers.

    The first command creates a PSSession on each of the remote computers.

    The second command uses the Invoke-Command cmdlet to run the Register-EngineEvent command in the remote sessions.

    The Register-EngineEvent command uses the SourceIdentifier parameter to identify the event. It uses the Forward parameter to forward the events from the remote session to the local session.

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

    C:\PS>$j = Register-EngineEvent -SourceIdentifier PowerShell.ProcessCreated -Action { $processName | Add-Content processLog.txt }

    C:\PS> Get-Event

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

    C:\PS> Unregister-Event PowerShell.ProcessCreated

    Description
    ———–
    This command shows how to use the Job cmdlets to manage the event job object that Register-EngineEvent returns when you use the Action parameter.

    An event job is managed just like any other Windows PowerShell job. For more information, see about_jobs. In this example, the Receive-Job cmdlet is used to get the results of the job.

    To delete the job from the session, use Remove-Job. To cancel your event subscription, use the Unregister-Event cmdlet. To delete the events in the event queue, use Remove-Event.

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

cmdlet, Job, Receive

Receive-Job

NAME
    Receive-Job

SYNOPSIS
    Gets the results of the Windows PowerShell background jobs in the current session.

SYNTAX
    Receive-Job [-Job] <Job[]> [[-ComputerName] <string[]>] [-Keep] [-NoRecurse] [<CommonParameters>]

    Receive-Job [[-InstanceId] <Guid[]>] [-Keep] [-NoRecurse] [<CommonParameters>]

    Receive-Job [-Job] <Job[]> [[-Location] <string[]>] [-Keep] [-NoRecurse] [<CommonParameters>]

    Receive-Job [[-Name] <string[]>] [-Keep] [-NoRecurse] [<CommonParameters>]

    Receive-Job [-Job] <Job[]> [[-Session] <PSSession[]>] [-Keep] [-NoRecurse] [<CommonParameters>]

    Receive-Job [-Id] <Int32[]> [-Keep] [-NoRecurse] [<CommonParameters>]

DESCRIPTION
    The Receive-Job cmdlet gets the results of Windows Powershell background jobs. Use Receive-Job to get the results of jobs started by using the Start-Job cmdlet or the AsJob parameter of any cmdlet. You can get the results of all jobs or identify jobs by their name, ID, instance ID, computer name, location, or session, or by submitting a job object.

    When you start a Windows PowerShell background job, the job starts, but the results do not appear immediately. Instead, the command returns an object that represents the background job. The job object contains useful information about the job, but it does not contain the results. This method allows you to continue working in the session while the job runs. For more information about background jobs in Windows PowerShell, see about_jobs.

    To get the results of the command, use the Receive-Job cmdlet. Receive-Job gets the results that have been generated by the time that the Receive-Job command is submitted. If the results are not yet complete, you can run additional Receive-Job commands to get the remaining results.

    By default, job results are deleted from the system when you receive them, but you can use the Keep parameter to save the results so that you can receive them again. To delete the job results, receive them again (without the Keep parameter), close the session, or use the Remove-Job cmdlet to delete the job from the session.

PARAMETERS
    -ComputerName <string[]>
        Gets the results of jobs that were run on the specified computers. Enter the computer names. The default is all jobs in the current session.

        This parameter selects from among the job results that are stored on the local computer. It does not get data from remote computers. To get job results that are stored on remote computers, use the Invoke-Command cmdlet to run a Receive-Job command remotely.

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

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

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

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

    -InstanceId <Guid[]>
        Gets the results of jobs with the specified instance IDs. The default is all jobs in the current session.

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

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

    -Job <Job[]>
        Specifies the job for which results are being retrieved. This parameter is required in a Receive-Job command. Enter a Variable that contains the job or a command that gets the job. You can also pipe a job object to Receive-Job.

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

    -Keep [<SwitchParameter>]
        Saves the job results in the system, even after you have received them. By default, the job results are deleted when they are retrieved.

        To delete the results, use Receive-Job to receive them again without the Keep parameter, close the session, or use the Remove-Job cmdlet to delete the job from the session.

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

    -Location <string[]>
        Gets only the results of jobs with the specified location. The default is all jobs in the current session.

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

    -Name <string[]>
        Gets the results of jobs with the specified friendly name. The default is all jobs in the current session.

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

    -NoRecurse [<SwitchParameter>]
        Gets results only from the specified job. By default, Receive-Job also gets the results of all child jobs of the specified job.

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

    -Session <PSSession[]>
        Gets the results of jobs that were run in the specified Windows Powershell session (PSSession). Enter a Variable that contains the PSSession or a command that gets the PSSession, such as a Get-PSSession command. The default is all jobs in the current session.

        Required?                    false
        Position?                    2
        Default value
        Accept pipeline input?     true (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.Management.Automation.Job
        You can pipe job objects to Receive-Job.

OUTPUTS
    PSObject
        Receive-Job returns the results of the commands in the job.

NOTES

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

    C:\PS>$job = Start-Job -scriptblock {Get-Process}

    C:\PS> Receive-Job -Job $job

    Description
    ———–
    These commands use the Job parameter to get the results of a particular job. The first command uses the Start-Job cmdlet to start a job that runs a “Get-Process” command. The command uses the assignment operator (=) to save the resulting job object in the $job Variable.

    The second command uses the Receive-Job cmdlet to get the results of the job. It uses the Job parameter to specify the job.

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

    C:\PS>$job = Start-Job -scriptblock {Get-Process}

    C:\PS> $job | Receive-Job

    Description
    ———–
    This example is the same as Example 2, except that the command uses a pipeline operator (|) to send the job object to Receive-Job. As a result, the command does not need a Job parameter to specify the job.

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

    C:\PS>$j = Invoke-Command -computername Server01, Server02, Server03 -scriptblock {Get-Service} -AsJob

    C:\PS> $j.childjobs

    Id Name     State     HasMoreData Location     Command
    — —-     —–     ———– ——–     ——-
    2    Job2     Completed True         Server01     Get-Service
    3    Job3     Completed True         Server02     Get-Service
    4    Job4     Completed True         Server03     Get-Service

    C:\PS> Receive-Job -name Job3 -Keep

    Status Name        DisplayName                        PSComputerName
    —— ———– ———–                        ————–
    Running AeLookupSvc Application Experience             Server02
    Stopped ALG         Application Layer Gateway Service Server02
    Running Appinfo     Application Information            Server02
    Running AppMgmt     Application Management             Server02

    Description
    ———–
    These commands use the Name parameter of Receive-Job to get the results of one of several background jobs run on remote computers.

    The first command uses the Invoke-Command cmdlet to start a background job that runs a Get-Service command on three remote computers. The command uses the AsJob parameter to run the command as a background job. The command saves the resulting job object in the $j Variable.

    When you use the AsJob parameter of Invoke-Command to start a job, the job object is created on the local computer, even though the job runs on the remote computers. As a result, you use local commands to manage the job.

    Also, when you use AsJob, Windows PowerShell returns one job object that contains a child job for each job that was started. In this case, the job object contains three child jobs, one for each job on each remote computer.

    The second command uses the dot method to display the value of the ChildJobs property of the job object in $j. The display shows that the command created three child jobs, one for the job on each remote computer.

    The third command uses the Receive-Job cmdlet to get the results of the Job3 child job that ran on the Server02 computer. It uses the Name parameter to specify the name of the child job and the Keep parameter to save the job results even after they are received.

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

    C:\PS>$s = New-PSSession -computername Server01, Server02, Server03

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

    C:\PS> $j

    Id Name     State     HasMoreData Location Command
    — —-     —–     ———– ——– ——-
    1    Job1     Completed True         Localhost Get-Eventlog system
    2    Job2     Completed True         Localhost Get-Eventlog system
    3    Job3     Completed True         Localhost Get-Eventlog system

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

    Description
    ———–
    This example shows how to get the results of background jobs run on three remote computers.

    The first command uses the New-PSSession cmdlet to create three PSSessions, one on each of the servers specified in the command. It saves the PSSessions in the $s Variable.

    The second command uses the Invoke-Command cmdlet to run a Start-Job command in each of the PSSessions in the $s Variable. The job runs a Get-Eventlog command that gets the events in the System log. The command saves the results in the $j Variable.

    Because the command used Invoke-Command to run the Start-Job command, the command actually started three independent jobs on each of the three computers. As a result, the command returned three job objects representing three jobs run locally on three different computers.

    The third command displays the three job objects in $j.

    The fourth command uses Invoke-Command to run a Receive-Job command in each of the PSSessions in $s and save the results in the $results Variable.

    Because $j is a local Variable, the script block uses the “param” keyword to declare the Variables in the command and the ArgumentList parameter to supply the value of $j.

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

cmdlet, Host, Read

Read-Host

NAME
    Read-Host

SYNOPSIS
    Reads a line of input from the console.

SYNTAX
    Read-Host [[-Prompt] <Object>] [-AsSecureString] [<CommonParameters>]

DESCRIPTION
    The Read-Host cmdlet reads a line of input from the console. You can use it to prompt a user for input. Because you can save the input as a secure string, you can use this cmdlet to prompt users for secure data, such as passwords, as well as shared data.

PARAMETERS
    -AsSecureString [<SwitchParameter>]
        Displays asterisks (*) in place of the characters that the user types as input.

        When you use this parameter, the output of the Read-Host cmdlet is a SecureString object (System.Security.SecureString).

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

    -Prompt <Object>
        Specifies the text of the prompt. Type a string. If the string includes spaces, enclose it in quotation marks. For example, “Type an integer: “.

        Required?                    false
        Position?                    1
        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
    System.String or System.Security.SecureString
        If the AsSecureString parameter is used, Read-Host returns a SecureString. Otherwise, it returns a string.

NOTES

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

    C:\PS>$age = Read-Host “Please enter your age:”

    Description
    ———–
    This command displays the string “Please enter your age:” as a prompt. When a value is entered and the Enter key is pressed, the value is stored in the $age Variable.

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

    C:\PS>$pwd_secure_string = Read-Host “Enter a Password:” -AsSecureString

    Description
    ———–
    This command displays the string “Enter a Password:” as a prompt. As a value is being entered, asterisks (*) appear on the console in place of the input. When the Enter key is pressed, the value is stored as a SecureString object in the $pwd_secure_string Variable.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113371
    Get-Host
    Out-Host
    Write-Host
    ConvertFrom-SecureString