Register-ObjectEvent is used to register interest in an event raised by a .NET object. The command creates a PSEventSubscriber object.

The Register-ObjectEvent command expects at least the name of the object that will be raising the event and the name of the event.

The following FileSystemWatcher instance watches the C:Data folder. By default, the watcher will only watch for changes at that level, the IncludeSubDirectories property might be changed if this must change. Subscribers are created for the Changed and Created events in the following example:

$watcher = [System.IO.FileSystemWatcher]::new('C:Data')
Register-ObjectEvent -InputObject $watcher -EventName Changed
Register-ObjectEvent -InputObject $watcher -EventName Created

If a file is created in the folder specified, an event will be raised. The Get-Event command can be used to view the event data:

PS> New-Item C:Data
ew.txt | Out-Null
PS> Get-Event

ComputerName     :
RunspaceId       : 46d2a562-2d07-4c58-9416-f82a3e9da5b8
EventIdentifier  : 3
Sender           : System.IO.FileSystemWatcher
SourceEventArgs  : System.IO.FileSystemEventArgs
SourceArgs       : {System.IO.FileSystemWatcher, new.txt}
SourceIdentifier : ff0784dc-1f0f-4214-b5e7-5d5516eaa13e
TimeGenerated    : 19/02/2019 17:29:53
MessageData      :

The SourceEventArgs property contains a FileSystemEventArgs object. This object includes the type of change, the path, and the filename.

The event remains until it is removed using Remove-Event. If another event is raised, it will be returned by Get-Event in addition to the existing event.

Depending on the operation performed, FileSystemWatcher may return more than one event. When using Add-Content, a single event will be raised as follows:

PS> Get-Event | Remove-Event
PS> Add-Content C:Data
ew.txt -Value value
PS> Get-Event | Select-Object -ExpandProperty SourceEventArgs

ChangeType    FullPath           Name
----------    --------           ----
   Changed    C:Data
ew.txt    new.txt

Set-Content is used when two events are raised. Set-Content makes two changes to the file, directly or indirectly. This will often be the case, depending on how an application interacts with the filesystem which is shown as follows:

PS> Get-Event | Remove-Event
PS> Set-Content C:Data
ew.txt -Value value
PS> Get-Event | Select-Object -ExpandProperty SourceEventArgs

ChangeType    FullPath           Name
----------    --------           ----
   Changed    C:Data
ew.txt    new.txt
   Changed    C:Data
ew.txt    new.txt

Whether an event will trigger once or twice depends on the type in use, the event raised, and the subsystem that caused the event to be raised in the first place.

If events are being handled in the foreground using Get-Event, Wait-Event might be used to wait until an event is raised.