ведение журнала ASP.NET Core Blazor

В этой статье содержатся сведения о входе в приложения Blazor, особенно в сценариях логирования на стороне клиента.

Общие рекомендации по логированию в ASP.NET Core, включая как осуществлять логирование из компонентов Razor, см. в разделе Логирование в .NET и ASP.NET Core.

Configuration

Конфигурацию ведения журнала можно загрузить из файлов параметров приложения. Дополнительные сведения см. в разделе ASP.NET Core Blazor configuration.

На уровнях журналов по умолчанию и без настройки дополнительных поставщиков ведения журнала:

• На сервере ведение журнала выполняется только на серверной консоли .NET в среде Development на уровне LogLevel.Information или выше.
• На клиенте ведение журнала происходит только в консоли инструментов разработчика браузера на уровне LogLevel.Information или выше.

Уровни логирования

Уровни журналов соответствуют уровням журналов приложений ASP.NET Core, которые перечислены в документации API на LogLevel.

Ведение журнала на стороне клиента

Не каждая функция ведения журнала ASP.NET Core поддерживается на стороне клиента. Например, клиентские компоненты не имеют доступа к файловой системе или сети клиента, поэтому запись журналов в физическое или сетевое хранилище клиента невозможна. При использовании сторонней службы ведения журналов, предназначенной для работы с одностраничными приложениями, следуйте инструкциям в руководстве по безопасности службы. Помните, что все части данных, включая ключи или секреты, хранящиеся на стороне клиента, небезопасны и могут быть легко обнаружены вредоносными пользователями.

using Microsoft.Extensions.Logging;

Настройте журналирование в клиентских приложениях, используя свойство WebAssemblyHostBuilder.Logging. Свойство Logging имеет тип ILoggingBuilder, поэтому поддерживаются методы расширения ILoggingBuilder.

Чтобы задать минимальный уровень ведения журнала, вызовите метод LoggingBuilderExtensions.SetMinimumLevel на построителе узлов в Program файле с помощью LogLevel. В следующем примере значение минимального уровня ведения журнала устанавливается равным Warning:

builder.Logging.SetMinimumLevel(LogLevel.Warning);

var host = builder.Build();

var logger = host.Services.GetRequiredService<ILoggerFactory>()
    .CreateLogger<Program>();

logger.LogInformation("Logged after the app is built in the Program file.");

await host.RunAsync();

var logger = LoggerFactory.CreateLogger("CustomCategory");
logger.LogWarning("Someone has clicked me!");

public class LogEvent
{
    public const int Event1 = 1000;
    public const int Event2 = 1001;
}

logger.LogInformation(LogEvent.Event1, "Someone has clicked me!");
logger.LogWarning(LogEvent.Event2, "Someone has clicked me!");

logger.LogInformation("Someone clicked me at {CurrentDT}!", DateTime.UtcNow);

currentCount++;

try
{
    if (currentCount == 3)
    {
        currentCount = 4;
        throw new OperationCanceledException("Skip 3");
    }
}
catch (Exception ex)
{
    logger.LogWarning(ex, "Exception (currentCount: {Count})!", currentCount);
}

builder.Logging.AddFilter((provider, category, logLevel) =>
    category.Equals("CustomCategory2") && logLevel == LogLevel.Information);

var logger1 = LoggerFactory.CreateLogger("CustomCategory1");
logger1.LogInformation("Someone has clicked me!");

var logger2 = LoggerFactory.CreateLogger("CustomCategory1");
logger2.LogWarning("Someone has clicked me!");

var logger3 = LoggerFactory.CreateLogger("CustomCategory2");
logger3.LogInformation("Someone has clicked me!");

var logger4 = LoggerFactory.CreateLogger("CustomCategory2");
logger4.LogWarning("Someone has clicked me!");

builder.Logging.SetMinimumLevel(LogLevel.Trace);

Поставщик пользовательского средства ведения журнала на стороне клиента

В примере в этом разделе демонстрируется пользовательский поставщик средства ведения журнала для дальнейшей настройки.

Добавьте ссылку на пакет Майкрософт.Extensions.Logging.Configuration в приложение.

Добавьте следующую настраиваемую конфигурацию средства ведения журнала. Конфигурация создает словарь LogLevels, который задает пользовательский формат журнала для трех уровней ведения журнала: Information, Warning и Error. Используется LogFormatenum для описания коротких () и длинных (LogFormat.ShortLogFormat.Long) форматов.

CustomLoggerConfiguration.cs:

using Microsoft.Extensions.Logging;

public class CustomLoggerConfiguration
{
    public int EventId { get; set; }

    public Dictionary<LogLevel, LogFormat> LogLevels { get; set; } = 
        new()
        {
            [LogLevel.Information] = LogFormat.Short,
            [LogLevel.Warning] = LogFormat.Short,
            [LogLevel.Error] = LogFormat.Long
        };

    public enum LogFormat
    {
        Short,
        Long
    }
}

Добавьте в приложение следующее пользовательское средство ведения журнала. CustomLogger выводит пользовательские форматы журнала с учетом значений logLevel, определенных в предыдущей конфигурации CustomLoggerConfiguration.

using Microsoft.Extensions.Logging;
using static CustomLoggerConfiguration;

public sealed class CustomLogger : ILogger
{
    private readonly string name;
    private readonly Func<CustomLoggerConfiguration> getCurrentConfig;

    public CustomLogger(
        string name,
        Func<CustomLoggerConfiguration> getCurrentConfig) =>
        (this.name, this.getCurrentConfig) = (name, getCurrentConfig);

    public IDisposable BeginScope<TState>(TState state) => default!;

    public bool IsEnabled(LogLevel logLevel) =>
        getCurrentConfig().LogLevels.ContainsKey(logLevel);

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

        CustomLoggerConfiguration config = getCurrentConfig();

        if (config.EventId == 0 || config.EventId == eventId.Id)
        {
            switch (config.LogLevels[logLevel])
            {
                case LogFormat.Short:
                    Console.WriteLine($"{name}: {formatter(state, exception)}");
                    break;
                case LogFormat.Long:
                    Console.WriteLine($"[{eventId.Id, 2}: {logLevel, -12}] {name} - {formatter(state, exception)}");
                    break;
                default:
                    // No-op
                    break;
            }
        }
    }
}

Добавьте в приложение следующее пользовательское средство ведения журнала. CustomLoggerProvider использует методику на основе Options для настройки логгера с помощью встроенных функций конфигурации журнала. Например, приложение может устанавливать или изменять форматы журналов с помощью файла appsettings.json, не требуя изменений в коде пользовательского средства ведения журнала, как показано в конце этого раздела.

CustomLoggerProvider.cs:

using System.Collections.Concurrent;
using Microsoft.Extensions.Options;

[ProviderAlias("CustomLog")]
public sealed class CustomLoggerProvider : ILoggerProvider
{
    private readonly IDisposable onChangeToken;
    private CustomLoggerConfiguration config;
    private readonly ConcurrentDictionary<string, CustomLogger> loggers =
        new(StringComparer.OrdinalIgnoreCase);

    public CustomLoggerProvider(
        IOptionsMonitor<CustomLoggerConfiguration> config)
    {
        this.config = config.CurrentValue;
        onChangeToken = config.OnChange(updatedConfig => this.config = updatedConfig);
    }

    public ILogger CreateLogger(string categoryName) =>
        loggers.GetOrAdd(categoryName, name => new CustomLogger(name, GetCurrentConfig));

    private CustomLoggerConfiguration GetCurrentConfig() => config;

    public void Dispose()
    {
        loggers.Clear();
        onChangeToken.Dispose();
    }
}

Добавьте следующие расширения пользовательского средства ведения журнала.

CustomLoggerExtensions.cs:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Configuration;

public static class CustomLoggerExtensions
{
    public static ILoggingBuilder AddCustomLogger(
        this ILoggingBuilder builder)
    {
        builder.AddConfiguration();

        builder.Services.TryAddEnumerable(
            ServiceDescriptor.Singleton<ILoggerProvider, CustomLoggerProvider>());

        LoggerProviderOptions.RegisterProviderOptions
            <CustomLoggerConfiguration, CustomLoggerProvider>(builder.Services);

        return builder;
    }
}

В файле Program на хост-билдере очистите существующего провайдера, вызвав ClearProviders, и добавьте пользовательский логгинг провайдер:

builder.Logging.ClearProviders().AddCustomLogger();

В следующем компоненте CustomLoggerExample:

• Сообщение отладки не регистрируется в журнале.
• Информационное сообщение вносится в журнал в коротком формате (LogFormat.Short).
• Предупреждение регистрируется в журнале в коротком формате (LogFormat.Short).
• Сообщение об ошибке регистрируется в длинном формате (LogFormat.Long).
• Сообщение трассировки не вносится в журнал.

CustomLoggerExample.razor:

@page "/custom-logger-example"
@inject ILogger<CustomLoggerExample> Logger

<p>
    <button @onclick="LogMessages">Log Messages</button>
</p>

@code{
    private void LogMessages()
    {
        Logger.LogDebug(1, "This is a debug message.");
        Logger.LogInformation(3, "This is an information message.");
        Logger.LogWarning(5, "This is a warning message.");
        Logger.LogError(7, "This is an error message.");
        Logger.LogTrace(5!, "This is a trace message.");
    }
}

@page "/custom-logger-example"
@using Microsoft.Extensions.Logging
@inject ILogger<CustomLoggerExample> Logger

<p>
    <button @onclick="LogMessages">Log Messages</button>
</p>

@code{
    private void LogMessages()
    {
        Logger.LogDebug(1, "This is a debug message.");
        Logger.LogInformation(3, "This is an information message.");
        Logger.LogWarning(5, "This is a warning message.");
        Logger.LogError(7, "This is an error message.");
        Logger.LogTrace(5!, "This is a trace message.");
    }
}

Следующие выходные данные отображаются в консоли средств разработчика в браузере при нажатии на кнопку Log Messages. Записи журнала отражают соответствующие форматы, применяемые пользовательским средством ведения журнала (клиентское приложение называется LoggingTest):

LoggingTest.Pages.CustomLoggerExample: This is an information message.
LoggingTest.Pages.CustomLoggerExample: This is a warning message.
[ 7: Error ] LoggingTest.Pages.CustomLoggerExample - This is an error message.

При изучении предыдущего примера становится очевидным, что установка форматов строк журнала с помощью словаря в CustomLoggerConfiguration не является обязательной. Форматы линий, применяемые пользовательским средством ведения журнала (CustomLogger), могут быть применены путем простой проверки logLevel в методе Log. Назначение формата журнала с помощью конфигурации выполняется для того, чтобы разработчик мог легко изменить формат журнала с помощью конфигурации приложения, как показано в следующем примере.

В клиентском приложении добавьте или обновите appsettings.json файл, чтобы включить конфигурацию ведения журнала. Задайте формат журнала Long для всех трех уровней ведения журнала:

{
  "Logging": {
    "CustomLog": {
      "LogLevels": {
        "Information": "Long",
        "Warning": "Long",
        "Error": "Long"
      }
    }
  }
}

Обратите внимание, что в предыдущем примере запись для конфигурации пользовательского средства ведения журнала имеет значение CustomLog, которое было применено к пользовательскому поставщику средства ведения журнала (CustomLoggerProvider) в качестве псевдонима с [ProviderAlias("CustomLog")]. Конфигурация ведения журнала может быть применена с именем CustomLoggerProvider вместо CustomLog, но использование псевдонима CustomLog более удобно для пользователя.

В файле Program задействуется конфигурация ведения журнала. Добавьте следующий код:

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

Вызов LoggingBuilderConfigurationExtensions.AddConfiguration можно выполнить как до, так и после добавления пользовательского поставщика журналов.

Снова запустите приложение. Выберите кнопку Log Messages. Обратите внимание, что конфигурация ведения журнала применяется из файла appsettings.json. Все три записи журнала находятся в формате long (LogFormat.Long) (клиентское приложение называется LoggingTest):

[ 3: Information ] LoggingTest.Pages.CustomLoggerExample - This is an information message.
[ 5: Warning ] LoggingTest.Pages.CustomLoggerExample - This is a warning message.
[ 7: Error ] LoggingTest.Pages.CustomLoggerExample - This is an error message.

using (Logger.BeginScope("L1"))
{
    Logger.LogInformation(3, "INFO: ONE scope.");
}

using (Logger.BeginScope("L1"))
{
    using (Logger.BeginScope("L2"))
    {
        Logger.LogInformation(3, "INFO: TWO scopes.");
    }
}

using (Logger.BeginScope("L1"))
{
    using (Logger.BeginScope("L2"))
    {
        using (Logger.BeginScope("L3"))
        {
            Logger.LogInformation(3, "INFO: THREE scopes.");
        }
    }
}

Ведение журнала предварительно подготовленных компонентов

Предварительно созданные компоненты дважды выполняют код инициализации компонентов. Ведение журнала выполняется на стороне сервера при первом выполнении кода инициализации и на стороне клиента при втором выполнении кода инициализации. В зависимости от цели ведения журнала при инициализации, проверяйте журналы на стороне сервера и (или) на стороне клиента.

SignalR логирование клиента с помощью SignalR билдера клиента

Этот раздел относится к приложениям на стороне сервера.

В Blazor конфигурации запуска скрипта передайте объект конфигурации, вызывающий configureSignalRconfigureLogging уровень журнала.

configureLogging Для значения уровня журнала передайте аргумент в виде строки или целочисленного уровня журнала, показанного в следующей таблице.

Пример 1. Задайте Information уровень журнала строковым значением.

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    circuit: {
      configureSignalR: function (builder) {
        builder.configureLogging("information");
      }
    }
  });
</script>

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    configureSignalR: function (builder) {
      builder.configureLogging("information");
    }
  });
</script>

В предыдущем примере заполнитель {BLAZOR SCRIPT} — это путь к скрипту и имя файла Blazor. Расположение скрипта см. в разделе ASP.NET Core Blazor структура проекта.

Пример 2. Установите Information уровень логирования целым значением.

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    circuit: {
      configureSignalR: function (builder) {
        builder.configureLogging(2); // LogLevel.Information
      }
    }
  });
</script>

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    configureSignalR: function (builder) {
      builder.configureLogging(2); // LogLevel.Information
    }
  });
</script>

Дополнительные сведения о запуске Blazor (Blazor.start()) см. в разделе ASP.NET Core Blazor startup.

SignalR журналирование клиента с конфигурацией приложения

Настройте конфигурацию параметров приложения, как описано в разделе ASP.NET Core Blazor configuration. Поместите файлы параметров приложения внутрь wwwroot, которые содержат параметр приложения Logging:LogLevel:HubConnection.

Logging:LogLevel:HubConnection Укажите параметр приложения в файле по умолчанию appsettings.json и в Development файле параметров приложения среды. Используйте типичный уровень журналирования с меньшей детализацией по умолчанию, например LogLevel.Warning. Значение параметров приложения по умолчанию используется в средах Staging и Production в случае, если файлы параметров приложения для этих сред отсутствуют. Используйте подробный уровень журнала в Development файле параметров приложения среды, например LogLevel.Trace.

wwwroot/appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "HubConnection": "Warning"
    }
  }
}

wwwroot/appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "HubConnection": "Trace"
    }
  }
}

В верхней части Razor файла компонента (.razor):

• Вставьте ILoggerProvider, чтобы добавить WebAssemblyConsoleLogger к поставщикам ведения журнала, передаваемым в HubConnectionBuilder. В отличие от ConsoleLoggerProvider, WebAssemblyConsoleLogger служит оболочкой для API ведения журналов, характерного для разных браузеров (например, console.log). Использование WebAssemblyConsoleLogger делает возможным ведение журнала в Mono внутри контекста браузера.
• Внедрите IConfiguration для чтения параметра приложения Logging:LogLevel:HubConnection.

@inject ILoggerProvider LoggerProvider
@inject IConfiguration Config

В методе OnInitializedAsync используйте HubConnectionBuilderExtensions.ConfigureLogging для добавления поставщика ведения журнала и установки минимального уровня ведения журнала из конфигурации.

protected override async Task OnInitializedAsync()
{
    hubConnection = new HubConnectionBuilder()
        .WithUrl(Navigation.ToAbsoluteUri("/chathub"))
        .ConfigureLogging(builder => 
        {
            builder.AddProvider(LoggerProvider);
            builder.SetMinimumLevel(
                Config.GetValue<LogLevel>("Logging:LogLevel:HubConnection"));
        })
        .Build();

    hubConnection.On<string, string>("ReceiveMessage", (user, message) => ...

    await hubConnection.StartAsync();
}

Дополнительные сведения о настройке среды приложения см. в разделе ASP.NET Core Blazor среды.

Дополнительные ресурсы

• Журналирование (Logging) в .NET и ASP.NET Core
• Loglevel Перечисление (документация по API)
• Реализовать пользовательский поставщик ведения журнала в .NET
• Документация по инструментам разработчика браузера:
  • Средства разработчика Chrome
  • Обзор средств разработчика Microsoft Edge
• Blazor примеры репозитория GitHub (dotnet/blazor-samples) (как загрузить)