Journalisation dans .NET Core et ASP.NET CoreLogging in .NET Core and ASP.NET Core

Par Kirk Larkin, Juergen Gutsch et Rick AndersonBy Kirk Larkin, Juergen Gutsch and Rick Anderson

.NET Core prend en charge une API de journalisation qui fonctionne avec différents fournisseurs de journalisation tiers et intégrés..NET Core supports a logging API that works with a variety of built-in and third-party logging providers. Cet article explique comment utiliser cette API de journalisation avec les fournisseurs de journalisation intégrés.This article shows how to use the logging API with built-in providers.

La plupart des exemples de code présentés dans cet article proviennent d’applications ASP.NET Core.Most of the code examples shown in this article are from ASP.NET Core apps. Les parties spécifiques à la journalisation de ces extraits de code s’appliquent à n’importe quelle application .NET Core qui utilise l' hôte générique.The logging-specific parts of these code snippets apply to any .NET Core app that uses the Generic Host. Les modèles d’application Web ASP.NET Core utilisent l’hôte générique.The ASP.NET Core web app templates use the Generic Host.

Afficher ou télécharger l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

Fournisseurs de journalisationLogging providers

Les fournisseurs de journalisation stockent les journaux, à l’exception du Console fournisseur qui affiche les journaux.Logging providers store logs, except for the Console provider which displays logs. Par exemple, le fournisseur Azure Application Insights stocke les journaux dans Azure Application Insights.For example, the Azure Application Insights provider stores logs in Azure Application Insights. Plusieurs fournisseurs peuvent être activés.Multiple providers can be enabled.

Les modèles d’application Web ASP.NET Core par défaut :The default ASP.NET Core web app templates:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Le code précédent montre la Program classe créée avec les modèles d’application web ASP.net core.The preceding code shows the Program class created with the ASP.NET Core web app templates. Les sections suivantes fournissent des exemples basés sur les modèles d’application Web ASP.NET Core, qui utilisent l’hôte générique.The next several sections provide samples based on the ASP.NET Core web app templates, which use the Generic Host. Les applications de console non-hôte sont présentées plus loin dans ce document.Non-host console apps are discussed later in this document.

Pour remplacer l’ensemble par défaut des fournisseurs de journalisation ajoutés par Host.CreateDefaultBuilder , appelez ClearProviders et ajoutez les fournisseurs de journalisation requis.To override the default set of logging providers added by Host.CreateDefaultBuilder, call ClearProviders and add the required logging providers. Par exemple, le code suivant :For example, the following code:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Pour obtenir des fournisseurs supplémentaires, consultez :For additional providers, see:

Créer des journauxCreate logs

Pour créer des journaux, utilisez un ILogger<TCategoryName> objet à partir de l' injection de dépendances (di).To create logs, use an ILogger<TCategoryName> object from dependency injection (DI).

L’exemple suivant :The following example:

  • Crée un enregistreur d’événements, ILogger<AboutModel> , qui utilise une catégorie de journal du nom qualifié complet du type AboutModel .Creates a logger, ILogger<AboutModel>, which uses a log category of the fully qualified name of the type AboutModel. La catégorie du journal est une chaîne associée à chaque journal.The log category is a string that is associated with each log.
  • Appels LogInformation à consigner au Information niveau.Calls LogInformation to log at the Information level. Le niveau du journal indique la gravité de l’événement consigné.The Log level indicates the severity of the logged event.
public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }
    public string Message { get; set; }

    public void OnGet()
    {
        Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
        _logger.LogInformation(Message);
    }
}

Les niveaux et les catégories sont expliqués plus en détail plus loin dans ce document.Levels and categories are explained in more detail later in this document.

Pour plus d’informations sur Blazor , consultez créer des journaux dans Blazor et Blazor WebAssembly dans ce document.For information on Blazor, see Create logs in Blazor and Blazor WebAssembly in this document.

Créer des journaux dans main et Startup montre comment créer des journaux dans Main et Startup .Create logs in Main and Startup shows how to create logs in Main and Startup.

Configuration de la journalisationConfigure logging

La configuration de la journalisation est généralement fournie par la Logging section de appSettings. {Environment} fichiers . JSON .Logging configuration is commonly provided by the Logging section of appsettings.{Environment}.json files. Le appsettings.Development.jssuivant sur le fichier est généré par les modèles d’application Web ASP.net Core :The following appsettings.Development.json file is generated by the ASP.NET Core web app templates:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Dans le code JSON précédent :In the preceding JSON:

  • Les "Default" "Microsoft" catégories, et "Microsoft.Hosting.Lifetime" sont spécifiées.The "Default", "Microsoft", and "Microsoft.Hosting.Lifetime" categories are specified.
  • La "Microsoft" catégorie s’applique à toutes les catégories qui commencent par "Microsoft" .The "Microsoft" category applies to all categories that start with "Microsoft". Par exemple, ce paramètre s’applique à la "Microsoft.AspNetCore.Routing.EndpointMiddleware" catégorie.For example, this setting applies to the "Microsoft.AspNetCore.Routing.EndpointMiddleware" category.
  • La "Microsoft" catégorie enregistre les journaux au niveau du journal et au niveau Warning supérieur.The "Microsoft" category logs at log level Warning and higher.
  • La catégorie "Microsoft.Hosting.Lifetime" est plus spécifique que la catégorie "Microsoft" , de sorte que la "Microsoft.Hosting.Lifetime" catégorie enregistre les journaux au niveau du journal « information » et supérieur.The "Microsoft.Hosting.Lifetime" category is more specific than the "Microsoft" category, so the "Microsoft.Hosting.Lifetime" category logs at log level "Information" and higher.
  • Un module fournisseur d’informations spécifique n’étant pas spécifié, LogLevel s’applique à tous les fournisseurs de journalisation activés, à l’exception du journal des événements Windows.A specific log provider is not specified, so LogLevel applies to all the enabled logging providers except for the Windows EventLog.

La Logging propriété peut avoir LogLevel et enregistrer les propriétés du fournisseur.The Logging property can have LogLevel and log provider properties. LogLevelSpécifie le niveau minimal à enregistrer pour les catégories sélectionnées.The LogLevel specifies the minimum level to log for selected categories. Dans le code JSON précédent, les Information Warning niveaux de journalisation sont spécifiés.In the preceding JSON, Information and Warning log levels are specified. LogLevelindique la gravité du journal et les plages de 0 à 6 :LogLevel indicates the severity of the log and ranges from 0 to 6:

Trace= 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5 et None = 6.Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5, and None = 6.

Lorsqu’un LogLevel est spécifié, la journalisation est activée pour les messages au niveau spécifié et supérieur.When a LogLevel is specified, logging is enabled for messages at the specified level and higher. Dans le code JSON précédent, la Default catégorie est journalisée pour Information et les versions ultérieures.In the preceding JSON, the Default category is logged for Information and higher. Par exemple, les messages,, Information Warning Error et Critical sont journalisés.For example, Information, Warning, Error, and Critical messages are logged. Si aucun LogLevel n’est spécifié, la journalisation est définie par défaut sur le Information niveau.If no LogLevel is specified, logging defaults to the Information level. Pour plus d’informations, consultez niveaux de journalisation.For more information, see Log levels.

Une propriété de fournisseur peut spécifier une LogLevel propriété.A provider property can specify a LogLevel property. LogLevelsous un fournisseur spécifie les niveaux de journalisation pour ce fournisseur, et remplace les paramètres du journal non fournisseur.LogLevel under a provider specifies levels to log for that provider, and overrides the non-provider log settings. Prenez en compte les appsettings.jssuivantes sur le fichier :Consider the following appsettings.json file:

{
  "Logging": {
    "LogLevel": { // All providers, LogLevel applies to all the enabled providers.
      "Default": "Error", // Default logging, Error and higher.
      "Microsoft": "Warning" // All Microsoft* categories, Warning and higher.
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information", // Overrides preceding LogLevel:Default setting.
        "Microsoft.Hosting": "Trace" // Debug:Microsoft.Hosting category.
      }
    },
    "EventSource": { // EventSource provider
      "LogLevel": {
        "Default": "Warning" // All categories of EventSource provider.
      }
    }
  }
}

Paramètres dans les Logging.{providername}.LogLevel paramètres de remplacement dans Logging.LogLevel .Settings in Logging.{providername}.LogLevel override settings in Logging.LogLevel. Dans le code JSON précédent, le Debug niveau de journalisation par défaut du fournisseur est défini sur Information :In the preceding JSON, the Debug provider's default log level is set to Information:

Logging:Debug:LogLevel:Default:Information

Le paramètre précédent spécifie le Information niveau de journalisation pour chaque Logging:Debug: catégorie, à l’exception de Microsoft.Hosting .The preceding setting specifies the Information log level for every Logging:Debug: category except Microsoft.Hosting. Quand une catégorie spécifique est indiquée, la catégorie spécifique remplace la catégorie par défaut.When a specific category is listed, the specific category overrides the default category. Dans le JSON précédent, les Logging:Debug:LogLevel catégories "Microsoft.Hosting" et "Default" remplacent les paramètres dansLogging:LogLevelIn the preceding JSON, the Logging:Debug:LogLevel categories "Microsoft.Hosting" and "Default" override the settings in Logging:LogLevel

Le niveau de journal minimal peut être spécifié pour l’un des éléments suivants :The minimum log level can be specified for any of:

  • Fournisseurs spécifiques : par exemple,Logging:EventSource:LogLevel:Default:InformationSpecific providers: For example, Logging:EventSource:LogLevel:Default:Information
  • Catégories spécifiques : par exemple,Logging:LogLevel:Microsoft:WarningSpecific categories: For example, Logging:LogLevel:Microsoft:Warning
  • Tous les fournisseurs et toutes les catégories :Logging:LogLevel:Default:WarningAll providers and all categories: Logging:LogLevel:Default:Warning

Les journaux situés en dessous du niveau minimal ne sont pas:Any logs below the minimum level are not:

  • Passé au fournisseur.Passed to the provider.
  • Consigné ou affiché.Logged or displayed.

Pour supprimer tous les journaux, spécifiez LogLevel. None.To suppress all logs, specify LogLevel.None. LogLevel.Nonea une valeur de 6, qui est supérieure à LogLevel.Critical (5).LogLevel.None has a value of 6, which is higher than LogLevel.Critical (5).

Si un fournisseur prend en charge les étendues de journal, IncludeScopes indique s’ils sont activés.If a provider supports log scopes, IncludeScopes indicates whether they're enabled. Pour plus d’informations, consultez étendues de journauxFor more information, see log scopes

Le appsettings.jssuivant sur le fichier contient tous les fournisseurs activés par défaut :The following appsettings.json file contains all the providers enabled by default:

{
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Error",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information" // Overrides preceding LogLevel:Default setting.
      }
    },
    "Console": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "EventSource": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "EventLog": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "AzureAppServicesFile": {
      "IncludeScopes": true,
      "LogLevel": {
        "Default": "Warning"
      }
    },
    "AzureAppServicesBlob": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

Dans l’exemple précédent :In the preceding sample:

  • Les catégories et les niveaux ne sont pas des valeurs suggérées.The categories and levels are not suggested values. L’exemple est fourni pour afficher tous les fournisseurs par défaut.The sample is provided to show all the default providers.
  • Paramètres dans les Logging.{providername}.LogLevel paramètres de remplacement dans Logging.LogLevel .Settings in Logging.{providername}.LogLevel override settings in Logging.LogLevel. Par exemple, le niveau dans Debug.LogLevel.Default remplace le niveau dans LogLevel.Default .For example, the level in Debug.LogLevel.Default overrides the level in LogLevel.Default.
  • Chaque alias de fournisseur par défaut est utilisé.Each default provider alias is used. Chaque fournisseur définit un alias qui peut être utilisé dans la configuration à la place du nom de type complet.Each provider defines an alias that can be used in configuration in place of the fully qualified type name. Les alias des fournisseurs intégrés sont les suivants :The built-in providers aliases are:
    • ConsoleConsole
    • DébogageDebug
    • EventSourceEventSource
    • EventLogEventLog
    • AzureAppServicesFileAzureAppServicesFile
    • AzureAppServicesBlobAzureAppServicesBlob
    • ApplicationInsightsApplicationInsights

Définir le niveau de journalisation à l’aide d’une ligne de commande, de variables d’environnement et d’autres configurationsSet log level by command line, environment variables, and other configuration

Le niveau de journal peut être défini par l’un des fournisseurs de configuration.Log level can be set by any of the configuration providers.

Le : séparateur ne fonctionne pas avec les clés hiérarchiques de variable d’environnement sur toutes les plateformes.The : separator doesn't work with environment variable hierarchical keys on all platforms. __, le double trait de soulignement, est :__, the double underscore, is:

  • Pris en charge par toutes les plateformes.Supported by all platforms. Par exemple, le : séparateur n’est pas pris en charge par __ bash, mais est.For example, the : separator is not supported by Bash, but __ is.
  • Automatiquement remplacé par un:Automatically replaced by a :

Les commandes suivantes :The following commands:

  • Affectez à la clé d’environnement la Logging:LogLevel:Microsoft valeur Information sur Windows.Set the environment key Logging:LogLevel:Microsoft to a value of Information on Windows.
  • Testez les paramètres lors de l’utilisation d’une application créée avec les modèles d’application Web ASP.NET Core.Test the settings when using an app created with the ASP.NET Core web application templates. La dotnet run commande doit être exécutée dans le répertoire du projet après l’utilisation de set .The dotnet run command must be run in the project directory after using set.
set Logging__LogLevel__Microsoft=Information
dotnet run

Le paramètre d’environnement précédent :The preceding environment setting:

  • Est défini uniquement dans les processus lancés à partir de la fenêtre de commande dans laquelle ils ont été définis.Is only set in processes launched from the command window they were set in.
  • N’est pas lu par les navigateurs lancés avec Visual Studio.Isn't read by browsers launched with Visual Studio.

La commande setx suivante définit également la clé et la valeur de l’environnement sur Windows.The following setx command also sets the environment key and value on Windows. Contrairement à set , setx les paramètres sont conservés.Unlike set, setx settings are persisted. Le /M commutateur définit la variable dans l’environnement système.The /M switch sets the variable in the system environment. Si /M n’est pas utilisé, une variable d’environnement utilisateur est définie.If /M isn't used, a user environment variable is set.

setx Logging__LogLevel__Microsoft=Information /M

Dans Azure App service, sélectionnez nouveau paramètre d’application dans la page paramètres > configuration .On Azure App Service, select New application setting on the Settings > Configuration page. Azure App Service paramètres de l’application sont les suivants :Azure App Service application settings are:

  • Chiffré au repos et transmis sur un canal chiffré.Encrypted at rest and transmitted over an encrypted channel.
  • Exposés en tant que variables d’environnement.Exposed as environment variables.

Pour plus d’informations, consultez Azure Apps : remplacer la configuration de l’application à l’aide du portail Azure.For more information, see Azure Apps: Override app configuration using the Azure Portal.

Pour plus d’informations sur la définition de valeurs de configuration ASP.NET Core à l’aide de variables d’environnement, consultez variables d’environnement.For more information on setting ASP.NET Core configuration values using environment variables, see environment variables. Pour plus d’informations sur l’utilisation d’autres sources de configuration, notamment la ligne de commande, Azure Key Vault, la configuration de Azure App, d’autres formats de fichier, etc., consultez Configuration dans ASP.NET Core .For information on using other configuration sources, including the command line, Azure Key Vault, Azure App Configuration, other file formats, and more, see Configuration dans ASP.NET Core.

Mode d’application des règles de filtreHow filtering rules are applied

À la création d’un objet ILogger<TCategoryName>, l’objet ILoggerFactory sélectionne une seule règle à appliquer à cet enregistrement d’événements par fournisseur.When an ILogger<TCategoryName> object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. Tous les messages écrits par une instance ILogger sont filtrés selon les règles sélectionnées.All messages written by an ILogger instance are filtered based on the selected rules. La règle la plus spécifique pour chaque paire fournisseur et catégorie est sélectionnée parmi les règles disponibles.The most specific rule for each provider and category pair is selected from the available rules.

L’algorithme suivant est utilisé pour chaque fournisseur quand un objet ILogger est créé pour une catégorie donnée :The following algorithm is used for each provider when an ILogger is created for a given category:

  • Sélectionnez toutes les règles qui correspondent au fournisseur ou à son alias.Select all rules that match the provider or its alias. Si aucune correspondance n’est trouvée, sélectionnez toutes les règles avec un fournisseur vide.If no match is found, select all rules with an empty provider.
  • À partir du résultat de l’étape précédente, sélectionnez les règles ayant le plus long préfixe de catégorie correspondant.From the result of the preceding step, select rules with longest matching category prefix. Si aucune correspondance n’est trouvée, sélectionnez toutes les règles qui ne spécifient pas de catégorie.If no match is found, select all rules that don't specify a category.
  • Si plusieurs règles sont sélectionnées, prenez la dernière.If multiple rules are selected, take the last one.
  • Si aucune règle n’est sélectionnée, utilisez MinimumLevel.If no rules are selected, use MinimumLevel.

Journalisation de la sortie de dotnet Run et de Visual StudioLogging output from dotnet run and Visual Studio

Les journaux créés avec les fournisseurs de journalisation par défaut sont affichés :Logs created with the default logging providers are displayed:

  • Dans Visual StudioIn Visual Studio
    • Dans la fenêtre sortie de débogage lors du débogage.In the Debug output window when debugging.
    • Dans la fenêtre serveur Web ASP.NET Core.In the ASP.NET Core Web Server window.
  • Dans la fenêtre de console lorsque l’application est exécutée dotnet run .In the console window when the app is run with dotnet run.

Les journaux qui commencent par des catégories « Microsoft » proviennent du code ASP.NET Core Framework.Logs that begin with "Microsoft" categories are from ASP.NET Core framework code. Les ASP.NET Core et le code d’application utilisent les mêmes API de journalisation et fournisseurs.ASP.NET Core and application code use the same logging API and providers.

Catégorie de journalLog category

Lorsqu’un ILogger objet est créé, une catégorie est spécifiée.When an ILogger object is created, a category is specified. Cette catégorie est incluse dans tous les messages de journal créés par cette instance de ILogger.That category is included with each log message created by that instance of ILogger. La chaîne de catégorie est arbitraire, mais la Convention consiste à utiliser le nom de la classe.The category string is arbitrary, but the convention is to use the class name. Par exemple, dans un contrôleur, le nom peut être "TodoApi.Controllers.TodoController" .For example, in a controller the name might be "TodoApi.Controllers.TodoController". Les applications Web ASP.NET Core utilisent ILogger<T> pour recevoir automatiquement une ILogger instance qui utilise le nom de type qualifié complet de T comme catégorie :The ASP.NET Core web apps use ILogger<T> to automatically get an ILogger instance that uses the fully qualified type name of T as the category:

public class PrivacyModel : PageModel
{
    private readonly ILogger<PrivacyModel> _logger;

    public PrivacyModel(ILogger<PrivacyModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.PrivacyModel called.");
    }
}

Pour spécifier explicitement la catégorie, appelez ILoggerFactory.CreateLogger :To explicitly specify the category, call ILoggerFactory.CreateLogger:

public class ContactModel : PageModel
{
    private readonly ILogger _logger;

    public ContactModel(ILoggerFactory logger)
    {
        _logger = logger.CreateLogger("TodoApi.Pages.ContactModel");
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.ContactModel called.");
    }

ILogger<T> équivaut à appeler CreateLogger avec le nom de type complet T.ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

Log levelLog level

Le tableau suivant répertorie les LogLevel valeurs, la Log{LogLevel} méthode d’extension de commodité et l’utilisation suggérée :The following table lists the LogLevel values, the convenience Log{LogLevel} extension method, and the suggested usage:

LogLevelLogLevel ValeurValue MéthodeMethod DescriptionDescription
TraceTrace 00 LogTrace Contiennent les messages les plus détaillés.Contain the most detailed messages. Ces messages peuvent contenir des données d’application sensibles.These messages may contain sensitive app data. Ces messages sont désactivés par défaut et ne doivent pas être activés en production.These messages are disabled by default and should not be enabled in production.
DéboguerDebug 11 LogDebug Pour le débogage et le développement.For debugging and development. Utilisez avec précaution en production en raison du volume élevé.Use with caution in production due to the high volume.
InformationsInformation 22 LogInformation Effectue le suivi du déroulement général de l’application.Tracks the general flow of the app. Peut avoir une valeur à long terme.May have long-term value.
AvertissementWarning 33 LogWarning Pour les événements anormaux ou inattendus.For abnormal or unexpected events. Comprend généralement des erreurs ou des conditions qui ne provoquent pas l’échec de l’application.Typically includes errors or conditions that don't cause the app to fail.
ErrorError 44 LogError Fournit des informations sur des erreurs et des exceptions qui ne peuvent pas être gérées.For errors and exceptions that cannot be handled. Ces messages indiquent un échec dans l’opération ou la demande en cours, et non dans l’ensemble de l’application.These messages indicate a failure in the current operation or request, not an app-wide failure.
CriticalCritical 55 LogCritical Fournit des informations sur des échecs qui nécessitent un examen immédiat.For failures that require immediate attention. Exemples : perte de données, espace disque insuffisant.Examples: data loss scenarios, out of disk space.
AucunNone 66 Spécifie qu’une catégorie de journalisation ne doit écrire aucun message.Specifies that a logging category should not write any messages.

Dans le tableau précédent, la LogLevel est indiquée du niveau de gravité le plus bas au plus élevé.In the previous table, the LogLevel is listed from lowest to highest severity.

Le premier paramètre de la méthode de journalisation , LogLevel , indique la gravité du journal.The Log method's first parameter, LogLevel, indicates the severity of the log. Au lieu d’appeler Log(LogLevel, ...) , la plupart des développeurs appellent les méthodes d’extension log {LogLevel} .Rather than calling Log(LogLevel, ...), most developers call the Log{LogLevel} extension methods. Les Log{LogLevel} méthodes d’extension appellent la méthode log et spécifient LogLevel.The Log{LogLevel} extension methods call the Log method and specify the LogLevel. Par exemple, les deux appels de journalisation suivants sont fonctionnellement équivalents et produisent le même journal :For example, the following two logging calls are functionally equivalent and produce the same log:

[HttpGet]
public IActionResult Test1(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);

    _logger.Log(LogLevel.Information, MyLogEvents.TestItem, routeInfo);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItemest l’ID de l’événement.MyLogEvents.TestItem is the event ID. MyLogEventsfait partie de l’exemple d’application et s’affiche dans la section enregistrer l’ID d’événement .MyLogEvents is part of the sample app and is displayed in the Log event ID section.

MyDisplayRouteInfo et ToCtxString sont fournis par le package NuGet Rick.Docs. Samples. RouteInfo .MyDisplayRouteInfo and ToCtxString are provided by the Rick.Docs.Samples.RouteInfo NuGet package. Les méthodes affichent les Controller informations de routage.The methods display Controller route information.

Le code suivant crée des journaux Information et Warning :The following code creates Information and Warning logs:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Dans le code précédent, le premier Log{LogLevel} paramètre, MyLogEvents.GetItem , est l' ID d’événement du journal.In the preceding code, the first Log{LogLevel} parameter,MyLogEvents.GetItem, is the Log event ID. Le deuxième paramètre est un modèle de message contenant des espaces réservés pour les valeurs d’argument fournies par les autres paramètres de méthode.The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. Les paramètres de méthode sont expliqués dans la section modèle de message , plus loin dans ce document.The method parameters are explained in the message template section later in this document.

Appelez la Log{LogLevel} méthode appropriée pour contrôler la quantité de sortie de journal écrite sur un support de stockage particulier.Call the appropriate Log{LogLevel} method to control how much log output is written to a particular storage medium. Par exemple :For example:

  • En production :In production:
    • La journalisation au Trace niveau des ou de Information génère un volume important de messages journaux détaillés.Logging at the Trace or Information levels produces a high-volume of detailed log messages. Pour contrôler les coûts et ne pas dépasser les limites de stockage des données, Trace Information les messages de journal et de niveau dans un magasin de données volumineux et à faible coût.To control costs and not exceed data storage limits, log Trace and Information level messages to a high-volume, low-cost data store. Envisagez Trace de limiter et Information à des catégories spécifiques.Consider limiting Trace and Information to specific categories.
    • La journalisation au Warning Critical niveau des niveaux doit produire peu de messages de journal.Logging at Warning through Critical levels should produce few log messages.
      • Les coûts et les limites de stockage ne sont généralement pas un problème.Costs and storage limits usually aren't a concern.
      • Certains journaux offrent davantage de flexibilité dans les choix de magasins de données.Few logs allow more flexibility in data store choices.
  • En cours de développement :In development:
    • Défini sur Warning.Set to Warning.
    • Ajoutez Trace Information des messages ou lors de la résolution des problèmes.Add Trace or Information messages when troubleshooting. Pour limiter la sortie, Trace la définition ou Information uniquement pour les catégories en cours d’investigation.To limit output, set Trace or Information only for the categories under investigation.

ASP.NET Core écrit des journaux pour les événements de framework.ASP.NET Core writes logs for framework events. Par exemple, considérez la sortie du journal pour :For example, consider the log output for:

  • RazorApplication pages créée avec les modèles ASP.net core.A Razor Pages app created with the ASP.NET Core templates.
  • Journalisation défini surLogging:Console:LogLevel:Microsoft:InformationLogging set to Logging:Console:LogLevel:Microsoft:Information
  • Navigation vers la page confidentialité :Navigation to the Privacy page:
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
      Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
      Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
      Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
      Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
      Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
      Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 149.3023ms 200 text/html; charset=utf-8

Le code JSON suivant définit Logging:Console:LogLevel:Microsoft:Information :The following JSON sets Logging:Console:LogLevel:Microsoft:Information:

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

ID d’événement de logLog event ID

Chaque journal peut spécifier un ID d’événement.Each log can specify an event ID. L’exemple d’application utilise la MyLogEvents classe pour définir les ID d’événement :The sample app uses the MyLogEvents class to define event IDs:

public class MyLogEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems     = 1001;
    public const int GetItem       = 1002;
    public const int InsertItem    = 1003;
    public const int UpdateItem    = 1004;
    public const int DeleteItem    = 1005;

    public const int TestItem      = 3000;

    public const int GetItemNotFound    = 4000;
    public const int UpdateItemNotFound = 4001;
}
[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Un ID d’événement associe un jeu d’événements.An event ID associates a set of events. Par exemple, tous les journaux liés à l’affichage d’une liste d’éléments sur une page peuvent être 1001.For example, all logs related to displaying a list of items on a page might be 1001.

Le fournisseur de journalisation peut stocker l’ID d’événement dans un champ ID, dans le message de journalisation, ou pas du tout.The logging provider may store the event ID in an ID field, in the logging message, or not at all. Le fournisseur Debug n’affiche pas les ID d’événements.The Debug provider doesn't show event IDs. Le fournisseur Console affiche les ID d’événements entre crochets après la catégorie :The console provider shows event IDs in brackets after the category:

info: TodoApi.Controllers.TodoItemsController[1002]
      Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
      Get(1) NOT FOUND

Certains fournisseurs de journalisation stockent l’ID d’événement dans un champ, ce qui permet de filtrer l’ID.Some logging providers store the event ID in a field, which allows for filtering on the ID.

Modèle de message de journalLog message template

Chaque API de journal utilise un modèle de message.Each log API uses a message template. Ce dernier peut contenir des espaces réservés pour lesquels les arguments sont fournis.The message template can contain placeholders for which arguments are provided. Utilisez des noms et non des nombres pour les espaces réservés.Use names for the placeholders, not numbers.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

L’ordre des espaces réservés, pas leurs noms, détermine quels paramètres sont utilisés pour fournir leurs valeurs.The order of placeholders, not their names, determines which parameters are used to provide their values. Dans le code suivant, les noms de paramètres sont hors séquence dans le modèle de message :In the following code, the parameter names are out of sequence in the message template:

string p1 = "param1";
string p2 = "param2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);

Le code précédent crée un message de journal avec les valeurs de paramètre dans l’ordre :The preceding code creates a log message with the parameter values in sequence:

Parameter values: param1, param2

Cette approche permet aux fournisseurs de journalisation d’implémenter la journalisation sémantique ou structurée.This approach allows logging providers to implement semantic or structured logging. Les arguments proprement dits, et pas seulement le modèle de message mis en forme, sont transmis au système de journalisation.The arguments themselves are passed to the logging system, not just the formatted message template. Cela permet aux fournisseurs de journalisation de stocker les valeurs de paramètres en tant que champs.This enables logging providers to store the parameter values as fields. Par exemple, considérez la méthode d’enregistreur d’événements suivante :For example, consider the following logger method:

_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);

Par exemple, lors de la journalisation dans le stockage table Azure :For example, when logging to Azure Table Storage:

  • Chaque entité de table Azure peut avoir des ID RequestTime Propriétés et.Each Azure Table entity can have ID and RequestTime properties.
  • Les tables avec des propriétés simplifient les requêtes sur les données journalisées.Tables with properties simplify queries on logged data. Par exemple, une requête peut trouver tous les journaux d’une RequestTime plage donnée sans avoir à analyser le délai d’attente du message texte.For example, a query can find all logs within a particular RequestTime range without having to parse the time out of the text message.

Journaliser les exceptionsLog exceptions

Les méthodes d’enregistreur d’événements ont des surcharges qui prennent un paramètre d’exception :The logger methods have overloads that take an exception parameter:

[HttpGet("{id}")]
public IActionResult TestExp(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    try
    {
        if (id == 3)
        {
            throw new Exception("Test exception");
        }
    }
    catch (Exception ex)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, ex, "TestExp({Id})", id);
        return NotFound();
    }

    return ControllerContext.MyDisplayRouteInfo();
}

MyDisplayRouteInfo et ToCtxString sont fournis par le package NuGet Rick.Docs. Samples. RouteInfo .MyDisplayRouteInfo and ToCtxString are provided by the Rick.Docs.Samples.RouteInfo NuGet package. Les méthodes affichent les Controller informations de routage.The methods display Controller route information.

La journalisation des exceptions est spécifique au fournisseur.Exception logging is provider-specific.

Niveau de journalisation par défautDefault log level

Si le niveau de journalisation par défaut n’est pas défini, la valeur par défaut du niveau de journal est Information .If the default log level is not set, the default log level value is Information.

Par exemple, considérez l’application Web suivante :For example, consider the following web app:

  • Créé avec les modèles d’application Web ASP.NET.Created with the ASP.NET web app templates.
  • appsettings.jssur et appsettings.Development.jssur supprimé ou renommé.appsettings.json and appsettings.Development.json deleted or renamed.

Avec la configuration précédente, la navigation vers la page confidentialité ou d’origine génère de nombreux Trace Debug messages, et Information avec Microsoft dans le nom de catégorie.With the preceding setup, navigating to the privacy or home page produces many Trace, Debug, and Information messages with Microsoft in the category name.

Le code suivant définit le niveau de journalisation par défaut lorsque le niveau de journalisation par défaut n’est pas défini dans la configuration :The following code sets the default log level when the default log level is not set in configuration:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

En règle générale, les niveaux de journalisation doivent être spécifiés dans la configuration et non dans le code.Generally, log levels should be specified in configuration and not code.

fonction FilterFilter function

Une fonction de filtre est appelée pour tous les fournisseurs et toutes les catégories pour lesquels aucune règle n’est assignée par la configuration ou le code :A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
            {
                logging.AddFilter((provider, category, logLevel) =>
                {
                    if (provider.Contains("ConsoleLoggerProvider")
                        && category.Contains("Controller")
                        && logLevel >= LogLevel.Information)
                    {
                        return true;
                    }
                    else if (provider.Contains("ConsoleLoggerProvider")
                        && category.Contains("Microsoft")
                        && logLevel >= LogLevel.Information)
                    {
                        return true;
                    }
                    else
                    {
                        return false;
                    }
                });
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Le code précédent affiche les journaux de console lorsque la catégorie contient Controller ou Microsoft et que le niveau de journal est Information ou supérieur.The preceding code displays console logs when the category contains Controller or Microsoft and the log level is Information or higher.

En règle générale, les niveaux de journalisation doivent être spécifiés dans la configuration et non dans le code.Generally, log levels should be specified in configuration and not code.

Catégories ASP.NET Core et EF CoreASP.NET Core and EF Core categories

Le tableau suivant contient des catégories utilisées par ASP.NET Core et Entity Framework Core, avec des remarques sur les journaux :The following table contains some categories used by ASP.NET Core and Entity Framework Core, with notes about the logs:

CategoryCategory NotesNotes
Microsoft.AspNetCoreMicrosoft.AspNetCore Diagnostics ASP.NET Core généraux.General ASP.NET Core diagnostics.
Microsoft.AspNetCore.DataProtectionMicrosoft.AspNetCore.DataProtection Liste des clés considérées, trouvées et utilisées.Which keys were considered, found, and used.
Microsoft.AspNetCore.HostFilteringMicrosoft.AspNetCore.HostFiltering Hôtes autorisés.Hosts allowed.
Microsoft.AspNetCore.HostingMicrosoft.AspNetCore.Hosting Temps de traitement des requêtes HTTP et heure de démarrage.How long HTTP requests took to complete and what time they started. Liste des assemblys de démarrage d’hébergement chargés.Which hosting startup assemblies were loaded.
Microsoft.AspNetCore.MvcMicrosoft.AspNetCore.Mvc MVC et Razor Diagnostics.MVC and Razor diagnostics. Liaison de données, exécution de filtres, compilation de vues, sélection d’actions.Model binding, filter execution, view compilation, action selection.
Microsoft.AspNetCore.RoutingMicrosoft.AspNetCore.Routing Informations de correspondance des itinéraires.Route matching information.
Microsoft.AspNetCore.ServerMicrosoft.AspNetCore.Server Démarrage et arrêt de la connexion, et réponses persistantes.Connection start, stop, and keep alive responses. Informations du certificat HTTPS.HTTPS certificate information.
Microsoft.AspNetCore.StaticFilesMicrosoft.AspNetCore.StaticFiles Fichiers pris en charge.Files served.
Microsoft.EntityFrameworkCoreMicrosoft.EntityFrameworkCore Diagnostics Entity Framework Core généraux.General Entity Framework Core diagnostics. Activité et configuration de la base de données, détection des modifications, migrations.Database activity and configuration, change detection, migrations.

Pour afficher plus de catégories dans la fenêtre de la console, définissez appsettings.Development.jssur ce qui suit :To view more categories in the console window, set appsettings.Development.json to the following:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Trace",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Étendues de journalLog scopes

Une étendue peut regrouper un ensemble d’opérations logiques.A scope can group a set of logical operations. Ce regroupement permet de joindre les mêmes données à tous les journaux créés au sein d’un ensemble.This grouping can be used to attach the same data to each log that's created as part of a set. Par exemple, chaque journal créé dans le cadre du traitement d’une transaction peut contenir l’ID de la transaction.For example, every log created as part of processing a transaction can include the transaction ID.

Une étendue :A scope:

Les fournisseurs suivants prennent en charge les étendues :The following providers support scopes:

Utilisez une étendue en incluant les appels de l’enregistrement d’événements dans un bloc using :Use a scope by wrapping logger calls in a using block:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    TodoItem todoItem;

    using (_logger.BeginScope("using block message"))
    {
        _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

        todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            _logger.LogWarning(MyLogEvents.GetItemNotFound, 
                "Get({Id}) NOT FOUND", id);
            return NotFound();
        }
    }

    return ItemToDTO(todoItem);
}

Le code JSON suivant active des étendues pour le fournisseur de console :The following JSON enables scopes for the console provider:

{
  "Logging": {
    "Debug": {
      "LogLevel": {
        "Default": "Information"
      }
    },
    "Console": {
      "IncludeScopes": true, // Required to use Scopes.
      "LogLevel": {
        "Microsoft": "Warning",
        "Default": "Information"
      }
    },
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

Le code suivant active les étendues pour le fournisseur Console :The following code enables scopes for the console provider:

public class Scopes
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging((hostingContext, logging) =>
            {
                logging.ClearProviders();
                logging.AddConsole(options => options.IncludeScopes = true);
                logging.AddDebug();
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

En règle générale, la journalisation doit être spécifiée dans la configuration et non dans le code.Generally, logging should be specified in configuration and not code.

Fournisseurs de journalisation intégrésBuilt-in logging providers

ASP.NET Core comprend les fournisseurs de journalisation suivants :ASP.NET Core includes the following logging providers:

Pour plus d’informations sur stdout et le débogage de la journalisation avec le Module ASP.net Core, consultez Résoudre les problèmes de ASP.NET Core sur Azure App Service et IIS et Module ASP.NET Core .For information on stdout and debug logging with the ASP.NET Core Module, see Résoudre les problèmes de ASP.NET Core sur Azure App Service et IIS and Module ASP.NET Core.

ConsoleConsole

Le Console fournisseur journalise la sortie dans la console.The Console provider logs output to the console. Pour plus d’informations sur Console l’affichage des journaux dans le développement, consultez journalisation de la sortie de dotnet Run et de Visual Studio.For more information on viewing Console logs in development, see Logging output from dotnet run and Visual Studio.

DébogageDebug

Le Debug fournisseur écrit la sortie du journal à l’aide de la classe System. Diagnostics. Debug .The Debug provider writes log output by using the System.Diagnostics.Debug class. Appelle pour System.Diagnostics.Debug.WriteLine écrire dans le Debug fournisseur.Calls to System.Diagnostics.Debug.WriteLine write to the Debug provider.

Sur Linux, l' Debug emplacement du journal du fournisseur est dépendant de la distribution et peut être l’un des suivants :On Linux, the Debug provider log location is distribution-dependent and may be one of the following:

  • /var/log/message/var/log/message
  • /var/log/syslog/var/log/syslog

Source de l’événementEvent Source

Le EventSource fournisseur écrit dans une source d’événements multiplateforme portant le nom Microsoft-Extensions-Logging .The EventSource provider writes to a cross-platform event source with the name Microsoft-Extensions-Logging. Sur Windows, le fournisseur utilise ETW.On Windows, the provider uses ETW.

outils de trace dotnetdotnet trace tooling

L’outil dotnet-trace est un outil global de l’interface CLI multiplateforme qui permet la collecte des traces .net core d’un processus en cours d’exécution.The dotnet-trace tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process. L’outil collecte les Microsoft.Extensions.Logging.EventSource données du fournisseur à l’aide d’un LoggingEventSource .The tool collects Microsoft.Extensions.Logging.EventSource provider data using a LoggingEventSource.

Consultez dotnet-trace pour obtenir des instructions d’installation.See dotnet-trace for installation instructions.

Utilisez les outils de trace dotnet pour collecter une trace à partir d’une application :Use the dotnet trace tooling to collect a trace from an app:

  1. Exécutez l’application avec la dotnet run commande.Run the app with the dotnet run command.

  2. Déterminez l’identificateur de processus (PID) de l’application .NET Core :Determine the process identifier (PID) of the .NET Core app:

    Recherchez le PID pour le processus qui porte le même nom que l’assembly de l’application.Find the PID for the process that has the same name as the app's assembly.

  3. Exécutez la dotnet trace commande.Execute the dotnet trace command.

    Syntaxe de la commande générale :General command syntax:

    dotnet trace collect -p {PID} 
        --providers Microsoft-Extensions-Logging:{Keyword}:{Event Level}
            :FilterSpecs=\"
                {Logger Category 1}:{Event Level 1};
                {Logger Category 2}:{Event Level 2};
                ...
                {Logger Category N}:{Event Level N}\"
    

    Quand vous utilisez une interface de commande PowerShell, placez la --providers valeur entre guillemets simples ( ' ) :When using a PowerShell command shell, enclose the --providers value in single quotes ('):

    dotnet trace collect -p {PID} 
        --providers 'Microsoft-Extensions-Logging:{Keyword}:{Event Level}
            :FilterSpecs=\"
                {Logger Category 1}:{Event Level 1};
                {Logger Category 2}:{Event Level 2};
                ...
                {Logger Category N}:{Event Level N}\"'
    

    Sur les plateformes non-Windows, ajoutez l' -f speedscope option permettant de modifier le format du fichier de trace de sortie en speedscope .On non-Windows platforms, add the -f speedscope option to change the format of the output trace file to speedscope.

    Mot cléKeyword DescriptionDescription
    11 Consignez les événements méta sur le LoggingEventSource .Log meta events about the LoggingEventSource. N’enregistre pas les événements à partir de ILogger ).Doesn't log events from ILogger).
    22 Active l' Message événement lorsque ILogger.Log() est appelé.Turns on the Message event when ILogger.Log() is called. Fournit des informations d’une façon de programmation (non mise en forme).Provides information in a programmatic (not formatted) way.
    44 Active l' FormatMessage événement lorsque ILogger.Log() est appelé.Turns on the FormatMessage event when ILogger.Log() is called. Fournit la version de chaîne mise en forme des informations.Provides the formatted string version of the information.
    88 Active l' MessageJson événement lorsque ILogger.Log() est appelé.Turns on the MessageJson event when ILogger.Log() is called. Fournit une représentation JSON des arguments.Provides a JSON representation of the arguments.
    Niveau d'événementEvent Level DescriptionDescription
    00 LogAlways
    11 Critical
    22 Error
    33 Warning
    44 Informational
    55 Verbose

    FilterSpecsles entrées pour {Logger Category} et {Event Level} représentent des conditions de filtrage de journal supplémentaires.FilterSpecs entries for {Logger Category} and {Event Level} represent additional log filtering conditions. Séparez FilterSpecs les entrées par un point-virgule ( ; ).Separate FilterSpecs entries with a semicolon (;).

    Exemple utilisant un interpréteur de commandes Windows (sans guillemets simples autour de la --providers valeur) :Example using a Windows command shell (no single quotes around the --providers value):

    dotnet trace collect -p {PID} --providers Microsoft-Extensions-Logging:4:2:FilterSpecs=\"Microsoft.AspNetCore.Hosting*:4\"
    

    La commande précédente active :The preceding command activates:

    • Enregistreur d’événements de la source d’événements pour produire des chaînes mises en forme ( 4 ) pour les erreurs ( 2 ).The Event Source logger to produce formatted strings (4) for errors (2).
    • Microsoft.AspNetCore.Hostingjournalisation au Informational niveau de la journalisation ( 4 ).Microsoft.AspNetCore.Hosting logging at the Informational logging level (4).
  4. Arrêtez les outils de trace dotnet en appuyant sur la touche entrée ou Ctrl + C.Stop the dotnet trace tooling by pressing the Enter key or Ctrl+C.

    La trace est enregistrée avec le nom trace. NetTrace dans le dossier où la dotnet trace commande est exécutée.The trace is saved with the name trace.nettrace in the folder where the dotnet trace command is executed.

  5. Ouvrez la trace avec Perfview.Open the trace with Perfview. Ouvrez le fichier trace. NetTrace et explorez les événements de trace.Open the trace.nettrace file and explore the trace events.

Si l’application ne crée pas l’hôte avec CreateDefaultBuilder , ajoutez le fournisseur de la source d’événements à la configuration de journalisation de l’application.If the app doesn't build the host with CreateDefaultBuilder, add the Event Source provider to the app's logging configuration.

Pour plus d’informations, consultez :For more information, see:

PerfviewPerfview

Utilisez l' utilitaire PerfView pour collecter et afficher les journaux.Use the PerfView utility to collect and view logs. Il existe d’autres outils d’affichage des journaux ETW, mais PerfView est l’outil recommandé pour gérer les événements ETW générés par ASP.NET Core.There are other tools for viewing ETW logs, but PerfView provides the best experience for working with the ETW events emitted by ASP.NET Core.

Pour configurer PerfView afin qu’il collecte les événements enregistrés par ce fournisseur, ajoutez la chaîne *Microsoft-Extensions-Logging à la liste des fournisseurs supplémentaires.To configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. Ne manquez pas le * au début de la chaîne.Don't miss the * at the start of the string.

Journal des événements WindowsWindows EventLog

Le EventLog fournisseur envoie la sortie de journal dans le journal des événements Windows.The EventLog provider sends log output to the Windows Event Log. Contrairement aux autres fournisseurs, le EventLog fournisseur n’hérite pas des paramètres non-fournisseur par défaut.Unlike the other providers, the EventLog provider does not inherit the default non-provider settings. Si EventLog les paramètres du journal ne sont pas spécifiés, ils utilisent par défaut LogLevel. Warning.If EventLog log settings aren't specified, they default to LogLevel.Warning.

Pour consigner les événements inférieurs à LogLevel.Warning , définissez explicitement le niveau de journalisation.To log events lower than LogLevel.Warning, explicitly set the log level. L’exemple suivant définit le niveau de journalisation par défaut du journal des événements sur LogLevel.Information :The following example sets the Event Log default log level to LogLevel.Information:

"Logging": {
  "EventLog": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Les surcharges AddEventLog peuvent passer EventLogSettings .AddEventLog overloads can pass in EventLogSettings. Si null ou n’est pas spécifié, les paramètres par défaut suivants sont utilisés :If null or not specified, the following default settings are used:

  • LogName: « Application »LogName: "Application"
  • SourceName: « .NET Runtime »SourceName: ".NET Runtime"
  • MachineName: Le nom de l’ordinateur local est utilisé.MachineName: The local machine name is used.

Le code suivant remplace la SourceName valeur par défaut de par ".NET Runtime" MyLogs :The following code changes the SourceName from the default value of ".NET Runtime" to MyLogs:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
            {
                logging.AddEventLog(eventLogSettings =>
                {
                    eventLogSettings.SourceName = "MyLogs"; 
                });
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Azure App ServiceAzure App Service

Le package de fournisseur Microsoft.Extensions.Logging.AzureAppServices écrit les enregistrements de journal dans des fichiers texte dans le système de fichiers d’une application Azure App Service, et dans un stockage Blob dans un compte de stockage Azure.The Microsoft.Extensions.Logging.AzureAppServices provider package writes logs to text files in an Azure App Service app's file system and to blob storage in an Azure Storage account.

Le fournisseur de package n’est pas inclus dans le framework partagé.The provider package isn't included in the shared framework. Pour utiliser le fournisseur, ajoutez le package du fournisseur au projet.To use the provider, add the provider package to the project.

Pour configurer les paramètres du fournisseur, utilisez AzureFileLoggerOptions et AzureBlobLoggerOptions, comme illustré dans l’exemple suivant :To configure provider settings, use AzureFileLoggerOptions and AzureBlobLoggerOptions, as shown in the following example:

public class Scopes
{
    public class Program
    {
        public static void Main(string[] args)
        {
            CreateHostBuilder(args).Build().Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
                .ConfigureServices(serviceCollection => serviceCollection
                    .Configure<AzureFileLoggerOptions>(options =>
                    {
                        options.FileName = "azure-diagnostics-";
                        options.FileSizeLimit = 50 * 1024;
                        options.RetainedFileCountLimit = 5;
                    })
                    .Configure<AzureBlobLoggerOptions>(options =>
                    {
                        options.BlobName = "log.txt";
                    }))
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
    }
}

Lors du déploiement sur Azure App Service, l’application utilise les paramètres de la section app service les journaux de la page app service du portail Azure.When deployed to Azure App Service, the app uses the settings in the App Service logs section of the App Service page of the Azure portal. Quand les paramètres suivants sont mis à jour, les changements prennent effet immédiatement sans avoir besoin de redémarrer ou redéployer l’application.When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • Journalisation des applications (système de fichiers)Application Logging (Filesystem)
  • Journalisation des applications (objet blob)Application Logging (Blob)

L’emplacement par défaut des fichiers journaux est le dossier D:\racine\LogFiles\Application, et le nom de fichier par défaut est diagnostics-aaaammjj.txt.The default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is diagnostics-yyyymmdd.txt. La limite de taille de fichier par défaut est de 10 Mo, et le nombre maximal de fichiers conservés par défaut est de 2.The default file size limit is 10 MB, and the default maximum number of files retained is 2. Le nom par défaut du blob est {app-name}{timestamp}/aaaa/mm/jj/hh/{guid}-applicationLog.txt.The default blob name is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Ce fournisseur se connecte uniquement lorsque le projet s’exécute dans l’environnement Azure.This provider only logs when the project runs in the Azure environment.

Streaming des journaux AzureAzure log streaming

Azure log streaming prend en charge l’affichage de l’activité des journaux en temps réel à partir de :Azure log streaming supports viewing log activity in real time from:

  • Serveur d'applicationsThe app server
  • Serveur webThe web server
  • Suivi des demandes ayant échouéFailed request tracing

Pour configurer le streaming des journaux Azure :To configure Azure log streaming:

  • Accédez à la page journaux App service à partir de la page du portail de l’application.Navigate to the App Service logs page from the app's portal page.
  • Définissez Journal des applications (Système de fichiers) sur Activé.Set Application Logging (Filesystem) to On.
  • Choisissez le niveau du journal.Choose the log Level. Ce paramètre s’applique uniquement à la diffusion en continu de journaux Azure.This setting only applies to Azure log streaming.

Accédez à la page flux de journal pour afficher les journaux.Navigate to the Log Stream page to view logs. Les messages journalisés sont enregistrés avec l' ILogger interface.The logged messages are logged with the ILogger interface.

Azure Application InsightsAzure Application Insights

Le package du fournisseur Microsoft. extensions. Logging. ApplicationInsights écrit les journaux dans Azure application Insights.The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights. Application Insights est un service qui surveille une application web et fournit des outils pour interroger et analyser les données de télémétrie.Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. Si vous utilisez ce fournisseur, vous pouvez interroger et analyser vos journaux à l’aide des outils Application Insights.If you use this provider, you can query and analyze your logs by using the Application Insights tools.

Le fournisseur de journalisation est inclus en tant que dépendance de Microsoft.ApplicationInsights.AspNetCore, le package qui fournit toutes les données de télémétrie disponibles pour ASP.NET Core.The logging provider is included as a dependency of Microsoft.ApplicationInsights.AspNetCore, which is the package that provides all available telemetry for ASP.NET Core. Si vous utilisez ce package, vous n’avez pas besoin d’installer le package du fournisseur.If you use this package, you don't have to install the provider package.

Le package Microsoft. ApplicationInsights. Web est destiné à ASP.net 4. x, et non ASP.net core.The Microsoft.ApplicationInsights.Web package is for ASP.NET 4.x, not ASP.NET Core.

Pour plus d’informations, consultez les ressources suivantes :For more information, see the following resources:

Fournisseurs de journalisation tiersThird-party logging providers

Frameworks de journalisation tiers qui sont pris en charge dans ASP.NET Core :Third-party logging frameworks that work with ASP.NET Core:

Certains frameworks tiers prennent en charge la journalisation sémantique, également appelée journalisation structurée.Some third-party frameworks can perform semantic logging, also known as structured logging.

L’utilisation d’un framework tiers est semblable à l’utilisation des fournisseurs intégrés :Using a third-party framework is similar to using one of the built-in providers:

  1. Ajoutez un package NuGet à votre projet.Add a NuGet package to your project.
  2. Appeler une ILoggerFactory méthode d’extension fournie par le Framework de journalisation.Call an ILoggerFactory extension method provided by the logging framework.

Pour plus d’informations, consultez la documentation de chaque fournisseur.For more information, see each provider's documentation. Les fournisseurs de journalisation tiers ne sont pas pris en charge par Microsoft.Third-party logging providers aren't supported by Microsoft.

Application console non-hôteNon-host console app

Pour obtenir un exemple d’utilisation de l’hôte générique dans une application de console non Web, consultez le fichier Program.cs de l' exemple d’application tâches en arrière-plan ( Tâches d’arrière-plan avec des services hébergés dans ASP.NET Core ).For an example of how to use the Generic Host in a non-web console app, see the Program.cs file of the Background Tasks sample app (Tâches d’arrière-plan avec des services hébergés dans ASP.NET Core).

Le code de journalisation pour les applications sans hôte générique diffère dans la façon dont les fournisseurs sont ajoutés et les enregistreurs d'événements créés.Logging code for apps without Generic Host differs in the way providers are added and loggers are created.

Fournisseurs de journalisationLogging providers

Dans une application de console non hôte, appelez la méthode d’extension Add{provider name} du fournisseur lors de la création d’un LoggerFactory :In a non-host console app, call the provider's Add{provider name} extension method while creating a LoggerFactory:

class Program
{
    static void Main(string[] args)
    {
        var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

Créer des journauxCreate logs

Pour créer des journaux, utilisez un objet ILogger<TCategoryName>.To create logs, use an ILogger<TCategoryName> object. Utilisez LoggerFactory pour créer un ILogger .Use the LoggerFactory to create an ILogger.

L’exemple suivant crée un enregistreur d’événements avec LoggingConsoleApp.Program comme catégorie.The following example creates a logger with LoggingConsoleApp.Program as the category.

class Program
{
    static void Main(string[] args)
    {
        var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

Dans les exemples de base ASP.NET suivants, l’enregistreur d’événements est utilisé pour créer des journaux avec Information comme niveau.In the following ASP.NET CORE examples, the logger is used to create logs with Information as the level. Le niveau du journal indique la gravité de l’événement consigné.The Log level indicates the severity of the logged event.

class Program
{
    static void Main(string[] args)
    {
        var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

Les niveaux et les catégories sont expliqués plus en détail dans ce document.Levels and categories are explained in more detail in this document.

Journal lors de la construction de l’hôteLog during host construction

La journalisation pendant la construction de l’hôte n’est pas prise en charge directement.Logging during host construction isn't directly supported. Toutefois, un enregistreur d’événements distinct peut être utilisé.However, a separate logger can be used. Dans l’exemple suivant, un enregistreur d’événements Serilog est utilisé pour se connecter CreateHostBuilder .In the following example, a Serilog logger is used to log in CreateHostBuilder. AddSerilogutilise la configuration statique spécifiée dans Log.Logger :AddSerilog uses the static configuration specified in Log.Logger:

using System;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var builtConfig = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .AddCommandLine(args)
            .Build();

        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
            .WriteTo.File(builtConfig["Logging:FilePath"])
            .CreateLogger();

        try
        {
            return Host.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    services.AddRazorPages();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    config.AddConfiguration(builtConfig);
                })
                .ConfigureLogging(logging =>
                {   
                    logging.AddSerilog();
                })
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host builder error");

            throw;
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }
}

Configurer un service qui dépend de ILoggerConfigure a service that depends on ILogger

L’injection de constructeur d’un enregistreur d’événements dans Startup fonctionne dans les versions antérieures d’ASP.NET Core, car un conteneur d’injection de dépendances distinct est créé pour l’hôte web.Constructor injection of a logger into Startup works in earlier versions of ASP.NET Core because a separate DI container is created for the Web Host. Pour plus d’informations sur la raison de la création d’un seul conteneur pour l’hôte générique, consultez l’annonce de changement cassant.For information about why only one container is created for the Generic Host, see the breaking change announcement.

Pour configurer un service qui dépend de ILogger<T> , utilisez l’injection de constructeur ou fournissez une méthode de fabrique.To configure a service that depends on ILogger<T>, use constructor injection or provide a factory method. L’approche de la méthode de fabrique est recommandée uniquement s’il n’y a aucune autre option.The factory method approach is recommended only if there is no other option. Par exemple, considérez un service qui a besoin d’une ILogger<T> instance fournie par di :For example, consider a service that needs an ILogger<T> instance provided by DI:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddRazorPages();

    services.AddSingleton<IMyService>((container) =>
    {
        var logger = container.GetRequiredService<ILogger<MyService>>();
        return new MyService() { Logger = logger };
    });
}

Le code en surbrillance précédent est un Func qui s’exécute la première fois que le conteneur di doit construire une instance de MyService .The preceding highlighted code is a Func that runs the first time the DI container needs to construct an instance of MyService. Vous pouvez accéder à tous les services inscrits de cette manière.You can access any of the registered services in this way.

Créer des journaux dans mainCreate logs in Main

Le code suivant se connecte Main en obtenant une ILogger instance à partir de di après avoir généré l’hôte :The following code logs in Main by getting an ILogger instance from DI after building the host:

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Host created.");

    host.Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Créer des journaux au démarrageCreate logs in Startup

Le code suivant écrit les journaux dans Startup.Configure :The following code writes logs in Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env,
                      ILogger<Startup> logger)
{
    if (env.IsDevelopment())
    {
        logger.LogInformation("In Development.");
        app.UseDeveloperExceptionPage();
    }
    else
    {
        logger.LogInformation("Not Development.");
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapRazorPages();
    });
}

L’écriture de journaux avant la fin de l’installation du conteneur d’injection de dépendances dans la méthode Startup.ConfigureServices n’est pas prise en charge :Writing logs before completion of the DI container setup in the Startup.ConfigureServices method is not supported:

  • L’injection d’un enregistreur d’événements dans le constructeur Startup n’est pas prise en charge.Logger injection into the Startup constructor is not supported.
  • L’injection d’un enregistreur d’événements dans la signature de méthode Startup.ConfigureServices n’est pas prise en charge.Logger injection into the Startup.ConfigureServices method signature is not supported

La raison de cette restriction est que la journalisation dépend de l’injection de dépendances et de la configuration qui, à son tour, dépend de l’injection de dépendances.The reason for this restriction is that logging depends on DI and on configuration, which in turns depends on DI. Le conteneur d’injection de dépendances n’est pas configuré avant que ConfigureServices soit terminé.The DI container isn't set up until ConfigureServices finishes.

Pour plus d’informations sur la configuration d’un service qui dépend de ILogger<T> ou de la raison pour laquelle l’injection d’un enregistreur d’événements dans les Startup versions antérieures, consultez configurer un service qui dépend de ILoggerFor information on configuring a service that depends on ILogger<T> or why constructor injection of a logger into Startup worked in earlier versions, see Configure a service that depends on ILogger

Aucune méthode d’enregistreur d’événements asynchroneNo asynchronous logger methods

La journalisation doit être suffisamment rapide par rapport au coût du code asynchrone en matière de performances.Logging should be so fast that it isn't worth the performance cost of asynchronous code. Si un magasin de données de journalisation est lent, n’écrivez pas directement dessus.If a logging data store is slow, don't write to it directly. Envisagez d’écrire les messages du journal dans un magasin rapide, puis de les déplacer ultérieurement vers la Banque lente.Consider writing the log messages to a fast store initially, then moving them to the slow store later. Par exemple, lorsque vous vous connectez à SQL Server, ne le faites pas directement dans une Log méthode, puisque les Log méthodes sont synchrones.For example, when logging to SQL Server, don't do so directly in a Log method, since the Log methods are synchronous. Ajoutez plutôt de façon synchronisée des messages de journal à une file d’attente en mémoire, puis configurez un traitement en arrière-plan afin d’extraire les messages de la file d’attente et d’effectuer le travail asynchrone d’envoi des données vers SQL Server.Instead, synchronously add log messages to an in-memory queue and have a background worker pull the messages out of the queue to do the asynchronous work of pushing data to SQL Server. Pour plus d’informations, consultez ce problème github.For more information, see this GitHub issue.

Modifier les niveaux de journal dans une application en cours d’exécutionChange log levels in a running app

L’API de journalisation n’inclut pas de scénario pour modifier les niveaux de journal lorsqu’une application est en cours d’exécution.The Logging API doesn't include a scenario to change log levels while an app is running. Toutefois, certains fournisseurs de configuration sont en charge du rechargement de la configuration, ce qui prend immédiatement effet sur la configuration de la journalisation.However, some configuration providers are capable of reloading configuration, which takes immediate effect on logging configuration. Par exemple, le fournisseur de configuration de fichier, recharge la configuration de journalisation par défaut.For example, the File Configuration Provider, reloads logging configuration by default. Si la configuration est modifiée dans le code pendant qu’une application est en cours d’exécution, l’application peut appeler IConfigurationRoot. Reload pour mettre à jour la configuration de journalisation de l’application.If configuration is changed in code while an app is running, the app can call IConfigurationRoot.Reload to update the app's logging configuration.

ILogger et ILoggerFactoryILogger and ILoggerFactory

Les ILogger<TCategoryName> ILoggerFactory interfaces et et les implémentations sont incluses dans la kit SDK .net core.The ILogger<TCategoryName> and ILoggerFactory interfaces and implementations are included in the .NET Core SDK. Ils sont également disponibles dans les packages NuGet suivants :They are also available in the following NuGet packages:

Appliquer les règles de filtre de journal dans le codeApply log filter rules in code

L’approche recommandée pour définir des règles de filtre de journal consiste à utiliser la configuration.The preferred approach for setting log filter rules is by using Configuration.

L'exemple suivant montre comment enregistrer des règles de filtre dans le code :The following example shows how to register filter rules in code:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
               logging.AddFilter("System", LogLevel.Debug)
                  .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)
                  .AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace))
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

logging.AddFilter("System", LogLevel.Debug)spécifie la System catégorie et le niveau de journalisation Debug .logging.AddFilter("System", LogLevel.Debug) specifies the System category and log level Debug. Le filtre est appliqué à tous les fournisseurs, car un fournisseur spécifique n’a pas été configuré.The filter is applied to all providers because a specific provider was not configured.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)indiquantAddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) specifies:

  • DebugFournisseur de journalisation.The Debug logging provider.
  • Niveau de journalisation Information et supérieur.Log level Information and higher.
  • Toutes les catégories commençant par "Microsoft" .All categories starting with "Microsoft".

Créer un enregistreur d’événements personnaliséCreate a custom logger

Pour ajouter un enregistreur d’événements personnalisé, ajoutez un ILoggerProvider avec ILoggerFactory :To add a custom logger, add an ILoggerProvider with ILoggerFactory:

public void Configure(
    IApplicationBuilder app,
    IWebHostEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory.AddProvider(new CustomLoggerProvider(new CustomLoggerConfiguration()));

Le ILoggerProvider crée une ou plusieurs ILogger instances.The ILoggerProvider creates one or more ILogger instances. Les ILogger instances sont utilisées par le Framework pour enregistrer les informations.The ILogger instances are used by the framework to log the information.

Exemple de configuration d’un enregistreur d’événements personnaliséSample custom logger configuration

L'exemple :The sample:

  • Est conçu pour être un exemple très basique qui définit la couleur de la console du journal par l’ID d’événement et le niveau de journalisation.Is designed to be a very basic sample that sets the color of the log console by event ID and log level. Les journaux ne sont généralement pas modifiés par l’ID d’événement et ne sont pas spécifiques au niveau du journal.Loggers generally don't change by event ID and are not specific to log level.
  • Crée différentes entrées de console couleur par niveau de journalisation et ID d’événement en utilisant le type de configuration suivant :Creates different color console entries per log level and event ID using the following configuration type:
public class ColorConsoleLoggerConfiguration
{
    public LogLevel LogLevel { get; set; } = LogLevel.Warning;
    public int EventId { get; set; } = 0;
    public ConsoleColor Color { get; set; } = ConsoleColor.Yellow;
}

Le code précédent affecte au niveau par défaut la valeur Warning et à la couleur Yellow .The preceding code sets the default level to Warning and the color to Yellow. Si le EventId est défini sur 0, tous les événements seront journalisés.If the EventId is set to 0, we will log all events.

Créer l’enregistreur d’événements personnaliséCreate the custom logger

Le ILogger nom de catégorie d’implémentation correspond généralement à la source de journalisation.The ILogger implementation category name is typically the logging source. Par exemple, le type dans lequel l’enregistreur d’événements est créé :For example, the type where the logger is created:

public class ColorConsoleLogger : ILogger
{
    private readonly string _name;
    private readonly ColorConsoleLoggerConfiguration _config;

    public ColorConsoleLogger(string name, ColorConsoleLoggerConfiguration config)
    {
        _name = name;
        _config = config;
    }

    public IDisposable BeginScope<TState>(TState state)
    {
        return null;
    }

    public bool IsEnabled(LogLevel logLevel)
    {
        return logLevel == _config.LogLevel;
    }

    public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, 
                        Exception exception, Func<TState, Exception, string> formatter)
    {
        if (!IsEnabled(logLevel))
        {
            return;
        }

        if (_config.EventId == 0 || _config.EventId == eventId.Id)
        {
            var color = Console.ForegroundColor;
            Console.ForegroundColor = _config.Color;
            Console.WriteLine($"{logLevel} - {eventId.Id} " +
                              $"- {_name} - {formatter(state, exception)}");
            Console.ForegroundColor = color;
        }
    }
}

Le code précédent :The preceding code:

  • Crée une instance d’enregistreur d’événements par nom de catégorie.Creates a logger instance per category name.
  • Archive logLevel == _config.LogLevel IsEnabled , donc chaque logLevel a un enregistreur d’événements unique.Checks logLevel == _config.LogLevel in IsEnabled, so each logLevel has a unique logger. En règle générale, les enregistreurs d’événements doivent également être activés pour tous les niveaux de journalisation les plus élevés :Generally, loggers should also be enabled for all higher log levels:
public bool IsEnabled(LogLevel logLevel)
{
    return logLevel >= _config.LogLevel;
}

Créer le LoggerProvider personnaliséCreate the custom LoggerProvider

LoggerProviderEst la classe qui crée les instances d’enregistreur d’événements.The LoggerProvider is the class that creates the logger instances. Il n’est peut-être pas nécessaire de créer une instance d’enregistreur d’événements par catégorie, mais cela est logique pour certains enregistreurs d’événements, tels que NLog ou log4net.Maybe it is not needed to create a logger instance per category, but this makes sense for some Loggers, like NLog or log4net. En procédant ainsi, vous pouvez choisir différentes cibles de sortie de journalisation par catégorie, si nécessaire :Doing this you are also able to choose different logging output targets per category if needed:

public class ColorConsoleLoggerProvider : ILoggerProvider
{
    private readonly ColorConsoleLoggerConfiguration _config;
    private readonly ConcurrentDictionary<string, ColorConsoleLogger> _loggers = new ConcurrentDictionary<string, ColorConsoleLogger>();

    public ColorConsoleLoggerProvider(ColorConsoleLoggerConfiguration config)
    {
        _config = config;
    }

    public ILogger CreateLogger(string categoryName)
    {
        return _loggers.GetOrAdd(categoryName, name => new ColorConsoleLogger(name, _config));
    }

    public void Dispose()
    {
        _loggers.Clear();
    }
}

Dans le code précédent, CreateLogger crée une seule instance de ColorConsoleLogger par nom de catégorie et la stocke dans le ConcurrentDictionary<TKey,TValue> ;In the preceding code, CreateLogger creates a single instance of the ColorConsoleLogger per category name and stores it in the ConcurrentDictionary<TKey,TValue>;

Utilisation et inscription de l’enregistreur d’événements personnaliséUsage and registration of the custom logger

Inscrire l’enregistreur d’événements dans Startup.Configure :Register the logger in the Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, 
                      ILoggerFactory loggerFactory)
{
    // Default registration.
    loggerFactory.AddProvider(new ColorConsoleLoggerProvider(
                              new ColorConsoleLoggerConfiguration
    {
        LogLevel = LogLevel.Error,
        Color = ConsoleColor.Red
    }));

    // Custom registration with default values.
    loggerFactory.AddColorConsoleLogger();

    // Custom registration with a new configuration instance.
    loggerFactory.AddColorConsoleLogger(new ColorConsoleLoggerConfiguration
    {
        LogLevel = LogLevel.Debug,
        Color = ConsoleColor.Gray
    });

    // Custom registration with a configuration object.
    loggerFactory.AddColorConsoleLogger(c =>
    {
        c.LogLevel = LogLevel.Information;
        c.Color = ConsoleColor.Blue;
    });

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
        app.UseHsts();
    }
    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

Pour le code précédent, fournissez au moins une méthode d’extension pour le ILoggerFactory :For the preceding code, provide at least one extension method for the ILoggerFactory:

public static class ColorConsoleLoggerExtensions
{
    public static ILoggerFactory AddColorConsoleLogger(
                                      this ILoggerFactory loggerFactory, 
                                      ColorConsoleLoggerConfiguration config)
    {
        loggerFactory.AddProvider(new ColorConsoleLoggerProvider(config));
        return loggerFactory;
    }
    public static ILoggerFactory AddColorConsoleLogger(
                                      this ILoggerFactory loggerFactory)
    {
        var config = new ColorConsoleLoggerConfiguration();
        return loggerFactory.AddColorConsoleLogger(config);
    }
    public static ILoggerFactory AddColorConsoleLogger(
                                    this ILoggerFactory loggerFactory, 
                                    Action<ColorConsoleLoggerConfiguration> configure)
    {
        var config = new ColorConsoleLoggerConfiguration();
        configure(config);
        return loggerFactory.AddColorConsoleLogger(config);
    }
}

Ressources supplémentairesAdditional resources

Par Tom Dykstra et Steve SmithBy Tom Dykstra and Steve Smith

.NET Core prend en charge une API de journalisation qui fonctionne avec différents fournisseurs de journalisation tiers et intégrés..NET Core supports a logging API that works with a variety of built-in and third-party logging providers. Cet article explique comment utiliser cette API de journalisation avec les fournisseurs de journalisation intégrés.This article shows how to use the logging API with built-in providers.

Afficher ou télécharger l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

Ajouter des fournisseursAdd providers

Un fournisseur de journalisation affiche ou stocke des journaux.A logging provider displays or stores logs. Par exemple, le fournisseur Console affiche les journaux dans la console, et le fournisseur Azure Application Insights les stocke dans Azure Application Insights.For example, the Console provider displays logs on the console, and the Azure Application Insights provider stores them in Azure Application Insights. Il est possible d’envoyer les journaux à plusieurs endroits en ajoutant plusieurs fournisseurs.Logs can be sent to multiple destinations by adding multiple providers.

Pour ajouter un fournisseur, appelez la méthode d’extension Add{provider name} du fournisseur dans Program.cs :To add a provider, call the provider's Add{provider name} extension method in Program.cs:

public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            var env = hostingContext.HostingEnvironment;
            config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                  .AddJsonFile($"appsettings.{env.EnvironmentName}.json", 
                      optional: true, reloadOnChange: true);
            config.AddEnvironmentVariables();
        })
        .ConfigureLogging((hostingContext, logging) =>
        {
            // Requires `using Microsoft.Extensions.Logging;`
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
            logging.AddDebug();
            logging.AddEventSourceLogger();
        })
        .UseStartup<Startup>()
        .Build();

    webHost.Run();
}

Le code précédent nécessite des références à Microsoft.Extensions.Logging et Microsoft.Extensions.Configuration.The preceding code requires references to Microsoft.Extensions.Logging and Microsoft.Extensions.Configuration.

Le modèle de projet par défaut appelle CreateDefaultBuilder, qui ajoute les fournisseurs de journalisation suivants :The default project template calls CreateDefaultBuilder, which adds the following logging providers:

  • ConsoleConsole
  • DébogageDebug
  • EventSource (à partir d’ASP.NET Core 2.2)EventSource (starting in ASP.NET Core 2.2)
public static void Main(string[] args)
{
    CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>();

Si vous utilisez CreateDefaultBuilder, vous pouvez remplacer les fournisseurs par défaut par ceux de votre choix.If you use CreateDefaultBuilder, you can replace the default providers with your own choices. Appelez ClearProviders et ajoutez les fournisseurs que vous souhaitez.Call ClearProviders, and add the providers you want.

public static void Main(string[] args)
{
    var host = CreateWebHostBuilder(args).Build();

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        });

Vous trouverez des informations sur les fournisseurs de journalisation intégrés et les fournisseurs de journalisation tiers plus loin dans cet article.Learn more about built-in logging providers and third-party logging providers later in the article.

Créer des journauxCreate logs

Pour créer des journaux, utilisez un objet ILogger<TCategoryName>.To create logs, use an ILogger<TCategoryName> object. Dans une application web ou un service hébergé, obtenez un ILogger à partir de l’injection de dépendances (DI).In a web app or hosted service, get an ILogger from dependency injection (DI). Dans les applications de console non hôtes, utilisez le LoggerFactory pour créer un ILogger.In non-host console apps, use the LoggerFactory to create an ILogger.

L’exemple d’ASP.NET Core suivant crée un enregistreur d’événements de catégorie TodoApiSample.Pages.AboutModel.The following ASP.NET Core example creates a logger with TodoApiSample.Pages.AboutModel as the category. La catégorie du journal est une chaîne associée à chaque journal.The log category is a string that is associated with each log. L’instance ILogger<T> fournie par l’injection de dépendances crée des journaux ayant comme catégorie un nom complet de type T.The ILogger<T> instance provided by DI creates logs that have the fully qualified name of type T as the category.

public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }

Dans les exemples d’ASP.NET Core et d’application de console suivants, l’enregistreur d’événements est utilisé pour créer des journaux de niveau Information.In the following ASP.NET Core and console app examples, the logger is used to create logs with Information as the level. Le niveau du journal indique la gravité de l’événement consigné.The Log level indicates the severity of the logged event.

public void OnGet()
{
    Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
    _logger.LogInformation("Message displayed: {Message}", Message);
}

Les niveaux et les catégories sont expliqués plus en détail plus loin dans cet article.Levels and categories are explained in more detail later in this article.

Créer des journaux au démarrageCreate logs in Startup

Pour écrire des journaux dans la classe Startup, ajoutez un paramètre ILogger dans la signature de constructeur :To write logs in the Startup class, include an ILogger parameter in the constructor signature:

public class Startup
{
    private readonly ILogger _logger;

    public Startup(IConfiguration configuration, ILogger<Startup> logger)
    {
        Configuration = configuration;
        _logger = logger;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        // Add our repository type
        services.AddSingleton<ITodoRepository, TodoRepository>();
        _logger.LogInformation("Added TodoRepository to services");
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment())
        {
            _logger.LogInformation("In Development environment");
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseCookiePolicy();

        app.UseMvc();
    }
}

Créer des journaux dans la classe ProgrammeCreate logs in the Program class

Pour écrire des journaux dans la classe Program, récupérez une instance ILogger auprès de l’injection de dépendances :To write logs in the Program class, get an ILogger instance from DI:

public static void Main(string[] args)
{
    var host = CreateWebHostBuilder(args).Build();

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        });

La journalisation pendant la construction de l’hôte n’est pas prise en charge directement.Logging during host construction isn't directly supported. Toutefois, un enregistreur d’événements distinct peut être utilisé.However, a separate logger can be used. Dans l’exemple suivant, un enregistreur d’événements Serilog est utilisé pour se connecter CreateWebHostBuilder .In the following example, a Serilog logger is used to log in CreateWebHostBuilder. AddSerilogutilise la configuration statique spécifiée dans Log.Logger :AddSerilog uses the static configuration specified in Log.Logger:

using System;
using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var builtConfig = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .AddCommandLine(args)
            .Build();

        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
            .WriteTo.File(builtConfig["Logging:FilePath"])
            .CreateLogger();

        try
        {
            return WebHost.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    services.AddMvc();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    config.AddConfiguration(builtConfig);
                })
                .ConfigureLogging(logging =>
                {
                    logging.AddSerilog();
                })
                .UseStartup<Startup>();
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host builder error");

            throw;
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }
}

Aucune méthode d’enregistreur d’événements asynchroneNo asynchronous logger methods

La journalisation doit être suffisamment rapide par rapport au coût du code asynchrone en matière de performances.Logging should be so fast that it isn't worth the performance cost of asynchronous code. Si votre magasin de données de journalisation est lent, n’écrivez pas directement dedans.If your logging data store is slow, don't write to it directly. Écrivez au départ les messages de journal dans un magasin rapide, puis déplacez-les dans le magasin lent.Consider writing the log messages to a fast store initially, then move them to the slow store later. Par exemple, si vous vous connectez à SQL Server, évitez de le faire directement dans une méthode Log, car les méthodes Log sont synchrones.For example, if you're logging to SQL Server, you don't want to do that directly in a Log method, since the Log methods are synchronous. Ajoutez plutôt de façon synchronisée des messages de journal à une file d’attente en mémoire, puis configurez un traitement en arrière-plan afin d’extraire les messages de la file d’attente et d’effectuer le travail asynchrone d’envoi des données vers SQL Server.Instead, synchronously add log messages to an in-memory queue and have a background worker pull the messages out of the queue to do the asynchronous work of pushing data to SQL Server. Pour plus d’informations, consultez ce problème github.For more information, see this GitHub issue.

ConfigurationConfiguration

La configuration de fournisseur de journalisation est fournie par un ou plusieurs fournisseurs de configuration :Logging provider configuration is provided by one or more configuration providers:

  • Formats de fichiers (INI, JSON et XML).File formats (INI, JSON, and XML).
  • Arguments de ligne de commandeCommand-line arguments.
  • Variables d'environnement.Environment variables.
  • Objets .NET en mémoire.In-memory .NET objects.
  • Stockage Secret Manager non chiffré.The unencrypted Secret Manager storage.
  • Magasin utilisateur chiffré comme Azure Key Vault.An encrypted user store, such as Azure Key Vault.
  • Fournisseurs personnalisés (installés ou créés).Custom providers (installed or created).

Par exemple, la configuration de journalisation est généralement fournie par la section Logging des fichiers de paramètres d’application.For example, logging configuration is commonly provided by the Logging section of app settings files. L’exemple suivant montre le contenu d’un fichier appsettings.Development.json standard :The following example shows the contents of a typical appsettings.Development.json file:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    },
    "Console":
    {
      "IncludeScopes": true
    }
  }
}

La propriété Logging peut avoir un niveau LogLevel et des propriétés de module fournisseur d'informations (Console ici).The Logging property can have LogLevel and log provider properties (Console is shown).

La propriété LogLevel sous Logging spécifie le niveau de journalisation minimal pour les catégories sélectionnées.The LogLevel property under Logging specifies the minimum level to log for selected categories. Dans l’exemple, les catégories System et Microsoft sont consignées au niveau Information, et toutes les autres au niveau Debug.In the example, System and Microsoft categories log at Information level, and all others log at Debug level.

Les autres propriétés sous Logging spécifient les fournisseurs de journalisation.Other properties under Logging specify logging providers. Cet exemple concerne le fournisseur Console.The example is for the Console provider. Si un fournisseur prend en charge les étendues de journal, IncludeScopes indique s’ils sont activés.If a provider supports log scopes, IncludeScopes indicates whether they're enabled. Une propriété de fournisseur (comme Console dans l’exemple) peut également spécifier une propriété LogLevel.A provider property (such as Console in the example) may also specify a LogLevel property. LogLevel sous un fournisseur spécifie les niveaux à consigner pour ce fournisseur.LogLevel under a provider specifies levels to log for that provider.

Si les niveaux sont spécifiés dans Logging.{providername}.LogLevel, ils remplacent ce qui est défini dans Logging.LogLevel.If levels are specified in Logging.{providername}.LogLevel, they override anything set in Logging.LogLevel. Considérons, par exemple, le code JSON suivant :For example, consider the following JSON:

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

Dans le code JSON précédent, les Console paramètres du fournisseur remplacent le niveau de journalisation précédent (par défaut).In the preceding JSON, the Console provider settings overrides the preceding (default) log level.

L’API de journalisation n’inclut pas de scénario pour modifier les niveaux de journal lorsqu’une application est en cours d’exécution.The Logging API doesn't include a scenario to change log levels while an app is running. Toutefois, certains fournisseurs de configuration sont en charge du rechargement de la configuration, ce qui prend immédiatement effet sur la configuration de la journalisation.However, some configuration providers are capable of reloading configuration, which takes immediate effect on logging configuration. Par exemple, le fournisseur de configuration de fichier, qui est ajouté par CreateDefaultBuilder pour lire les fichiers de paramètres, recharge la configuration de journalisation par défaut.For example, the File Configuration Provider, which is added by CreateDefaultBuilder to read settings files, reloads logging configuration by default. Si la configuration est modifiée dans le code pendant qu’une application est en cours d’exécution, l’application peut appeler IConfigurationRoot. Reload pour mettre à jour la configuration de journalisation de l’application.If configuration is changed in code while an app is running, the app can call IConfigurationRoot.Reload to update the app's logging configuration.

Pour plus d’informations sur l’implémentation des fournisseurs de configuration, consultez Configuration dans ASP.NET Core.For information on implementing configuration providers, see Configuration dans ASP.NET Core.

Exemple de sortie de la journalisationSample logging output

Avec l’exemple de code présenté dans la section précédente, les journaux s’affichent dans la console lorsque l’application est exécutée en ligne de commande.With the sample code shown in the preceding section, logs appear in the console when the app is run from the command line. Voici un exemple de sortie de la console :Here's an example of console output:

info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
      Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 42.9286ms
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
      Request finished in 148.889ms 404

Les journaux précédents ont été générés par une requête HTTP Get à l’exemple d’application à l’adresse http://localhost:5000/api/todo/0.The preceding logs were generated by making an HTTP Get request to the sample app at http://localhost:5000/api/todo/0.

Voici un exemple des mêmes journaux tels qu’ils s’affichent dans la fenêtre Débogage quand vous exécutez l’exemple d’application dans Visual Studio :Here's an example of the same logs as they appear in the Debug window when you run the sample app in Visual Studio:

Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request starting HTTP/1.1 GET http://localhost:53104/api/todo/0  
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
TodoApi.Controllers.TodoController:Information: Getting item 0
TodoApi.Controllers.TodoController:Warning: GetById(0) NOT FOUND
Microsoft.AspNetCore.Mvc.StatusCodeResult:Information: Executing HttpStatusCodeResult, setting HTTP status code 404
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 152.5657ms
Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request finished in 316.3195ms 404

Les journaux créés par les appels de ILogger illustrés dans la section précédente commencent par « TodoApi ».The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApi". Ceux qui commencent par les catégories « Microsoft » proviennent du code du framework ASP.NET Core.The logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core et le code d’application utilisent la même API de journalisation et les mêmes fournisseurs.ASP.NET Core and application code are using the same logging API and providers.

Les autres sections de cet article détaillent certains points et présentent les options de journalisation.The remainder of this article explains some details and options for logging.

Packages NuGetNuGet packages

Les interfaces ILogger et ILoggerFactory se trouvent dans Microsoft.Extensions.Logging.Abstractions, et leurs implémentations par défaut se trouvent dans Microsoft.Extensions.Logging.The ILogger and ILoggerFactory interfaces are in Microsoft.Extensions.Logging.Abstractions, and default implementations for them are in Microsoft.Extensions.Logging.

Catégorie de journalLog category

Quand un objet ILogger est créé, une catégorie lui est spécifiée.When an ILogger object is created, a category is specified for it. Cette catégorie est incluse dans tous les messages de journal créés par cette instance de ILogger.That category is included with each log message created by that instance of ILogger. Si la catégorie peut être n’importe quelle chaîne, la convention est d’utiliser le nom de la classe, par exemple « TodoApi.Controllers.TodoController ».The category may be any string, but the convention is to use the class name, such as "TodoApi.Controllers.TodoController".

Utilisez ILogger<T> pour obtenir une instance de ILogger qui utilise le nom de type complet T comme catégorie :Use ILogger<T> to get an ILogger instance that uses the fully qualified type name of T as the category:

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }

Pour spécifier explicitement la catégorie, appelez ILoggerFactory.CreateLogger :To explicitly specify the category, call ILoggerFactory.CreateLogger:

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILoggerFactory logger)
    {
        _todoRepository = todoRepository;
        _logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
    }

ILogger<T> équivaut à appeler CreateLogger avec le nom de type complet T.ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

Log levelLog level

Chaque journal spécifie une valeur LogLevel.Every log specifies a LogLevel value. Le niveau de journalisation indique la gravité ou l’importance.The log level indicates the severity or importance. Vous pourriez par exemple écrire un journal Information lorsqu’une méthode se termine normalement et un journal Warning lorsqu’une méthode retourne un code de statut 404 Not Found.For example, you might write an Information log when a method ends normally and a Warning log when a method returns a 404 Not Found status code.

Le code suivant crée des journaux Information et Warning :The following code creates Information and Warning logs:

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

Dans le code précédent, les MyLogEvents.GetItem MyLogEvents.GetItemNotFound paramètres et sont l' ID d’événement du journal.In the preceding code, the MyLogEvents.GetItem and MyLogEvents.GetItemNotFound parameters are the Log event ID. Le deuxième paramètre est un modèle de message contenant des espaces réservés pour les valeurs d’argument fournies par les autres paramètres de méthode.The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. Les paramètres de méthode sont expliqués dans la section modèle de message de journal de cet article.The method parameters are explained in the Log message template section in this article.

Les méthodes de journal qui comportent le niveau dans leur nom (par exemple, LogInformation et LogWarning) sont des méthodes d’extension pour ILogger.Log methods that include the level in the method name (for example, LogInformation and LogWarning) are extension methods for ILogger. Elles appellent une méthode Log qui prend un paramètre LogLevel.These methods call a Log method that takes a LogLevel parameter. Vous pouvez appeler la méthode Log directement au lieu d’appeler ces méthodes d’extension, mais la syntaxe est relativement complexe.You can call the Log method directly rather than one of these extension methods, but the syntax is relatively complicated. Pour plus d’informations, voir ILogger et le code source des extensions d’enregistreur d'événements.For more information, see ILogger and the logger extensions source code.

ASP.NET Core définit les niveaux de journalisation suivants, classés selon leur degré de gravité (du plus faible au plus élevé).ASP.NET Core defines the following log levels, ordered here from lowest to highest severity.

  • Trace = 0Trace = 0

    Informations en général exclusivement utiles à des fins de débogage.For information that's typically valuable only for debugging. Ces messages peuvent contenir des données d’application sensibles. Ils ne doivent donc pas être activés dans un environnement de production.These messages may contain sensitive application data and so shouldn't be enabled in a production environment. Désactivé par défaut.Disabled by default.

  • Debug = 1Debug = 1

    Informations qui peuvent être utiles dans le développement et le débogage.For information that may be useful in development and debugging. Exemple : Entering method Configure with flag set to true. En raison de leur volume élevé, n’activez les journaux de niveau Debug en production que pour résoudre des problèmes.Example: Entering method Configure with flag set to true. Enable Debug level logs in production only when troubleshooting, due to the high volume of logs.

  • Information = 2Information = 2

    Informations de suivi du flux général de l’application.For tracking the general flow of the app. Ces journaux ont généralement une utilité à long terme.These logs typically have some long-term value. Exemple : Request received for path /api/todoExample: Request received for path /api/todo

  • Warning = 3Warning = 3

    Informations sur les événements anormaux ou inattendus dans le flux de l’application.For abnormal or unexpected events in the app flow. Il peut s’agir d’erreurs ou d’autres situations qui ne provoquent pas l’arrêt de l’application, mais qu’il peut être intéressant d’examiner.These may include errors or other conditions that don't cause the app to stop but might need to be investigated. Le niveau de journalisation Warning est généralement utilisé pour les exceptions gérées.Handled exceptions are a common place to use the Warning log level. Exemple : FileNotFoundException for file quotes.txt.Example: FileNotFoundException for file quotes.txt.

  • Error = 4Error = 4

    Fournit des informations sur des erreurs et des exceptions qui ne peuvent pas être gérées.For errors and exceptions that cannot be handled. Ces messages indiquent un échec de l’activité ou de l’opération en cours (par exemple, la requête HTTP actuellement exécutée), pas un échec au niveau de l’application.These messages indicate a failure in the current activity or operation (such as the current HTTP request), not an app-wide failure. Exemple de message de journal : Cannot insert record due to duplicate key violation.Example log message: Cannot insert record due to duplicate key violation.

  • Critical = 5Critical = 5

    Fournit des informations sur des échecs qui nécessitent un examen immédiat.For failures that require immediate attention. Exemples : perte de données, espace disque insuffisant.Examples: data loss scenarios, out of disk space.

Le niveau de journalisation permet de contrôler le volume de la sortie de journal écrite sur un support de stockage ou dans une fenêtre d’affichage.Use the log level to control how much log output is written to a particular storage medium or display window. Par exemple :For example:

  • En production :In production:
    • La journalisation Trace au Information niveau des niveaux de production génère un volume important de messages journaux détaillés.Logging at the Trace through Information levels produces a high-volume of detailed log messages. Pour contrôler les coûts et ne pas dépasser les limites de stockage des données, consignez les Trace Information messages de niveau dans un magasin de données volumineux et à faible coût.To control costs and not exceed data storage limits, log Trace through Information level messages to a high-volume, low-cost data store.
    • La journalisation au niveau Warning Critical des niveaux produit généralement moins de messages journaux plus petits.Logging at Warning through Critical levels typically produces fewer, smaller log messages. Par conséquent, les coûts et les limites de stockage ne sont généralement pas un problème, ce qui se traduit par une plus grande flexibilité du choix des magasins de données.Therefore, costs and storage limits usually aren't a concern, which results in greater flexibility of data store choice.
  • Lors du développement :During development:
    • Journalisation Warning Critical des messages dans la console.Log Warning through Critical messages to the console.
    • Ajoutez Trace Information des messages lors de la résolution des problèmes.Add Trace through Information messages when troubleshooting.

La section Filtrage de journal plus loin dans cet article explique comment déterminer les niveaux de journalisation gérés par un fournisseur.The Log filtering section later in this article explains how to control which log levels a provider handles.

ASP.NET Core écrit des journaux pour les événements de framework.ASP.NET Core writes logs for framework events. Aucun journal du niveau Debug ou Trace n’était créé dans les exemples de journaux présentés plus haut dans cet article, puisque les journaux au-dessous du niveau Information étaient exclus.The log examples earlier in this article excluded logs below Information level, so no Debug or Trace level logs were created. Voici un exemple de journaux Console produits par l’exemple d’application configurée pour afficher les journaux Debug :Here's an example of console logs produced by running the sample app configured to show Debug logs:

info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
      Request starting HTTP/1.1 GET http://localhost:62555/api/todo/0
dbug: Microsoft.AspNetCore.Routing.Tree.TreeRouter[1]
      Request successfully matched the route with name 'GetTodo' and template 'api/Todo/{id}'.
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
      Action 'TodoApi.Controllers.TodoController.Update (TodoApi)' with id '089d59b6-92ec-472d-b552-cc613dfd625d' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
      Action 'TodoApi.Controllers.TodoController.Delete (TodoApi)' with id 'f3476abe-4bd9-4ad3-9261-3ead09607366' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action TodoApi.Controllers.TodoController.GetById (TodoApi)
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action method TodoApi.Controllers.TodoController.GetById (TodoApi), returned result Microsoft.AspNetCore.Mvc.NotFoundResult.
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 0.8788ms
dbug: Microsoft.AspNetCore.Server.Kestrel[9]
      Connection id "0HL6L7NEFF2QD" completed keep alive response.
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
      Request finished in 2.7286ms 404

ID d’événement de logLog event ID

Chaque journal peut spécifier un ID d’événement.Each log can specify an event ID. Pour cela, l’exemple d’application utilise une classe LoggingEvents définie localement :The sample app does this by using a locally defined LoggingEvents class:

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public class LoggingEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems = 1001;
    public const int GetItem = 1002;
    public const int InsertItem = 1003;
    public const int UpdateItem = 1004;
    public const int DeleteItem = 1005;

    public const int GetItemNotFound = 4000;
    public const int UpdateItemNotFound = 4001;
}

Un ID d’événement associe un jeu d’événements.An event ID associates a set of events. Par exemple, tous les journaux liés à l’affichage d’une liste d’éléments sur une page peuvent être 1001.For example, all logs related to displaying a list of items on a page might be 1001.

Le fournisseur de journalisation peut stocker l’ID d’événement dans un champ ID, dans le message de journalisation, ou pas du tout.The logging provider may store the event ID in an ID field, in the logging message, or not at all. Le fournisseur Debug n’affiche pas les ID d’événements.The Debug provider doesn't show event IDs. Le fournisseur Console affiche les ID d’événements entre crochets après la catégorie :The console provider shows event IDs in brackets after the category:

info: TodoApi.Controllers.TodoController[1002]
      Getting item invalidid
warn: TodoApi.Controllers.TodoController[4000]
      GetById(invalidid) NOT FOUND

Modèle de message de journalLog message template

Chaque journal spécifie un modèle de message.Each log specifies a message template. Ce dernier peut contenir des espaces réservés pour lesquels les arguments sont fournis.The message template can contain placeholders for which arguments are provided. Utilisez des noms et non des nombres pour les espaces réservés.Use names for the placeholders, not numbers.

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

L’ordre des espaces réservés, pas leurs noms, détermine quels paramètres sont utilisés pour fournir leurs valeurs.The order of placeholders, not their names, determines which parameters are used to provide their values. Dans le code suivant, on voit que les noms de paramètres sont hors séquence dans le modèle de message :In the following code, notice that the parameter names are out of sequence in the message template:

string p1 = "parm1";
string p2 = "parm2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);

Ce code crée un message de journal avec les valeurs des paramètres dans la séquence :This code creates a log message with the parameter values in sequence:

Parameter values: parm1, parm2

Le framework de journalisation fonctionne ainsi pour permettre aux fournisseurs de journalisation d’implémenter la journalisation sémantique, également appelée journalisation structurée.The logging framework works this way so that logging providers can implement semantic logging, also known as structured logging. Les arguments proprement dits, et pas seulement le modèle de message mis en forme, sont transmis au système de journalisation.The arguments themselves are passed to the logging system, not just the formatted message template. C’est grâce à ces informations que les fournisseurs de journalisation peuvent stocker les valeurs des paramètres sous forme de champs.This information enables logging providers to store the parameter values as fields. Supposons par exemple que les appels de méthodes d’enregistreur d’événements se présentent ainsi :For example, suppose logger method calls look like this:

_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);

Si vous envoyez les journaux au Stockage Table Azure, chaque entité Table Azure peut avoir les propriétés ID et RequestTime, ce qui simplifie les requêtes sur les données de journaux.If you're sending the logs to Azure Table Storage, each Azure Table entity can have ID and RequestTime properties, which simplifies queries on log data. Une requête peut rechercher tous les journaux compris dans une plage RequestTime spécifique sans analyser le délai d’expiration du message texte.A query can find all logs within a particular RequestTime range without parsing the time out of the text message.

Journalisation des exceptionsLogging exceptions

Les méthodes logger ont des surcharges qui vous permettent de passer une exception, comme dans l’exemple suivant :The logger methods have overloads that let you pass in an exception, as in the following example:

catch (Exception ex)
{
    _logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({Id}) NOT FOUND", id);
    return NotFound();
}
return new ObjectResult(item);

Tous les fournisseurs ne gèrent pas les informations sur les exceptions de la même façon.Different providers handle the exception information in different ways. Voici un exemple de sortie du fournisseur Debug extrait du code montré plus haut.Here's an example of Debug provider output from the code shown above.

TodoApiSample.Controllers.TodoController: Warning: GetById(55) NOT FOUND

System.Exception: Item not found exception.
   at TodoApiSample.Controllers.TodoController.GetById(String id) in C:\TodoApiSample\Controllers\TodoController.cs:line 226

Filtrage de journalLog filtering

Vous pouvez spécifier un niveau de journalisation minimum pour une catégorie ou un fournisseur spécifique, ou pour l’ensemble des fournisseurs ou des catégories.You can specify a minimum log level for a specific provider and category or for all providers or all categories. Les enregistrements de journal en dessous du niveau minimum ne sont pas passés à ce fournisseur, et ne sont donc pas affichés ou stockés.Any logs below the minimum level aren't passed to that provider, so they don't get displayed or stored.

Pour supprimer tous les journaux, choisissez LogLevel.None comme niveau de journalisation minimal.To suppress all logs, specify LogLevel.None as the minimum log level. La valeur entière de LogLevel.None est 6, soit un niveau supérieur à LogLevel.Critical (5).The integer value of LogLevel.None is 6, which is higher than LogLevel.Critical (5).

Créer des règles de filtre dans la configurationCreate filter rules in configuration

Le code du modèle de projet appelle CreateDefaultBuilder pour configurer la journalisation des fournisseurs de console, de débogage et EventSource (ASP.NET Core 2,2 ou version ultérieure).The project template code calls CreateDefaultBuilder to set up logging for the Console, Debug, and EventSource (ASP.NET Core 2.2 or later) providers. La méthode CreateDefaultBuilder définit également la journalisation pour rechercher la configuration dans une section Logging, conformément à ce qui a été expliqué plus haut dans cet article.The CreateDefaultBuilder method sets up logging to look for configuration in a Logging section, as explained earlier in this article.

Les données de configuration spécifient des niveaux de journalisation minimum par fournisseur et par catégorie, comme dans l’exemple suivant :The configuration data specifies minimum log levels by provider and category, as in the following example:

{
  "Logging": {
    "Debug": {
      "LogLevel": {
        "Default": "Information"
      }
    },
    "Console": {
      "IncludeScopes": false,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

Ce code JSON crée six règles de filtre : une pour le fournisseur Debug, quatre pour le fournisseur Console et une pour tous les fournisseurs.This JSON creates six filter rules: one for the Debug provider, four for the Console provider, and one for all providers. Une seule règle est choisie pour chaque fournisseur à la création d’un objet ILogger.A single rule is chosen for each provider when an ILogger object is created.

Règles de filtre dans le codeFilter rules in code

L'exemple suivant montre comment enregistrer des règles de filtre dans le code :The following example shows how to register filter rules in code:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logging =>
        logging.AddFilter("System", LogLevel.Debug)
               .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace));

Le second AddFilter spécifie le fournisseur Debug par son nom de type.The second AddFilter specifies the Debug provider by using its type name. Le premier AddFilter s’applique à tous les fournisseurs, car il ne spécifie aucun type de fournisseur.The first AddFilter applies to all providers because it doesn't specify a provider type.

Mode d’application des règles de filtreHow filtering rules are applied

Les données de configuration et le code AddFilter contenus dans les exemples précédents créent les règles présentées dans le tableau suivant.The configuration data and the AddFilter code shown in the preceding examples create the rules shown in the following table. Les six premières proviennent de l’exemple de configuration et les deux dernières, de l’exemple de code.The first six come from the configuration example and the last two come from the code example.

NumberNumber FournisseurProvider Catégories commençant par...Categories that begin with ... Niveau de journalisation minimumMinimum log level
11 DébogageDebug Toutes les catégoriesAll categories InformationInformation
22 ConsoleConsole Microsoft. AspNetCore. Mvc. Razor . IntérieursMicrosoft.AspNetCore.Mvc.Razor.Internal AvertissementWarning
33 ConsoleConsole Microsoft. AspNetCore. Mvc. Razor .RazorMicrosoft.AspNetCore.Mvc.Razor.Razor DébogageDebug
44 ConsoleConsole Microsoft. AspNetCore. Mvc.RazorMicrosoft.AspNetCore.Mvc.Razor ErrorError
55 ConsoleConsole Toutes les catégoriesAll categories InformationInformation
66 Tous les fournisseursAll providers Toutes les catégoriesAll categories DébogageDebug
77 Tous les fournisseursAll providers SystèmeSystem DébogageDebug
88 DébogageDebug MicrosoftMicrosoft TraceTrace

À la création d’un objet ILogger, l’objet ILoggerFactory sélectionne une seule règle à appliquer à cet enregistrement d’événements par fournisseur.When an ILogger object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. Tous les messages écrits par une instance ILogger sont filtrés selon les règles sélectionnées.All messages written by an ILogger instance are filtered based on the selected rules. La règle la plus spécifique pouvant être appliquée à chaque paire catégorie/fournisseur est sélectionnée parmi les règles disponibles.The most specific rule possible for each provider and category pair is selected from the available rules.

L’algorithme suivant est utilisé pour chaque fournisseur quand un objet ILogger est créé pour une catégorie donnée :The following algorithm is used for each provider when an ILogger is created for a given category:

  • Sélectionnez toutes les règles qui correspondent au fournisseur ou à son alias.Select all rules that match the provider or its alias. Si aucune correspondance n’est trouvée, sélectionnez toutes les règles avec un fournisseur vide.If no match is found, select all rules with an empty provider.
  • À partir du résultat de l’étape précédente, sélectionnez les règles ayant le plus long préfixe de catégorie correspondant.From the result of the preceding step, select rules with longest matching category prefix. Si aucune correspondance n’est trouvée, sélectionnez toutes les règles qui ne spécifient pas de catégorie.If no match is found, select all rules that don't specify a category.
  • Si plusieurs règles sont sélectionnées, prenez la dernière.If multiple rules are selected, take the last one.
  • Si aucune règle n’est sélectionnée, utilisez MinimumLevel.If no rules are selected, use MinimumLevel.

Avec la liste de règles ci-dessus, supposons que vous créez un ILogger objet pour la catégorie «Microsoft. AspNetCore. Mvc. Razor Razor Moteur " :With the preceding list of rules, suppose you create an ILogger object for category "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":

  • Les règles 1, 6 et 8 s’appliquent au fournisseur Debug.For the Debug provider, rules 1, 6, and 8 apply. La règle 8 est sélectionnée, car c’est la plus spécifique.Rule 8 is most specific, so that's the one selected.
  • Les règles 3, 4, 5 et 6 s’appliquent au fournisseur Console.For the Console provider, rules 3, 4, 5, and 6 apply. La règle 3 est la plus spécifique.Rule 3 is most specific.

L’instance ILogger ainsi produite envoie des journaux de niveau Trace ou supérieur au fournisseur Debug.The resulting ILogger instance sends logs of Trace level and above to the Debug provider. Les journaux de niveau Debug et supérieurs sont envoyés au fournisseur Console.Logs of Debug level and above are sent to the Console provider.

Alias de fournisseurProvider aliases

Chaque fournisseur définit un alias qui peut être utilisé dans la configuration à la place du nom de type complet.Each provider defines an alias that can be used in configuration in place of the fully qualified type name. Pour les fournisseurs intégrés, utilisez les alias suivants :For the built-in providers, use the following aliases:

  • ConsoleConsole
  • DébogageDebug
  • EventSourceEventSource
  • EventLogEventLog
  • TraceSourceTraceSource
  • AzureAppServicesFileAzureAppServicesFile
  • AzureAppServicesBlobAzureAppServicesBlob
  • ApplicationInsightsApplicationInsights

Niveau minimum par défautDefault minimum level

Un paramètre de niveau minimum est utilisé uniquement si aucune règle de la configuration ou du code ne s’applique à une catégorie ou un fournisseur spécifique.There's a minimum level setting that takes effect only if no rules from configuration or code apply for a given provider and category. L’exemple suivant montre comment définir le niveau minimum :The following example shows how to set the minimum level:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning));

Si vous ne définissez pas explicitement le niveau minimum, la valeur par défaut est Information, ce qui signifie que les niveaux Trace et Debug sont ignorés.If you don't explicitly set the minimum level, the default value is Information, which means that Trace and Debug logs are ignored.

Fonctions de filtrageFilter functions

Une fonction de filtre est appelée pour tous les fournisseurs et toutes les catégories pour lesquels la configuration ou le code n’applique aucune règle.A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code. Le code de la fonction a accès au type de fournisseur, à la catégorie et au niveau de journalisation.Code in the function has access to the provider type, category, and log level. Par exemple :For example:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logBuilder =>
    {
        logBuilder.AddFilter((provider, category, logLevel) =>
        {
            if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
                category == "TodoApiSample.Controllers.TodoController")
            {
                return false;
            }
            return true;
        });
    });

Niveaux et les catégories de systèmeSystem categories and levels

Voici quelques catégories utilisées par ASP.NET Core et Entity Framework Core, avec des notes sur les journaux associés :Here are some categories used by ASP.NET Core and Entity Framework Core, with notes about what logs to expect from them:

CategoryCategory NotesNotes
Microsoft.AspNetCoreMicrosoft.AspNetCore Diagnostics ASP.NET Core généraux.General ASP.NET Core diagnostics.
Microsoft.AspNetCore.DataProtectionMicrosoft.AspNetCore.DataProtection Liste des clés considérées, trouvées et utilisées.Which keys were considered, found, and used.
Microsoft.AspNetCore.HostFilteringMicrosoft.AspNetCore.HostFiltering Hôtes autorisés.Hosts allowed.
Microsoft.AspNetCore.HostingMicrosoft.AspNetCore.Hosting Temps de traitement des requêtes HTTP et heure de démarrage.How long HTTP requests took to complete and what time they started. Liste des assemblys de démarrage d’hébergement chargés.Which hosting startup assemblies were loaded.
Microsoft.AspNetCore.MvcMicrosoft.AspNetCore.Mvc MVC et Razor Diagnostics.MVC and Razor diagnostics. Liaison de données, exécution de filtres, compilation de vues, sélection d’actions.Model binding, filter execution, view compilation, action selection.
Microsoft.AspNetCore.RoutingMicrosoft.AspNetCore.Routing Informations de correspondance des itinéraires.Route matching information.
Microsoft.AspNetCore.ServerMicrosoft.AspNetCore.Server Démarrage et arrêt de la connexion, et réponses persistantes.Connection start, stop, and keep alive responses. Informations du certificat HTTPS.HTTPS certificate information.
Microsoft.AspNetCore.StaticFilesMicrosoft.AspNetCore.StaticFiles Fichiers pris en charge.Files served.
Microsoft.EntityFrameworkCoreMicrosoft.EntityFrameworkCore Diagnostics Entity Framework Core généraux.General Entity Framework Core diagnostics. Activité et configuration de la base de données, détection des modifications, migrations.Database activity and configuration, change detection, migrations.

Étendues de journalLog scopes

Une étendue peut regrouper un ensemble d’opérations logiques.A scope can group a set of logical operations. Ce regroupement permet de joindre les mêmes données à tous les journaux créés au sein d’un ensemble.This grouping can be used to attach the same data to each log that's created as part of a set. Par exemple, chaque journal créé dans le cadre du traitement d’une transaction peut contenir l’ID de la transaction.For example, every log created as part of processing a transaction can include the transaction ID.

Une étendue est un type IDisposable qui est retourné par la méthode BeginScope. Elle s’applique tant qu’elle n’est pas supprimée.A scope is an IDisposable type that's returned by the BeginScope method and lasts until it's disposed. Utilisez une étendue en incluant les appels de l’enregistrement d’événements dans un bloc using :Use a scope by wrapping logger calls in a using block:

public IActionResult GetById(string id)
{
    TodoItem item;
    using (_logger.BeginScope("Message attached to logs created in the using block"))
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        item = _todoRepository.Find(id);
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
    }
    return new ObjectResult(item);
}

Le code suivant active les étendues pour le fournisseur Console :The following code enables scopes for the console provider:

Program.cs:Program.cs:

.ConfigureLogging((hostingContext, logging) =>
{
    logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
    logging.AddConsole(options => options.IncludeScopes = true);
    logging.AddDebug();
})

Notes

La configuration de l’option logger IncludeScopes pour la console est nécessaire pour activer la journalisation basée sur des étendues.Configuring the IncludeScopes console logger option is required to enable scope-based logging.

Pour plus d'informations sur la configuration, reportez-vous à la section Configuration.For information on configuration, see the Configuration section.

Chaque message de journal fournit les informations incluses dans l’étendue :Each log message includes the scoped information:

info: TodoApiSample.Controllers.TodoController[1002]
      => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApiSample.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
      Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
      => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApiSample.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
      GetById(0) NOT FOUND

Fournisseurs de journalisation intégrésBuilt-in logging providers

ASP.NET Core contient les fournisseurs suivants :ASP.NET Core ships the following providers:

Pour plus d’informations sur stdout et sur la journalisation du débogage avec le module ASP.NET Core, consultez Résoudre les problèmes de ASP.NET Core sur Azure App Service et IIS et Module ASP.NET Core.For information on stdout and debug logging with the ASP.NET Core Module, see Résoudre les problèmes de ASP.NET Core sur Azure App Service et IIS and Module ASP.NET Core.

Fournisseur ConsoleConsole provider

Le package de fournisseur Microsoft.Extensions.Logging.Console envoie la sortie de journal dans la console.The Microsoft.Extensions.Logging.Console provider package sends log output to the console.

logging.AddConsole();

Pour voir la sortie de la journalisation Console, ouvrez une invite de commandes dans le dossier du projet et exécutez la commande suivante :To see console logging output, open a command prompt in the project folder and run the following command:

dotnet run

Fournisseur DebugDebug provider

Le package de fournisseur Microsoft.Extensions.Logging.Debug écrit la sortie de journal à l’aide de la classe System.Diagnostics.Debug (appels de la méthode Debug.WriteLine).The Microsoft.Extensions.Logging.Debug provider package writes log output by using the System.Diagnostics.Debug class (Debug.WriteLine method calls).

Sur Linux, ce fournisseur écrit la sortie de log dans /var/log/message.On Linux, this provider writes logs to /var/log/message.

logging.AddDebug();

Fournisseur de source d’événementsEvent Source provider

Le package du fournisseur Microsoft. extensions. Logging. EventSource écrit dans une source d’événement multiplateforme portant le nom Microsoft-Extensions-Logging .The Microsoft.Extensions.Logging.EventSource provider package writes to an Event Source cross-platform with the name Microsoft-Extensions-Logging. Sur Windows, le fournisseur utilise ETW.On Windows, the provider uses ETW.

logging.AddEventSourceLogger();

Le fournisseur de la source d’événements est ajouté automatiquement lorsque CreateDefaultBuilder est appelé pour générer l’hôte.The Event Source provider is added automatically when CreateDefaultBuilder is called to build the host.

Utilisez l' utilitaire PerfView pour collecter et afficher les journaux.Use the PerfView utility to collect and view logs. Il existe d’autres outils d’affichage des journaux ETW, mais PerfView est l’outil recommandé pour gérer les événements ETW générés par ASP.NET Core.There are other tools for viewing ETW logs, but PerfView provides the best experience for working with the ETW events emitted by ASP.NET Core.

Pour configurer PerfView afin qu’il collecte les événements enregistrés par ce fournisseur, ajoutez la chaîne *Microsoft-Extensions-Logging à la liste des fournisseurs supplémentaires.To configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. (N’oubliez pas d’inclure l’astérisque au début de la chaîne.)(Don't miss the asterisk at the start of the string.)

Fournisseurs supplémentaires dans PerfView

Fournisseur EventLog WindowsWindows EventLog provider

Le package de fournisseur Microsoft.Extensions.Logging.EventLog envoie la sortie de journal dans le journal des événements Windows.The Microsoft.Extensions.Logging.EventLog provider package sends log output to the Windows Event Log.

logging.AddEventLog();

Les surcharges AddEventLog vous permettent de passer à EventLogSettings.AddEventLog overloads let you pass in EventLogSettings. Si null ou n’est pas spécifié, les paramètres par défaut suivants sont utilisés :If null or not specified, the following default settings are used:

  • LogName: « Application »LogName: "Application"
  • SourceName: « .NET Runtime »SourceName: ".NET Runtime"
  • MachineName: Le nom de l’ordinateur local est utilisé.MachineName: The local machine name is used.

Les événements sont consignés pour le niveau d’avertissement et supérieur.Events are logged for Warning level and higher. L’exemple suivant définit le niveau de journalisation par défaut du journal des événements sur LogLevel.Information :The following example sets the Event Log default log level to LogLevel.Information:

"Logging": {
  "EventLog": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Fournisseur TraceSourceTraceSource provider

Le package de fournisseur Microsoft.Extensions.Logging.TraceSource utilise les bibliothèques et fournisseurs TraceSource.The Microsoft.Extensions.Logging.TraceSource provider package uses the TraceSource libraries and providers.

logging.AddTraceSource(sourceSwitchName);

Les surcharges AddTraceSource vous permettent de passer un commutateur de source et un écouteur de suivi.AddTraceSource overloads let you pass in a source switch and a trace listener.

Pour pouvoir utiliser ce fournisseur, il faut que l’application s’exécute sur .NET Framework (au lieu de .NET Core).To use this provider, an app has to run on the .NET Framework (rather than .NET Core). Le fournisseur peut acheminer les messages vers différents détecteurs d’événements, comme TextWriterTraceListener (utilisé dans l’exemple d’application).The provider can route messages to a variety of listeners, such as the TextWriterTraceListener used in the sample app.

Fournisseur Azure App ServiceAzure App Service provider

Le package de fournisseur Microsoft.Extensions.Logging.AzureAppServices écrit les enregistrements de journal dans des fichiers texte dans le système de fichiers d’une application Azure App Service, et dans un stockage Blob dans un compte de stockage Azure.The Microsoft.Extensions.Logging.AzureAppServices provider package writes logs to text files in an Azure App Service app's file system and to blob storage in an Azure Storage account.

logging.AddAzureWebAppDiagnostics();

Le package du fournisseur n’est pas inclus dans le métapaquet Microsoft.AspNetCore.App.The provider package isn't included in the Microsoft.AspNetCore.App metapackage. Lorsque vous ciblez .NET framework ou référencez le métapackage Microsoft.AspNetCore.App, ajoutez le package de fournisseur dans le projet.When targeting .NET Framework or referencing the Microsoft.AspNetCore.App metapackage, add the provider package to the project.

Une surcharge AddAzureWebAppDiagnostics permet de transmettre AzureAppServicesDiagnosticsSettings.An AddAzureWebAppDiagnostics overload lets you pass in AzureAppServicesDiagnosticsSettings. L’objet de paramètres peut remplacer les paramètres par défaut, comme le modèle de sortie de journalisation, le nom d’objet blob et la limite de taille de fichier.The settings object can override default settings, such as the logging output template, blob name, and file size limit. (Modèle de sortie est un modèle de message qui s’applique à tous les journaux en plus de ce qui est fourni avec un appel de méthode ILogger.)(Output template is a message template that's applied to all logs in addition to what's provided with an ILogger method call.)

En cas de déploiement sur une application App Service, celle-ci applique les paramètres définis dans la section Journaux App Service de la page App Service du portail Azure.When you deploy to an App Service app, the application honors the settings in the App Service logs section of the App Service page of the Azure portal. Quand les paramètres suivants sont mis à jour, les changements prennent effet immédiatement sans avoir besoin de redémarrer ou redéployer l’application.When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • Journalisation des applications (système de fichiers)Application Logging (Filesystem)
  • Journalisation des applications (objet blob)Application Logging (Blob)

L’emplacement par défaut des fichiers journaux est le dossier D:\racine\LogFiles\Application, et le nom de fichier par défaut est diagnostics-aaaammjj.txt.The default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is diagnostics-yyyymmdd.txt. La limite de taille de fichier par défaut est de 10 Mo, et le nombre maximal de fichiers conservés par défaut est de 2.The default file size limit is 10 MB, and the default maximum number of files retained is 2. Le nom par défaut du blob est {app-name}{timestamp}/aaaa/mm/jj/hh/{guid}-applicationLog.txt.The default blob name is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Le fournisseur fonctionne uniquement quand le projet s’exécute dans l’environnement Azure.The provider only works when the project runs in the Azure environment. Il n’a aucun effet si le projet s’exécute localement — il n’écrit pas d’enregistrements dans les fichiers locaux ou dans le stockage de développement local pour les objets blob.It has no effect when the project is run locally—it doesn't write to local files or local development storage for blobs.

Streaming des journaux AzureAzure log streaming

La diffusion en continu des journaux Azure permet d’afficher l’activité de journalisation en temps réel aux emplacements suivants :Azure log streaming lets you view log activity in real time from:

  • Serveur d'applicationsThe app server
  • Serveur webThe web server
  • Suivi des demandes ayant échouéFailed request tracing

Pour configurer le streaming des journaux Azure :To configure Azure log streaming:

  • Accédez à la page Journaux App Service dans le portail de votre application.Navigate to the App Service logs page from your app's portal page.
  • Définissez Journal des applications (Système de fichiers) sur Activé.Set Application Logging (Filesystem) to On.
  • Choisissez le niveau du journal.Choose the log Level. Ce paramètre s’applique uniquement à la diffusion en continu de journaux Azure, pas aux autres fournisseurs de journalisation de l’application.This setting only applies to Azure log streaming, not other logging providers in the app.

Accédez à la page Streaming des journaux pour voir les messages d’application.Navigate to the Log Stream page to view app messages. Ils sont consignés par application par le biais de l’interface ILogger.They're logged by the app through the ILogger interface.

Journalisation des traces Azure Application InsightsAzure Application Insights trace logging

Le package de fournisseur Microsoft.Extensions.Logging.ApplicationInsights écrit des journaux dans Azure Application Insights.The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights. Application Insights est un service qui surveille une application web et fournit des outils pour interroger et analyser les données de télémétrie.Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. Si vous utilisez ce fournisseur, vous pouvez interroger et analyser vos journaux à l’aide des outils Application Insights.If you use this provider, you can query and analyze your logs by using the Application Insights tools.

Le fournisseur de journalisation est inclus en tant que dépendance de Microsoft.ApplicationInsights.AspNetCore, le package qui fournit toutes les données de télémétrie disponibles pour ASP.NET Core.The logging provider is included as a dependency of Microsoft.ApplicationInsights.AspNetCore, which is the package that provides all available telemetry for ASP.NET Core. Si vous utilisez ce package, vous n’avez pas besoin d’installer le package du fournisseur.If you use this package, you don't have to install the provider package.

N’utilisez pas le package Microsoft.ApplicationInsights.Web package—destiné à ASP.NET 4.x.Don't use the Microsoft.ApplicationInsights.Web package—that's for ASP.NET 4.x.

Pour plus d’informations, consultez les ressources suivantes :For more information, see the following resources:

Fournisseurs de journalisation tiersThird-party logging providers

Frameworks de journalisation tiers qui sont pris en charge dans ASP.NET Core :Third-party logging frameworks that work with ASP.NET Core:

Certains frameworks tiers prennent en charge la journalisation sémantique, également appelée journalisation structurée.Some third-party frameworks can perform semantic logging, also known as structured logging.

L’utilisation d’un framework tiers est semblable à l’utilisation des fournisseurs intégrés :Using a third-party framework is similar to using one of the built-in providers:

  1. Ajoutez un package NuGet à votre projet.Add a NuGet package to your project.
  2. Appeler une ILoggerFactory méthode d’extension fournie par le Framework de journalisation.Call an ILoggerFactory extension method provided by the logging framework.

Pour plus d’informations, consultez la documentation de chaque fournisseur.For more information, see each provider's documentation. Les fournisseurs de journalisation tiers ne sont pas pris en charge par Microsoft.Third-party logging providers aren't supported by Microsoft.

Ressources supplémentairesAdditional resources