Pengelogan dalam .NET

.NET mendukung API pengelogan yang berfungsi dengan berbagai penyedia pengelogan bawaan dan pihak ketiga. Artikel ini menunjukkan cara menggunakan API pengelogan dengan penyedia bawaan. Sebagian besar contoh kode yang ditampilkan dalam artikel ini berlaku untuk aplikasi .NET apa pun yang menggunakan Host Generik. Untuk aplikasi yang tidak menggunakan Host Generik, lihat Aplikasi konsol non-host.

Tip

Semua contoh pengelogan kode sumber tersedia di Browser Sampel untuk diunduh. Untuk informasi selengkapnya, lihat Menelusuri sampel kode: Masuk ke .NET.

Penting

Dimulai dengan .NET 6, layanan pengelogan tidak lagi mendaftarkan jenisnya ILogger . Saat menggunakan pencatat, tentukan alternatif ILogger<TCategoryName> jenis generik atau daftarkan ILogger dengan injeksi dependensi (DI).

Membuat log

Untuk membuat log, gunakan ILogger<TCategoryName> objek dari DI.

Lihat contoh berikut:

• Membuat pencatat, ILogger<Worker>, yang menggunakan kategori log dari nama jenis Workeryang sepenuhnya memenuhi syarat. Kategori log adalah string yang terkait dengan setiap log.
• LogInformation Panggilan untuk masuk ke tingkat .Information Tingkat Log menunjukkan tingkat keparahan peristiwa yang dicatat.

public class Worker : BackgroundService
{
    private readonly ILogger<Worker> _logger;

    public Worker(ILogger<Worker> logger) =>
        _logger = logger;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            _logger.LogInformation("Worker running at: {time}", DateTimeOffset.UtcNow);
            await Task.Delay(1000, stoppingToken);
        }
    }
}

Tingkat dan kategori dijelaskan secara lebih rinci nanti di artikel ini.

Mengonfigurasi pengelogan

Konfigurasi pengelogan umumnya disediakan oleh bagian Loggingappsettings.{Environment}File .json. Appsetting berikut. File Development.json dihasilkan oleh templat layanan Pekerja .NET:

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

Dalam JSON sebelumnya:

• Kategori "Default", "Microsoft", dan "Microsoft.Hosting.Lifetime" ditentukan.
• Kategori "Microsoft" ini berlaku untuk semua kategori yang dimulai dengan "Microsoft".
• Kategori "Microsoft" mencatat pada tingkat Warning log dan yang lebih tinggi.
• Kategori "Microsoft.Hosting.Lifetime" ini lebih spesifik daripada "Microsoft" kategori, sehingga "Microsoft.Hosting.Lifetime" log kategori di tingkat log "Informasi" dan yang lebih tinggi.
• Penyedia log tertentu tidak ditentukan, jadi LogLevel berlaku untuk semua penyedia pengelogan yang diaktifkan kecuali untuk Windows EventLog.

Properti Logging dapat memiliki LogLevel properti penyedia log dan . LogLevel menentukan tingkat minimum yang akan dicatat untuk kategori yang dipilih. Di JSON sebelumnya, Information dan Warning tingkat log ditentukan. LogLevel menunjukkan tingkat keparahan log dan berkisar antara 0 hingga 6:

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

LogLevel Ketika ditentukan, pengelogan diaktifkan untuk pesan pada tingkat yang ditentukan dan yang lebih tinggi. Dalam JSON sebelumnya, Default kategori dicatat dan Information lebih tinggi. Misalnya, Informationpesan , Warning, Error, dan Critical dicatat. Jika tidak LogLevel ditentukan, pengelogan default ke Information tingkat . Untuk informasi selengkapnya, lihat Tingkat log.

Properti penyedia dapat menentukan LogLevel properti . LogLevel di bawah penyedia menentukan tingkat untuk mencatat penyedia tersebut, dan mengambil alih pengaturan log non-penyedia. Pertimbangkan file appsettings.json berikut:

{
    "Logging": {
        "LogLevel": {
            "Default": "Error",
            "Microsoft": "Warning"
        },
        "Debug": {
            "LogLevel": {
                "Default": "Information",
                "Microsoft.Hosting": "Trace"
            }
        },
        "EventSource": {
            "LogLevel": {
                "Default": "Warning"
            }
        }
    }
}

Pengaturan dalam Logging.{ProviderName}.LogLevel mengesampingkan pengaturan di Logging.LogLevel. Di JSON sebelumnya, Debug tingkat log default penyedia diatur ke Information:

Logging:Debug:LogLevel:Default:Information

Pengaturan sebelumnya menentukan Information tingkat log untuk setiap Logging:Debug: kategori kecuali Microsoft.Hosting. Saat kategori tertentu tercantum, kategori tertentu akan mengambil alih kategori default. Di JSON sebelumnya, Logging:Debug:LogLevel kategori "Microsoft.Hosting" dan "Default" ambil alih pengaturan di Logging:LogLevel

Tingkat log minimum dapat ditentukan untuk salah satu dari:

• Penyedia tertentu: Misalnya, Logging:EventSource:LogLevel:Default:Information
• Kategori tertentu: Misalnya, Logging:LogLevel:Microsoft:Warning
• Semua penyedia dan semua kategori: Logging:LogLevel:Default:Warning

Log apa pun di bawah tingkat minimum tidak:

• Diteruskan ke penyedia.
• Dicatat atau ditampilkan.

Untuk menekan semua log, tentukan LogLevel.None. LogLevel.None memiliki nilai 6, yang lebih tinggi dari LogLevel.Critical (5).

Jika penyedia mendukung cakupan log, IncludeScopes menunjukkan apakah mereka diaktifkan. Untuk informasi selengkapnya, lihat cakupan log

File appsettings.json berikut berisi pengaturan untuk semua penyedia bawaan:

{
    "Logging": {
        "LogLevel": {
            "Default": "Error",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Warning"
        },
        "Debug": {
            "LogLevel": {
                "Default": "Information"
            }
        },
        "Console": {
            "IncludeScopes": true,
            "LogLevel": {
                "Microsoft.Extensions.Hosting": "Warning",
                "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"
            }
        }
    }
}

Dalam sampel sebelumnya:

• Kategori dan tingkatan bukan nilai yang disarankan. Sampel disediakan untuk menampilkan semua penyedia default.
• Pengaturan dalam Logging.{ProviderName}.LogLevel mengesampingkan pengaturan di Logging.LogLevel. Misalnya, tingkat dalam Debug.LogLevel.Default mengambil alih tingkat di LogLevel.Default.
• Alias setiap penyedia digunakan. Setiap penyedia mendefinisikan alias yang dapat digunakan dalam konfigurasi sebagai pengganti nama jenis yang sepenuhnya memenuhi syarat. Alias penyedia bawaan adalah:
  • Konsol
  • Debug
  • EventSource
  • EventLog
  • AzureAppServicesFile
  • AzureAppServicesBlob
  • ApplicationInsights

Mengatur tingkat log menurut baris perintah, variabel lingkungan, dan konfigurasi lainnya

Tingkat log dapat diatur oleh salah satu penyedia konfigurasi. Misalnya, Anda dapat membuat variabel lingkungan yang bertahan bernama Logging:LogLevel:Microsoft dengan nilai Information.

Baris Perintah

Buat dan tetapkan variabel lingkungan yang bertahan, mengingat nilai tingkat log.

:: Assigns the env var to the value
setx "Logging__LogLevel__Microsoft" "Information" /M

Dalam instans baruPrompt Perintah, baca variabel lingkungan.

:: Prints the env var value
echo %Logging__LogLevel__Microsoft%

PowerShell

Buat dan tetapkan variabel lingkungan yang bertahan, mengingat nilai tingkat log.

# Assigns the env var to the value
[System.Environment]::SetEnvironmentVariable(
    "Logging__LogLevel__Microsoft", "Information", "Machine")

Dalam instans baruPowerShell, baca variabel lingkungan.

# Prints the env var value
[System.Environment]::GetEnvironmentVariable(
    "Logging__LogLevel__Microsoft", "Machine")

Bash

Buat dan tetapkan variabel lingkungan yang bertahan, mengingat nilai tingkat log.

# Assigns the env var to the value, persists it across sessions
echo export Logging__LogLevel__Microsoft="Information" >> ~/.bashrc && source ~/.bashrc

Untuk membaca variabel lingkungan.

# Prints the env var value
echo $Logging__LogLevel__Microsoft

# Or use printenv:
# printenv Logging__LogLevel__Microsoft

Catatan

Saat mengonfigurasi variabel lingkungan dengan nama yang berisi . (titik), pertimbangkan "Mengekspor variabel dengan titik (.) di dalamnya" pertanyaan tentang Stack Exchange dan jawaban yang diterima yang sesuai.

Pengaturan lingkungan sebelumnya tetap ada di lingkungan. Untuk menguji pengaturan saat menggunakan aplikasi yang dibuat dengan templat layanan .NET Worker, gunakan dotnet run perintah di direktori proyek setelah variabel lingkungan ditetapkan.

dotnet run

Tip

Setelah menetapkan variabel lingkungan, mulai ulang lingkungan pengembangan terpadu (IDE) Anda untuk memastikan bahwa variabel lingkungan yang baru ditambahkan tersedia.

Pada Azure App Service, pilih Pengaturan aplikasi baru di halaman Konfigurasi Pengaturan>. Azure App Service pengaturan aplikasi adalah:

• Dienkripsi saat tidak aktif dan ditransmisikan melalui saluran terenkripsi.
• Diekspos sebagai variabel lingkungan.

Untuk informasi selengkapnya tentang mengatur nilai konfigurasi .NET menggunakan variabel lingkungan, lihat variabel lingkungan.

Bagaimana aturan pemfilteran diterapkan

ILogger<TCategoryName> Saat objek dibuat, ILoggerFactory objek memilih satu aturan per penyedia untuk diterapkan ke pencatat tersebut. Semua pesan yang ILogger ditulis oleh instans difilter berdasarkan aturan yang dipilih. Aturan paling spesifik untuk setiap penyedia dan pasangan kategori dipilih dari aturan yang tersedia.

Algoritma berikut digunakan untuk setiap penyedia saat ILogger dibuat untuk kategori tertentu:

• Pilih semua aturan yang cocok dengan penyedia atau aliasnya. Jika tidak ada kecocokan yang ditemukan, pilih semua aturan dengan penyedia kosong.
• Dari hasil langkah sebelumnya, pilih aturan dengan awalan kategori pencocokan terpanjang. Jika tidak ada kecocokan yang ditemukan, pilih semua aturan yang tidak menentukan kategori.
• Jika beberapa aturan dipilih, ambil aturan terakhir .
• Jika tidak ada aturan yang dipilih, gunakan LoggingBuilderExtensions.SetMinimumLevel(ILoggingBuilder, LogLevel) untuk menentukan tingkat pengelogan minimum.

Kategori log

ILogger Saat objek dibuat, kategori ditentukan. Kategori tersebut disertakan dengan setiap pesan log yang dibuat oleh instans tersebut.ILogger String kategori bersifat arbitrer, tetapi konvensinya adalah menggunakan nama kelas. Misalnya, dalam aplikasi dengan layanan yang ditentukan seperti objek berikut, kategorinya mungkin "Example.DefaultService":

namespace Example
{
    public class DefaultService : IService
    {
        private readonly ILogger<DefaultService> _logger;

        public DefaultService(ILogger<DefaultService> logger) =>
            _logger = logger;

        // ...
    }
}

Untuk menentukan kategori secara eksplisit, panggil LoggerFactory.CreateLogger:

namespace Example
{
    public class DefaultService : IService
    {
        private readonly ILogger _logger;

        public DefaultService(ILoggerFactory loggerFactory) =>
            _logger = loggerFactory.CreateLogger("CustomCategory");

        // ...
    }
}

CreateLogger Panggilan dengan nama tetap dapat berguna saat digunakan dalam beberapa kelas/jenis sehingga peristiwa dapat diatur berdasarkan kategori.

ILogger<T> setara dengan panggilan CreateLogger dengan nama jenis yang sepenuhnya memenuhi syarat dari T.

Tingkat log

Tabel berikut ini mencantumkan LogLevel nilai, metode ekstensi kenyamanan Log{LogLevel} , dan penggunaan yang disarankan:

LogLevel	Nilai	Metode	Deskripsi
Lacak	0	LogTrace	Berisi pesan yang paling rinci. Pesan-pesan ini mungkin berisi data aplikasi sensitif. Pesan-pesan ini dinonaktifkan secara default dan tidak boleh diaktifkan dalam produksi.
Debug	1	LogDebug	Untuk penelusuran kesalahan dan pengembangan. Gunakan dengan hati-hati dalam produksi karena volume yang tinggi.
Informasi	2	LogInformation	Melacak alur umum aplikasi. Mungkin memiliki nilai jangka panjang.
Peringatan	3	LogWarning	Untuk peristiwa abnormal atau tak terduga. Biasanya menyertakan kesalahan atau kondisi yang tidak menyebabkan aplikasi gagal.
Kesalahan	4	LogError	Untuk kesalahan dan pengecualian yang tidak dapat ditangani. Pesan-pesan ini menunjukkan kegagalan dalam operasi atau permintaan saat ini, bukan kegagalan di seluruh aplikasi.
Kritis	5	LogCritical	Untuk kegagalan yang membutuhkan perhatian segera. Contoh: skenario kehilangan data, kehabisan ruang disk.
Tidak ada	6		Menentukan bahwa tidak ada pesan yang harus ditulis.

Dalam tabel sebelumnya, LogLevel dicantumkan dari tingkat keparahan terendah hingga tertinggi.

Parameter pertama metode Log , LogLevel, menunjukkan tingkat keparahan log. Daripada memanggil Log(LogLevel, ...), sebagian besar pengembang memanggil metode ekstensi Log{LogLevel} . Metode Log{LogLevel} ekstensi memanggil metode Log dan menentukan LogLevel. Misalnya, dua panggilan pengelogan berikut secara fungsional setara dan menghasilkan log yang sama:

public void LogDetails()
{
    var logMessage = "Details for log.";

    _logger.Log(LogLevel.Information, AppLogEvents.Details, logMessage);
    _logger.LogInformation(AppLogEvents.Details, logMessage);
}

AppLogEvents.Details adalah ID peristiwa, dan secara implisit diwakili oleh nilai konstanta Int32 . AppLogEvents adalah kelas yang mengekspos berbagai konstanta pengidentifikasi bernama dan ditampilkan di bagian ID peristiwa Log .

Kode berikut membuat Information dan Warning mencatat:

public async Task<T> GetAsync<T>(string id)
{
    _logger.LogInformation(AppLogEvents.Read, "Reading value for {Id}", id);

    var result = await _repository.GetAsync(id);
    if (result is null)
    {
        _logger.LogWarning(AppLogEvents.ReadNotFound, "GetAsync({Id}) not found", id);
    }

    return result;
}

Dalam kode sebelumnya, parameter pertama Log{LogLevel} ,AppLogEvents.Read adalah ID peristiwa Log. Parameter kedua adalah templat pesan dengan tempat penampung untuk nilai argumen yang disediakan oleh parameter metode yang tersisa. Parameter metode dijelaskan di bagian templat pesan nanti di artikel ini.

Konfigurasikan tingkat log yang sesuai dan panggil metode yang benar Log{LogLevel} untuk mengontrol berapa banyak output log yang ditulis ke media penyimpanan tertentu. Contohnya:

• Dalam produksi:
  • Pengelogan di Trace tingkat atau Debug menghasilkan pesan log terperinci dalam volume tinggi. Untuk mengontrol biaya dan tidak melebihi batas penyimpanan data, catat Trace dan Debug tingkat pesan ke penyimpanan data bervolume tinggi dengan biaya rendah. Pertimbangkan untuk membatasi Trace dan Debug untuk kategori tertentu.
  • Pengelogan melalui WarningCritical tingkat harus menghasilkan beberapa pesan log.
    • Biaya dan batas penyimpanan biasanya tidak menjadi perhatian.
    • Beberapa log memungkinkan lebih banyak fleksibilitas dalam pilihan penyimpanan data.
• Dalam pengembangan:
  • Atur ke Warning.
  • Tambahkan Trace pesan atau Debug saat memecahkan masalah. Untuk membatasi output, atur Trace atau Debug hanya untuk kategori yang sedang diselidiki.

Set Logging:Console:LogLevel:Microsoft:InformationJSON berikut :

{
    "Logging": {
        "LogLevel": {
            "Microsoft": "Warning"
        },
        "Console": {
            "LogLevel": {
                "Microsoft": "Information"
            }
        }
    }
}

ID peristiwa log

Setiap log dapat menentukan pengidentifikasi peristiwa, EventId adalah struktur dengan Id properti readonly opsional Name dan . Kode sumber sampel menggunakan AppLogEvents kelas untuk menentukan ID peristiwa:

using Microsoft.Extensions.Logging;

internal static class AppLogEvents
{
    internal EventId Create = new(1000, "Created");
    internal EventId Read = new(1001, "Read");
    internal EventId Update = new(1002, "Updated");
    internal EventId Delete = new(1003, "Deleted");

    // These are also valid EventId instances, as there's
    // an implicit conversion from int to an EventId
    internal const int Details = 3000;
    internal const int Error = 3001;

    internal EventId ReadNotFound = 4000;
    internal EventId UpdateNotFound = 4001;

    // ...
}

Tip

Untuk informasi selengkapnya tentang mengonversi int ke EventId, lihat Operator EventId.Implicit(Int32 ke EventId).

ID peristiwa mengaitkan serangkaian peristiwa. Misalnya, semua log yang terkait dengan membaca nilai dari repositori mungkin .1001

Penyedia pengelogan dapat mencatat ID peristiwa di bidang ID, dalam pesan pengelogan, atau tidak sama sekali. Penyedia Debug tidak menampilkan ID peristiwa. Penyedia konsol menampilkan ID peristiwa dalam tanda kurung setelah kategori:

info: Example.DefaultService.GetAsync[1001]
      Reading value for a1b2c3
warn: Example.DefaultService.GetAsync[4000]
      GetAsync(a1b2c3) not found

Beberapa penyedia pengelogan menyimpan ID peristiwa di bidang , yang memungkinkan pemfilteran pada ID.

Templat pesan log

Setiap API log menggunakan templat pesan. Templat pesan dapat berisi tempat penampung tempat argumen disediakan. Gunakan nama untuk tempat penampung, bukan angka. Urutan tempat penampung, bukan namanya, menentukan parameter mana yang digunakan untuk memberikan nilainya. Dalam kode berikut, nama parameter di luar urutan dalam templat pesan:

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

Kode sebelumnya membuat pesan log dengan nilai parameter secara berurutan:

Parameter values: param1, param2

Catatan

Berhati-hatilah saat menggunakan beberapa tempat penampung dalam satu templat pesan, karena berbasis ordinal. Nama tidak digunakan untuk meratakan argumen ke tempat penampung.

Pendekatan ini memungkinkan penyedia pengelogan untuk menerapkan pengelogan semantik atau terstruktur. Argumen itu sendiri diteruskan ke sistem pengelogan, bukan hanya templat pesan yang diformat. Ini memungkinkan penyedia pengelogan untuk menyimpan nilai parameter sebagai bidang. Pertimbangkan metode pencatat berikut:

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

Misalnya, saat masuk ke Azure Table Storage:

• Setiap entitas Tabel Azure dapat memiliki ID properti dan RunTime .
• Tabel dengan properti menyederhanakan kueri pada data yang dicatat. Misalnya, kueri dapat menemukan semua log dalam rentang tertentu RunTime tanpa harus mengurai waktu habis pesan teks.

Pemformatan templat pesan log

Templat pesan log mendukung pemformatan tempat penampung. Templat bebas untuk menentukan format yang valid untuk argumen jenis yang diberikan. Misalnya, pertimbangkan templat pesan pencatat berikut Information :

_logger.LogInformation("Logged on {PlaceHolderName:MMMM dd, yyyy}", DateTimeOffset.UtcNow);
// Logged on January 06, 2022

Dalam contoh sebelumnya, DateTimeOffset instans adalah jenis yang sesuai dengan PlaceHolderName di templat pesan pencatat. Nama ini bisa apa saja karena nilainya berbasis ordinal. MMMM dd, yyyy Format ini valid untuk jenis tersebutDateTimeOffset.

Untuk informasi selengkapnya tentang DateTime dan DateTimeOffset pemformatan, lihat String format tanggal dan waktu kustom.

Contoh pemformatan templat pesan log

Templat pesan log memungkinkan pemformatan tempat penampung. Contoh berikut menunjukkan cara memformat templat pesan menggunakan {} sintaks tempat penampung. Selain itu, contoh pelepasan {} sintaks tempat penampung ditunjukkan dengan outputnya. Akhirnya, interpolasi string dengan tempat penampung templat juga ditampilkan:

logger.LogInformation("Number: {Number}", 1);               // Number: 1
logger.LogInformation("{{Number}}: {Number}", 3);           // {Number}: 3
logger.LogInformation($"{{{{Number}}}}: {{Number}}", 5);    // {Number}: 5

Tip

Anda harus selalu menggunakan pemformatan templat pesan log saat pengelogan. Anda harus menghindari interpolasi string karena dapat menyebabkan masalah performa.

Pengecualian log

Metode pencatat memiliki kelebihan beban yang mengambil parameter pengecualian:

public void Test(string id)
{
    try
    {
        if (id == "none")
        {
            throw new Exception("Default Id detected.");
        }
    }
    catch (Exception ex)
    {
        _logger.LogWarning(
            AppLogEvents.Error, ex,
            "Failed to process iteration: {Id}", id);
    }
}

Pengelogan pengecualian khusus untuk penyedia.

Tingkat log default

Jika tingkat log default tidak diatur, nilai tingkat log default adalah Information.

Misalnya, pertimbangkan aplikasi layanan pekerja berikut:

• Dibuat dengan templat .NET Worker.
• appsettings.json dan appsettings. Development.json dihapus atau diganti namanya.

Dengan penyiapan sebelumnya, menavigasi ke privasi atau halaman beranda menghasilkan banyak Tracepesan , Debug, dan Information dengan Microsoft dalam nama kategori.

Kode berikut menetapkan tingkat log default saat tingkat log default tidak diatur dalam konfigurasi:

class Program
{
    static Task Main(string[] args) =>
        CreateHostBuilder(args).Build().RunAsync();

    static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning));
}

Fungsi filter

Fungsi filter dipanggil untuk semua penyedia dan kategori yang tidak memiliki aturan yang ditetapkan untuknya berdasarkan konfigurasi atau kode:

await Host.CreateDefaultBuilder(args)
    .ConfigureLogging(logging =>
        logging.AddFilter((provider, category, logLevel) =>
        {
            return provider.Contains("ConsoleLoggerProvider")
                && (category.Contains("Example") || category.Contains("Microsoft"))
                && logLevel >= LogLevel.Information;
        }))
    .Build()
    .RunAsync();

Kode sebelumnya menampilkan log konsol saat kategori berisi Example atau Microsoft dan tingkat Information log atau lebih tinggi.

Cakupan log

Cakupan dapat mengelompokkan serangkaian operasi logis. Pengelompokan ini dapat digunakan untuk melampirkan data yang sama ke setiap log yang dibuat sebagai bagian dari set. Misalnya, setiap log yang dibuat sebagai bagian dari pemrosesan transaksi dapat menyertakan ID transaksi.

Cakupan:

• IDisposable Adalah jenis yang dikembalikan oleh BeginScope metode .
• Berlangsung sampai dibuang.

Penyedia berikut mendukung cakupan:

• Console
• AzureAppServicesFile dan AzureAppServicesBlob

Gunakan cakupan dengan membungkus panggilan pencatat dalam using blok:

public async Task<T> GetAsync<T>(string id)
{
    T result;

    using (_logger.BeginScope("using block message"))
    {
        _logger.LogInformation(
            AppLogEvents.Read, "Reading value for {Id}", id);

        var result = await _repository.GetAsync(id);
        if (result is null)
        {
            _logger.LogWarning(
                AppLogEvents.ReadNotFound, "GetAsync({Id}) not found", id);
        }
    }

    return result;
}

JSON berikut memungkinkan cakupan untuk penyedia konsol:

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

Kode berikut memungkinkan cakupan untuk penyedia konsol:

await Host.CreateDefaultBuilder(args)
    .ConfigureLogging((_, logging) =>
        logging.ClearProviders()
            .AddConsole(options => options.IncludeScopes = true))
    .Build()
    .RunAsync();

Aplikasi konsol non-host

Kode pengelogan untuk aplikasi tanpa Host Generik berbeda dalam cara penyedia ditambahkan dan pencatat dibuat. Di aplikasi konsol non-host, panggil metode ekstensi penyedia Add{provider name} saat membuat LoggerFactory:

using var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddFilter("Microsoft", LogLevel.Warning)
        .AddFilter("System", LogLevel.Warning)
        .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
        .AddConsole();
});

ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Example log message");

Objek loggerFactory digunakan untuk membuat ILogger instans.

Membuat log di Utama

Kode berikut masuk Main dengan mendapatkan ILogger instans dari DI setelah membangun host:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

IHost host = Host.CreateDefaultBuilder(args).Build();

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

await host.RunAsync();

Kode sebelumnya bergantung pada dua paket NuGet:

• Microsoft.Extensions.Hosting
• Microsoft.Extensions.Logging

File proyeknya akan terlihat mirip dengan yang berikut ini:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="6.0.1" />
    <PackageReference Include="Microsoft.Extensions.Logging" Version="6.0.0" />
  </ItemGroup>

</Project>

Tidak ada metode pencatat asinkron

Pengelogan harus sangat cepat sehingga tidak sebanding dengan biaya performa kode asinkron. Jika datastore pengelogan lambat, jangan menulisnya secara langsung. Pertimbangkan untuk menulis pesan log ke penyimpanan cepat pada awalnya, lalu pindahkan ke penyimpanan lambat nanti. Misalnya, saat pengelogan ke SQL Server, jangan melakukannya secara langsung dalam Log metode , karena metodenya Log sinkron. Sebagai gantinya, tambahkan pesan log secara sinkron ke antrean dalam memori dan minta pekerja latar belakang menarik pesan keluar dari antrean untuk melakukan pekerjaan asinkron mendorong data ke SQL Server.

Mengubah tingkat log di aplikasi yang sedang berjalan

API Pengelogan tidak menyertakan skenario untuk mengubah tingkat log saat aplikasi sedang berjalan. Namun, beberapa penyedia konfigurasi mampu memuat ulang konfigurasi, yang langsung berpengaruh pada konfigurasi pengelogan. Misalnya, Penyedia Konfigurasi File memuat ulang konfigurasi pengelogan secara default. Jika konfigurasi diubah dalam kode saat aplikasi berjalan, aplikasi dapat memanggil IConfigurationRoot.Reload untuk memperbarui konfigurasi pengelogan aplikasi.

Paket NuGet

Antarmuka ILogger<TCategoryName> dan ILoggerFactory implementasi disertakan dalam .NET SDK. Mereka juga tersedia dalam paket NuGet berikut:

• Antarmuka berada di Microsoft.Extensions.Logging.Abstractions.
• Implementasi default ada di Microsoft.Extensions.Logging.

Menerapkan aturan filter log dalam kode

Pendekatan yang disukai untuk mengatur aturan filter log adalah dengan menggunakan Konfigurasi.

Contoh berikut menunjukkan cara mendaftarkan aturan filter dalam kode:

await Host.CreateDefaultBuilder(args)
    .ConfigureLogging(logging =>
        logging.AddFilter("System", LogLevel.Debug)
            .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)
            .AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace))
    .Build()
    .RunAsync();

logging.AddFilter("System", LogLevel.Debug)System menentukan kategori dan tingkat Debuglog . Filter diterapkan ke semua penyedia karena penyedia tertentu tidak dikonfigurasi.

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

• Penyedia Debug pengelogan.
• Tingkat log dan yang Information lebih tinggi.
• Semua kategori dimulai dengan "Microsoft".

Lihat juga

• Penyedia pengelogan di .NET
• Menerapkan penyedia pengelogan kustom di .NET
• Pemformatan log konsol
• Pengelogan berkinerja tinggi di .NET
• Bug pengelogan harus dibuat di repositori github.com/dotnet/runtime