Blazor/Documentation/docusaurus/i18n/fr/docusaurus-plugin-content-docs/current/use-logging.md

sidebar_position	title
14	Utiliser les logs

Installer la journalisation

Par défaut, une application Blazor Server est déjà parametré pour l'utilisation de la journalisation.

Avec Blazor WebAssembly, nous sommes désormais en mesure de créer des applications monopage (SPA) à l'aide de C# et du framework ASP.NET Core. Lorsque vous venez d'ASP.NET Core MVC, vous pouvez vous demander quelles fonctionnalités .NET sont disponibles, limitées ou non disponibles lors de l'exécution dans le navigateur. L'une d'eux est la journalisation, qui est un moyen de base pour le débogage dans les environnements de production et pendant le développement.

Pour une application Blazor WASM l'installation du nuget Microsoft.Extensions.Logging.Configuration sera requis.

Dans le fichier de paramètres de l’application, fournissez la configuration de journalisation. La configuration de la journalisation est chargée dans Program.cs.

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

De même pour Blazor WASM l'ajout de l’espace de noms Microsoft.Extensions.Logging.Configuration et la configuration de la journalidation à Program.cs sera requis :

using Microsoft.Extensions.Logging;

...

builder.Logging.AddConfiguration(builder.Configuration.GetSection("Logging"));

Utiliser les logs

Pour créer des journaux, utilisez un objet ILogger<TCategoryName> à partir de la DI ILogger<TCategoryName>.

L’exemple suivant :

• Crée un enregistreur d’événements, ILogger<CreateLog> , qui utilise une ILogger<CreateLog> de journal du nom qualifié complet du type CreateLog . La catégorie du journal est une chaîne associée à chaque journal.
• Appels chaque niveau de log avec la méthode Log.

@page "/logs"

<h3>CreateLog</h3>

<button @onclick="CreateLogs">Create logs</button>

using Microsoft.Extensions.Logging;

public partial class CreateLog
{
	[Inject]
	public ILogger<CreateLog> Logger { get; set; }

	private void CreateLogs()
	{
		var logLevels = Enum.GetValues(typeof(LogLevel)).Cast<LogLevel>();

		foreach (var logLevel in logLevels.Where(l => l != LogLevel.None))
		{
			Logger.Log(logLevel, $"Log message for the level: {logLevel}");
		}
	}
}

Voici le résultat une fois le bouton cliqué :

Configuration de la journalisation

La configuration de la journalisation est généralement fournie par la section Logging des fichiers appsettings.{Environment}.json.

L’exemple de code suivant appsettings.Development.json est généré par les modèles d’application web :

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

Dans le code JSON précédent :

• Les catégories "Default", "Microsoft" et "Microsoft.Hosting.Lifetime" sont spécifiées.
• La catégorie "Microsoft" s’applique à toutes les catégories qui commencent par "Microsoft". Par exemple, ce paramètre s’applique à la catégorie "Microsoft.AspNetCore.Routing.EndpointMiddleware".
• La catégorie "Microsoft" enregistre les logs au niveau Warning et supérieur.
• La catégorie "Microsoft.Hosting.Lifetime" est plus spécifique que la catégorie "Microsoft", de sorte que la catégorie "Microsoft.Hosting.Lifetime" enregistre les logs au niveau Information et supérieur.

La propriété Logging peut avoir différent LogLevel et fournisseur. LogLevel spécifie le LogLevel minimal à enregistrer pour les catégories sélectionnées. Dans le code JSON précédent, les niveaux Information & Warning de journalisation sont spécifiés. LogLevel indique la gravité du journal et les plages de 0 à 6 :

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

Lorsqu’un LogLevel est spécifié, la journalisation est activée pour les messages au niveau spécifié et supérieur. Dans le code JSON précédent, la catégorie Default est journalisée pour Information et les versions ultérieures. Par exemple, les messages Information, Warning, Error et Critical sont journalisés. Si aucun LogLevel n’est spécifié, la journalisation est définie par défaut sur le niveau Information.

Une propriété de fournisseur peut spécifier une propriété LogLevel. LogLevel sous un fournisseur spécifie les niveaux de journalisation pour ce fournisseur, et remplace les paramètres du journal non fournisseur.

Prenons le appsettings.json fichier suivant :

{
  "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.
      }
    }
  }
}

Les paramètres dans Logging.{providername}.LogLevel remplace les paramètres dans Logging.LogLevel. Dans le code JSON précédent, le valeur par défaut du provider Debug sont à Information :

Logging:Debug:LogLevel:Default:Information

Mode d’application des règles de filtre

À 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. Tous les messages écrits par une instance ILogger sont filtrés selon les règles sélectionnées. La règle la plus spécifique pour chaque paire fournisseur et catégorie est sélectionnée parmi les règles disponibles.

L’algorithme suivant est utilisé pour chaque fournisseur quand un objet ILogger est créé pour une catégorie donnée :

• Sélectionnez toutes les règles qui correspondent au fournisseur ou à son alias. Si aucune correspondance n’est trouvée, sélectionnez toutes les règles avec un fournisseur vide.
• À 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. Si aucune correspondance n’est trouvée, sélectionnez toutes les règles qui ne spécifient pas de catégorie.
• Si plusieurs règles sont sélectionnées, prenez la dernière.
• Si aucune règle n’est sélectionnée, utilisez MinimumLevel.

Log level

Le tableau suivant répertorie les valeurs de LogLevel :

LogLevel	Valeur	Méthode	Description
Trace	0	LogTrace	Contiennent les messages les plus détaillés. Ces messages peuvent contenir des données d’application sensibles. Ces messages sont désactivés par défaut et ne doivent pas être activés en production.
Déboguer	1	LogDebug	Pour le débogage et le développement. Utilisez avec précaution en production en raison du volume élevé.
Informations	2	LogInformation	Effectue le suivi du déroulement général de l’application. Peut avoir une valeur à long terme.
Avertissement	3	LogWarning	Pour les événements anormaux ou inattendus. Comprend généralement des erreurs ou des conditions qui ne provoquent pas l’échec de l’application.
Error	4	LogError	Fournit des informations sur des erreurs et des exceptions qui ne peuvent pas être gérées. Ces messages indiquent un échec dans l’opération ou la demande en cours, et non dans l’ensemble de l’application.
Critique	5	LogCritical	Fournit des informations sur des échecs qui nécessitent un examen immédiat. Exemples : perte de données, espace disque insuffisant.
Aucun	6		Spécifie qu’une catégorie de journalisation ne doit écrire aucun message.

Dans le tableau précédent, la LogLevel est indiquée du niveau de gravité le plus bas au plus élevé.

Le premier paramètre de la méthode de journalisation, LogLevel, indique la gravité du journal.

Au lieu d’appeler Log(LogLevel, ...), la plupart des développeurs appellent les méthodes d’extension Log{LogLevel}. Les méthodes d’extension Log{LogLevel} appellent la méthode Log en spécifiant le LogLevel. Par exemple, les deux appels de journalisation suivants sont fonctionnellement équivalents et produisent le même journal :

var message = "My Log Message";

Logger.Log(LogLevel.Information, message);
Logger.LogInformation(message);

Le code suivant crée des journaux Information et Warning :

var id = 10;

Logger.LogInformation("Getting item {Id}", id);

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

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

Dans le code précédent, le premier argument de Log{LogLevel} 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.

Modèle de message de journal

Chaque API de journal utilise un modèle de message. Ce dernier peut contenir des espaces réservés pour lesquels les arguments sont fournis. Utilisez des noms et non des nombres pour les espaces réservés.

var id = 10;

Logger.LogInformation("Getting item {Id}", id);

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

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

L'ordre des paramètres, et non leurs noms d’espaces réservés, détermine les paramètres qui sont utilisés pour fournir des valeurs d’espace réservé dans les messages de journal.

Dans le code suivant, les noms de paramètres sont hors séquence dans les espaces réservés du modèle de message :

int apples = 1;
int pears = 2;
int bananas = 3;

Logger.LogInformation("Parameters: {pears}, {bananas}, {apples}", apples, pears, bananas);

Toutefois, les paramètres sont affectés aux espaces réservés dans l’ordre suivant : apples , pears , bananas .

Le message du journal reflète l' ordre des paramètres:

Parameters: 1, 2, 3

Cette approche permet aux fournisseurs de journalisation d’implémenter la journalisation sémantique ou structurée. Les arguments proprement dits, et pas seulement le modèle de message mis en forme, sont transmis au système de journalisation. Cela permet aux fournisseurs de journalisation de stocker les valeurs de paramètres en tant que champs.

Par exemple, considérez la méthode d’enregistreur d’événements suivante :

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

par exemple, lors de la journalisation dans le Stockage de Table Azure :

• Chaque entité de table Azure peut avoir des propriétés ID et RequestTime.
• Les tables avec des propriétés simplifient les requêtes sur les données journalisées. Par exemple, une requête peut trouver tous les journaux d’une plage donnée RequestTime sans avoir à analyser le délai d’attente du message texte.