Aracılığıyla paylaş

.NET kitaplığı yazarları için günlüğe kaydetme kılavuzu

Bir kütüphane yazarı olarak, günlük kaydını kullanıma sunmak, kullanıcılara kütüphanenizin iç işleyişine dair içgörüler sağlamanın harika bir yoludur. Bu kılavuz, günlüğü diğer .NET kitaplıkları ve çerçeveleriyle tutarlı bir şekilde kullanıma sunmanıza yardımcı olur. Ayrıca yaygın performans sorunlarını önlemenize de yardımcı olur.

Arabirimi ne zaman kullanmalı ILoggerFactory

Günlükler oluşturan bir kütüphane yazarken, günlükleri kaydetmek için bir ILogger nesnesine ihtiyacınız vardır. Bu nesneyi almak için API'niz ya bir ILogger<TCategoryName> parametresi kabul edebilir ya da bir ILoggerFactory kabul edip ardından ILoggerFactory.CreateLogger çağırabilirsiniz. Hangi yaklaşım tercih edilmelidir?

  • Tümünün günlükleri yayabilmesi için birden çok sınıfa geçirilebilen bir günlük nesnesine ihtiyacınız olduğunda kullanın ILoggerFactory. Her sınıfın, sınıfla aynı adlı ayrı bir kategoriye sahip günlükler oluşturması önerilir. Bunu yapmak için fabrikanın günlükleri yayan her sınıf için benzersiz ILogger<TCategoryName> nesneler oluşturması gerekir. Yaygın örnekler arasında, bir kitaplık için genel giriş noktası API'leri veya dahili olarak yardımcı sınıflar oluşturabilecek türlerin ortak oluşturucuları yer alır.
  • Yalnızca bir sınıfta kullanılan ve hiç paylaşılmamış bir günlük nesnesine ihtiyacınız olduğunda, kullanın ILogger<TCategoryName>. Burada TCategoryName günlükleri oluşturan türdür. Bunun yaygın bir örneği, bağımlılık ekleme tarafından oluşturulan bir sınıf için oluşturucudur.

Zaman içinde kararlı kalması gereken bir genel API tasarlarsanız, gelecekte iç uygulamanızı yeniden düzenlemeyi isteyebileceğinizi unutmayın. Bir sınıf başlangıçta herhangi bir iç yardımcı türü oluşturmasa bile, kod geliştikçe bu değişebilir. ILoggerFactory kullanımı, genel API'yi değiştirmeden tüm yeni sınıflar için yeni nesneler oluşturmayı ILogger<TCategoryName> mümkün kılar.

Daha fazla bilgi için bkz. Filtreleme kuralları nasıl uygulanır?

Kaynak tarafından oluşturulan günlüğü tercih edin

API, ILogger API'yi kullanmaya yönelik iki yaklaşımı destekler. LoggerExtensions.LogError ve LoggerExtensions.LogInformation gibi yöntemleri çağırabilir veya günlük kaydı kaynak oluşturucusunu kullanarak güçlü bir şekilde yazılmış günlük yöntemlerini tanımlayabilirsiniz. Çoğu durumda, üstün performans ve daha güçlü yazma özelliği sunduğundan kaynak oluşturucu önerilir. Ayrıca ileti şablonları, kimlikler ve günlük düzeyleri gibi günlüğe kaydetmeye özgü hususları da çağrılan koddan ayırır. Kaynak oluşturulmayan yaklaşım, kodu daha kısa hale getirmek için bu avantajlardan vazgeçmeye istekli olduğunuz senaryolar için öncelikli olarak yararlıdır.

using Microsoft.Extensions.Logging;

namespace Logging.LibraryAuthors;

internal static partial class LogMessages
{
    [LoggerMessage(
        Message = "Sold {Quantity} of {Description}",
        Level = LogLevel.Information)]
    internal static partial void LogProductSaleDetails(
        this ILogger logger,
        int quantity,
        string description);
}

Önceki kod:

  • ILogger türünde uzantı yöntemlerini tanımlamak için kullanılabilmesi için LogMessages olarak adlandırılmış bir static öğesini partial class tanımlar.
  • Bir LogProductSaleDetails uzantı yöntemini LoggerMessage öznitelikle ve Message şablonla süsler.
  • LogProductSaleDetails öğesini bildirir, ILogger öğesini genişletir ve bir quantity ile description kabul eder.

Tavsiye

Hata ayıklama sırasında kaynak tarafından oluşturulan koda adım atabilirsiniz çünkü bu kod, onu çağıran kodla aynı derlemenin bir parçasıdır.

Pahalı parametre değerlendirmesini önlemek için kullanın IsEnabled

Parametreleri değerlendirmenin pahalı olduğu durumlar olabilir. Önceki örneği genişleterek, description parametresinin hesaplaması pahalı bir string olduğunu düşünün. Belki de satılan ürün kolay bir ürün açıklaması alır ve bir veritabanı sorgusuna veya bir dosyadan okumaya dayanır. Bu gibi durumlarda, kaynak oluşturucuyu IsEnabled korumasını atlaması için yönlendirebilir ve IsEnabled korumasını çağrı alanına kendiniz ekleyebilirsiniz. Bu, kullanıcının korumanın nerede çağrıldığını belirlemesine olanak tanır ve hesaplanması pahalı olabilecek parametrelerin yalnızca gerçekten gerekli olduğunda değerlendirilmesini sağlar. Aşağıdaki kodu inceleyin:

using Microsoft.Extensions.Logging;

namespace Logging.LibraryAuthors;

internal static partial class LogMessages
{
    [LoggerMessage(
        Message = "Sold {Quantity} of {Description}",
        Level = LogLevel.Information,
        SkipEnabledCheck = true)]
    internal static partial void LogProductSaleDetails(
        this ILogger logger,
        int quantity,
        string description);
}

LogProductSaleDetails uzantı yöntemi çağrıldığında, IsEnabled koruma manuel olarak etkinleştirilir ve pahalı parametre değerlendirmesi yalnızca gerektiğinde yapılır. Aşağıdaki kodu inceleyin:

if (_logger.IsEnabled(LogLevel.Information))
{
    // Expensive parameter evaluation
    var description = product.GetFriendlyProductDescription();

    _logger.LogProductSaleDetails(
        quantity,
        description);
}

Daha fazla bilgi için bkz. Derleme zamanında günlük kaynağı oluşturma ve .NET'te yüksek performanslı günlük kaydı.

Günlük kaydında string interpolasyonu kullanmaktan kaçının

Günlük iletileri oluşturmak için dize ilişkilendirmesini kullanmak yaygın bir hatadır. Dize iç içe yerleştirme, ilgili LogLevel etkin olmasa bile değerlendirildiği için günlükleme sırasında performans açısından sorunludur. Dize ilişkilendirmesi yerine log mesajı şablonunu, formatlamayı ve bağımsız değişken listesini kullanın. Daha fazla bilgi için bkz . .NET'te oturum açma: Günlük iletisi şablonu.

no-op günlük varsayılanlarını kullan

ILogger veya ILoggerFactory bekleyen günlük API'lerini açığa çıkaran bir kütüphaneyi kullandığınızda, günlükçü sağlamak istemediğiniz zamanlar olabilir. Bu durumlarda, Microsoft.Extensions.Logging.Abstractions NuGet paketi herhangi bir işlem yapmayan (no-op) günlük varsayılanlarını sağlar.

Kütüphane kullanıcıları, ILoggerFactory sağlanmadığında varsayılan olarak null günlüğe kaydetmeyi kullanabilir. Null kaydı kullanımı, türler null değildir, ILoggerFactory? dolayısıyla türlerin null atanabilir olarak tanımlanmasından farklıdır. Bu kullanım kolaylığı sağlayan türler hiçbir şeyi günlüğe kaydetmez ve esasen işlem yapmazlar. Uygun olduğunda kullanılabilir soyutlama türlerinden herhangi birini kullanmayı göz önünde bulundurun:

  • Last updated on