Provides interaction with Windows event logs.
See Also: EventLog Members
Syntax
[System.ComponentModel.InstallerType(typeof(System.Diagnostics.EventLogInstaller))]
[System.Diagnostics.MonitoringDescription("Represents an event log")]
public class EventLog : System.ComponentModel.Component, System.ComponentModel.ISupportInitialize
Remarks
System.Diagnostics.EventLog lets you access or customize Windows event logs, which record information about important software or hardware events. Using System.Diagnostics.EventLog, you can read from existing logs, write entries to logs, create or delete event sources, delete logs, and respond to log entries. You can also create new logs when creating an event source.
If the EventLog.Source for the event log associated with the System.Diagnostics.EventLog instance does not exist, a new event source is created. To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges.
The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a System.Security.SecurityException is thrown.
Starting with Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator.
Creating an System.Diagnostics.EventLog object, writing an entry, then passing the System.Diagnostics.EventLog object to partially trusted code can create a security issue. Never pass any event log object, including System.Diagnostics.EventLogEntry and System.Diagnostics.EventLogEntryCollection objects, to less trusted code.
In versions 1.0 and 1.1 of the .NET Framework, this class requires immediate callers to be fully trusted. In version 2.0 this class requires System.Diagnostics.EventLogPermission for specific actions. It is strongly recommended that System.Diagnostics.EventLogPermission not be granted to partially trusted code. The ability to read and write the event log allows code to perform actions such as issuing event log messages in the name of another application.
Creating or deleting an event source requires synchronization of the underlying code by using a named mutex. If a highly privileged application locks the named mutex, attempts to create or delete an event source causes the application to stop responding until the lock is released. To help avoid this problem, never grant System.Security.Permissions.SecurityPermissionFlag.UnmanagedCode permission to untrusted code. In addition, System.Security.Permissions.SecurityPermissionFlag.UnmanagedCode permission potentially allows other permissions to be bypassed and should only be granted to highly trusted code.
To read from a log, specify the EventLog.Log name and EventLog.MachineName (server computer name) for the System.Diagnostics.EventLog. It is not necessary to specify the EventLog.Source, as a source is required only for writing to logs. The EventLog.Entries member is automatically populated with the event log's list of entries.
You are not required to specify the EventLog.MachineName if you are connecting to a log by specifying a EventLog.Log / EventLog.MachineName pair. If you do not specify the EventLog.MachineName, the local computer, ".", is assumed.
If you write to an event log, you must specify or create an event EventLog.Source. You must have administrative rights on the computer to create a new event source. The EventLog.Source registers your application with the event log as a valid source of entries. You can only use the EventLog.Source to write to one log at a time. The EventLog.Source can be any random string, but the name must be distinct from other sources on the computer. It is common for the source to be the name of the application or another identifying string. An attempt to create a duplicated EventLog.Source value throws an exception. However, a single event log can be associated with multiple sources.
There is nothing to protect an application from writing as any registered source. If an application is granted EventLogPermissionAccess.Write permission, it can write events for any valid source registered on the computer.
Applications and services should write to the Application log or a custom log. Device drivers should write to the System log. If you do not explicitly set the EventLog.Log property, the event log defaults to the Application log.
The Security log is read-only.
Use erload:System.Diagnostics.EventLog.WriteEvent and erload:System.Diagnostics.EventLog.WriteEntry to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source.
Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an System.Diagnostics.EventLogInstaller, or using the erload:System.Diagnostics.EventLog.CreateEventSource method. You must have administrative rights on the computer to create a new event source.
Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source.
You can register the event source with localized resources for your event category and message strings. Your application can write event log entries using resource identifiers, rather than specifying the actual string values. Refer to the System.Diagnostics.EventLogInstaller and System.Diagnostics.EventSourceCreationData classes for more information on configuring your source with resource files.
If your application writes string values directly to the event log, you do not need to set the resource file properties for the source. The source must be configured either for writing localized entries or for writing direct strings. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the erload:System.Diagnostics.EventLog.WriteEvent method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the erload:System.Diagnostics.EventLog.WriteEntry method to write strings directly to the event log using that source.
When writing events, you must at least specify either a message string or the resource identifier for a message string. Other event properties are optional. Examples of optional event settings include the following: you can set the System.Diagnostics.EventLogEntryType to specify the icon that the Event Viewer displays for the entry; you can specify a category identifier for the event, if your application uses categories for filtering the events; and you can also attach binary data to your event entry if you need to associate additional information with a given event.
In addition to accessing individual event logs and their entries, the System.Diagnostics.EventLog class provides access to the collection of all event logs. You can use the static members of System.Diagnostics.EventLog to delete logs, get log lists, create or delete a source, or determine if a computer already contains a particular source.
There are three default event logs: Application, System, and Security. Other installed applications and services, such as Active Directory, can have additional event logs. You can use System.Diagnostics.EventLog to create custom event logs that you can view through the server's Event Viewer. Use the EventLog.RegisterDisplayName(string, long) method to display a localized name for your event log in the Event Viewer. Use the EventLog.ModifyOverflowPolicy(OverflowAction, int) method to configure the behavior of your event log when it reaches its maximum log size.
Event logging consumes disk space, processor time, and other system resources. It is important to log only essential information. It is recommended that you place event log calls in an error path, rather than in the main code path, so as not to adversely affect performance.
For a list of initial property values for an instance of System.Diagnostics.EventLog, see the EventLog.#ctor constructor.
Requirements
Assembly: System (in System.dll)
Assembly Versions: 1.0.3300.0, 1.0.5000.0, 2.0.0.0, 4.0.0.0