Write-Event Log

Writes an event to an event log.

Syntax

Description

The Write-EventLog cmdlet writes an event to an event log.

To write an event to an event log, the event log must exist on the computer and the source must be registered for the event log.

The cmdlets that contain the EventLog noun (the EventLog cmdlets) work only on classic event logs. To get events from logs that use the Windows Event Log technology in Windows Vista and later versions of the Windows operating system, use the Get-WinEvent cmdlet.

Examples

Example 1: Write an event to the Application event log

This command writes an event from the MyApp source to the Application event log.

Example 2: Write an event to the Application event log of a remote computer

This command writes an event from the MyApp source to the Application event log on the Server01 remote computer.

Parameters

Specifies a task category for the event. Enter an integer that is associated with the strings in the category message file for the event log.

Type:	Int16
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies a remote computer. The default is the local computer.

Type the NetBIOS name, an IP address, or a fully qualified domain name of a remote computer.

This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of the Get-EventLog cmdlet even if your computer is not configured to run remote commands.

Type:	String
Aliases:	CN
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies the entry type of the event. The acceptable values for this parameter are: Error, Warning, Information, SuccessAudit, and FailureAudit. The default value is Information.

For a description of the values, see EventLogEntryType Enumeration.

Type:	EventLogEntryType
Aliases:	ET
Accepted values:	Error, Information, FailureAudit, SuccessAudit, Warning
Position:	3
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies the event identifier. This parameter is required. The maximum value for the EventId parameter is 65535.

Type:	Int32
Aliases:	ID, EID
Position:	2
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies the name of the log to which the event is written. Enter the log name. The log name is the value of the Log property, not the LogDisplayName. Wildcard characters are not permitted. This parameter is required.

Type:	String
Aliases:	LN
Position:	0
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies the event message. This parameter is required.

Type:	String
Aliases:	MSG
Position:	4
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies the binary data that is associated with the event, in bytes.

Type:	Byte [ ]
Aliases:	RD
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies the event source, which is typically the name of the application that is writing the event to the log.

Type:	String
Aliases:	SRC
Position:	1
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Inputs

None

You cannot pipe input to this cmdlet.

Outputs

This cmdlet returns objects that represents the events in the logs.

Notes

For some Windows event logs, writing events requires administrator rights. You must start PowerShell using the Run as Administrator option.

Limit-Event Log

Sets the event log properties that limit the size of the event log and the age of its entries.

Syntax

Description

The Limit-EventLog cmdlet sets the maximum size of a classic event log, how long each event must be retained, and what happens when the log reaches its maximum size. You can use it to limit the event logs on local or remote computers.

The cmdlets that contain the EventLog noun (the EventLog cmdlets) work only on classic event logs. To get events from logs that use the Windows Event Log technology in Windows Vista and later versions of Windows, use Get-WinEvent.

Examples

Example 1: Increase the size of an event log

This command increases the maximum size of the Windows PowerShell event log on the local computer to 20480 bytes (20 KB).

Example 2: Retain an event log for a specified duration

This command ensures that events in the Security log on the Server01 and Server02 computers are retained for at least 7 days.

Example 3: Change the overflow action of all event logs

This example changes the overflow action of all event logs on the local computer to OverwriteOlder.

The first command gets the log names of all of the logs on the local computer. The second command sets the overflow action. The third command displays the results.

Parameters

Specifies remote computers. The default is the local computer.

Type the NetBIOS name, an Internet Protocol (IP) address, or a fully qualified domain name (FQDN) of a remote computer. To specify the local computer, type the computer name, a dot (.), or localhost.

This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Limit-EventLog even if your computer is not configured to run remote commands.

Type:	String [ ]
Aliases:	CN
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Prompts you for confirmation before running the cmdlet.

Type:	SwitchParameter
Aliases:	cf
Position:	Named
Default value:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies the event logs. Enter the log name (the value of the Log property; not the LogDisplayName) of one or more event logs, separated by commas. Wildcard characters are not permitted. This parameter is required.

Type:	String [ ]
Aliases:	LN
Position:	0
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies the maximum size of the event logs in bytes. Enter a value between 64 kilobytes (KB) and 4 gigabytes (GB). The value must be divisible by 64 KB (65536).

This parameter specifies the value of the MaximumKilobytes property of the System.Diagnostics.EventLog object that represents a classic event log.

Type:	Int64
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies what happens when the event log reaches its maximum size.

The acceptable values for this parameter are:

• DoNotOverwrite: Existing entries are retained and new entries are discarded.
• OverwriteAsNeeded: Each new entry overwrites the oldest entry.
• OverwriteOlder: New events overwrite events older than the value specified by the MinimumRetentionDays property. If there are no events older than specified by the MinimumRetentionDays property value, new events are discarded.

This parameter specifies the value of the OverflowAction property of the System.Diagnostics.EventLog object that represents a classic event log.

Type:	OverflowAction
Aliases:	OFA
Accepted values:	OverwriteOlder, OverwriteAsNeeded, DoNotOverwrite
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies the minimum number of days that an event must remain in the event log.

This parameter specifies the value of the MinimumRetentionDays property of the System.Diagnostics.EventLog object that represents a classic event log.

Type:	Int32
Aliases:	MRD
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type:	SwitchParameter
Aliases:	wi
Position:	Named
Default value:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Inputs

None

You cannot pipe input to this cmdlet.

Outputs

None

This cmdlet does not generate any output.

Notes

To use this cmdlet on Windows Vista and later versions of Windows, open Windows PowerShell with the Run as administrator option.

Event Logging (Windows Installer)

Windows Events provides a standard, centralized way for applications (and the operating system) to record important software and hardware events. The event-logging service stores events from various sources in a single collection called an event log. Prior to WindowsВ Vista, you would use either Event Tracing for Windows (ETW) or Event Logging to log events. WindowsВ Vista introduced a new eventing model that unifies both ETW and the Windows Event Log API.

The installer also writes entries into the event log. These record events such as following:

• Success or failure of the installation; removal or repair of a product.
• Errors that occur during product configuration.
• Detection of corrupted configuration data.

If a large amount of information is written, the Event Log file can become full and the installer displays the message, «The Application log file is full.»

The installer may write the following entries in the event log. All event log messages have a unique event ID. All general errors authored in the Error table that are returned for an installation that fails are logged in the Application Event Log with a message ID equal to the Error + 10,000. For example, the error number in the Error table for an installation completed successfully is 1707. The successful installation is logged in the Application Event Log with a message ID of 11707 (1707 + 10,000).

For information about how to enable verbose logging on a user’s computer when troubleshooting deployment, see Windows Installer Best Practices.

Consuming Events (Windows Event Log)

You can consume events from channels or from log files. To consume events, you can consume all events or you can specify an XPath expression that identifies the events that you want to consume. To determine the elements and attributes of an event that you can use in your XPath expression, see Event Schema.

Windows Event Log supports a subset of XPath 1.0. For details on the limitations, see XPath 1.0 limitations.

The following examples show simple XPath expressions.

You can use the XPath expressions directly when calling the EvtQuery or EvtSubscribe functions or you can use a structured XML query that contains the XPath expression. For simple queries that query events from a single source, using an XPath expression is fine. If the XPath expression is a compound expression that contains more than 20 expressions or you are querying for events from multiple sources, then you must use a structured XML query. For details on the elements of a structured XML query, see Query Schema.

A structured query identifies the source of the events and one or more selectors or suppressors. A selector contains an XPath expressions that selects events from the source and a suppressor contains an XPath expression that prevents events from being selected. You can select events from more than one source. If a selector and suppressor identify the same event, the event is not included in the result.

The following shows a structured XML query that specifies a set of selectors and suppressors.

The result set from the query does not contain a snapshot of the events at the time of the query. Instead, the result set includes the events at the time of the query and will also contain all new events that are raised that match the query criteria while you are enumerating the results.

The order of the events is preserved for events that are written by the same thread. However, it is possible for events written by separate threads on different processors of a multiple processor computer to appear out of order.

For details on consuming events, see the following topics:

The standard end user tools for consuming event are:

XPath 1.0 limitations

Windows Event Log supports a subset of XPath 1.0. The primary restriction is that only XML elements that represent events can be selected by an event selector. An XPath query that does not select an event is not valid. All valid selector paths start with * or «Event». All location paths operate on the event nodes and are composed of a series of steps. Each step is a structure of three parts: the axis, node test, and predicate. For more information about these parts and about XPath 1.0, see XML Path Language (XPath). Windows Event Log places the following restrictions on the expression:

• Axis: Only the Child (default) and Attribute (and its shorthand «@») axis are supported.
• Node Tests: Only node names and NCName tests are supported. The «*» character, which selects any character, is supported.
• Predicates: Any valid XPath expression is acceptable if the location paths conform to the following restrictions:
  • Standard operators OR, AND, =, !=, =, >, and parentheses are supported.
  • Generating a string value for a node name is not supported.
  • Evaluation in reverse order is not supported.
  • Node sets are not supported.
  • Namespace scoping is not supported.
  • Namespace, processing, and comment nodes are not supported.
  • Context size is not supported.
  • Variable bindings are not supported.
  • The position function, and its shorthand array reference, is supported (on leaf nodes only).
  • The Band function is supported. The function performs a bitwise AND for two integer number arguments. If the result of the bitwise AND is nonzero, the function evaluates to true; otherwise, the function evaluates to false.
  • The timediff function is supported. The function computes the difference between the second argument and the first argument. One of the arguments must be a literal number. The arguments must use FILETIME representation. The result is the number of milliseconds between the two times. The result is positive if the second argument represents a later time; otherwise, it is negative. When the second argument is not provided, the current system time is used.