EventLog.CreateEventSource-Methode (EventSourceCreationData)

Verwenden Sie diese Überladung, um eine neue Quelle zum Schreiben von Einträgen in ein Ereignisprotokoll auf dem lokalen Computer oder einem Remotecomputer zu konfigurieren. Es ist nicht erforderlich, diese Methode zum Lesen aus einem Ereignisprotokoll zu verwenden.

Die CreateEventSource-Methode erstellt mit der sourceData-Source-Eingabeeigenschaft, der LogName-Eingabeeigenschaft und der MachineName-Eingabeeigenschaft Registrierungswerte auf dem Zielcomputer für die neue Quelle und das zugeordnete Ereignisprotokoll. Neue Quellennamen dürfen nicht mit einem vorhandenen Quellennamen oder einem vorhandenen Ereignisprotokollnamen auf dem Zielcomputer übereinstimmen. Wenn die LogName-Eigenschaft nicht festgelegt ist, wird die Quelle für das Anwendungsereignisprotokoll registriert. Wenn der MachineName nicht festgelegt ist, wird die Quelle auf dem lokalen Computer registriert.

Hinweis

Zum Erstellen einer Ereignisquelle unter Windows Vista oder höher oder Windows Server 2003 müssen Sie über Administratorrechte verfügen. Der Grund für diese Anforderung besteht darin, dass alle Ereignisprotokolle, einschließlich der für die Sicherheit, durchsucht werden müssen, um zu bestimmen, ob die Ereignisquelle eindeutig ist. Ab Windows Vista verfügen Benutzer nicht über die Berechtigung, auf das Sicherheitsprotokoll zuzugreifen. Daher wird eine SecurityException ausgelöst. Ab Windows Vista werden die Berechtigungen eines Benutzers über die Benutzerkontensteuerung (UAC) bestimmt. Als Mitglied der integrierten Administratorgruppe sind Ihnen zwei Zugriffstoken für die Laufzeit zugewiesen: ein Standardbenutzertoken und ein Administratorzugriffstoken. Standardmäßig verwenden Sie die Standardbenutzerrolle. Um Code ausführen zu können, der auf das Sicherheitsprotokoll zugreift, müssen Sie zuerst Ihre Berechtigungen von Standardbenutzer auf Administrator erhöhen. Dazu starten Sie eine Anwendung, indem Sie mit der rechten Maustaste auf das Anwendungssymbol klicken und angeben, dass Sie die Anwendung als Administrator ausführen möchten.

Verwenden Sie WriteEvent und WriteEntry, um Ereignisse in ein Ereignisprotokoll zu schreiben. Sie müssen zum Schreiben von Ereignissen eine Ereignisquelle angeben. Bevor Sie den ersten Eintrag mit der Quelle schreiben, müssen Sie die Ereignisquelle erstellen und konfigurieren.

Erstellen Sie die neue Ereignisquelle während der Installation der Anwendung. Dies gibt dem Betriebssystem Gelegenheit, die Liste der registrierten Ereignisquellen und deren Konfiguration zu aktualisieren. Wenn die Liste der Ereignisquellen vom Betriebssystem nicht aktualisiert wurde und Sie versuchen, ein Ereignis für die neue Quelle zu schreiben, schlägt der Schreibvorgang fehl. Sie können eine neue Quelle entweder mithilfe eines EventLogInstaller oder mithilfe der CreateEventSource-Methode erstellen. Sie benötigen Administratorrechte für den Computer, um eine neue Ereignisquelle zu erstellen.

Sie können eine Ereignisquelle für ein vorhandenes oder für ein neues Ereignisprotokoll erstellen. Wenn Sie eine neue Quelle für ein neues Ereignisprotokoll erstellen, wird die Quelle für das Protokoll im System registriert, das Protokoll wird jedoch erst beim Schreiben des ersten Eintrags erstellt.

Das Betriebssystem speichert Ereignisprotokolle als Dateien. Wenn Sie ein neues Ereignisprotokoll mit EventLogInstaller oder CreateEventSource erstellen, wird die zugeordnete Datei auf dem angegebenen Computer im Verzeichnis %SystemRoot%\System32\Config gespeichert. Der Dateiname setzt sich aus den ersten acht Zeichen der Log-Eigenschaft und der Dateinamenerweiterung ".evt" zusammen.

Jede Quelle kann immer nur in ein Ereignisprotokoll schreiben. Die Anwendung kann jedoch mehrere Quellen verwenden, um in mehrere Ereignisprotokolle zu schreiben. Beispielsweise müssen für die Anwendung eventuell mehrere Quellen für unterschiedliche Ereignisprotokolle oder Ressourcendateien konfiguriert werden.

Sie können die Ereignisquelle in mehreren lokalisierten Ressourcendateien für die Ereigniskategorie und Meldungszeichenfolgen registrieren. Die Anwendung kann Ereignisprotokolleinträge mit Ressourcenbezeichnern schreiben, anstatt die tatsächliche Zeichenfolge anzugeben. Die Ereignisanzeige sucht anhand des Ressourcenbezeichners und der aktuellen Spracheinstellungen nach der entsprechenden Zeichenfolge in der lokalisierten Ressourcendatei und zeigt sie an. Sie können für Ereigniskategorien, Meldungen und Parametereinfügungs-Zeichenfolgen jeweils eine eigene Datei registrieren, oder Sie können für alle drei Typen von Zeichenfolgen dieselbe Ressourcendatei registrieren. Mit den Eigenschaften CategoryCount, CategoryResourceFile, MessageResourceFile und ParameterResourceFile konfigurieren Sie die Quelle zum Schreiben lokalisierter Einträge in das Ereignisprotokoll. Wenn die Anwendung Zeichenfolgenwerte direkt in das Ereignisprotokoll schreibt, müssen Sie diese Eigenschaften nicht festlegen.

Die Quelle muss entweder zum Schreiben lokalisierter Einträge oder zum Schreiben direkter Zeichenfolgen konfiguriert werden. Wenn die Anwendung beim Schreiben von Einträgen sowohl Ressourcenbezeichner als auch Zeichenfolgenwerte verwendet, müssen Sie zwei getrennte Quellen registrieren. Konfigurieren Sie beispielsweise eine Quelle mit Ressourcendateien, und verwenden Sie diese Quelle dann in der WriteEvent-Methode, um Einträge mithilfe von Ressourcenbezeichnern in das Ereignisprotokoll zu schreiben. Erstellen Sie dann eine andere Quelle ohne Ressourcendateien, und verwenden Sie diese Quelle in der WriteEntry-Methode, um Zeichenfolgen mithilfe dieser Quelle direkt in das Ereignisprotokoll zu schreiben.

Wenn Sie die Konfiguration einer vorhandenen Quelle ändern möchten, müssen Sie sie löschen und mit der neuen Konfiguration neu erstellen. Wenn andere Anwendungen oder Komponenten die vorhandene Quelle nutzen, erstellen Sie eine neue Quelle mit der aktualisierten Konfiguration, anstatt die vorhandene Quelle zu löschen.

Hinweis
Wenn eine Quelle für ein Ereignisprotokoll konfiguriert ist und Sie diese für ein anderes Ereignisprotokoll neu konfigurieren, müssen Sie den Computer neu starten, damit die Änderungen wirksam werden.

Im folgenden Beispiel wird bestimmt, ob die Ereignisquelle SampleApplicationSource auf dem lokalen Computer registriert ist. Wenn die Ereignisquelle nicht vorhanden ist, wird im Beispiel die Nachrichtenressourcendatei für die Quelle festgelegt und eine neue Ereignisquelle erstellt. Abschließend wird im Beispiel der lokalisierte Anzeigenamen für das Ereignisprotokoll mithilfe des URI-Werts in DisplayNameMsgId und des Ressourcendateipfades in messageFile festgelegt.

static void CreateEventSourceSample1(string messageFile)
{
    string myLogName;
    string sourceName = "SampleApplicationSource";

    // Create the event source if it does not exist.
    if(!EventLog.SourceExists(sourceName))
    {
        // Create a new event source for the custom event log
        // named "myNewLog."  

        myLogName = "myNewLog";
        EventSourceCreationData mySourceData = new EventSourceCreationData(sourceName, myLogName);

        // Set the message resource file that the event source references.
        // All event resource identifiers correspond to text in this file.
        if (!System.IO.File.Exists(messageFile))
        {
            Console.WriteLine("Input message resource file does not exist - {0}", 
                messageFile);
            messageFile = "";
        }
        else 
        {
            // Set the specified file as the resource
            // file for message text, category text, and 
            // message parameter strings.  

            mySourceData.MessageResourceFile = messageFile;
            mySourceData.CategoryResourceFile = messageFile;
            mySourceData.CategoryCount = CategoryCount;
            mySourceData.ParameterResourceFile = messageFile;

            Console.WriteLine("Event source message resource file set to {0}", 
                messageFile);
        }

        Console.WriteLine("Registering new source for event log.");
        EventLog.CreateEventSource(mySourceData);
    }
    else
    {
        // Get the event log corresponding to the existing source.
        myLogName = EventLog.LogNameFromSourceName(sourceName,".");
    }

    // Register the localized name of the event log.
    // For example, the actual name of the event log is "myNewLog," but
    // the event log name displayed in the Event Viewer might be
    // "Sample Application Log" or some other application-specific
    // text.
    EventLog myEventLog = new EventLog(myLogName, ".", sourceName);

    if (messageFile.Length > 0)
    {
        myEventLog.RegisterDisplayName(messageFile, DisplayNameMsgId);
    }
}

Im Beispiel wird die folgende Meldungstextdatei verwendet, die in der Ressourcenbibliothek EventLogMsgs.dll integriert ist. Eine Meldungstextdatei bildet die Quelle für die Erstellung einer Meldungsressourcendatei. In der Meldungstextdatei sind die Ressourcenbezeichner und der Text für die Kategorie, die Ereignismeldung und die Parametereinfügungs-Zeichenfolgen definiert. Insbesondere wird der Ressourcenbezeichner 5001 für den lokalisierten Namen des Ereignisprotokolls definiert.

; // EventLogMsgs.mc
; // ********************************************************

; // Use the following commands to build this file:

; //   mc -s EventLogMsgs.mc
; //   rc EventLogMsgs.rc
; //   link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res 
; // ********************************************************

; // - Event categories -
; // Categories must be numbered consecutively starting at 1.
; // ********************************************************

MessageId=0x1
Severity=Success
SymbolicName=INSTALL_CATEGORY
Language=English
Installation
.

MessageId=0x2
Severity=Success
SymbolicName=QUERY_CATEGORY
Language=English
Database Query
.

MessageId=0x3
Severity=Success
SymbolicName=REFRESH_CATEGORY
Language=English
Data Refresh
.

; // - Event messages -
; // *********************************

MessageId = 1000
Severity = Success
Facility = Application
SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000
Language=English
My application message text, in English, for message id 1000, called from %1.
.

MessageId = 1001
Severity = Warning
Facility = Application
SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001
Language=English
My application message text, in English, for message id 1001, called from %1.
.


MessageId = 1002
Severity = Success
Facility = Application
SymbolicName = GENERIC_INFO_MESSAGE_ID_1002
Language=English
My generic information message in English, for message id 1002.
.


MessageId = 1003
Severity = Warning
Facility = Application
SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003
Language=English
My generic warning message in English, for message id 1003, called from %1.
.


MessageId = 1004
Severity = Success
Facility = Application
SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004
Language=English
The update cycle is complete for %%5002.
.


MessageId = 1005
Severity = Warning
Facility = Application
SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005
Language=English
The refresh operation did not complete because the connection to server %1 could not be established.
.


; // - Event log display name -
; // ********************************************************


MessageId = 5001
Severity = Success
Facility = Application
SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID
Language=English
Sample Event Log
.



; // - Event message parameters -
; //   Language independent insertion strings
; // ********************************************************


MessageId = 5002
Severity = Success
Facility = Application
SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID
Language=English
SVC_UPDATE.EXE
.

.NET Framework

.NET Framework Client Profile

• EventLogPermission  

  für das Verwalten von Ereignisprotokollinformationen auf dem Computer. Zugeordnete Enumeration: EventLogPermissionAccess.Administer

Windows 7, Windows Vista SP1 oder höher, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core wird nicht unterstützt), Windows Server 2008 R2 (Server Core wird mit SP1 oder höher unterstützt), Windows Server 2003 SP2

Referenz