{"id":13686500,"url":"https://github.com/wgross/fswatcher-engine-event","last_synced_at":"2025-07-28T19:17:43.489Z","repository":{"id":45653144,"uuid":"345448014","full_name":"wgross/fswatcher-engine-event","owner":"wgross","description":"Publishes changes in file system as powershell engine event","archived":false,"fork":false,"pushed_at":"2024-07-31T17:25:44.000Z","size":108,"stargazers_count":66,"open_issues_count":1,"forks_count":11,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-01T09:38:59.029Z","etag":null,"topics":["filesystemwatcher","powershell"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wgross.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-07T20:39:02.000Z","updated_at":"2025-03-02T10:07:16.000Z","dependencies_parsed_at":"2024-01-14T15:26:36.524Z","dependency_job_id":"1c50a265-9b27-4b3d-a9e3-cf72874d007e","html_url":"https://github.com/wgross/fswatcher-engine-event","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/wgross/fswatcher-engine-event","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wgross%2Ffswatcher-engine-event","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wgross%2Ffswatcher-engine-event/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wgross%2Ffswatcher-engine-event/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wgross%2Ffswatcher-engine-event/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wgross","download_url":"https://codeload.github.com/wgross/fswatcher-engine-event/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wgross%2Ffswatcher-engine-event/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267571218,"owners_count":24109383,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filesystemwatcher","powershell"],"created_at":"2024-08-02T15:00:33.701Z","updated_at":"2025-07-28T19:17:43.424Z","avatar_url":"https://github.com/wgross.png","language":"C#","funding_links":[],"categories":["C# #"],"sub_categories":[],"readme":"# FSWatcherEngineEvent\n\nis a Powershell module which notifies of filesystem changes using a Powershell engine events.\n\nFor a quick walkthru: https://devblogs.microsoft.com/powershell-community/a-reusable-file-system-event-watcher-for-powershell/\n\nA new event handler can be created with the cmdlet ```New-FileSystemWatcher```:\n\n[![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)\n\n## How to Install\n\nFSWatcherEngineEvent is published to the [Powershell Gallery](https://www.powershellgallery.com/packages/FSWatcherEngineEvent). To Install it locally use PowerShellGets ```Install-Module``` command:\n\n```powershell\nPS\u003e Install-Module -Name FSWatcherEngineEvent\n```\n\n## Watch for Changes and Receive Events\n\nTo 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.\n\n```powershell\nPS\u003e New-FileSystemWatcher -SourceIdentifier \"myevent\" -Path c:\\temp\\files\n```\n\nThe 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.\n\nIf you wish to watch subdirectories, you can add `-IncludeSubdirectories` as a switch.\n\n```powershell\nPS\u003e New-FileSystemWatcher -SourceIdentifier \"myevent\" -Path c:\\temp\\files -IncludeSubdirectories\n```\n\nSince 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.\n\nTo receive the event an event handler must be registered for the source identifier. Powershell will write the subscription to the pipe.\n\n```powershell\nPS\u003e Register-EngineEvent -SourceIdentifier \"myevent\" -Action { $event | ConvertTo-Json | Write-Host }\n\nId     Name            PSJobTypeName   State         HasMoreData     Location             Command\n--     ----            -------------   -----         -----------     --------             -------\n1      myevent                         NotStarted    False                                $event|ConvertTo-Json|Wr…\n```\n\nThe above action will dump the whole event to the console. You will receive something like this:\n\n```powershell\n# change a file in the watched directory\nPS\u003e \"XYZ\" \u003e\u003e C:\\temp\\files\\xyz\n\n{\n  \"ComputerName\": null,\n  \"RunspaceId\": \"b92c271b-c147-4bd6-97e4-ffc2308a1fcc\",\n  \"EventIdentifier\": 4,\n  \"Sender\": {\n    \"NotifyFilter\": 19,\n    \"Filters\": [],\n    \"EnableRaisingEvents\": true,\n    \"Filter\": \"*\",\n    \"IncludeSubdirectories\": false,\n    \"InternalBufferSize\": 8192,\n    \"Path\": \"D:\\\\tmp\\\\files\\\\\",\n    \"Site\": null,\n    \"SynchronizingObject\": null,\n    \"Container\": null\n  },\n  \"SourceEventArgs\": null,\n  \"SourceArgs\": null,\n  \"SourceIdentifier\": \"myevent\",\n  \"TimeGenerated\": \"2021-03-13T21:39:50.4483088+01:00\",\n  \"MessageData\": {\n    \"ChangeType\": 4,\n    \"FullPath\": \"C:\\\\temp\\\\files\\\\xyz\",\n    \"Name\": \"xyz\"\n  }\n}\n```\n\nSince 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:\n\n```powershell\nPS\u003e New-FileSystemWatcher -SourceIdentifier \"myevent\" -Path c:\\temp\\files -Action { $event | ConvertTo-Json | Write-Host }\n```\n\nWhile 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.\nTo inspect the current registrations you may use PowerShells ```Get-EventSubscriber``` command:\n\n```powershell\nPS\u003e Get-EventSubscriber\n\nSubscriptionId   : 1\nSourceObject     : \nEventName        : \nSourceIdentifier : myevent\nAction           : System.Management.Automation.PSEventJob\nHandlerDelegate  : \nSupportEvent     : False\nForwardEvent     : False\n```\n\nYou 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:\n\n```powershell\nPS\u003e  Get-FileSystemWatcher\n\nSourceIdentifier      : myevent\nPath                  : C:\\temp\\files\\\nNotifyFilter          : FileName, DirectoryName, LastWrite\nEnableRaisingEvents   : True\nIncludeSubdirectories : False\nFilter                : *\n```\n\n## Debounce or Throttle Notifications\n\nWith version 1.5 notifications from teh file system watcher can be throttled or debounced.\nThrottling 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.\nDebouncing means that change notifications are held back until no further event occurs for a given time span.\nThe now sent event contains also a list of changes that were held back.\nIt isn't possible to combine these two options.\nThe structure of the event is different from the notifications without debouncing or throttling:\n\n```json\n{\n  // the upper part is unchanged\n  ..\n\n  \"MessageData\": [{ // \u003c- message data is an array of events instead of a single one\n    \"ChangeType\": 4,\n    \"FullPath\": \"C:\\\\temp\\\\files\\\\xyz\",\n    \"Name\": \"xyz\"\n  },\n  .. // more events\n  ]\n}\n```\n\nTo enable debouncing or throttling specify the method and the time interval as a parameter:\n\n```powershell\nPS\u003e New-FileSystemWatcher -SourceIdentifier \"myevent\" -Path c:\\temp\\files -Action { $event | ConvertTo-Json | Write-Host } -DebounceMs 100\n\nPS\u003e New-FileSystemWatcher -SourceIdentifier \"myevent\" -Path c:\\temp\\files -Action { $event | ConvertTo-Json | Write-Host } -ThrottleMs 100\n```\n\n## Suspend and Resume Watching\n\nThe notifications can be suspended and resumed without disabling the file system watcher or removing the event handlers:\n\n```powershell\nPS\u003e Suspend-FileSystemWatcher -SourceIdentifier \"myevent\"\n\nPS\u003e Resume-FileSystemWatcher -SourceIdentifier \"myevent\"\n```\n\n## Stop Watching and Clean up\n\nIf no longer needed the file system watcher can be disposed:\n\n```powershell\nPS\u003e Remove-FileSystemWatcher -SourceIdentifier \"myevent\"\n```\n\nNow you may create a new file system watcher to replaced the removed one or you may also unregister the event handlers:\n\n```powershell\nPS\u003e Get-EventSubscriber -SourceIdentifier \"myevent\" | Unregister-Event\n```\n\nSince version 1.2 all subscribers can be removed together with the file system watcher:$$\n\n```powershell\nPS\u003e Remove-FileSystemWatcher -SourceIdentifier \"myevent\" -UnregisterAll\n```\n\nSince version 1.3 a call to `New-FileSystemWatcher` registers a script block at PowerShells `Exiting` event to clean up all file system watchers automatically.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwgross%2Ffswatcher-engine-event","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwgross%2Ffswatcher-engine-event","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwgross%2Ffswatcher-engine-event/lists"}