Delen via

Logboekregistratie in C# en .NET

  • Artikel

.NET biedt ondersteuning voor hoge prestaties, gestructureerde logboekregistratie via de ILogger API om het gedrag van toepassingen te bewaken en problemen te diagnosticeren. Logboeken kunnen naar verschillende bestemmingen worden geschreven door verschillende logboekregistratieproviders te configureren. Basisproviders voor logboekregistratie zijn ingebouwd en er zijn ook veel externe providers beschikbaar.

Aan de slag

In dit eerste voorbeeld ziet u de basisbeginselen, maar deze is alleen geschikt voor een triviale console-app. Deze voorbeeldconsole-app is afhankelijk van de volgende NuGet-pakketten:

In de volgende sectie ziet u hoe u de code kunt verbeteren, rekening houdend met schalen, prestaties, configuratie en typische programmeerpatronen.

using Microsoft.Extensions.Logging;

using ILoggerFactory factory = LoggerFactory.Create(builder => builder.AddConsole());
ILogger logger = factory.CreateLogger("Program");
logger.LogInformation("Hello World! Logging is {Description}.", "fun");

Het voorgaande voorbeeld:

  • Hiermee maakt u een ILoggerFactory. Alle ILoggerFactory configuraties die bepalen waar logboekberichten worden verzonden, worden opgeslagen. In dit geval configureert u de provider voor consolelogboekregistratie, zodat logboekberichten naar de console worden geschreven.
  • Hiermee maakt u een ILogger met een categorie met de naam 'Programma'. De categorie is een string categorie die is gekoppeld aan elk bericht dat door het ILogger object is geregistreerd. Het wordt gebruikt om logboekberichten van dezelfde klasse (of categorie) samen te groeperen bij het zoeken of filteren van logboeken.
  • Aanroepen LogInformation om een bericht op het Information niveau te registreren. Het logboekniveau geeft de ernst van de vastgelegde gebeurtenis aan en wordt gebruikt om minder belangrijke logboekberichten te filteren. De logboekvermelding bevat ook een berichtsjabloon "Hello World! Logging is {Description}." en een sleutel-waardepaar Description = fun. De sleutelnaam (of tijdelijke aanduiding) komt van het woord in de accolades in de sjabloon en de waarde komt uit het resterende methodeargument.

Dit projectbestand voor dit voorbeeld bevat twee NuGet-pakketten:

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

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

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.0" />
    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.0" />
  </ItemGroup>

</Project>

Tip

Alle voorbeeldbroncode voor logboekregistratie is beschikbaar in de voorbeeldenbrowser om te downloaden. Zie Bladeren in codevoorbeelden: Logboekregistratie in .NET voor meer informatie.

Aanmelden bij een niet-triviale app

Er zijn verschillende wijzigingen die u in het vorige voorbeeld moet aanbrengen wanneer u zich aanmeldt in een minder triviaal scenario:

  • Als uw toepassing gebruikmaakt van afhankelijkheidsinjectie (DI) of een host zoals ASP. WebApplication of Generic Host van NET moet u deze gebruiken ILoggerFactory en ILogger objecten uit hun respectieve DI-containers in plaats van ze rechtstreeks te maken. Zie Integratie met DI en Hosts voor meer informatie.

  • Het genereren van compileertijdbronnen voor logboekregistratie is meestal een beter alternatief voor ILogger extensiemethoden zoals LogInformation. Het genereren van logboekregistratiebronnen biedt betere prestaties, sterker typen en vermijdt het verspreiden van string constanten in uw methoden. Het nadeel is dat het gebruik van deze techniek wat meer code vereist.

using Microsoft.Extensions.Logging;

internal partial class Program
{
    static void Main(string[] args)
    {
        using ILoggerFactory factory = LoggerFactory.Create(builder => builder.AddConsole());
        ILogger logger = factory.CreateLogger("Program");
        LogStartupMessage(logger, "fun");
    }

    [LoggerMessage(Level = LogLevel.Information, Message = "Hello World! Logging is {Description}.")]
    static partial void LogStartupMessage(ILogger logger, string description);
}
  • De aanbevolen procedure voor logboekcategorienamen is het gebruik van de volledig gekwalificeerde naam van de klasse die het logboekbericht maakt. Dit helpt logboekberichten terug te relateren aan de code die ze heeft geproduceerd en biedt een goed beheerniveau bij het filteren van logboeken. CreateLogger accepteert een Type om deze naamgeving eenvoudig te maken.
using Microsoft.Extensions.Logging;

internal class Program
{
    static void Main(string[] args)
    {
        using ILoggerFactory factory = LoggerFactory.Create(builder => builder.AddConsole());
        ILogger logger = factory.CreateLogger<Program>();
        logger.LogInformation("Hello World! Logging is {Description}.", "fun");
    }
}

using Microsoft.Extensions.Logging;
using OpenTelemetry.Logs;

using ILoggerFactory factory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(logging =>
    {
        logging.AddOtlpExporter();
    });
});
ILogger logger = factory.CreateLogger("Program");
logger.LogInformation("Hello World! Logging is {Description}.", "fun");

Integratie met hosts en afhankelijkheidsinjectie

Als uw toepassing gebruikmaakt van afhankelijkheidsinjectie (DI) of een host zoals ASP. WebApplication of Generic Host van NET moet u en objecten uit de DI-container gebruiken ILoggerFactory ILogger in plaats van ze rechtstreeks te maken.

Een ILogger ophalen van DI

In dit voorbeeld wordt een ILogger-object in een gehoste app opgehaald met behulp van ASP.NET Minimale API's:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ExampleHandler>();

var app = builder.Build();

var handler = app.Services.GetRequiredService<ExampleHandler>();
app.MapGet("/", handler.HandleRequest);

app.Run();

partial class ExampleHandler(ILogger<ExampleHandler> logger)
{
    public string HandleRequest()
    {
        LogHandleRequest(logger);
        return "Hello World";
    }

    [LoggerMessage(LogLevel.Information, "ExampleHandler.HandleRequest was called")]
    public static partial void LogHandleRequest(ILogger logger);
}

Het voorgaande voorbeeld:

  • Er is een singleton-service gemaakt die binnenkomende webaanvragen heeft aangeroepen ExampleHandler en toegewezen om de ExampleHandler.HandleRequest functie uit te voeren.
  • Regel 8 definieert een primaire constructor voor ExampleHandler, een functie die is toegevoegd in C# 12. Het gebruik van de oudere C#-constructor werkt even goed, maar is iets uitgebreider.
  • De constructor definieert een parameter van het type ILogger<ExampleHandler>. ILogger<TCategoryName> is afgeleid van ILogger en geeft aan welke categorie het ILogger object heeft. De DI-container zoekt een ILogger met de juiste categorie en levert deze als het constructorargument. Als die categorie nog niet ILogger bestaat, wordt deze automatisch gemaakt vanuit de ILoggerFactory serviceprovider.
  • De logger parameter die in de constructor is ontvangen, is gebruikt voor logboekregistratie in de HandleRequest functie.

Door de host geleverde ILoggerFactory

Hostbouwers initialiseren de standaardconfiguratie en voegen vervolgens een geconfigureerd ILoggerFactory object toe aan de DI-container van de host wanneer de host wordt gebouwd. Voordat de host wordt gebouwd, kunt u de configuratie van logboekregistratie aanpassen via HostApplicationBuilder.Logging, WebApplicationBuilder.Loggingof vergelijkbare API's op andere hosts. Hosts passen ook logboekconfiguratie van standaardconfiguratiebronnen toe als appsettings.json en omgevingsvariabelen. Zie Configuratie in .NET voor meer informatie.

In dit voorbeeld wordt de vorige uitgebreid om de ILoggerFactory aangeboden door WebApplicationBuilder. Er wordt OpenTelemetry toegevoegd als een logboekregistratieprovider die de logboeken via OTLP (OpenTelemetry protocol) verzendt:

var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddOpenTelemetry(logging => logging.AddOtlpExporter());
builder.Services.AddSingleton<ExampleHandler>();
var app = builder.Build();

Een ILoggerFactory maken met DI

Als u een DI-container zonder host gebruikt, gebruikt AddLogging u deze om de container te configureren en toe te voegen ILoggerFactory .

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

// Add services to the container including logging
var services = new ServiceCollection();
services.AddLogging(builder => builder.AddConsole());
services.AddSingleton<ExampleService>();
IServiceProvider serviceProvider = services.BuildServiceProvider();

// Get the ExampleService object from the container
ExampleService service = serviceProvider.GetRequiredService<ExampleService>();

// Do some pretend work
service.DoSomeWork(10, 20);

class ExampleService(ILogger<ExampleService> logger)
{
    public void DoSomeWork(int x, int y)
    {
        logger.LogInformation("DoSomeWork was called. x={X}, y={Y}", x, y);
    }
}

Het voorgaande voorbeeld:

  • Een DI-servicecontainer gemaakt met een ILoggerFactory geconfigureerde schrijfbewerking naar de console
  • Een singleton ExampleService toegevoegd aan de container
  • Er is een exemplaar gemaakt van de ExampleService DI-container die ook automatisch een ILogger<ExampleService> te gebruiken als constructorargument heeft gemaakt.
  • ExampleService.DoSomeWork Aangeroepen waarmee een ILogger<ExampleService> bericht is vastgelegd in de console.

Logboekregistratie configureren

Configuratie van logboekregistratie wordt ingesteld in code of via externe bronnen, zoals configuratiebestanden en omgevingsvariabelen. Het gebruik van externe configuratie is nuttig indien mogelijk, omdat deze kan worden gewijzigd zonder de toepassing opnieuw te bouwen. Sommige taken, zoals het instellen van logboekregistratieproviders, kunnen echter alleen worden geconfigureerd vanuit code.

Logboekregistratie zonder code configureren

Voor apps die een host gebruiken, wordt de configuratie van logboekregistratie meestal aangeboden door de "Logging" sectie appsettings.{Environment}.json-bestanden. Voor apps die geen host gebruiken, worden externe configuratiebronnen expliciet ingesteld of geconfigureerd in code .

De volgende appsettings. Development.json bestand wordt gegenereerd door de .NET Worker-servicesjablonen:

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

In de voorgaande JSON:

  • De "Default"categorieën en "Microsoft""Microsoft.Hosting.Lifetime" logboekniveaus worden opgegeven.
  • De "Default" waarde wordt toegepast op alle categorieën die niet anders zijn opgegeven, waardoor alle standaardwaarden voor alle categorieën "Information"effectief worden gemaakt. U kunt dit gedrag overschrijven door een waarde voor een categorie op te geven.
  • De "Microsoft" categorie is van toepassing op alle categorieën die beginnen met "Microsoft".
  • De "Microsoft" categorielogboeken op logboekniveau van Warning en hoger.
  • De "Microsoft.Hosting.Lifetime" categorie is specifieker dan de "Microsoft" categorie, dus de "Microsoft.Hosting.Lifetime" categorielogboeken op logboekniveau "Information" en hoger.
  • Er is geen specifieke logboekprovider opgegeven, dus LogLevel geldt dit voor alle ingeschakelde logboekregistratieproviders, met uitzondering van het Windows-gebeurtenislogboek.

De Logging eigenschap kan eigenschappen van de provider hebben LogLevel en vastleggen. Hiermee LogLevel geeft u het minimumniveau op dat moet worden vastgelegd voor geselecteerde categorieën. In de voorgaande JSON Information worden logboekniveaus Warning opgegeven. LogLevel geeft de ernst van het logboek aan en varieert van 0 tot 6:

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

Wanneer een LogLevel opgegeven is, wordt logboekregistratie ingeschakeld voor berichten op het opgegeven niveau en hoger. In de voorgaande JSON wordt de Default categorie geregistreerd voor Information en hoger. Bijvoorbeeld, Information, Warningen ErrorCritical berichten worden vastgelegd. Als er geen LogLevel is opgegeven, wordt logboekregistratie standaard ingesteld op het Information niveau. Zie Logboekniveaus voor meer informatie.

Een providereigenschap kan een LogLevel eigenschap opgeven. LogLevel onder een provider geeft de niveaus op die moeten worden vastgelegd voor die provider en overschrijft de logboekinstellingen die niet van de provider zijn. Houd rekening met het volgende appsettings.json-bestand :

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

Instellingen in Logging.{ProviderName}.LogLevel onderdrukkingsinstellingen in Logging.LogLevel. In de voorgaande JSON is het standaardlogboekniveau van de Debug provider ingesteld op Information:

Logging:Debug:LogLevel:Default:Information

Met de voorgaande instelling wordt het Information logboekniveau voor elke Logging:Debug: categorie opgegeven, behalve Microsoft.Hosting. Wanneer een specifieke categorie wordt weergegeven, overschrijft de specifieke categorie de standaardcategorie. In de voorgaande JSON worden de Logging:Debug:LogLevel categorieën "Microsoft.Hosting" overschreven en "Default" worden de instellingen overschreven in Logging:LogLevel

Het minimale logboekniveau kan worden opgegeven voor een van de volgende:

  • Specifieke providers: bijvoorbeeld Logging:EventSource:LogLevel:Default:Information
  • Specifieke categorieën: bijvoorbeeld Logging:LogLevel:Microsoft:Warning
  • Alle providers en alle categorieën: Logging:LogLevel:Default:Warning

Logboeken onder het minimumniveau zijn niet:

  • Doorgegeven aan de provider.
  • Geregistreerd of weergegeven.

Als u alle logboeken wilt onderdrukken, geeft u LogLevel.None op. LogLevel.None heeft een waarde van 6, die hoger is dan LogLevel.Critical (5).

Als een provider logboekbereiken ondersteunt, IncludeScopes geeft u aan of deze zijn ingeschakeld. Zie logboekbereiken voor meer informatie

Het volgende appsettings.json bestand bevat instellingen voor alle ingebouwde providers:

{
    "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"
            }
        }
    }
}

In het voorgaande voorbeeld:

  • De categorieën en niveaus zijn geen voorgestelde waarden. Het voorbeeld wordt verstrekt om alle standaardproviders weer te geven.
  • Instellingen in Logging.{ProviderName}.LogLevel onderdrukkingsinstellingen in Logging.LogLevel. Het niveau in het niveau overschrijft Debug.LogLevel.Default bijvoorbeeld het niveau in LogLevel.Default.
  • De alias van elke provider wordt gebruikt. Elke provider definieert een alias die kan worden gebruikt in de configuratie in plaats van de volledig gekwalificeerde typenaam. De aliassen van de ingebouwde providers zijn:
    • Console
    • Debug
    • EventSource
    • EventLog
    • AzureAppServicesFile
    • AzureAppServicesBlob
    • ApplicationInsights

Logboekniveau instellen op opdrachtregel, omgevingsvariabelen en andere configuratie

Logboekniveau kan worden ingesteld door een van de configuratieproviders. U kunt bijvoorbeeld een persistente omgevingsvariabele met de naam Logging:LogLevel:Microsoft maken met een waarde van Information.

Maak en wijs persistente omgevingsvariabele toe op basis van de waarde van het logboekniveau.

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

Lees de omgevingsvariabele in een nieuw exemplaar van de opdrachtprompt.

:: Prints the env var value
echo %Logging__LogLevel__Microsoft%

De voorgaande omgevingsinstelling blijft behouden in de omgeving. Als u de instellingen wilt testen wanneer u een app gebruikt die is gemaakt met de .NET Worker-servicesjablonen, gebruikt u de dotnet run opdracht in de projectmap nadat de omgevingsvariabele is toegewezen.

dotnet run

Tip

Nadat u een omgevingsvariabele hebt ingesteld, start u uw IDE (Integrated Development Environment) opnieuw op om ervoor te zorgen dat nieuw toegevoegde omgevingsvariabelen beschikbaar zijn.

Selecteer op Azure-app Service de optie Nieuwe toepassingsinstelling op de pagina Instellingenconfiguratie>. Azure-app servicetoepassingsinstellingen zijn:

  • Versleuteld at-rest en verzonden via een versleuteld kanaal.
  • Weergegeven als omgevingsvariabelen.

Zie omgevingsvariabelen voor meer informatie over het instellen van .NET-configuratiewaarden met behulp van omgevingsvariabelen.

Logboekregistratie configureren met code

Gebruik de ILoggingBuilder API om logboekregistratie in code te configureren. Dit kan vanaf verschillende locaties worden geopend:

In dit voorbeeld ziet u hoe u de provider voor consolelogboekregistratie en verschillende filters instelt.

using Microsoft.Extensions.Logging;

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

ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogDebug("Hello {Target}", "Everyone");

In het voorgaande voorbeeld AddFilter wordt het logboekniveau aangepast dat is ingeschakeld voor verschillende categorieën. AddConsole wordt gebruikt om de provider voor consolelogboekregistratie toe te voegen. Logboeken met Debug ernst zijn standaard niet ingeschakeld, maar omdat de configuratie de filters heeft aangepast, wordt het foutopsporingsbericht Hallo iedereen weergegeven op de console.

Hoe filterregels worden toegepast

Wanneer een ILogger<TCategoryName> object wordt gemaakt, selecteert het ILoggerFactory object één regel per provider die op die logboekregistratie moet worden toegepast. Alle berichten die door een ILogger exemplaar zijn geschreven, worden gefilterd op basis van de geselecteerde regels. De meest specifieke regel voor elk provider- en categoriepaar is geselecteerd op basis van de beschikbare regels.

Het volgende algoritme wordt gebruikt voor elke provider wanneer een ILogger wordt gemaakt voor een bepaalde categorie:

  • Selecteer alle regels die overeenkomen met de provider of de alias. Als er geen overeenkomst wordt gevonden, selecteert u alle regels met een lege provider.
  • Selecteer in het resultaat van de vorige stap regels met het langste overeenkomende categorievoorvoegsel. Als er geen overeenkomst wordt gevonden, selecteert u alle regels die geen categorie opgeven.
  • Als er meerdere regels zijn geselecteerd, neemt u de laatste regel.
  • Als er geen regels zijn geselecteerd, gebruikt LoggingBuilderExtensions.SetMinimumLevel(ILoggingBuilder, LogLevel) u deze optie om het minimale logboekregistratieniveau op te geven.

Logboekcategorie

Wanneer een ILogger object wordt gemaakt, wordt er een categorie opgegeven. Deze categorie is opgenomen in elk logboekbericht dat is gemaakt door dat exemplaar van ILogger. De categorietekenreeks is willekeurig, maar de conventie is het gebruik van de volledig gekwalificeerde klassenaam. In een toepassing met een service die is gedefinieerd als het volgende object, kan de categorie bijvoorbeeld zijn "Example.DefaultService":

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

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

        // ...
    }
}

Als verdere categorisatie gewenst is, is het de conventie om een hiërarchische naam te gebruiken door een subcategorie toe te voegen aan de volledig gekwalificeerde klassenaam en expliciet de categorie op te geven met behulp van LoggerFactory.CreateLogger:

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

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

        // ...
    }
}

Bellen CreateLogger met een vaste naam kan handig zijn bij gebruik in meerdere klassen/typen, zodat de gebeurtenissen op categorie kunnen worden georganiseerd.

ILogger<T> is gelijk aan het aanroepen CreateLogger met de volledig gekwalificeerde typenaam van T.

Registratieniveau

De volgende tabel bevat de LogLevel waarden, de gemaksextensiemethode Log{LogLevel} en het voorgestelde gebruik:

Logniveau Weergegeven als Wijze Description
Trace 0 LogTrace De meest gedetailleerde berichten bevatten. Deze berichten kunnen gevoelige app-gegevens bevatten. Deze berichten zijn standaard uitgeschakeld en mogen niet worden ingeschakeld in productie.
Fouten opsporen 1 LogDebug Voor foutopsporing en ontwikkeling. Wees voorzichtig bij de productie vanwege het grote volume.
Informatie 2 LogInformation Houdt de algemene stroom van de app bij. Kan een langetermijnwaarde hebben.
Waarschuwing 3 LogWarning Voor abnormale of onverwachte gebeurtenissen. Bevat meestal fouten of voorwaarden die ervoor zorgen dat de app niet mislukt.
Fout 4 LogError Voor fouten en uitzonderingen die niet kunnen worden verwerkt. Deze berichten geven een fout aan in de huidige bewerking of aanvraag, niet een fout in de hele app.
Kritiek 5 LogCritical Voor fouten die onmiddellijk aandacht vereisen. Voorbeelden: scenario's voor gegevensverlies, onvoldoende schijfruimte.
Geen 6 Hiermee geeft u op dat er geen berichten moeten worden geschreven.

In de vorige tabel wordt de LogLevel tabel van laag naar hoog weergegeven.

De eerste parameter van de logmethode , LogLevelgeeft de ernst van het logboek aan. In plaats van aan te roepen Log(LogLevel, ...), noemen de meeste ontwikkelaars de extensiemethoden Log{LogLevel} . De Log{LogLevel} extensiemethoden roepen de Log methode aan en geven de LogLevel. De volgende twee aanroepen voor logboekregistratie zijn bijvoorbeeld functioneel equivalent en produceren hetzelfde logboek:

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

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

AppLogEvents.Details is de gebeurtenis-id en wordt impliciet vertegenwoordigd door een constante Int32 waarde. AppLogEvents is een klasse die verschillende benoemde id-constanten weergeeft en wordt weergegeven in de sectie Logboekgebeurtenis-id .

De volgende code maakt Information en Warning registreert:

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;
}

In de voorgaande code is de eerste Log{LogLevel} parameter, AppLogEvents.Readde gebeurtenis-id van het logboek. De tweede parameter is een berichtsjabloon met tijdelijke aanduidingen voor argumentwaarden die worden geleverd door de resterende methodeparameters. De methodeparameters worden verderop in dit artikel uitgelegd in de sectie berichtsjabloon .

Configureer het juiste logboekniveau en roep de juiste Log{LogLevel} methoden aan om te bepalen hoeveel logboekuitvoer naar een bepaald opslagmedium wordt geschreven. Voorbeeld:

  • In productie:
    • Logboekregistratie op de Trace niveaus Debug produceert een groot aantal gedetailleerde logboekberichten. Als u de kosten wilt beheren en niet de limieten voor gegevensopslag wilt overschrijden, kunt u berichten vastleggen Trace en Debug e-mail op een hoog volume, laaggeprijsd gegevensarchief. Overweeg het beperken Trace van en Debug tot specifieke categorieën.
    • Logboekregistratie op Warning Critical niveaus moet enkele logboekberichten opleveren.
      • Kosten- en opslaglimieten zijn meestal geen probleem.
      • Enkele logboeken bieden meer flexibiliteit in keuzes voor gegevensopslag.
  • In ontwikkeling:
    • Ingesteld op Warning.
    • Toevoegen of Debug berichten bij Trace het oplossen van problemen. Als u de uitvoer wilt beperken, stelt u deze in Trace of Debug alleen voor de categorieën die worden onderzocht.

De volgende JSON-sets Logging:Console:LogLevel:Microsoft:Information:

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

Gebeurtenis-id van logboek

Elk logboek kan een gebeurtenis-id opgeven, het EventId is een structuur met een Id en optionele Name leeseigenschappen. De voorbeeldbroncode gebruikt de AppLogEvents klasse om gebeurtenis-id's te definiëren:

using Microsoft.Extensions.Logging;

internal static class AppLogEvents
{
    internal static EventId Create = new(1000, "Created");
    internal static EventId Read = new(1001, "Read");
    internal static EventId Update = new(1002, "Updated");
    internal static 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 static EventId ReadNotFound = 4000;
    internal static EventId UpdateNotFound = 4001;

    // ...
}

Tip

Zie EventId.Implicit(Int32 naar EventId) Operator voor meer informatie over het converteren van een int naar een EventIdoperator.

Een gebeurtenis-id koppelt een set gebeurtenissen. Alle logboeken met betrekking tot het lezen van waarden uit een opslagplaats kunnen bijvoorbeeld zijn 1001.

De logboekregistratieprovider kan de gebeurtenis-id registreren in een id-veld, in het logboekbericht of helemaal niet. De foutopsporingsprovider toont geen gebeurtenis-id's. De consoleprovider toont gebeurtenis-id's tussen vierkante haken na de categorie:

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

Sommige logboekproviders slaan de gebeurtenis-id op in een veld, waardoor de id kan worden gefilterd.

Sjabloon voor logboekberichten

Elke logboek-API maakt gebruik van een berichtsjabloon. De berichtsjabloon kan tijdelijke aanduidingen bevatten waarvoor argumenten worden opgegeven. Gebruik namen voor de tijdelijke aanduidingen, niet voor getallen. De volgorde van tijdelijke aanduidingen, niet hun namen, bepaalt welke parameters worden gebruikt om hun waarden op te geven. In de volgende code zijn de parameternamen niet op volgorde in de berichtsjabloon:

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

Met de voorgaande code wordt een logboekbericht gemaakt met de parameterwaarden in volgorde:

Parameter values: param1, param2

Notitie

Houd rekening met het gebruik van meerdere tijdelijke aanduidingen binnen één berichtsjabloon, omdat deze zijn gebaseerd op rangschikken. De namen worden niet gebruikt om de argumenten uit te lijnen op de tijdelijke aanduidingen.

Met deze aanpak kunnen logboekproviders semantische of gestructureerde logboekregistratie implementeren. De argumenten zelf worden doorgegeven aan het logboekregistratiesysteem, niet alleen de opgemaakte berichtsjabloon. Hierdoor kunnen logboekproviders de parameterwaarden opslaan als velden. Houd rekening met de volgende loggermethode:

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

Bijvoorbeeld wanneer u zich aanmeldt bij Azure Table Storage:

  • Elke Azure Table-entiteit kan eigenschappen en RunTime eigenschappen hebbenID.
  • Tabellen met eigenschappen vereenvoudigen query's op vastgelegde gegevens. Een query kan bijvoorbeeld alle logboeken binnen een bepaald RunTime bereik vinden zonder de time-out van het tekstbericht te hoeven parseren.

Opmaak van sjabloon voor logboekberichten

Logboekberichtsjablonen ondersteunen de opmaak van tijdelijke aanduidingen. Sjablonen kunnen elke geldige indeling voor het opgegeven typeargument opgeven. Denk bijvoorbeeld aan de volgende Information sjabloon voor logboekberichten:

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

In het voorgaande voorbeeld is het DateTimeOffset exemplaar het type dat overeenkomt met de PlaceHolderName sjabloon voor het logboekbericht. Deze naam kan alles zijn, omdat de waarden ordinaal zijn. De MMMM dd, yyyy notatie is geldig voor het DateTimeOffset type.

Zie Tekenreeksen voor aangepaste datum- en tijdnotatie voor meer informatie DateTime over en DateTimeOffset opmaak.

Voorbeelden

In de volgende voorbeelden ziet u hoe u een berichtsjabloon opmaken met behulp van de syntaxis van de {} tijdelijke aanduiding. Daarnaast wordt een voorbeeld van het ontsnappen van de syntaxis van de {} tijdelijke aanduiding weergegeven met de uitvoer. Ten slotte wordt tekenreeksinterpolatie met tijdelijke aanduidingen voor tijdelijke aanduidingen ook weergegeven:

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

Tip

  • In de meeste gevallen moet u logboekberichtsjabloonopmaak gebruiken bij logboekregistratie. Het gebruik van tekenreeksinterpolatie kan prestatieproblemen veroorzaken.
  • Codeanalyseregel CA2254: Sjabloon moet een statische expressie zijn om u te waarschuwen bij plaatsen waar uw logboekberichten niet de juiste opmaak gebruiken.

Uitzonderingen in logboeken

De logboekregistratiemethoden hebben overbelastingen die een uitzonderingsparameter gebruiken:

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

Uitzonderingslogboekregistratie is providerspecifiek.

Standaardlogboekniveau

Als het standaardlogboekniveau niet is ingesteld, is Informationde standaardwaarde voor het logboekniveau .

Denk bijvoorbeeld aan de volgende werkservice-app:

  • Gemaakt met de .NET Worker-sjablonen.
  • appsettings.json en appsettings. Development.json verwijderd of hernoemd.

Met de voorgaande installatie produceert het navigeren naar de privacy- of startpagina veel Trace, Debugen Information berichten met Microsoft de categorienaam.

Met de volgende code wordt het standaardlogboekniveau ingesteld wanneer het standaardlogboekniveau niet is ingesteld in de configuratie:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.SetMinimumLevel(LogLevel.Warning);

using IHost host = builder.Build();

await host.RunAsync();

Filterfunctie

Er wordt een filterfunctie aangeroepen voor alle providers en categorieën waaraan geen regels zijn toegewezen door configuratie of code:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.AddFilter((provider, category, logLevel) =>
{
    return provider.Contains("ConsoleLoggerProvider")
        && (category.Contains("Example") || category.Contains("Microsoft"))
        && logLevel >= LogLevel.Information;
});

using IHost host = builder.Build();

await host.RunAsync();

In de voorgaande code worden consolelogboeken weergegeven wanneer de categorie het logboekniveau bevat Example of Microsoft hoger is Information .

Logboekbereiken

Een bereik groept een set logische bewerkingen. Deze groepering kan worden gebruikt om dezelfde gegevens toe te voegen aan elk logboek dat is gemaakt als onderdeel van een set. Elk logboek dat is gemaakt als onderdeel van het verwerken van een transactie, kan bijvoorbeeld de transactie-id bevatten.

Een bereik:

  • Is een IDisposable type dat wordt geretourneerd door de BeginScope methode.
  • Duurt totdat het wordt verwijderd.

De volgende providers ondersteunen bereiken:

Gebruik een bereik door logboekoproepen in een using blok te verpakken:

public async Task<T> GetAsync<T>(string id)
{
    T result;
    var transactionId = Guid.NewGuid().ToString();

    using (_logger.BeginScope(new List<KeyValuePair<string, object>>
        {
            new KeyValuePair<string, object>("TransactionId", transactionId),
        }))
    {
        _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;
}

Met de volgende JSON worden bereiken voor de consoleprovider ingeschakeld:

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

Met de volgende code worden bereiken voor de consoleprovider ingeschakeld:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.ClearProviders();
builder.Logging.AddConsole(options => options.IncludeScopes = true);

using IHost host = builder.Build();

await host.RunAsync();

Logboeken maken in Main

De volgende code meldt zich aan Main door een ILogger exemplaar van DI op te halen na het bouwen van de host:

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

using IHost host = Host.CreateApplicationBuilder(args).Build();

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

await host.RunAsync();

De voorgaande code is afhankelijk van twee NuGet-pakketten:

Het projectbestand ziet er ongeveer als volgt uit:

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

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

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="7.0.1" />
    <PackageReference Include="Microsoft.Extensions.Logging" Version="7.0.0" />
  </ItemGroup>

</Project>

Geen asynchrone logboekregistratiemethoden

Logboekregistratie moet zo snel zijn dat het de prestatiekosten van asynchrone code niet waard is. Als een gegevensarchief voor logboekregistratie traag is, moet u er niet rechtstreeks naar schrijven. U kunt de logboekberichten in eerste instantie naar een snelle opslag schrijven en deze later verplaatsen naar het trage archief. Als u zich bijvoorbeeld aanmeldt bij SQL Server, doet u dit niet rechtstreeks in een Log methode, omdat de Log methoden synchroon zijn. Voeg in plaats daarvan synchroon logboekberichten toe aan een wachtrij in het geheugen en laat een achtergrondmedewerker de berichten uit de wachtrij halen om het asynchrone werk van het pushen van gegevens naar SQL Server uit te voeren.

Logboekniveaus wijzigen in een actieve app

De Logboekregistratie-API bevat geen scenario om logboekniveaus te wijzigen terwijl een app wordt uitgevoerd. Sommige configuratieproviders kunnen de configuratie echter opnieuw laden, wat direct van kracht wordt op de configuratie van logboekregistratie. De configuratie van de bestandsconfiguratieprovider laadt bijvoorbeeld standaard de configuratie van logboekregistratie opnieuw. Als de configuratie in code wordt gewijzigd terwijl een app wordt uitgevoerd, kan de app IConfigurationRoot.Reload aanroepen om de logboekregistratieconfiguratie van de app bij te werken.

NuGet-pakketten

ILoggerFactory De ILogger<TCategoryName> interfaces en implementaties zijn opgenomen in de meeste .NET SDK's als impliciete pakketreferentie. Ze zijn ook expliciet beschikbaar in de volgende NuGet-pakketten wanneer anders impliciet wordt verwezen:

Zie .NET SDK: tabel naar impliciete naamruimte voor meer informatie over welke .NET SDK impliciete pakketverwijzingen bevat.

Zie ook