ASP.NET Core Blazor 記錄

發行項
04/30/2024

注意

這不是這篇文章的最新版本。如需目前版本，請參閱本文的 .NET 8 版本。

警告

不再支援此版本的 ASP.NET Core。如需詳細資訊，請參閱 .NET 和 .NET Core 支援原則。如需目前版本，請參閱本文的 .NET 8 版本。

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

如需目前版本，請參閱本文的 .NET 8 版本。

本文說明 Blazor 應用程式記錄，包括設定，以及如何從 Razor 元件寫入記錄訊息。

組態

記錄設定可以從應用程式設定檔案載入。如需詳細資訊，請參閱 ASP.NET Core Blazor 組態。

在預設記錄層級，且未設定其他記錄提供者：

在伺服器上，記錄只會發生在 LogLevel.Information 層級或更高層級 Development 環境中的伺服器端 .NET 主控台。
在用戶端上，記錄只會發生在 LogLevel.Information 層級或更高層級的用戶端瀏覽器開發人員工具主控台。

當專案檔中的應用程式設定為使用隱含命名空間 (<ImplicitUsings>enable</ImplicitUsings>)，不需要 Microsoft.Extensions.Logging 的 using 指示詞或 LoggerExtensions 類別中的任何 API，即可支援 API Visual Studio IntelliSense 完成或建置應用程式。如果未啟用隱含命名空間，Razor 元件必須明確定義未透過 _Imports.razor 檔案匯入的記錄命名空間的@using指示詞。

記錄層級

記錄層級會符合 ASP.NET Core 應用程式記錄層級，其列在 LogLevel 的 API 文件中。

Razor 元件記錄

Microsoft.Extensions.Logging 的 using 指示詞必須支援 API 的 IntelliSense 完成，例如 LogWarning 和 LogError。

下列範例將：

插入 ILogger (ILogger<Counter1>) 物件以建立記錄器。記錄的類別是元件型別 Counter 的完整名稱。
呼叫 LogWarning 以在 Warning 層級記錄。

Counter1.razor：

@page "/counter-1"
@inject ILogger<Counter1> Logger

<PageTitle>Counter 1</PageTitle>

<h1>Counter 1</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        Logger.LogWarning("Someone has clicked me!");

        currentCount++;
    }
}

@page "/counter-1"
@inject ILogger<Counter1> Logger

<PageTitle>Counter 1</PageTitle>

<h1>Counter 1</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        Logger.LogWarning("Someone has clicked me!");

        currentCount++;
    }
}

@page "/counter-1"
@inject ILogger<Counter1> Logger

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        Logger.LogWarning("Someone has clicked me!");

        currentCount++;
    }
}

@page "/counter-1"
@inject ILogger<Counter1> Logger

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        Logger.LogWarning("Someone has clicked me!");

        currentCount++;
    }
}

@page "/counter-1"
@using Microsoft.Extensions.Logging
@inject ILogger<Counter1> Logger

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        Logger.LogWarning("Someone has clicked me!");

        currentCount++;
    }
}

@page "/counter-1"
@using Microsoft.Extensions.Logging
@inject ILogger<Counter1> Logger

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        Logger.LogWarning("Someone has clicked me!");

        currentCount++;
    }
}

下列範例示範使用元件中 ILoggerFactory 的記錄。

Counter2.razor：

@page "/counter-2"
@inject ILoggerFactory LoggerFactory

<PageTitle>Counter 2</PageTitle>

<h1>Counter 2</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        var logger = LoggerFactory.CreateLogger<Counter2>();
        logger.LogWarning("Someone has clicked me!");

        currentCount++;
    }
}

@page "/counter-2"
@inject ILoggerFactory LoggerFactory

<PageTitle>Counter 2</PageTitle>

<h1>Counter 2</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        var logger = LoggerFactory.CreateLogger<Counter2>();
        logger.LogWarning("Someone has clicked me!");

        currentCount++;
    }
}

@page "/counter-2"
@inject ILoggerFactory LoggerFactory

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        var logger = LoggerFactory.CreateLogger<Counter2>();
        logger.LogWarning("Someone has clicked me!");

        currentCount++;
    }
}

@page "/counter-2"
@inject ILoggerFactory LoggerFactory

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        var logger = LoggerFactory.CreateLogger<Counter2>();
        logger.LogWarning("Someone has clicked me!");

        currentCount++;
    }
}

@page "/counter-2"
@using Microsoft.Extensions.Logging
@inject ILoggerFactory LoggerFactory

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        var logger = LoggerFactory.CreateLogger<Counter2>();
        logger.LogWarning("Someone has clicked me!");

        currentCount++;
    }
}

@page "/counter-2"
@using Microsoft.Extensions.Logging
@inject ILoggerFactory LoggerFactory

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        var logger = LoggerFactory.CreateLogger<Counter2>();
        logger.LogWarning("Someone has clicked me!");

        currentCount++;
    }
}

伺服器端記錄

如需一般 ASP.NET Core 記錄指導，請參閱 .NET Core 和 ASP.NET Core 中的記錄。

用戶端記錄

並非 ASP.NET Core 記錄的每個功能都受到用戶端支援。例如，用戶端元件無法存取用戶端的檔案系統或網路，因此無法將記錄寫入用戶端的實體或網路儲存體。使用設計為搭配單頁應用程式 (SPA) 使用的第三方記錄服務時，請遵循服務的安全性指導。請記住，每一個資料片段，包括儲存在用戶端的金鑰或祕密都不安全，而且可由惡意使用者輕鬆探索。

視架構版本和記錄功能而定，記錄實作可能需要將 Microsoft.Extensions.Logging 的命名空間新增至 Program 檔案：

using Microsoft.Extensions.Logging;

使用 WebAssemblyHostBuilder.Logging 屬性在用戶端應用程式中設定記錄。 Logging 屬性的型別為 ILoggingBuilder，因此支援 ILoggingBuilder 的擴充方法。

若要設定最低記錄層級，請使用 LogLevel 在 Program 檔案中的主機產生器上呼叫 LoggingBuilderExtensions.SetMinimumLevel。下列範例會將記錄層級下限設定為 Warning：

builder.Logging.SetMinimumLevel(LogLevel.Warning);

登入用戶端 `Program` 檔案

使用架構的內部主控台記錄器提供者 (WebAssemblyConsoleLoggerProvider (參考來源)) 建置 WebAssemblyHostBuilder 之後，用戶端應用程式中會支援記錄。

在 Program 檔案中：

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();

開發人員工具主控台輸出：

info: Program[0]
Logged after the app is built in the Program file.

注意

.NET 參考來源的文件連結通常會載入存放庫的預設分支，這表示下一版 .NET 的目前開發。若要選取特定版本的標籤，請使用 [切換分支或標籤] 下拉式清單。如需詳細資訊，請參閱如何選取 ASP.NET Core 原始程式碼 (dotnet/AspNetCore.Docs #26205) 的版本標籤。

用戶端記錄類別

支援記錄類別。

下列範例示範如何使用記錄類別搭配從 Blazor 專案範本建立的應用程式的 Counter 元件。

在將 ILoggerFactory 插入為 LoggerFactory 的應用程式 Counter 元件 (Counter.razor) IncrementCount 方法中：

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

開發人員工具主控台輸出：

warn: CustomCategory[0]
Someone has clicked me!

用戶端記錄事件識別碼

支援記錄事件識別碼。

下列範例示範如何使用記錄事件識別碼搭配從 Blazor 專案範本建立的應用程式的 Counter 元件。

LogEvent.cs：

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

在應用程式 Counter 元件 (Counter.razor) 的 IncrementCount 方法中：

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

開發人員工具主控台輸出：

info: BlazorSample.Pages.Counter[1000]
Someone has clicked me!
warn: BlazorSample.Pages.Counter[1001]
Someone has clicked me!

用戶端記錄訊息範本

支援記錄訊息範本：

下列範例示範如何使用記錄訊息範本搭配從 Blazor 專案範本建立的應用程式的 Counter 元件。

在應用程式 Counter 元件 (Counter.razor) 的 IncrementCount 方法中：

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

開發人員工具主控台輸出：

info: BlazorSample.Pages.Counter[0]
Someone clicked me at 04/21/2022 12:15:57!

用戶端記錄例外狀況參數

支援記錄例外狀況參數。

下列範例示範如何使用記錄例外狀況參數搭配從 Blazor 專案範本建立的應用程式的 Counter 元件。

在應用程式 Counter 元件 (Counter.razor) 的 IncrementCount 方法中：

currentCount++;

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

開發人員工具主控台輸出：

warn: BlazorSample.Pages.Counter[0]
Exception (currentCount: 4)!
System.OperationCanceledException: Skip 3
at BlazorSample.Pages.Counter.IncrementCount() in C:UsersAlabaDesktopBlazorSamplePagesCounter.razor:line 28

用戶端篩選函式

支援篩選函式。

下列範例示範如何使用篩選搭配從 Blazor 專案範本建立的應用程式的 Counter 元件。

在 Program 檔案中：

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

在將 ILoggerFactory 插入為 LoggerFactory 的應用程式 Counter 元件 (Counter.razor) IncrementCount 方法中：

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!");

在開發人員工具主控台輸出中，篩選只允許記錄 CustomCategory2 類別和 Information 記錄層級訊息：

info: CustomCategory2[0]
Someone has clicked me!

應用程式也可以為特定命名空間設定記錄篩選。例如，將 Program 檔案中的記錄層級設定為 Trace：

builder.Logging.SetMinimumLevel(LogLevel.Trace);

通常，在 Trace 記錄層級，詳細資訊層級的開發人員工具主控台輸出包含 Microsoft.AspNetCore.Components.RenderTree 記錄訊息，例如下列：

dbug: Microsoft.AspNetCore.Components.RenderTree.Renderer[3]
Rendering component 14 of type Microsoft.AspNetCore.Components.Web.HeadOutlet

在 Program 檔案中，可以使用下列其中一種方法來停用 Microsoft.AspNetCore.Components.RenderTree 的特定記錄訊息：

builder.Logging.AddFilter("Microsoft.AspNetCore.Components.RenderTree.*", LogLevel.None);

builder.Services.PostConfigure<LoggerFilterOptions>(options =>
    options.Rules.Add(
        new LoggerFilterRule(null, 
                             "Microsoft.AspNetCore.Components.RenderTree.*", 
                             LogLevel.None, 
                             null)
    ));

將上述其中一個篩選新增至應用程式之後，詳細資訊層級的主控台輸出不會顯示來自 Microsoft.AspNetCore.Components.RenderTree API 的記錄訊息。

用戶端自訂記錄器提供者

本節中的範例示範自訂記錄器提供者以進行進一步自訂。

將封裝參考新增至 Microsoft.Extensions.Logging.Configuration 封裝的應用程式。

注意

如需將套件新增至 .NET 應用程式的指引，請參閱在套件取用工作流程 (NuGet 文件) 的安裝及管理套件底下的文章。在 NuGet.org 確認正確的套件版本。

新增下列自訂記錄器設定。設定會建立 LogLevels 字典，以設定三個記錄層級的自訂記錄格式：Information、Warning 和 Error。 LogFormat enum 用來描述簡短 (LogFormat.Short) 和長 (LogFormat.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 會根據上述 CustomLoggerConfiguration 設定中定義的 logLevel 值輸出自訂記錄格式。

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)，只能藉由檢查 Log 方法中的 logLevel 來套用。透過設定指派記錄格式的目的是，開發人員可以透過應用程式設定輕鬆地變更記錄格式，如下列範例所示。

在用戶端應用程式中，新增或更新 appsettings.json 檔案以包含記錄設定。針對這三個記錄層級，將記錄格式設定為 Long：

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

在上述範例中，請注意，自訂記錄器設定的項目是 CustomLog，其已使用 [ProviderAlias("CustomLog")] 別名套用至自訂記錄器提供者 (CustomLoggerProvider)。記錄設定可能已套用名稱 CustomLoggerProvider 而非 CustomLog，但使用別名 CustomLog 對使用者較方便。

在 Program 檔案中，取用記錄設定。新增下列程式碼：

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

在新增自訂記錄器提供者之前或之後，可以放置對 LoggingBuilderConfigurationExtensions.AddConfiguration 的呼叫。

重新執行應用程式。選取 Log Messages 按鈕。請注意，記錄設定會從 appsettings.json 檔案套用。這三個記錄項目都為長 (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.

用戶端記錄範圍

開發人員工具主控台記錄器不支援記錄範圍。不過，自訂記錄器可以支援記錄範圍。如需您可以進一步開發以符合需求的不支援範例，請參閱 Blazor GitHub 存放庫範例 (如何下載) 中的 BlazorWebAssemblyScopesLogger 範例應用程式。

範例應用程式會使用標準 ASP.NET Core BeginScope 記錄語法來指出已記錄訊息的範圍。下列範例中的 Logger 服務是 ILogger<CustomLoggerExample>，其會插入至應用程式的 CustomLoggerExample 元件 (CustomLoggerExample.razor)。

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.");
        }
    }
}

輸出：

[ 3: Information ] {CLASS} - INFO: ONE scope. => L1 blazor.webassembly。js:1:35542
[ 3: Information ] {CLASS} - INFO: TWO scopes. => L1 => L2 blazor.webassembly。js:1:35542
[ 3: Information ] {CLASS} - INFO: THREE scopes. => L1 => L2 => L3

上述範例中的 {CLASS} 預留位置為 BlazorWebAssemblyScopesLogger.Pages.CustomLoggerExample。

預先轉譯的元件記錄

預先轉譯的元件會執行元件初始化程式碼兩次。記錄會在第一次執行初始化程式碼時於伺服器端進行，並在第二次執行初始化程式碼時於用戶端進行。根據初始化期間記錄的目標，檢查記錄伺服器端、用戶端或兩者。

使用 SignalR 用戶端產生器進行 SignalR 用戶端記錄

本節適用伺服器端應用程式。

在 Blazor 指令碼啟動設定中，傳入以記錄層級呼叫 configureLogging 的 configureSignalR 設定物件。

針對 configureLogging 記錄層級值，傳遞引數做為下表所示的字串或整數記錄層級。

LogLevel	字串設定	整數設定
Trace	`trace`	0
Debug	`debug`	1
Information	`information`	2
Warning	`warning`	3
Error	`error`	4
Critical	`critical`	5
None	`none`	6

範例 1：使用字串值設定 Information 記錄層級。

Blazor Web App：

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

Blazor Server：

<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 記錄層級。

Blazor Web App：

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

Blazor Server：

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

在上述範例中，{BLAZOR SCRIPT} 預留位置是 Blazor 指令碼路徑和檔案名稱。 如需指令碼的位置，請參閱 ASP.NET Core Blazor 專案結構。

注意

在範例 2 中使用整數來指定記錄層級 (通常稱為幻數或魔幻常數) 被認為是一種不佳的撰寫程式碼做法，因為整數在檢視原始程式碼時無法清楚地識別記錄層級。如果優先考慮最小化傳輸到瀏覽器的位元組，則使用整數可能是合理的 (在這種情況下考慮移除註解)。

如需關於 Blazor 啟動 (Blazor.start()) 的詳細資訊，請參閱 ASP.NET Core Blazor 啟動。

使用應用程式設定的 SignalR 用戶端記錄

如 ASP.NET Core Blazor 設定中所述，設定應用程式設定組態。將包含 Logging:LogLevel:HubConnection 應用程式設定的應用程式設定檔案放置在 wwwroot 中。

注意

除了使用應用程式設定，您也可以在 Razor 元件中建立中樞連線時，將 LogLevel 做為引數傳遞至 LoggingBuilderExtensions.SetMinimumLevel。不過，不小心將應用程式部署到具有詳細資訊記錄的生產裝載環境，可能會導致效能降低。建議您使用應用程式設定來設定記錄層級。

在預設 appsettings.json 檔案和 Development 環境應用程式設定檔案中提供 Logging:LogLevel:HubConnection 應用程式設定。使用一般較不詳細的記錄層級做為預設值，例如 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"
    }
  }
}

重要

如果遵循 ASP.NET Core Blazor 設定中的指導，應用程式才會使用上述應用程式設定檔案中的設定。

在 Razor 元件檔案 (.razor) 頂端：

插入 ILoggerProvider，將 WebAssemblyConsoleLogger 新增至傳遞至 HubConnectionBuilder 的記錄提供者。不同於 ConsoleLoggerProvider，WebAssemblyConsoleLogger 是瀏覽器特定記錄 API 的包裝函式 (例如，console.log)。使用 WebAssemblyConsoleLogger 使得在瀏覽器內容內的 Mono 內記錄變得可行。
插入 IConfiguration 以讀取 Logging:LogLevel:HubConnection 應用程式設定。

注意

WebAssemblyConsoleLogger 是內部，不支援直接在開發人員程式碼中使用。

@inject ILoggerProvider LoggerProvider
@inject IConfiguration Config

注意

下列範例是以 SignalR 搭配 Blazor 教學課程中的示範為基礎。如需進一步的詳細資料，請參閱教學課程。

在元件的 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();
}

注意

在上述範例中，Navigation 是插入的 NavigationManager。

如需設定應用程式環境的詳細資訊，請參閱 ASP.NET Core Blazor 環境。

用戶端驗證記錄

在應用程式設定中使用記錄設定在 LogLevel.Debug 或 LogLevel.Trace 記錄層級，或在 Program 檔案中針對 Microsoft.AspNetCore.Components.WebAssembly.Authentication 使用記錄篩選，以記錄 Blazor 驗證訊息。

使用下列其中一個方法：

在應用程式設定檔案中 (例如，wwwroot/appsettings.Development.json)：
```
"Logging": {
  "LogLevel": {
    "Microsoft.AspNetCore.Components.WebAssembly.Authentication": "Debug"
  }
}
```
如需如何設定用戶端應用程式以讀取應用程式設定檔案的詳細資訊，請參閱 ASP.NET Core Blazor 設定。
使用記錄篩選，下列範例：
- 使用 C# 前置處理器指示詞啟用 Debug 組建設定的記錄。
- 在 Debug 記錄層級記錄 Blazor 驗證訊息。
```
#if DEBUG
    builder.Logging.AddFilter(
        "Microsoft.AspNetCore.Components.WebAssembly.Authentication", 
        LogLevel.Debug);
#endif
```

注意

用戶端上轉譯的 Razor 元件只會記錄到用戶端瀏覽器開發人員工具主控台。

其他資源

.NET Core 和 ASP.NET Core 中的記錄 (機器翻譯)
Loglevel 列舉 (API 文件)
在 .NET 中實作自訂記錄提供者
瀏覽器開發人員工具文件：
- Chrome DevTools
- Microsoft Edge 開發人員工具概觀
Blazor 範例 GitHub 存放庫 (dotnet/blazor-samples) (如何下載)

共用方式為

ASP.NET Core Blazor 記錄

組態

記錄層級

Razor 元件記錄

伺服器端記錄

用戶端記錄

登入用戶端 Program 檔案

用戶端記錄類別

用戶端記錄事件識別碼

用戶端記錄訊息範本

用戶端記錄例外狀況參數

用戶端篩選函式

用戶端自訂記錄器提供者

用戶端記錄範圍

預先轉譯的元件記錄

使用 SignalR 用戶端產生器進行 SignalR 用戶端記錄

使用應用程式設定的 SignalR 用戶端記錄

用戶端驗證記錄

其他資源

其他資源

登入用戶端 `Program` 檔案