Propriétés obsolètes sur ConsoleLoggerOptions

Le type Microsoft.Extensions.Logging.Console.ConsoleLoggerFormat et certaines propriétés sur ConsoleLoggerOptions sont désormais obsolètes.

Description de la modification

À compter de .NET 5, le type Microsoft.Extensions.Logging.Console.ConsoleLoggerFormat et plusieurs propriétés sur ConsoleLoggerOptions sont obsolètes. Les propriétés obsolètes sont les suivantes :

• ConsoleLoggerOptions.DisableColors
• ConsoleLoggerOptions.IncludeScopes
• ConsoleLoggerOptions.TimestampFormat
• ConsoleLoggerOptions.UseUtcTimestamp
• ConsoleLoggerOptions.Format

Avec l’introduction de nouveaux formateurs, ces propriétés sont désormais disponibles sur les formateurs individuels.

Raison du changement

La propriété Format est un type d’énumération, qui ne peut pas représenter un formateur personnalisé.

Les propriétés restantes ont été définies sur ConsoleLoggerOptions et appliquées aux deux formats intégrés pour les journaux de console. Toutefois, avec l’introduction d’une nouvelle API de formateur, il est plus logique que la mise en forme soit représentée sur les options spécifiques au formateur. Cette modification offre une meilleure séparation entre l’enregistreur d’événements et les formateurs de l’enregistreur d’événements.

Version introduite

5,0

Action recommandée

• Utilisez la nouvelle propriété ConsoleLoggerOptions.FormatterName à la place de la propriété ConsoleLoggerOptions.Format. Par exemple :

  loggingBuilder.AddConsole(options =>
  {
    options.FormatterName = ConsoleFormatterNames.Systemd;
  });
  

  Il existe plusieurs différences entre FormatterName et Format :

  • Format n’a que deux options possibles : Default et Systemd.
  • FormatterName ne respecte pas la casse et peut être n’importe quelle chaîne. Les noms intégrés réservés sont Simple, Systemd et Json (.NET 5 et versions ultérieures).
  • "Format": "Systemd" correspond à "FormatterName": "Systemd".
  • "Format": "Default" correspond à "FormatterName": "Simple".

• Pour les propriétés DisableColors, IncludeScopes, TimestampFormat et UseUtcTimestamp, utilisez la propriété correspondante sur les nouveaux types ConsoleFormatterOptions, JsonConsoleFormatterOptions ou SimpleConsoleFormatterOptions à la place. Par exemple, le paramètre correspondant pour ConsoleLoggerOptions.DisableColors est SimpleConsoleFormatterOptions.ColorBehavior.

  Code précédent :

  loggingBuilder.AddConsole(options =>
  {
      options.DisableColors = true;
  });
  

  Nouveau code :

  loggingBuilder.AddSimpleConsole(options =>
  {
      options.ColorBehavior = LoggerColorBehavior.Disabled;
  });
  

Les deux extraits de code JSON suivants montrent comment le fichier de configuration change. Ancien fichier de configuration :

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

    "Console": {
      "LogLevel": {
        "Default": "Information"
      },
      "Format": "Systemd",
      "IncludeScopes": true,
      "TimestampFormat": "HH:mm:ss",
      "UseUtcTimestamp": true
    }
  },
  "AllowedHosts": "*"
}

Nouveau fichier de configuration :

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

    "Console": {
      "LogLevel": {
        "Default": "Information"
      },
      "FormatterName": "Systemd",
      "FormatterOptions": {
        "IncludeScopes": true,
        "TimestampFormat": "HH:mm:ss",
        "UseUtcTimestamp": true
      }
    }
  },
  "AllowedHosts": "*"
}

API affectées

• Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.DisableColors
• Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.IncludeScopes
• Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.TimestampFormat
• Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.UseUtcTimestamp
• Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.Format