Delen via

Loggen in C# en .NET

.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, 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.
  • Roept LogInformation aan om een bericht op het Information niveau te loggen. 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 uit het woord binnen de accolades in de sjabloon, en de waarde komt uit het resterende methode-argument.

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.6" />
    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.6" />
  </ItemGroup>

</Project>

Aanbeveling

Alle voorbeeldbroncode voor logboekregistratie is beschikbaar in de voorbeeldenbrowser om te downloaden. Zie Blader door 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 WebApplication van ASP.NET of de Generic Host, moet u de ILoggerFactory- en ILogger-objecten vanuit hun respectieve DI-containers gebruiken in plaats van ze rechtstreeks te maken. Zie Integratie met DI en Hosts voor meer informatie.

  • Het gebruik van bron generatie tijdens compilatietijd voor logging is meestal een beter alternatief voor ILogger extensiemethoden zoals LogInformation. Het genereren van logbronnen biedt betere prestaties, sterkere types en voorkomt 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 WebApplication of Generic Host van ASP.NET, moet u de ILoggerFactory en ILogger objecten uit de DI-container gebruiken in plaats van ze rechtstreeks te maken.

Een ILogger verkrijgen via DI

In dit voorbeeld wordt een ILogger-object voor een gehoste app opgehaald met behulp van ASP.NET Minimal APIs.

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 met de naam ExampleHandler, waarbij binnenkomende webaanvragen worden toegewezen om de functie ExampleHandler.HandleRequest uit te voeren.
  • Regel 12 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 er nog geen ILogger met die categorie bestaat, wordt deze automatisch door de ILoggerFactory in de serviceprovider aangemaakt.
  • 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.

Dit voorbeeld bouwt voort op het vorige om de door ILoggerFactory aangeboden WebApplicationBuilder aan te passen. 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 u AddLogging om deze te configureren en voegt u ILoggerFactory toe aan de container.

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 dat geconfigureerd is om naar de console te schrijven.
  • Een singleton ExampleService toegevoegd aan de container
  • Er is een instantie van de ExampleService gemaakt vanuit de DI-container, die ook automatisch een ILogger<ExampleService> heeft gecreëerd om te gebruiken als constructorargument.
  • 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 logboekconfiguratie meestal bepaald door de sectie van "Logging".{Environment} bestanden. Voor apps die geen host gebruiken, worden externe configuratiebronnen in plaats daarvan expliciet ingesteld of in code geconfigureerd.

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" categorie registreert op een logniveau 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 eigenschap Logging kan provider- en logeigenschappen LogLevel hebben. De LogLevel specificeert het minimale niveau dat moet worden vastgelegd voor geselecteerde categorieën. In de voorgaande JSON worden de logniveaus Information en 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 overschrijven instellingen 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 overschrijven de categorieën Logging:Debug:LogLevel en "Microsoft.Hosting" de instellingen in "Default".

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 aanbieders 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 aan of deze zijn ingeschakeld. Zie logboekbereikenvoor 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 overschrijven instellingen in Logging.LogLevel. Bijvoorbeeld, het niveau in Debug.LogLevel.Default overschrijdt 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

Aanbeveling

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 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 console-logboekregistratie 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 aanbieder of het alias. Als er geen overeenkomst wordt gevonden, selecteer alle regels met een lege aanbieder.
  • 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");

        // ...
    }
}

Het aanroepen van CreateLogger met een vaste naam kan handig zijn wanneer het in meerdere klassen/typen wordt gebruikt, zodat de events per categorie kunnen worden geordend.

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

Logniveau

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

Logniveau Waarde Wijze Beschrijving
Spoor 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 van laag naar hoog weergegeven op basis van ernst.

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 specificeren 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 creëert Information en Warning logboeken.

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:
    • Loggen op de Trace- of Debug-niveaus produceert veel gedetailleerde logboekberichten. Als u de kosten wilt beheersen en niet de limieten voor gegevensopslag wilt overschrijden, log dan Trace- en Debug-niveau berichten naar een gegevensarchief met een hoog volume en lage kosten. Overweeg het beperken Trace van en Debug tot specifieke categorieën.
    • Logging op Warning en Critical niveaus moet weinig logberichten opleveren.
      • Kosten- en opslaglimieten zijn meestal geen probleem.
      • Enkele logboeken bieden meer flexibiliteit in keuzes voor gegevensopslag.
  • In ontwikkeling:
    • Ingesteld op Warning.
    • Voeg Trace of Debug berichten toe bij 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"
            }
        }
    }
}

Logboekgebeurtenis-ID

Elk logboek kan een gebeurtenisidentificator opgeven, de structuur EventId bevat een Id en optionele alleen-lezen Name eigenschappen. 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;

    // ...
}

Aanbeveling

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 op volgorde zijn gebaseerd. De namen worden niet gebruikt om de argumenten uit te lijnen met 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 ID- en RunTime-eigenschappen hebben.
  • 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 voor meer informatie over DateTime- en DateTimeOffset-opmaak Tekenreeksen voor aangepaste datum- en tijdnotatie.

Voorbeelden

In de volgende voorbeelden ziet u hoe u een berichtsjabloon kunt formatteren met behulp van de {} tijdelijke aanduiding syntaxis. Daarnaast wordt een voorbeeld gegeven van het ontduiken van de {}-placeholder-syntaxis, samen met de uitvoer. Ten slotte wordt ook stringinterpolatie met sjabloon tijdelijke aanduidingen weergegeven.

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

Aanbeveling

  • In de meeste gevallen moet u sjabloonopmaak voor logboekberichten 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 consolelogs weergegeven wanneer de categorie Example of Microsoft bevat en het logniveau Information of hoger is.

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 scopes:

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-code worden bereiken voor de consoleprovider mogelijk gemaakt.

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

Met de volgende code worden scopes voor de console-provider 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 logt in Main door een ILogger exemplaar vanuit DI te verkrijgen nadat de host is opgebouwd.

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. Overweeg eerst de logboekberichten naar een snelle opslag te schrijven en ze later naar een langzamere opslag te verplaatsen. 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. Echter, sommige configuratieproviders kunnen de configuratie opnieuw laden, wat direct van kracht wordt op de logboekconfiguratie. De Bestandsconfiguratieprovider laadt bijvoorbeeld standaard de loggingconfiguratie 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

ILogger<TCategoryName> De ILoggerFactory 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 er niet anders impliciet naar verwezen wordt.

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

Zie ook