DSC resource for managing WMI permanent event filters, consumers, and bindings

I use WMI/CIM event functionality often in my orchestration scripts and WMI permanent events play a big role there. You can learn more about WMI permanent events by reading my book on WMI Query Language. Fellow PowerShell MVP, Trevor Sullivan, created a PowerShell module called PowerEvents that can be used to create permanent WMI filters, consumers, and bind them together. You can use that as well if DSC is not your cup of coffee.

But, being a DSC fanatic, I want to always manage my system configuration using DSC. So, I ended up creating a DSC resource module for managing WMI event filters, standard consumers, and bindings between them. This module supports all five standard WMI consumers – Script, Commandline, SMTP, Log File, and Event Log.

You can grab this module from my Github repo at https://github.com/rchaganti/DSCResources.

I have created seven DSC resources for managing WMI permanent event subscriptions.

DSC resource NameDescription
WMIEventFilterCreates an Event filter on the target system
WMIEventBindingCreates a binding between Event filter and Event consumer
WMIActiveScriptConsumerCreates an instance of script event consumer that can be used to trigger VBScript files or script fragments in response to an event
WMICommandLineConsumerCreates an instance of commandline consumer that can be used to execute a commandline application in response to an event
WMIEventLogConsumerCreates an instance of NTEventLog consumer that can be used to log event entries in the application log in response to an event
WMILogFileConsumerCreates an instance of LogFile consumer that can be used to write messages to a text-based log file in response to an event
WMISMTPConsumerCreates an instance of SMTP consumer that can be used to send emails in response to an event

While it is possible to combine all consumers into a single resource, I chose to separate them for ease of authoring as well as usage. The Event Filter and Event Binding do not provide any functionality on their own. They have to be always used along with a standard consumer. The following example shows a basic example of using one of the standard consumer DSC resource with an event filter and binding.

Configuration PermEventDemo2 {
	Import-DscResource -Module cWMIPermanentEvents
	Node Localhost {
		cWMIEventFilter ProcessEventFilter {
            Name = 'ProcessEventFilter'
            Query = "SELECT * FROM __InstanceCreationEvent WITHIN 5 WHERE TargetInstance ISA 'Win32_Process'"
            Ensure = 'Present'
		}

        cWMIEventLogConsumer ProcessEventLog {
            Name = 'ProcessEventLog'
            EventID = 10011
            Category = 0
            EventType = 'Error'
            SourceName = 'WSH'
            InsertionStringTemplates = 'New Process Created: %TargetInstance.Name%'
            Ensure = 'Present'
        }

        cWMIEventBinding ProcessEventLogBinder {
            Filter = 'ProcessEventFilter'
            Consumer = 'ProcessEventLog'
            Ensure = 'Present'
            ConsumerType = 'EventLog'
            DependsOn = '[WMIEventFilter]ProcessEventFilter','[WMIEventLogConsumer]ProcessEventLog'
        }
	}
}

PermEventDemo2

As you see, using a declarative way to specify the configuration is much easier and clearer. Go ahead and explore the module. This is still work in progress and I will add localization support and help content very soon.

I will also write detailed examples and walk-throughs for each resource in this module in the upcoming posts.

Share on: