Currently I am building the prototype of a PowerShell-based automation solution. From the high level perspective it will work like a Print Spooler meaning that some kind of watchdog listens in the background to a particular directory for incoming files in order to process them or rather pass them to a processing engine.

With PowerShell 2.0 it is an easy task to leverage the .NET Framework’s FileSystemWatcher Class to establish such a file system watchdog:

PS C:\Scripts> $fsw = New-Object System.IO.FileSystemWatcher
PS C:\Scripts> $fsw

NotifyFilter          : FileName, DirectoryName, LastWrite
EnableRaisingEvents   : False
Filter                : *.*
IncludeSubdirectories : False
InternalBufferSize    : 8192
Path                  :
Site                  :
SynchronizingObject   :
Container             :

PS C:\Scripts>

Obviously, a freshly initialized instance of System.IO.FileSystemWatcher is very roughly prepared to watch for file system changes. Five properties are preset, namely NotifyFilter (specifies the changes to watch for in a file system object), EnableRaisingEvents (indicates whether events are raised or not – yes, we want!), Filter (specifies what files are monitored), IncludeSubdirectories (indicates whether subdirectories are monitored or not), and InternalBufferSize. (Please look in the MSDN for more info on the FileSystemWatcher class.)

So, how about a PowerShell function to initialize a .NET FileSystemWatcher object with proper values for Patch, Filter, NotifyFilter, IncludeSubdirectories, and EnableRaisingEvents? Here we go!

function New-FSWatcher
{
    <#
    .SYNOPSIS
        Initializes a .NET file system watcher

    .DESCRIPTION
        Initializes a .NET file system watcher, given the specified directory and optionally the type of files to monitor.

    .PARAMETER Path
        Specifies the path of an existing directory to watch.

    .PARAMETER Filter
        Determines what files are monitored in Path. (Defaults to *.*)

    .PARAMETER NotifyFilter
        Specifies the types of changes to watch for. Valid types are FileName (default), DirectoryName (default), Attributes, Size, LastWrite (default), LastAccess (default), CreationTime, and Security.

    .PARAMETER Recurse
        Indicates whether subdirectories within the Path should be monitored.

    .OUTPUTS
        Returns a .NET FileSystemWatcher object

    .EXAMPLE
        PS C:\> $fsw = New-FSWatcher -Path 'C:\Temp'

        This command initializes a file system watcher for *.* in C:\Temp.

    .EXAMPLE
        PS C:\> $fswxml = New-FSWatcher C:\Temp *.xml -Recurse

        This command initializes a file system watcher for *.xml in C:\Temp including its subdirectories.

    .LINK
        Start-FSWatcher
        Register-FSWatcherEventHandler
    #>

    [CmdletBinding(SupportsShouldProcess=$true)]
    param (
        [Parameter(Mandatory=$true, Position=0)]
        [ValidateNotNullOrEmpty()]
        [String]
        $Path
        ,
        [Parameter(Mandatory=$false, Position=1)]
        [String]
        $Filter = '*.*'
        ,
        [Parameter(Mandatory=$false)]
        [System.IO.NotifyFilters]
        $NotifyFilter = ('FileName','LastWrite','LastAccess')
        ,
        [Switch]
        $Recurse
    )

    if ($PSCmdlet.ShouldProcess("$Path\$Filter", "Initialize FileSystemWatcher"))
    {
        $FileSystemWatcher = New-Object System.IO.FileSystemWatcher
        $FileSystemWatcher.Path = $Path
        $FileSystemWatcher.Filter = $Filter
        $FileSystemWatcher.NotifyFilter = $NotifyFilter
        if ($Recurse)
        {
            $FileSystemWatcher.IncludeSubdirectories = $true
        }
        $FileSystemWatcher.EnableRaisingEvents = $true
        $FileSystemWatcher
    }
}

That’s only half the battle. With New-FSWatcher you are able to initialize a FileSystemWatcher. But how to start monitoring?

If you look at the methods of System.IO.FileSystemWatcher you will sooner or later discover WaitForChanged(), "a synchronous method that returns a structure that contains specific information on the change that occurred, given the type of change you want to monitor and the time (in milliseconds) to wait before timing out".

So, with WaitForChanged() it is perfectly possible to stop script processing for a given amount of maximum time in order to wait for a file. Apart from the fact that I have a watchdog in mind that should wait for file system events in the background, I will provide a function to leverage a synchronous (foreground) wait for files anyways:

function Start-FSWatcher
{
    <#
    .SYNOPSIS
        Listens the file system changes for a given amount of time.

    .DESCRIPTION
        Uses a previously configured FileSystemWatcher to listen for changes in a directory using a synchronous method that returns specific information on each change that occurred, given the type of change you want to monitor and the time to wait before timing out.

    .PARAMETER FileSystemWatcher
        Specifies a FileSystemWatcher object.

    .PARAMETER Type
        Specifies the type of change you want to monitor. Valid type are All (default), Changed, Created, Deleted, Disposed, Error, and Renamed.

    .PARAMETER TimeOut
        Specifies the timeout in ms. (Defaults to 10000)

    .PARAMETER Infinite
        Specifies to watch infinitely. (Not recommended. Consider registering events instead.)

    .OUTPUTS
        A structure containing specific information on each change that occurred.

    .NOTES
        Hidden files are NOT ignored.

    .EXAMPLE
        PS C:\> $fsw = New-FSWatcher -Path 'C:\Temp' -Filter 'jobfinished.txt'
        PS C:\> Start-FSWatcher -FSW $fsw

        These two commands initialize and use a FileSystemWather for C:\Temp. The watcher listens 10 seconds (default) for any changes in the directory.

    .EXAMPLE
        PS C:\> New-FSWatcher C:\Temp *.xml | Start-FSWatcher -Infinite

        This pipeline shows how to start an infinite FileSystemWatcher for any change on any XML file in C:\Temp.

    .LINK
        New-FSWatcher
        Register-FSWatcherEventHandler
    #>

    [CmdletBinding(SupportsShouldProcess=$true)]
    param (
        [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)]
        [Alias("FSW")]
        [ValidateNotNullOrEmpty()]
        [System.IO.FileSystemWatcher]
        $FileSystemWatcher
        ,
        [Parameter(Mandatory=$false)]
        [ValidateSet('All','Changed', 'Created', 'Deleted', 'Disposed', 'Error', 'Renamed')]
        [String]
        $Type = 'All'
        ,
        [Parameter(Mandatory=$false)]
        [Int]
        $TimeOut = 10000
        ,
        [Switch]
        $Infinite
    )

    if ($PSCmdlet.ShouldProcess("$($FileSystemWatcher.Path)", "WaitForChanged($Type, $TimeOut)"))
    {
        do
        {
            $FileSystemChange = $FileSystemWatcher.WaitforChanged($Type, $TimeOut)
            if (!$FileSystemChange.TimedOut)
            {
                $FileSystemChange
            }
        }
        while ($Infinite)
    }
}

Please note that Start-FSWatcher will stop monitoring the file system as soon as the first change occurs that matches the FileSystemWatcher object’s configuration (unless the Infinite switch has been specified which causes the function to invoke the WaitForChanges() method again and again till the end of time). If you want to wait for a particular file you can define a FileSystemWatcher object and setup its Filter property to match the exact file name. Therefore, concerning a specific file name to be monitored, there’s no need to change the function.

To return to square one finally: how to define the file system watcher event handlers that will be fired on change, creation, deletion, or renaming of a file or directory? This is really straightforward. Basically you need to use the Register-ObjectEvent Cmdlet with a previously initialized FileSystemWatcher object, the event to act on, and the action to be executed on that event. Although it seems to be overkill, I’ll provide a third function, Register-FSWatcherEventHandler, that helps to define a proper event action for a file system watcher:

function Register-FSWatcherEventHandler
{
    <#
    .SYNOPSIS
        Registers a FileSystemWatcher event handler.

    .DESCRIPTION
        Specifies what is done when a file is changed, created, deleted, or renamed.

    .PARAMETER FileSystemWatcher
        Specifies a FileSystemWatcher object

    .PARAMETER EventName
        Specifies the type of event. Valid events are Changed, Created, Deleted, Disposed, Error, and Renamed.

    .PARAMETER EventAction
        Specifies what is done.

    .EXAMPLE
        PS C:\Scripts> $fsw = New-FSWatcher -Path 'C:\Temp'
        PS C:\Scripts> Register-FSWatcherEventHandler $fsw 'Created' -Action {
        >> Remove-Item $($eventArgs.FullPath) -Confirm
        }

        These two commands initialize a FileSystemWather for C:\Temp and registers an event handler which will offer to delete any created file.

    .LINK
        New-FSWatcher
        Start-FSWatcher
    #>

    [CmdletBinding(SupportsShouldProcess=$true)]
    param (
        [Parameter(Mandatory=$true, Position=0)]
        [Alias("FSW")]
        [ValidateNotNullOrEmpty()]
        [System.IO.FileSystemWatcher]
        $FileSystemWatcher
        ,
        [Parameter(Mandatory=$true, Position=1)]
        [ValidateSet('Changed', 'Created', 'Deleted', 'Disposed', 'Error', 'Renamed')]
        [String]
        $EventName
        ,
        [Parameter(Mandatory=$true, Position=2)]
        [Alias('Action')]
        [Scriptblock]
        $EventAction
    )

    if ($PSCmdlet.ShouldProcess("$($FileSystemWatcher.Path)", "Register Event Handler (for File $EventName)"))
    {
        Register-ObjectEvent -InputObject $FileSystemWatcher -EventName $EventName -Action $EventAction
    }
}

Have fun!

Pit