Partager via

Conseils de journalisation pour les auteurs de bibliothèques .NET

En tant qu’auteur de bibliothèque, exposer la journalisation est un excellent moyen de fournir aux utilisateurs un aperçu des mécanismes internes de votre bibliothèque. Cette aide vous aide à exposer la journalisation de manière cohérente avec d’autres bibliothèques et frameworks .NET. Il vous permet également d’éviter les goulots d’étranglement de performance courants.

Quand utiliser l’interface ILoggerFactory

Lors de la rédaction d'une bibliothèque qui émet des journaux, vous avez besoin d'un objet ILogger pour enregistrer les journaux. Pour obtenir cet objet, votre API peut accepter un ILogger<TCategoryName> paramètre ou accepter un ILoggerFactory après lequel vous appelez ILoggerFactory.CreateLogger. Quelle approche doit être recommandée ?

  • Lorsque vous avez besoin d’un objet de journalisation qui peut être transmis à plusieurs classes afin que tous puissent émettre des journaux, utilisez ILoggerFactory. Il est recommandé que chaque classe crée des journaux d’activité avec une catégorie distincte, nommée de la même façon que la classe. Pour ce faire, vous avez besoin de l'usine pour créer des objets ILogger<TCategoryName> uniques pour chaque classe qui journalise. Les exemples courants incluent des API de point d’entrée publique pour une bibliothèque ou des constructeurs publics de types susceptibles de créer des classes d’assistance en interne.
  • Lorsque vous avez besoin d’un objet de journalisation qui n’est utilisé qu’à l’intérieur d’une classe et qui n’est jamais partagé, utilisez ILogger<TCategoryName>, où TCategoryName est le type qui produit les journaux. Un exemple courant est un constructeur pour une classe créée par l’injection de dépendances.

Si vous concevez une API publique qui doit rester stable au fil du temps, gardez à l’esprit que vous souhaiterez peut-être refactoriser votre implémentation interne à l’avenir. Même si une classe ne crée pas initialement de types d’assistance internes, cela peut changer à mesure que le code évolue. L’utilisation ILoggerFactory permet de créer ILogger<TCategoryName> des objets pour toutes les nouvelles classes sans modifier l’API publique.

Pour plus d’informations, consultez Comment les règles de filtrage sont appliquées.

Préférer la journalisation générée par la source

L’API ILogger prend en charge deux approches pour utiliser l’API. Vous pouvez appeler des méthodes telles que LoggerExtensions.LogError et LoggerExtensions.LogInformation, ou utiliser le générateur de source de journalisation pour définir des méthodes de journalisation fortement typées. Pour la plupart des situations, le générateur de code source est recommandé, car il offre des performances supérieures et un typage plus strict. Il isole également les problèmes spécifiques à la journalisation tels que les modèles de message, les ID et les niveaux de journalisation du code appelant. L’approche non générée par la source est principalement utile pour les scénarios où vous êtes prêt à renoncer à ces avantages pour rendre le code plus concis.

using Microsoft.Extensions.Logging;

namespace Logging.LibraryAuthors;

internal static partial class LogMessages
{
    [LoggerMessage(
        Message = "Sold {Quantity} of {Description}",
        Level = LogLevel.Information)]
    internal static partial void LogProductSaleDetails(
        this ILogger logger,
        int quantity,
        string description);
}

Code précédent :

  • Définit un partial class nommé LogMessages, permettant ainsi de l'utiliser pour définir des méthodes d'extension sur le type ILogger.
  • Décore une méthode d’extension LogProductSaleDetails avec l'attribut LoggerMessage et le modèle Message.
  • Déclare LogProductSaleDetails, qui étend le ILogger et accepte un quantity et description.

Conseil / Astuce

Vous pouvez passer au code généré par la source pendant le débogage, car il fait partie du même assembly que le code qui l’appelle.

Utiliser IsEnabled pour éviter une évaluation coûteuse des paramètres

Il peut y avoir des situations où l’évaluation des paramètres est coûteuse. En développant l’exemple précédent, imaginez que le description paramètre est un string paramètre coûteux à calculer. Peut-être que le produit vendu obtient une description de produit conviviale et s’appuie sur une requête de base de données ou la lecture à partir d’un fichier. Dans ces situations, vous pouvez demander au générateur source d’ignorer la IsEnabled garde et d’ajouter manuellement le IsEnabled garde sur le site d’appel. Cela permet à l’utilisateur de déterminer où le garde est appelé et garantit que les paramètres susceptibles d’être coûteux pour le calcul ne sont évalués que si nécessaire. Considérez le code suivant :

using Microsoft.Extensions.Logging;

namespace Logging.LibraryAuthors;

internal static partial class LogMessages
{
    [LoggerMessage(
        Message = "Sold {Quantity} of {Description}",
        Level = LogLevel.Information,
        SkipEnabledCheck = true)]
    internal static partial void LogProductSaleDetails(
        this ILogger logger,
        int quantity,
        string description);
}

Lorsque la LogProductSaleDetails méthode d’extension est appelée, la IsEnabled protection est invoquée manuellement et l’évaluation coûteuse des paramètres est limitée au moment où elle est nécessaire. Considérez le code suivant :

if (_logger.IsEnabled(LogLevel.Information))
{
    // Expensive parameter evaluation
    var description = product.GetFriendlyProductDescription();

    _logger.LogProductSaleDetails(
        quantity,
        description);
}

Pour plus d’informations, consultez Génération de sources de journalisation au moment de la compilation et la journalisation hautes performances dans .NET.

Éviter l’interpolation de chaîne dans la journalisation

Une erreur courante consiste à utiliser l’interpolation de chaîne pour générer des messages de journal. L’interpolation de chaîne dans la journalisation est problématique pour les performances, car la chaîne est évaluée même si la chaîne correspondante LogLevel n’est pas activée. Au lieu d’interpolation de chaîne, utilisez le modèle de message de journal, la mise en forme et la liste d’arguments. Pour plus d’informations, consultez Journalisation dans .NET : Modèle de message de journal.

Utiliser les valeurs par défaut de journalisation no-op

Lorsque vous utilisez une bibliothèque qui expose des API de journalisation qui s’attendent à un ILogger ou ILoggerFactory, il peut arriver que vous ne souhaitiez pas fournir d’enregistreur d’événements. Dans ces cas, le package NuGet Microsoft.Extensions.Logging.Abstractions fournit des valeurs par défaut de journalisation no-op.

Les consommateurs de bibliothèque peuvent par défaut utiliser la journalisation null si aucun ILoggerFactory n’est fourni. L’utilisation de la journalisation null diffère de la définition des types comme étant nullables (ILoggerFactory?), car les types ne sont pas null. Ces types fondés sur la commodité ne journalisent rien et sont essentiellement des opérations sans effet. Envisagez d’utiliser l’un des types d’abstraction disponibles le cas échéant :

  • Last updated on