NLog pour C# (.NET) : guide complet avec exemples

Bienvenue dans ce guide détaillé sur la bibliothèque NLog pour la plateforme .NET. NLog est un système de logging puissant, flexible et haute performance, devenu un standard de facto pour de nombreux projets .NET. Dans cet article, nous aborderons tout : de l'installation aux techniques avancées, avec des exemples de code concrets et des conseils d'optimisation.

1. Qu'est-ce que NLog et pourquoi l'utiliser ?

NLog (abréviation de ".NET Logging") est une bibliothèque open source gratuite pour la plateforme .NET, conçue pour un logging flexible et performant. Elle permet aux développeurs d'enregistrer des informations de diagnostic (logs) vers différentes destinations : fichiers, console, bases de données, sockets réseau, systèmes de monitoring (Seq, Elasticsearch, Sentry, etc.) et bien d'autres.

Pourquoi le logging est-il essentiel ? Dans le développement logiciel moderne, les logs sont la « boîte noire » de l'application. Sans eux, il est impossible de comprendre pourquoi un serveur a planté, où une erreur s'est produite, ou quelles données étaient traitées au moment du dysfonctionnement. NLog résout ce problème en offrant :

• Flexibilité de routage : Possibilité de configurer différents niveaux de logging (Trace, Debug, Info, Warn, Error, Fatal) pour différentes parties de l'application.
• Performance : Écriture asynchrone, initialisation paresseuse, impact minimal sur la vitesse d'exécution.
• Extensibilité : Des centaines de cibles prêtes à l'emploi et la possibilité d'en créer vos propres.
• Configuration sans recompilation : Les paramètres peuvent être modifiés à chaud via XML, JSON ou le code.

NLog est idéal pour : les applications web (ASP.NET Core), les utilitaires console, les microservices, les applications desktop (WPF/WinForms) et les services d'arrière-plan (Windows Services, Worker Services).

2. Installation

L'installation de NLog se fait via le gestionnaire de paquets NuGet. Exécutez l'une des commandes suivantes dans la console du gestionnaire de paquets Visual Studio ou dans le terminal .NET CLI :

// Via .NET CLI (recommandé)
dotnet add package NLog

// Via Package Manager Console
Install-Package NLog

// Pour ASP.NET Core, installez également l'intégration :
dotnet add package NLog.Web.AspNetCore

Après l'installation, vous devrez créer un fichier de configuration nlog.config à la racine du projet (ou configurer NLog par programmation).

3. Démarrage rapide — exemple minimal fonctionnel

Créez une application console et ajoutez le fichier nlog.config (clic droit sur le projet → Add → New Item → XML File → nommez-le nlog.config). Insérez-y :

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <!-- Cible : où écrire les logs -->
    <targets>
        <target name="console" xsi:type="Console" layout="${longdate} | ${level:uppercase=true} | ${message} ${exception:format=ToString}" />
        <target name="file" xsi:type="File" fileName="${basedir}/logs/app-${shortdate}.log"
                layout="${longdate} | ${level:uppercase=true} | ${logger} | ${message} ${exception:format=ToString}" />
    </targets>

    <!-- Règles de routage -->
    <rules>
        <logger name="*" minlevel="Debug" writeTo="console,file" />
    </rules>
</nlog>

Écrivons maintenant le code dans Program.cs :

using NLog;

public class Program
{
    // Création du logger pour la classe actuelle
    private static readonly Logger Logger = LogManager.GetCurrentClassLogger();

    public static void Main(string[] args)
    {
        Logger.Info("Application démarrée");
        
        try
        {
            var result = Divide(10, 0);
            Logger.Debug($"Résultat : {result}");
        }
        catch (Exception ex)
        {
            Logger.Error(ex, "Erreur lors de la division");
        }
        
        Logger.Info("Application terminée");
    }
    
    static int Divide(int a, int b)
    {
        return a / b;
    }
}

Exécutez l'application. Vous devriez voir les logs dans la console et, après exécution, un fichier logs/app-YYYY-MM-DD.log contenant les mêmes informations.

4. Configuration avancée

NLog offre une configuration extrêmement flexible. Voici quelques exemples avancés :

4.1. Filtrage par niveau et par espace de noms

<rules>
    <!-- Logs Debug et supérieurs pour tous les espaces de noms -->
    <logger name="*" minlevel="Debug" writeTo="console" />
    <!-- Logs Warning et supérieurs pour le namespace MonApp.Services -->
    <logger name="MonApp.Services.*" minlevel="Warn" writeTo="file" />
    <!-- Désactiver les logs de Microsoft -->
    <logger name="Microsoft.*" maxlevel="Info" final="true" />
</rules>

4.2. Utilisation de variables

<nlog>
    <variable name="logDirectory" value="${basedir}/logs" />
    <variable name="logLayout" value="${longdate} | ${level:uppercase=true} | ${message}" />
    
    <targets>
        <target name="file" xsi:type="File" fileName="${logDirectory}/app.log" layout="${logLayout}" />
    </targets>
</nlog>

5. Bonnes pratiques

• Utilisez les niveaux de log appropriés : Trace pour le débogage détaillé, Debug pour les informations de développement, Info pour les événements normaux, Warn pour les situations anormales, Error pour les erreurs récupérables, Fatal pour les erreurs critiques.
• Évitez de logger des informations sensibles : mots de passe, numéros de carte de crédit, données personnelles.
• Structurez vos messages de log : incluez un contexte (ID utilisateur, ID de transaction) pour faciliter le débogage.
• Utilisez l'écriture asynchrone pour les applications à forte charge.
• Archivez et nettoyez régulièrement vos fichiers de log pour éviter de saturer le disque.

6. Conclusion

NLog est un outil indispensable pour tout développeur .NET. Sa flexibilité, ses performances et sa vaste communauté en font le choix idéal pour le logging dans vos applications. Que vous débutiez ou que vous soyez un expert, NLog s'adapte à tous vos besoins.

Pour aller plus loin, consultez la documentation officielle et n'hésitez pas à explorer les nombreux exemples disponibles sur GitHub.