Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wgross/fswatcher-engine-event

Publishes changes in file system as powershell engine event
https://github.com/wgross/fswatcher-engine-event

filesystemwatcher powershell

Last synced: 3 months ago
JSON representation

Publishes changes in file system as powershell engine event

Host: GitHub
URL: https://github.com/wgross/fswatcher-engine-event
Owner: wgross
License: mit
Created: 2021-03-07T20:39:02.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2024-07-31T17:25:44.000Z (3 months ago)
Last Synced: 2024-07-31T21:27:25.637Z (3 months ago)
Topics: filesystemwatcher, powershell
Language: C#
Homepage:
Size: 105 KB
Stars: 66
Watchers: 4
Forks: 11
Open Issues: 2
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# FSWatcherEngineEvent

is a Powershell module which notifies of filesystem changes using a Powershell engine events.

For a quick walkthru: https://devblogs.microsoft.com/powershell-community/a-reusable-file-system-event-watcher-for-powershell/

A new event handler can be created with the cmdlet ```New-FileSystemWatcher```:

[![CodeFactor](https://www.codefactor.io/repository/github/wgross/fswatcher-engine-event/badge/main)](https://www.codefactor.io/repository/github/wgross/fswatcher-engine-event/overview/main)

## How to Install

FSWatcherEngineEvent is published to the [Powershell Gallery](https://www.powershellgallery.com/packages/FSWatcherEngineEvent). To Install it locally use PowerShellGets ```Install-Module``` command:

```powershell
PS> Install-Module -Name FSWatcherEngineEvent
```

## Watch for Changes and Receive Events

To start watching for changes in a directory a file system watcher has to be created and an event handler to process the events. Event source and event receiver are associated by the user defined source identifier.

```powershell
PS> New-FileSystemWatcher -SourceIdentifier "myevent" -Path c:\temp\files
```

The parameter 'SourceIdentifier' is the unique name of the powershell engine event generated by the file system watcher. The other parameters of the cmdlet correspond to the properties of the .Net [FileSystemWatcher](https://docs.microsoft.com/en-us/dotnet/api/system.io.filesystemwatcher) class.

If you wish to watch subdirectories, you can add `-IncludeSubdirectories` as a switch.

```powershell
PS> New-FileSystemWatcher -SourceIdentifier "myevent" -Path c:\temp\files -IncludeSubdirectories
```

Since Version 1.4 the option `-EditOptions` presents a small text UI in the terminal where the notification parameters (Filter, notification flags, include/exclude sub dirs) can be set interactively.

To receive the event an event handler must be registered for the source identifier. Powershell will write the subscription to the pipe.

```powershell
PS> Register-EngineEvent -SourceIdentifier "myevent" -Action { $event | ConvertTo-Json | Write-Host }

Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
1 myevent NotStarted False $event|ConvertTo-Json|Wr…
```

The above action will dump the whole event to the console. You will receive something like this:

```powershell
# change a file in the watched directory
PS> "XYZ" >> C:\temp\files\xyz

{
"ComputerName": null,
"RunspaceId": "b92c271b-c147-4bd6-97e4-ffc2308a1fcc",
"EventIdentifier": 4,
"Sender": {
"NotifyFilter": 19,
"Filters": [],
"EnableRaisingEvents": true,
"Filter": "*",
"IncludeSubdirectories": false,
"InternalBufferSize": 8192,
"Path": "D:\\tmp\\files\\",
"Site": null,
"SynchronizingObject": null,
"Container": null
},
"SourceEventArgs": null,
"SourceArgs": null,
"SourceIdentifier": "myevent",
"TimeGenerated": "2021-03-13T21:39:50.4483088+01:00",
"MessageData": {
"ChangeType": 4,
"FullPath": "C:\\temp\\files\\xyz",
"Name": "xyz"
}
}
```

Since version 1.2 of the module an event handler can be specified at `New-FileSystemWatcher` instead of registering it after creation of the watcher as a separate command:

```powershell
PS> New-FileSystemWatcher -SourceIdentifier "myevent" -Path c:\temp\files -Action { $event | ConvertTo-Json | Write-Host }
```

While there can be only one file system watcher for a source identifier it is possible to register multiple event handlers for the same source identifier.
To inspect the current registrations you may use PowerShells ```Get-EventSubscriber``` command:

```powershell
PS> Get-EventSubscriber

SubscriptionId : 1
SourceObject :
EventName :
SourceIdentifier : myevent
Action : System.Management.Automation.PSEventJob
HandlerDelegate :
SupportEvent : False
ForwardEvent : False
```

You may also inspect the state of the file system watchers. It will write the current state of the watcher and its configuration to the pipe:

```powershell
PS> Get-FileSystemWatcher

SourceIdentifier : myevent
Path : C:\temp\files\
NotifyFilter : FileName, DirectoryName, LastWrite
EnableRaisingEvents : True
IncludeSubdirectories : False
Filter : *
```

## Debounce or Throttle Notifications

With version 1.5 notifications from teh file system watcher can be throttled or debounced.
Throttling aggregates all notifications within a given time interval and send a single notification contains a list of the collected notifications after the time interval has elapsed.
Debouncing means that change notifications are held back until no further event occurs for a given time span.
The now sent event contains also a list of changes that were held back.
It isn't possible to combine these two options.
The structure of the event is different from the notifications without debouncing or throttling:

```json
{
// the upper part is unchanged
..

"MessageData": [{ // <- message data is an array of events instead of a single one
"ChangeType": 4,
"FullPath": "C:\\temp\\files\\xyz",
"Name": "xyz"
},
.. // more events
]
}
```

To enable debouncing or throttling specify the method and the time interval as a parameter:

```powershell
PS> New-FileSystemWatcher -SourceIdentifier "myevent" -Path c:\temp\files -Action { $event | ConvertTo-Json | Write-Host } -DebounceMs 100

PS> New-FileSystemWatcher -SourceIdentifier "myevent" -Path c:\temp\files -Action { $event | ConvertTo-Json | Write-Host } -ThrottleMs 100
```

## Suspend and Resume Watching

The notifications can be suspended and resumed without disabling the file system watcher or removing the event handlers:

```powershell
PS> Suspend-FileSystemWatcher -SourceIdentifier "myevent"

PS> Resume-FileSystemWatcher -SourceIdentifier "myevent"
```

## Stop Watching and Clean up

If no longer needed the file system watcher can be disposed:

```powershell
PS> Remove-FileSystemWatcher -SourceIdentifier "myevent"
```

Now you may create a new file system watcher to replaced the removed one or you may also unregister the event handlers:

```powershell
PS> Get-EventSubscriber -SourceIdentifier "myevent" | Unregister-Event
```

Since version 1.2 all subscribers can be removed together with the file system watcher:$$

```powershell
PS> Remove-FileSystemWatcher -SourceIdentifier "myevent" -UnregisterAll
```

Since version 1.3 a call to `New-FileSystemWatcher` registers a script block at PowerShells `Exiting` event to clean up all file system watchers automatically.