EventLog, classe

EventLog vous permet d'accéder ou de personnaliser les journaux des événements Windows, qui enregistrent des informations sur les événements logiciels ou matériels importants. À l'aide de EventLog, vous pouvez lire les journaux existants, écrire des entrées dans les journaux, créer ou supprimer des sources d'événements, supprimer des journaux et répondre aux entrées de journal. Vous pouvez également créer de nouveaux journaux lors de la création d'une source d'événements.

Remarque

Si le Source pour le journal des événements associé à l'instance EventLog n'existe pas, une nouvelle source d'événement est créée. Pour créer une source d'événements dans Windows Vista et version ultérieure ou Windows Server 2003, vous devez disposer de privilèges d'administrateur. Cette configuration est nécessaire car tous les journaux d'événements (y compris la sécurité) doivent être recherchés pour déterminer si la source de l'événement est unique. À partir de Windows Vista, les utilisateurs ne sont pas autorisés à accéder au journal de sécurité ; SecurityException est donc levée. À partir de Windows Vista, le contrôle de compte d'utilisateur détermine les privilèges d'un utilisateur. Si vous êtes membre du groupe Administrateurs intégrés, deux jetons d'accès au moment de l'exécution vous sont assignés : un jeton d'accès utilisateur standard et un jeton d'accès administrateur. Par défaut, vous êtes dans le rôle d'utilisateur standard. Pour exécuter le code qui accède au journal de sécurité, vous devez d'abord élever vos privilèges d'utilisateur standard à administrateur. Cela peut être effectué au démarrage d'une application en cliquant avec le bouton droit sur l'icône de l'application et en indiquant que vous voulez l'exécuter en tant qu'administrateur.

Important
La création d'un objet EventLog, l'écriture d'une entrée, puis le passage de l'objet EventLog à un code de niveau de confiance partiel peut entraîner un problème de sécurité. Ne passez jamais un objet de journal des événements, y compris les objets EventLogEntry et EventLogEntryCollection, à un code de confiance inférieur.

Important

Cette classe requiert que les appelants immédiats soient d'un niveau de confiance suffisant dans les versions 1.0 et 1.1 du .NET Framework. Dans la version 2.0, cette classe requiert EventLogPermission pour des actions spécifiques. Il est fortement recommandé que EventLogPermission ne soit pas accordé au code de niveau de confiance partiel. La possibilité de lire et d'écrire le journal des événements permet au code d'exécuter des actions telles que l'émission de messages du journal des événements pour le compte d'une autre application.

Important

La création ou la suppression d'une source d'événements requiert la synchronisation du code sous-jacent à l'aide d'un mutex nommé. Si une application avec des privilèges importants verrouille le mutex nommé, toute tentative de création ou de suppression d'une source d'événements force l'application à cesser de répondre jusqu'à ce que le verrou soit libéré. Pour éviter ce problème, n'accordez jamais l'autorisation UnmanagedCode à un code non fiable. De plus, l'autorisation UnmanagedCode permettant potentiellement d'ignorer d'autres autorisations, elle ne doit être accordée qu'à un code à niveau de confiance extrêmement élevé.

Pour lire un journal, spécifiez le nom Log et MachineName (nom de l'ordinateur serveur) pour EventLog. Il n'est pas nécessaire de spécifier Source, puisqu'une source n'est requise que pour l'écriture dans les journaux. Le membre Entries est automatiquement rempli avec la liste des entrées du journal des événements.

Remarque
Il n'est pas nécessaire de spécifier MachineName pour la connexion à un journal si vous spécifiez une paire Log/MachineName. Si vous ne spécifiez pas MachineName, c'est l'ordinateur local, ".", qui est utilisé par défaut.

Si vous écrivez dans un journal des événements, vous devez spécifier ou créer un événement Source. Vous devez avoir des droits d'administration sur l'ordinateur pour créer une nouvelle source d'événements. Le Source inscrit votre application avec le journal des événements comme source des entrées valide. Vous ne pouvez utiliser que le Source pour écrire dans un journal à un moment donné. Le Source peut être toute chaîne aléatoire, mais le nom doit être distinct des autres sources sur l'ordinateur. Il est courant que la source soit le nom de l'application ou une autre chaîne d'identification. Une tentative de création d'une valeur Source dupliquée lève une exception. Cependant, un seul journal des événements peut être associé à de multiples sources.

Remarque
Rien ne peut empêcher une application d'écrire comme toute source inscrite. Si l'autorisation Write est accordée à une application, cette dernière peut écrire des événements pour n'importe quelle source valide inscrite sur l'ordinateur.

Les applications et les services doivent écrire dans le journal d'applications ou dans un journal personnalisé. Les pilotes de périphériques doivent écrire dans le journal système. Si vous ne définissez pas explicitement la propriété Log, le journal des événements par défaut est le journal d'applications.

Remarque
Le journal sécurité est en lecture seule.

Utilisez WriteEvent et WriteEntry pour écrire des événements dans un journal des événements. Vous devez spécifier une source d'événements pour écrire des événements ; vous devez créer et configurer la source d'événements avant d'écrire la première entrée avec la source.

Créez la nouvelle source d'événements pendant l'installation de votre application. Cela laisse au système d'exploitation le temps d'actualiser sa liste de sources d'événements inscrites et leur configuration. Si le système d'exploitation n'a pas actualisé sa liste de sources d'événements et que vous essayez d'écrire un événement avec la nouvelle source, l'opération d'écriture échouera. Vous pouvez configurer une nouvelle source à l'aide de EventLogInstaller ou de la méthode CreateEventSource. Vous devez avoir des droits d'administration sur l'ordinateur pour créer une nouvelle source d'événements.

Chaque source ne peut écrire que dans un seul journal des événements ; toutefois, votre application peut utiliser des sources multiples afin d'écrire dans plusieurs journaux des événements. Par exemple, votre application peut requérir des sources multiples configurées pour des journaux des événements ou des fichiers de ressources différents. Pour modifier les détails de configuration d'une source existante, vous devez supprimer cette source, puis la créer avec la nouvelle configuration. Si d'autres applications ou composants utilisent la source existante, créez une nouvelle source avec la configuration mise à jour plutôt que de supprimer la source existante.

Vous pouvez inscrire la source d'événements avec des ressources localisées pour votre catégorie d'événements et des chaînes de message. Votre application peut écrire des entrées de journal des événements en utilisant des identificateurs de ressources, plutôt qu'en spécifiant les valeurs de chaînes réelles. Reportez-vous aux classes EventLogInstaller et EventSourceCreationData pour plus d'informations sur la configuration de votre source avec des fichiers de ressources.

Si votre application écrit directement des valeurs de chaîne dans le journal des événements, il n'est pas nécessaire de définir les propriétés du fichier de ressources pour la source. La source doit être configurée pour l'écriture d'entrées localisées ou l'écriture de chaînes directes. Si votre application écrit des entrées composées d'identificateurs de ressource et de valeurs de chaîne, vous devez enregistrer deux sources séparées. Configurez par exemple une source avec des fichiers de ressources, puis utilisez cette source dans la méthode WriteEvent pour écrire des entrées utilisant des identificateurs de ressource dans le journal des événements. Créez ensuite une autre source, sans fichiers de ressources, et utilisez-la dans la méthode WriteEntry pour écrire des chaînes directement dans le journal des événements.

Lorsque vous écrivez des événements, vous devez spécifier au moins une chaîne de message ou l'identificateur de ressource pour une chaîne de message. Les autres propriétés d'événements sont facultatives. Exemples de paramètres d'événements facultatifs : vous pouvez définir EventLogEntryType de sorte à indiquer à l'icône que l'Observateur d'événements s'affiche pour l'entrée. Vous pouvez spécifier un identificateur de catégorie pour l'événement, si votre application utilise des catégories pour filtrer les événements. Vous pouvez également attacher des données binaires à votre entrée d'événement si vous devez associer des informations supplémentaires à un événement donné.

En plus de l'accès aux journaux des événements individuels et à leurs entrées, la classe EventLog permet d'accéder à la collection de tous les journaux des événements. Vous pouvez utiliser les static membres de EventLog pour supprimer les journaux, obtenir les listes de journaux, créer ou supprimer une source ou déterminer si un ordinateur contient déjà une source particulière.

Trois journaux des événements par défaut sont disponibles : applications, système et sécurité. D'autres applications et services installés, tels qu'Active Directory, peuvent avoir des journaux des événements supplémentaires. Vous pouvez utiliser EventLog pour créer des journaux des événements personnalisés que vous pouvez afficher par l'intermédiaire de l'Observateur d'événements du serveur. Utilisez la méthode RegisterDisplayName pour afficher un nom localisé pour votre journal des événements dans l'Observateur d'événements. Utilisez la méthode ModifyOverflowPolicy pour configurer le comportement de votre journal des événements lorsqu'il atteint sa taille maximale.

L'enregistrement d'événements dans le journal consomme de l'espace disque, du temps ainsi que d'autres ressources du système. Il est important d'enregistrer uniquement les informations essentielles. Il est recommandé que vous placiez les appels du journal des événements dans un chemin d'accès d'erreur plutôt que dans le chemin d'accès du code principal, de façon à ne pas influer sur la performance de manière indésirable.

Pour obtenir la liste des valeurs de propriétés initiales d'une instance de EventLog, consultez le constructeur EventLog.

Remarque sur la plateforme  : Ces journaux des événements ne sont pas pris en charge sur Windows 98 ou Windows Millennium Edition (Me).

L'exemple suivant crée la source MySource si elle n'existe pas déjà et écrit une entrée dans le journal des événements MyNewLog.

Remarque
À partir de Windows Vista, vous devez lancer cette application en tant qu'administrateur.

using System;
using System.Diagnostics;
using System.Threading;

class MySample{

    public static void Main(){

        // Create the source, if it does not already exist.
        if(!EventLog.SourceExists("MySource"))
        {
             //An event log source should not be created and immediately used.
             //There is a latency time to enable the source, it should be created
             //prior to executing the application that uses the source.
             //Execute this sample a second time to use the new source.
            EventLog.CreateEventSource("MySource", "MyNewLog");
            Console.WriteLine("CreatedEventSource");
            Console.WriteLine("Exiting, execute the application a second time to use the source.");
            // The source is created.  Exit the application to allow it to be registered.
            return;
        }

        // Create an EventLog instance and assign its source.
        EventLog myLog = new EventLog();
        myLog.Source = "MySource";

        // Write an informational entry to the event log.    
        myLog.WriteEntry("Writing to event log.");

    }
}
   

.NET Framework

.NET Framework Client Profile

Windows 7, Windows Vista SP1 ou ultérieur, Windows XP SP3, Windows XP SP2 Édition x64, Windows Server 2008 (installation minimale non prise en charge), Windows Server 2008 R2 (installation minimale prise en charge avec SP1 ou version ultérieure), Windows Server 2003 SP2

Référence