NAME
Register-EventRecordWrittenEvent

SYNOPSIS
Registers the EventRecordWritten event of the EventLogWatcher object specified.

SYNTAX
Register-EventRecordWrittenEvent [-InputObject] <EventLogWatcher> [[-BookmarkStreamPath] <String>] [[-SourceIdentif
ier] <String>] [[-Action] <ScriptBlock>] [[-MessageData] <PSObject>] [<CommonParameters>]


DESCRIPTION
The Register-EventRecordWrittenEvent registers the EventRecordWritten event of the EventLogWatcher object
specified. A ScriptBlock can be associated to trigger each time this event is raised, by passing the code
to the Action parameter.

IMPORTANT: The associated EventLogWatcher must be enabled for any events to be triggered, but this
SHOULD NOT be done until the Event is registered. If the EventLogWatcher is enabled prior to the
EventRecordWritten Event being registered, then the EventLogWatcher will process through Windows Event Log
events without being captured.

To ENABLE the returned EventLogWatcher:
$EventLogWatcher.Enabled = $True

To DISABLE the returned EventLogWatcher:
$EventLogWatcher.Enabled = $False


PARAMETERS
-InputObject <EventLogWatcher>
The EventLogWatcher object which will raise the associated EventRecordWritten Event that will be subscribed
to using Register-ObjectEvent.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters?

-BookmarkStreamPath <String>
The full path and filename for the EventBookmark to be serialized and stored as a file. The default Action
block will serialize and output the last EventBookmark object to the path specified.

DEFAULT = ".\bookmark.stream"

Required? false
Position? 2
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters?

-SourceIdentifier <String>
The SourceIdentifier for the event, which will be passed to Register-ObjectEvent.

DEFAULT = "NewEventLog"

Required? false
Position? 3
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters?

-Action <ScriptBlock>
Specifies commands to handle the events. The commands in the Action run when an event is raised, instead of
sending the event to the event queue. Enclose the commands in braces ( { } ) to create a script block.

The value of the Action parameter can include the Automatic Variables already provided by Register-ObjectEvent
($Event, $EventSubscriber, $Sender, $SourceEventArgs, and $SourceArgs).

Register-EventRecordWrittenEvent also created the following additional Automatice Variables $EventRecord,
$EventRecordXML, $EventBookmark, $BookmarkStreamPath. The variables are of the following types:

EventRecord <System.Diagnostics.Eventing.Reader.EventRecord>
- The Windows Log Event that raised the current EventRecordWritten Event.

EventRecordXML <XML>
- The XML representation of the current EventRecord, using the ToXml Method.
- As an example, the EventData properties can be retrieved with $EventRecordXML.Event.EventData.Data

EventBookmark <System.Diagnostics.Eventing.Reader.EventBookmark>
- The EventBookmark from the current EventRecord.
- This EventBookmark placeholder is serialized and stored in the BookmarkStreamPath for
later retrieval, if the EventLogWatcher would need to be restarted from where it left off.

BookmarkStreamPath <string>
- The full path and filename for the EventBookmark to be serialized and stored as a file.
- Value matches the value of the same parameter that was passed to Register-EventRecordWrittenEvent
at the time the event was registered.
- This serialized EventBookmark can be used for retrieval, if the EventLogWatcher would need to be
restarted from where it left off.

Any additional values required can be passed to the MessageData parameter for Register-EventRecordWrittenEvent.

Required? false
Position? 4
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters?

-MessageData <PSObject>
Specifies any additional data to be associated with this event subscription. The value of this parameter appear
s in the MessageData property of all events associated with this subscription.

Multiple objects can be passed to this parameter using custom objects. Build the custom object in using one of
the following methods:

METHOD 1

$Object1 = "Some Data"
$Object2 = "Other Data"
$CustomObject = New-Object psobject -property @{'Object1' = $Object1; 'Object2' = $Object2}
Register-EventRecordWrittenEvent $EventLogWatcher -Action $Action -MessageData $CustomObject

METHOD 2

$Object1 = "Some Data"
$Object2 = "Other Data"
$CustomObject = New-Object psobject
$CustomObject | Add-Member noteproperty Object1 $Object1
$CustomObject | Add-Member noteproperty Object2 $Object2
Register-EventRecordWrittenEvent $EventLogWatcher -Action $Action -MessageData $CustomObject

The data can then be accessed in the Action ScriptBlock with the following syntax:

$event.MessageData.Object1
$event.MessageData.Object2

Required? false
Position? 5
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".


-------------------------- EXAMPLE 1 --------------------------

C:\PS>$action = { write-host ("[ {0:g} ] Found Event {1} from {2} @ {3:g} " -f $Event.TimeGenerated,


$EventRecord.RecordID,$EventRecord.Machinename,$EventRecord.TimeCreated) }
C:\PS> Register-EventRecordWrittenEvent $EventLogWatcher -action $action

C:\PS> $EventLogWatcher.Enabled = $True

Description
-----------
This example will output using Write-Host for each EventRecordWritten Event that is raised by $EventLogWatcher,
and will serialize the last EventBookmark to the default location ".\bookmark.stream" The saved EventBookmark
can be used to restart the EventLogWatcher from where it left off if necessary.





-------------------------- EXAMPLE 2 --------------------------

C:\PS>$Action = {


$EventRecord |
Select-Object TimeCreated, ID, Level, MachineName, RecordID |
Convertto-CSV -Outvariable OutData -NoTypeInformation

$Outdata[1..($Outdata.count - 1)] |
ForEach-Object {Out-File -InputObject $_ "c:\EventRecord.csv" -append}
}
C:\PS> Register-EventRecordWrittenEvent $EventLogWatcher -action $action

C:\PS> $EventLogWatcher.Enabled = $True

Description
-----------
This example will output to "C:\EventRecord.CSV" for each EventRecordWritten Event that is raised by
$EventLogWatcher, and will serialize the last EventBookmark to the default location ".\bookmark.stream"
The saved EventBookmark can be used to restart the EventLogWatcher from where it left off if necessary.





Last edited Jun 15, 2011 at 9:29 PM by sgrinker, version 3

Comments

No comments yet.