Register CimIndicationEvent - PowerShell

Overview

The Register-CimIndicationEvent cmdlet registers a handler for Common Information Model (CIM) indication events. CIM indication events are messages sent by managed components to indicate significant changes or events that have occurred within the system. By registering a handler, you can receive and process these events in PowerShell. This can be useful for monitoring system activity, handling errors, or triggering automated actions.

Syntax

Register-CimIndicationEvent [-ComputerName] <String> [-CimSession] <CimSession[]> [-Namespace] <String> [-IndicationFilter] <String> [-Handler] <ScriptBlock> [-SubscriptionName] <String> [-WaitForEvent] [-IgnoreDupes] [-Output] <String> [-Source] <String> [-ErrorAction] <ActionPreference> [-AbortIfError] [-ThrottleLimit] <Int32> [-ConnectionUri] <String> [-DefaultAuthentication]

Options/Flags

  • -ComputerName: Specifies the remote computer where the event should be registered. If not provided, the local computer is used.
  • -CimSession: Specifies a CIM session to use for registering the event.
  • -Namespace: Specifies the namespace where the event should be registered.
  • -IndicationFilter: Specifies a filter to apply to the events. Only events that match the filter will be received by the handler.
  • -Handler: Specifies a script block to handle the events. The script block should accept a single parameter of type CimIndication.
  • -SubscriptionName: Specifies a name for the subscription. This name can be used to later unregister the subscription.
  • -WaitForEvent: Indicates that the cmdlet should block until an event is received.
  • -IgnoreDupes: Indicates that duplicate events should be ignored.
  • -Output: Specifies the path to a file where the events should be logged.
  • -Source: Specifies the source of the events.
  • -ErrorAction: Specifies the action to take if an error occurs.
  • -AbortIfError: Indicates that the cmdlet should abort if an error occurs.
  • -ThrottleLimit: Specifies the maximum number of events that can be received per second.
  • -ConnectionUri: Specifies the URI of the WMI connection to use.
  • -DefaultAuthentication: Indicates that default authentication should be used.

Examples

Simple Event Registration

Register-CimIndicationEvent -Namespace "root/cimv2" -IndicationFilter "SELECT * FROM __InstanceModificationEvent WHERE TargetInstance ISA \"Win32_Process\"" -Handler {
    Write-Host "Event received: $($_.TargetInstance.Name)"
}

Registering with a CIM Session

$session = New-CimSession -ComputerName "remotecomputer"
Register-CimIndicationEvent -CimSession $session -Namespace "root/cimv2" -IndicationFilter "SELECT * FROM __InstanceModificationEvent" -Handler {
    Write-Host "Event received on $remotecomputer: $($_.TargetInstance.Name)"
}

Filtering Events

Register-CimIndicationEvent -Namespace "root/cimv2" -IndicationFilter "SELECT * FROM __InstanceCreationEvent WHERE TargetInstance.Name = \"MyProcess\"" -Handler {
    Write-Host "New process created: $($_.TargetInstance.Name)"
}

Common Issues

  • Duplicate Events: Certain events may be received multiple times. To ignore duplicate events, use the -IgnoreDupes flag.
  • Access Denied: If you receive an access denied error, ensure that you have sufficient permissions to receive CIM events.
  • No Events Received: If you do not receive any events, check the indication filter to ensure it is correct. Also, verify that the managed component is actually generating the events.

Integration

Register-CimIndicationEvent can be combined with other PowerShell commands and tools to create advanced monitoring and automation solutions. For example, you can use Start-Job to run the event handler asynchronously or use Out-File to log the events to a file.