Aanmelden bij .NET en ASP.NET Core

Door Kirk Larkin, Juergen Gutsch en Rick Anderson

In dit artikel wordt de logboekregistratie in .NET beschreven, zoals deze van toepassing is op ASP.NET Core-apps. Zie Logboekregistratie in .NET voor gedetailleerde informatie over logboekregistratie in .NET.

Zie BlazorASP.NET Core-logboekregistratie Blazorvoor hulp bij logboekregistratie, waarmee de richtlijnen in dit knooppunt worden toegevoegd of vervangen.

Providers voor logboekregistratie

Logboekregistratieproviders slaan logboeken op, met uitzondering van de Console provider die logboeken weergeeft. De Azure Application Insights-provider slaat bijvoorbeeld logboeken op in Azure Application Insights. Meerdere providers kunnen worden ingeschakeld.

De standaardsjablonen voor ASP.NET Core-webapps roepen WebApplication.CreateBuilder aan, waarmee de volgende logboekregistratieproviders worden toegevoegd:

• Console
• Debug
• EventSource
• Gebeurtenislogboek: alleen Windows

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

In de voorgaande code ziet u het Program.cs bestand dat is gemaakt met de ASP.NET Core-web-app-sjablonen. De volgende secties bevatten voorbeelden op basis van de ASP.NET Core-web-app-sjablonen.

Met de volgende code wordt de standaardset van logging-providers die door WebApplication.CreateBuilder zijn toegevoegd, overschreven.

var builder = WebApplication.CreateBuilder(args);
builder.Logging.ClearProviders();
builder.Logging.AddConsole();

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

U kunt ook de voorgaande logboekcode als volgt schrijven:

var builder = WebApplication.CreateBuilder();
builder.Host.ConfigureLogging(logging =>
{
    logging.ClearProviders();
    logging.AddConsole();
});

Zie voor aanvullende providers:

• Ingebouwde providers voor logboekregistratie
• externe logboekregistratieproviders.

Logboeken maken

Als u logboeken wilt maken, gebruikt u een ILogger<TCategoryName> object van afhankelijkheidsinjectie (DI).

Het volgende voorbeeld:

• Hiermee maakt u een logger, ILogger<AboutModel> die gebruikmaakt van een logboekcategorie van de volledig gekwalificeerde naam van het type AboutModel. De logboekcategorie is een tekenreeks die aan elk logboek is gekoppeld.
• Roept LogInformation aan om u aan te melden op Information niveau. Het logboekniveau geeft de ernst van de vastgelegde gebeurtenis aan.

public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("About page visited at {DT}", 
            DateTime.UtcNow.ToLongTimeString());
    }
}

Niveaus en categorieën worden verderop in dit document uitgebreid beschreven.

Zie Blazor voor meer informatie over .

Logboekregistratie configureren

Configuratie van logboekregistratie wordt doorgaans gegeven door het gedeelte Logging van appsettings.{ENVIRONMENT}.json bestanden, waarbij de tijdelijke aanduiding {ENVIRONMENT} de omgeving voorstelt. Het volgende appsettings.Development.json bestand wordt gegenereerd door de ASP.NET Core-web-app-sjablonen:

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

In de voorgaande JSON:

• De "Default" en "Microsoft.AspNetCore" categorieën worden opgegeven.
• De "Microsoft.AspNetCore" categorie is van toepassing op alle categorieën die beginnen met "Microsoft.AspNetCore". Deze instelling is bijvoorbeeld van toepassing op de "Microsoft.AspNetCore.Routing.EndpointMiddleware" categorie.
• De "Microsoft.AspNetCore" categorie logt op logniveau Warning 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": { // All providers, LogLevel applies to all the enabled providers.
      "Default": "Error", // Default logging, Error and higher.
      "Microsoft": "Warning" // All Microsoft* categories, Warning and higher.
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information", // Overrides preceding LogLevel:Default setting.
        "Microsoft.Hosting": "Trace" // Debug:Microsoft.Hosting category.
      }
    },
    "EventSource": { // EventSource provider
      "LogLevel": {
        "Default": "Warning" // All categories of EventSource provider.
      }
    }
  }
}

Instellingen in Logging.{PROVIDER NAME}.LogLevel overrulen instellingen in Logging.LogLevel, waarbij de tijdelijke aanduiding {PROVIDER NAME} de naam van de provider is. 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 Logging:Debug:LogLevel categorieën "Microsoft.Hosting" en "Default" de instellingen 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 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 op LogLevel.None. 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 standaard alle providers die zijn ingeschakeld:

{
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Error",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information" // Overrides preceding LogLevel:Default setting.
      }
    },
    "Console": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "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 gegeven om alle standaardproviders weer te geven.
• Instellingen in Logging.{PROVIDER NAME}.LogLevel overrulen instellingen in Logging.LogLevel, waarbij de tijdelijke aanduiding {PROVIDER NAME} de naam van de provider is. Bijvoorbeeld, het niveau in Debug.LogLevel.Default overschrijdt het niveau in LogLevel.Default.
• Elke alias van een standaardprovider wordt gebruikt. Elke provider definieert een alias die kan worden gebruikt in de configuratie in plaats van de volledig gekwalificeerde typenaam. De ingebouwde providersaliassen zijn:
  • Console
  • Debug
  • EventSource
  • EventLog
  • AzureAppServicesFile
  • AzureAppServicesBlob
  • ApplicationInsights

Aanmelden Program.cs

Het volgende voorbeeld roept Builder.WebApplication.Logger in Program.cs en registreert informatieve berichten:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.Logger.LogInformation("Adding Routes");
app.MapGet("/", () => "Hello World!");
app.Logger.LogInformation("Starting the app");
app.Run();

Het volgende voorbeeld roept AddConsole in Program.cs aan en logt het /Test eindpunt:

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddConsole();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.MapGet("/Test", async (ILogger<Program> logger, HttpResponse response) =>
{
    logger.LogInformation("Testing logging in Program.cs");
    await response.WriteAsync("Testing");
});

app.Run();

In het volgende voorbeeld wordt AddSimpleConsole aangeroepen in Program.cs, wordt de kleuruitvoer uitgeschakeld, en wordt het /Test eindpunt gelogd.

using Microsoft.Extensions.Logging.Console;

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddSimpleConsole(i => i.ColorBehavior = LoggerColorBehavior.Disabled);

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.MapGet("/Test", async (ILogger<Program> logger, HttpResponse response) =>
{
    logger.LogInformation("Testing logging in Program.cs");
    await response.WriteAsync("Testing");
});

app.Run();

Logboekniveau instellen op opdrachtregel, omgevingsvariabelen en andere configuratie

Logboekniveau kan worden ingesteld door een van de configuratieproviders.

Het :-scheidingsteken werkt niet met hiërarchische sleutels van omgevingsvariabelen op alle platformen. Het :-scheidingsteken wordt bijvoorbeeld niet ondersteund door Bash. Het dubbele onderstrepingsteken, __, is:

• Ondersteund door alle platforms.
• Automatisch vervangen door dubbelpunt, :.

De volgende opdrachten:

• Stel de omgevingssleutel Logging:LogLevel:Microsoft in op een waarde in Information Windows.
• Test de instellingen bij het gebruik van een app die is gemaakt met de ASP.NET Core-webtoepassingssjablonen. De dotnet run opdracht moet in de projectmap worden uitgevoerd nadat set is gebruikt.

set Logging__LogLevel__Microsoft=Information
dotnet run

De voorgaande omgevingsinstelling:

• Is alleen ingesteld in processen die worden gestart vanuit het opdrachtvenster waarin ze zijn ingesteld.
• Wordt niet gelezen door browsers die zijn gestart met Visual Studio.

Met de volgende setx-opdracht wordt ook de omgevingssleutel en -waarde ingesteld in Windows. In tegenstelling tot set, setx instellingen blijven behouden. De /M switch stelt de variabele in de systeemomgeving in. Als /M niet wordt gebruikt, wordt een omgevingsvariabele voor de gebruiker ingesteld.

setx Logging__LogLevel__Microsoft Information /M

Houd rekening met het volgende appsettings.json bestand:

"Logging": {
  "Console": {
    "LogLevel": {
      "Microsoft.Hosting.Lifetime": "Trace"
    }
  }
}

Met de volgende opdracht wordt de voorgaande configuratie in de omgeving ingesteld:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

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 Azure Apps: App-configuratie overschrijven met behulp van Azure Portal voor meer informatie.

Zie omgevingsvariabelen voor meer informatie over het instellen van ASP.NET Core-configuratiewaarden met behulp van omgevingsvariabelen. Zie Configuratie in ASP.NET Core voor meer informatie over het gebruik van andere configuratiebronnen, waaronder de opdrachtregel, Azure Key Vault, Azure App Configuration, andere bestandsindelingen en meer.

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 u MinimumLevel.

Uitvoer van logboekregistratie van dotnet run en Visual Studio

Logboeken die zijn gemaakt met de standaardproviders voor logboekregistratie , worden weergegeven:

• In Visual Studio
  • In het debug-uitvoervenster tijdens het foutopsporen.
  • In het venster ASP.NET Core Web Server.
• In het consolevenster wanneer de app wordt uitgevoerd met dotnet run.

Logboeken die beginnen met 'Microsoft'-categorieën zijn afkomstig van .NET. .NET en toepassingscode maken gebruik van dezelfde logboekregistratie-API en providers.

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 controller kan de naam bijvoorbeeld zijn "TodoApi.Controllers.TodoController". De ASP.NET Core-web-apps gebruiken ILogger<T> om automatisch een ILogger exemplaar op te halen dat gebruikmaakt van de volledig gekwalificeerde typenaam van T als categorie:

public class PrivacyModel : PageModel
{
    private readonly ILogger<PrivacyModel> _logger;

    public PrivacyModel(ILogger<PrivacyModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.PrivacyModel called.");
    }
}

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 ILoggerFactory.CreateLogger:

public class ContactModel : PageModel
{
    private readonly ILogger _logger;

    public ContactModel(ILoggerFactory logger)
    {
        _logger = logger.CreateLogger("TodoApi.Pages.ContactModel.MyCategory");
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.ContactModel called.");
    }

Het aanroepen van CreateLogger met een vaste naam kan nuttig zijn wanneer het in meerdere methoden wordt gebruikt, zodat de gebeurtenissen per categorie kunnen worden georganiseerd.

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

Logboekniveau

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

LogLevel	Value	Method	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.
Debug	1	LogDebug	Voor foutopsporing en ontwikkeling. Wees voorzichtig bij de productie vanwege het grote volume.
Information	2	LogInformation	Houdt de algemene stroom van de app bij. Kan een langetermijnwaarde hebben.
Warning	3	LogWarning	Voor abnormale of onverwachte gebeurtenissen. Bevat meestal fouten of voorwaarden die ervoor zorgen dat de app niet mislukt.
Error	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.
Critical	5	LogCritical	Voor fouten die onmiddellijk aandacht vereisen. Voorbeelden: scenario's voor gegevensverlies, onvoldoende schijfruimte.
None	6		Hiermee geeft u op dat een categorie voor logboekregistratie geen berichten mag schrijven.

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

De eerste parameter van de Log methode, LogLevelgeeft de ernst van het logboek aan. In plaats van Log(LogLevel, ...) aan te roepen, gebruiken de meeste ontwikkelaars de Log{LOG LEVEL} uitbreidingsmethoden, waarbij de {LOG LEVEL} placeholder het logniveau is. De volgende twee aanroepen voor logboekregistratie zijn bijvoorbeeld functioneel equivalent en produceren hetzelfde logboek:

[HttpGet]
public IActionResult Test1(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);

    _logger.Log(LogLevel.Information, MyLogEvents.TestItem, routeInfo);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItem is de gebeurtenis-id. MyLogEvents maakt deel uit van de voorbeeld-app en wordt weergegeven in de sectie Logboekgebeurtenis-id .

MyDisplayRouteInfo en ToCtxString worden geleverd door het NuGet-pakket Rick.Docs.Samples.RouteInfo . De methodes geven route-informatie weer Controller en Razor Page.

De volgende code creëert Information en Warning logboeken.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

In de voorgaande code is de eerste Log{LOG LEVEL} parameterMyLogEvents.GetItem de 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 document uitgelegd in de sectie berichtsjabloon .

Roep de juiste Log{LOG LEVEL} methode aan om te bepalen hoeveel logboekuitvoer naar een bepaald opslagmedium wordt geschreven. Voorbeeld:

• In productie:
  • Logboekregistratie op de Trace, Debugof Information niveaus produceert een groot aantal gedetailleerde logboekberichten. Als u kosten wilt beheren en niet de limieten voor gegevensopslag wilt overschrijden, log Trace, Debug, of Information-niveau berichten naar een hoog-volume, laaggeprijsd gegevensarchief. Overweeg Trace, Debug, of Information te beperken 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.
  • Toevoegen Trace, Debugof Information berichten bij het oplossen van problemen. Om de uitvoer te beperken, stel Trace, Debug of Information alleen in voor de categorieën die worden onderzocht.

ASP.NET Core schrijft logboeken voor framework-gebeurtenissen. Denk bijvoorbeeld aan de logboekuitvoer voor:

• Een Razor Pagina-app die is gemaakt met de ASP.NET Core-sjablonen.
• Logging ingesteld op Logging:Console:LogLevel:Microsoft:Information.
• Navigatie naar de Privacy pagina:

info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
      Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
      Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
      Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
      Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
      Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
      Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 149.3023ms 200 text/html; charset=utf-8

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

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

Logboekgebeurtenis-ID

Elk logboek kan een gebeurtenis-id opgeven. De voorbeeld-app gebruikt de MyLogEvents klasse om gebeurtenis-id's te definiëren:

public class MyLogEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems     = 1001;
    public const int GetItem       = 1002;
    public const int InsertItem    = 1003;
    public const int UpdateItem    = 1004;
    public const int DeleteItem    = 1005;

    public const int TestItem      = 3000;

    public const int GetItemNotFound    = 4000;
    public const int UpdateItemNotFound = 4001;
}

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Een gebeurtenis-id koppelt een set gebeurtenissen. Alle logboeken met betrekking tot het weergeven van een lijst met items op een pagina kunnen bijvoorbeeld 1001 zijn.

De logboekregistratieprovider kan de gebeurtenis-id opslaan 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: TodoApi.Controllers.TodoItemsController[1002]
      Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
      Get(1) 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.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

De volgorde van de parameters, niet de namen van de tijdelijke aanduidingen, bepaalt welke parameters worden gebruikt om waarden voor tijdelijke aanduidingen in logboekberichten op te geven. In de volgende code staan de parameternamen in verkeerde volgorde in de tijdelijke aanduidingen van de berichtsjabloon.

var apples = 1;
var pears = 2;
var bananas = 3;

_logger.LogInformation("Parameters: {Pears}, {Bananas}, {Apples}", apples, pears, bananas);

De parameters worden echter toegewezen aan de tijdelijke aanduidingen in de volgorde: apples, pears, bananas. Het logboekbericht weerspiegelt de volgorde van de parameters:

Parameters: 1, 2, 3

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. Denk bijvoorbeeld aan de volgende logmethode:

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

Bijvoorbeeld wanneer u zich aanmeldt bij Azure Table Storage:

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

Uitzonderingen in logboeken

De logboekregistratiemethoden hebben overbelastingen die een uitzonderingsparameter gebruiken:

[HttpGet("{id}")]
public IActionResult TestExp(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    try
    {
        if (id == 3)
        {
            throw new Exception("Test exception");
        }
    }
    catch (Exception ex)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, ex, "TestExp({Id})", id);
        return NotFound();
    }

    return ControllerContext.MyDisplayRouteInfo();
}

MyDisplayRouteInfo en ToCtxString worden geleverd door het NuGet-pakket Rick.Docs.Samples.RouteInfo . De methodes geven route-informatie weer Controller en Razor Page.

Uitzonderingslogboekregistratie is providerspecifiek.

Standaardlogboekniveau

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

Denk bijvoorbeeld aan de volgende web-app:

• Gemaakt met de ASP.NET web-app-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:

var builder = WebApplication.CreateBuilder();
builder.Logging.SetMinimumLevel(LogLevel.Warning);

Over het algemeen moeten logboekniveaus worden opgegeven in de configuratie en niet in code.

Filterfunctie

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

var builder = WebApplication.CreateBuilder();
builder.Logging.AddFilter((provider, category, logLevel) =>
{
    if (provider.Contains("ConsoleLoggerProvider")
        && category.Contains("Controller")
        && logLevel >= LogLevel.Information)
    {
        return true;
    }
    else if (provider.Contains("ConsoleLoggerProvider")
        && category.Contains("Microsoft")
        && logLevel >= LogLevel.Information)
    {
        return true;
    }
    else
    {
        return false;
    }
});

In de voorgaande code worden consolelogs weergegeven wanneer de categorie Controller of Microsoft bevat en het logniveau Information of hoger is.

Over het algemeen moeten logboekniveaus worden opgegeven in de configuratie en niet in code.

ASP.NET Kerncategorieën

De volgende tabel bevat enkele categorieën die worden gebruikt door ASP.NET Core.

Category	Notes
Microsoft.AspNetCore	Algemene ASP.NET Kerndiagnose.
Microsoft.AspNetCore.DataProtection	Welke sleutels werden overwogen, gevonden en gebruikt.
Microsoft.AspNetCore.HostFiltering	Hosts zijn toegestaan.
Microsoft.AspNetCore.Hosting	Hoe lang HTTP-aanvragen namen om te voltooien en op welk tijdstip ze zijn gestart. Welke hosting-opstartassembly's zijn geladen.
Microsoft.AspNetCore.Mvc	MVC en Razor diagnostiek. Modelbinding, filteruitvoering, compilatie weergeven, actieselectie.
Microsoft.AspNetCore.Routing	Overeenkomende informatie routeren.
Microsoft.AspNetCore.Server	Verbindingsstart, stop en actief blijven antwoorden. HTTPS-certificaatgegevens.
Microsoft.AspNetCore.StaticFiles	Bestanden worden geleverd.

Als u meer categorieën in het consolevenster wilt weergeven, stelt u appsettings.Development.json het volgende in:

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

Zie EF-berichtcategorieën voor een lijst met Entity Framework-categorieën.

Logboekbereiken

Een bereik kan een set logische bewerkingen groeperen. 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:

• Console
• AzureAppServicesFile en AzureAppServicesBlob

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

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    TodoItem todoItem;
    var transactionId = Guid.NewGuid().ToString();
    using (_logger.BeginScope(new List<KeyValuePair<string, object>>
        {
            new KeyValuePair<string, object>("TransactionId", transactionId),
        }))
    {
        _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

        todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            _logger.LogWarning(MyLogEvents.GetItemNotFound, 
                "Get({Id}) NOT FOUND", id);
            return NotFound();
        }
    }

    return ItemToDTO(todoItem);
}

Ingebouwde providers voor logboekregistratie

ASP.NET Core bevat de volgende providers voor logboekregistratie als onderdeel van het gedeelde framework:

• Console
• Debug
• EventSource
• EventLog

De volgende providers voor logboekregistratie worden geleverd door Microsoft, maar niet als onderdeel van het gedeelde framework. Ze moeten worden geïnstalleerd als een extra NuGet.

• AzureAppServicesFile en AzureAppServicesBlob
• ApplicationInsights

ASP.NET Core bevat geen logboekregistratieprovider voor het schrijven van logboeken naar bestanden. Als u logboeken naar bestanden wilt schrijven vanuit een ASP.NET Core-app, kunt u overwegen een externe logboekregistratieprovider te gebruiken.

Zie stdoutASP.NET Core Module (ANCM) voor IIS oplossen voor informatie over logboekregistratie en fouten opsporen in logboekregistratie met de ASP.NET Core-module.

Console

De Console provider registreert uitvoer naar de console. Voor meer informatie over het weergeven van Console logboeken tijdens de ontwikkeling, zie Uitvoer van dotnet run en Visual Studio.

Debug

De Debug provider schrijft logboekuitvoer met behulp van de System.Diagnostics.Debug klasse. Oproepen aan System.Diagnostics.Debug.WriteLine om te schrijven naar de Debug provider.

In Linux is de locatie van het Debug providerlogboek distributieafhankelijk en kan dit een van de volgende zijn:

• /var/log/message
• /var/log/syslog

Bron van gebeurtenis

De EventSource provider schrijft naar een platformoverschrijdende gebeurtenisbron met de naam Microsoft-Extensions-Logging. In Windows gebruikt de provider ETW-.

dotnet-trace tooling

Het dotnet-trace hulpprogramma is een platformoverschrijdend ALGEMEEN CLI-hulpprogramma waarmee u .NET-traceringen van een actief proces kunt verzamelen. Het hulpprogramma verzamelt Microsoft.Extensions.Logging.EventSource providergegevens met behulp van een LoggingEventSource.

Zie voor installatie-instructies dotnet-trace.

Gebruik de dotnet-trace hulpprogramma's om een tracering van een app te verzamelen:

1. Voer de app uit met de dotnet run opdracht.

2. Bepaal de proces-id (PID) van de .NET-app:

   dotnet-trace ps
   

   Zoek de PID voor het proces met dezelfde naam als de assembly van de app.

3. Voer de dotnet-trace opdracht uit.

   Algemene opdrachtsyntaxis:

   dotnet-trace collect -p {PID} 
       --providers Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
           :FilterSpecs=\"
               {Logger Category 1}:{Category Level 1};
               {Logger Category 2}:{Category Level 2};
               ...
               {Logger Category N}:{Category Level N}\"
   

   Wanneer u een PowerShell-opdrachtshell gebruikt, plaatst u de --providers waarde tussen enkele aanhalingstekens ('):

   dotnet-trace collect -p {PID} 
       --providers 'Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
           :FilterSpecs=\"
               {Logger Category 1}:{Category Level 1};
               {Logger Category 2}:{Category Level 2};
               ...
               {Logger Category N}:{Category Level N}\"'
   

   Voeg op niet-Windows-platforms de -f speedscope optie toe om de indeling van het uitvoertraceringsbestand te wijzigen in speedscope.

   In de volgende tabel wordt het trefwoord gedefinieerd:

   Keyword	Description
   1	Logboekmeta-gebeurtenissen over de LoggingEventSource. Er worden geen gebeurtenissen vastgelegd van ILogger.
   2	Hiermee wordt de Message-gebeurtenis ingeschakeld wanneer ILogger.Log() wordt aangeroepen. Biedt informatie op een programmatische (niet opgemaakte) manier.
   4	Hiermee wordt de FormatMessage-gebeurtenis ingeschakeld wanneer ILogger.Log() wordt aangeroepen. Biedt de opgemaakte tekenreeksversie van de informatie.
   8	Hiermee wordt de MessageJson-gebeurtenis ingeschakeld wanneer ILogger.Log() wordt aangeroepen. Geeft een JSON-weergave van de argumenten.

   De volgende tabel bevat de providerniveaus:

   Providerniveau	Description
   0	LogAlways
   1	Critical
   2	Error
   3	Warning
   4	Informational
   5	Verbose

   De parsering voor een categorieniveau kan een tekenreeks of een getal zijn:

   Categorie benoemde waarde	Numerieke waarde
   Trace	0
   Debug	1
   Information	2
   Warning	3
   Error	4
   Critical	5

   Het niveau van de provider en het categorieniveau:

   • Zijn in omgekeerde volgorde.
   • De tekenreeksconstanten zijn niet allemaal identiek.

   Als er geen FilterSpecs zijn opgegeven, probeert de EventSourceLogger implementatie het providerniveau te converteren naar een categorieniveau en wordt deze toegepast op alle categorieën.

   Providerniveau	Categorieniveau
   Verbose(5)	Debug(1)
   Informational(4)	Information(2)
   Warning(3)	Warning(3)
   Error(2)	Error(4)
   Critical(1)	Critical(5)

   Als FilterSpecs worden verstrekt, wordt voor elke categorie die in de lijst is opgenomen het daar gecodeerde categorieniveau gebruikt, terwijl alle andere categorieën worden uitgefilterd.

   In de volgende voorbeelden wordt ervan uitgegaan:

   • Een app is actief en voert een oproep naar logger.LogDebug("12345") uit.
   • De proces-id (PID) is ingesteld via set PID=12345, waar 12345 is de werkelijke PID.

   Kijk eens naar de volgende opdracht:

   dotnet-trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5
   

   De bovenstaande opdracht:

   • Registreert foutopsporingsberichten.
   • Past geen FilterSpecs.
   • Specificeert niveau 5 dat de categorie Debug toewijst.

   Kijk eens naar de volgende opdracht:

   dotnet-trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:5\"
   

   De bovenstaande opdracht:

   • Registreert geen foutopsporingsberichten omdat categorieniveau 5 is Critical.
   • Biedt een FilterSpecs.

   Met de volgende opdracht worden foutopsporingsberichten vastgelegd omdat categorieniveau 1 aangeeft Debug.

   dotnet-trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:1\"
   

   Met de volgende opdracht worden foutopsporingsberichten vastgelegd omdat de categorie aangeeft Debug.

   dotnet-trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:Debug\"
   

   FilterSpecs-vermeldingen voor {Logger Category} en {Category Level} vertegenwoordigen aanvullende logboekfiltercondities. Scheid FilterSpecs vermeldingen met het ; puntkommateken.

   Voorbeeld van een Windows-opdrachtprompt:

   dotnet-trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:2:FilterSpecs=\"Microsoft.AspNetCore.Hosting*:4\"
   

   Met de voorgaande opdracht wordt het volgende geactiveerd:

   • De logboekregistratie van de gebeurtenisbron voor het produceren van opgemaakte tekenreeksen (4) voor fouten (2).
   • Microsoft.AspNetCore.Hosting logboekregistratie op logboekregistratieniveau Informational (4).

4. Stop de dotnet-trace hulpmiddelen door op Enter of Ctrl+C te drukken.

   De tracering wordt opgeslagen met de naam trace.nettrace in de map waarin de dotnet-trace opdracht wordt uitgevoerd.

5. Open de trace met Perfview. Open het trace.nettrace bestand en verken de traceringsevenementen.

Als de app de host niet opbouwt met WebApplication.CreateBuilder, voegt u de gebeurtenisbronprovider toe aan de logconfiguratie van de app.

Voor meer informatie, zie:

• Tracering voor hulpprogramma voor prestatieanalyse (dotnet-trace) (.NET-documentatie)
• dotnet-trace
• LoggingEventSource
• EventLevel
• Perfview: handig voor het weergeven van gebeurtenisbrontraceringen.

Perfview

Gebruik het hulpprogramma PerfView om logboeken te verzamelen en weer te geven. Er zijn andere hulpprogramma's voor het weergeven van ETW-logboeken, maar PerfView biedt de beste ervaring voor het werken met de ETW-gebeurtenissen die worden verzonden door ASP.NET Core.

Als u PerfView wilt configureren voor het verzamelen van gebeurtenissen die door deze provider zijn geregistreerd, voegt u de tekenreeks *Microsoft-Extensions-Logging toe aan de lijst Aanvullende providers . Mis het * aan het begin van de tekenreeks niet.

Windows EventLog

De EventLog-provider verzendt logboekuitvoer naar het Windows-gebeurtenislogboek. In tegenstelling tot de andere providers erft de EventLog provider niet de standaardinstellingen voor een niet-provider. Als EventLog logboekinstellingen niet zijn opgegeven, worden ze standaard ingesteld op LogLevel.Warning.

Als u gebeurtenissen wilt vastleggen die lager zijn dan LogLevel.Warning, stelt u het logboekniveau expliciet in. In het volgende voorbeeld wordt het standaardlogboekniveau van het gebeurtenislogboek ingesteld op LogLevel.Information:

"Logging": {
  "EventLog": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

AddEventLog overbelastingen kunnen worden EventLogSettingsdoorgegeven. Als null niet is opgegeven, worden de volgende standaardinstellingen gebruikt:

• LogName: "Toepassing"
• SourceName: '.NET Runtime'
• MachineName: de naam van de lokale computer wordt gebruikt.

Met de volgende code wordt de SourceName gewijzigd van de standaardwaarde van ".NET Runtime" in MyLogs:

var builder = WebApplication.CreateBuilder();
builder.Logging.AddEventLog(eventLogSettings =>
{
    eventLogSettings.SourceName = "MyLogs";
});

Azure App Service

Het Microsoft.Extensions.Logging.AzureAppServices provider-pakket schrijft logboeken naar tekstbestanden in het bestandssysteem van een Azure App Service-app en naar blob-opslag in een Azure Storage-account.

Het providerpakket is niet opgenomen in het gedeelde framework. Als u de provider wilt gebruiken, voegt u het providerpakket toe aan het project.

Als u providerinstellingen wilt configureren, gebruikt u AzureFileLoggerOptions en AzureBlobLoggerOptions, zoals wordt weergegeven in het volgende voorbeeld:

using Microsoft.Extensions.Logging.AzureAppServices;

var builder = WebApplication.CreateBuilder();
builder.Logging.AddAzureWebAppDiagnostics();
builder.Services.Configure<AzureFileLoggerOptions>(options =>
{
    options.FileName = "azure-diagnostics-";
    options.FileSizeLimit = 50 * 1024;
    options.RetainedFileCountLimit = 5;
});
builder.Services.Configure<AzureBlobLoggerOptions>(options =>
{
    options.BlobName = "log.txt";
});

Wanneer de app is geïmplementeerd in Azure App Service, worden de instellingen in de App Service-logboeken sectie van de pagina App Service van Azure Portal gebruikt. Wanneer de volgende instellingen worden bijgewerkt, worden de wijzigingen onmiddellijk van kracht zonder dat de app opnieuw hoeft te worden opgestart of opnieuw hoeft te worden geïmplementeerd.

• Toepassingslogboekregistratie (bestandssysteem)
• Logboekregistratie van toepassingen (blob)

De standaardlocatie voor logboekbestanden bevindt zich in de D:\\home\\LogFiles\\Application map en de standaardbestandsnaam is diagnostics-yyyymmdd.txt. De standaardlimiet voor de bestandsgrootte is 10 MB en het standaard maximum aantal bewaarde bestanden is 2. De standaard-blobnaam is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Deze provider registreert alleen wanneer het project wordt uitgevoerd in de Azure-omgeving.

Azure-logboekstreaming

Azure-logboekstreaming biedt ondersteuning voor het weergeven van logboekactiviteiten in realtime vanuit:

• De app-server
• De webserver
• Tracering van mislukte aanvragen

Om Azure-logstreaming te configureren:

• Navigeer naar de App Service-logboeken pagina vanaf de portalpagina van de app.
• Stel application logging (bestandssysteem) in op On.
• Kies het logboek niveau. Deze instelling is alleen van toepassing op Azure-logboekstreaming.

Navigeer naar de pagina Logstream om logs weer te geven. De vastgelegde berichten worden vastgelegd met de ILogger interface.

Azure Application Insights

Het Microsoft.Extensions.Logging.ApplicationInsights providerpakket schrijft logboeken naar Azure Application Insights. Application Insights is een service die een web-app bewaakt en hulpprogramma's biedt voor het opvragen en analyseren van de telemetriegegevens. Als u deze provider gebruikt, kunt u uw logboeken opvragen en analyseren met behulp van de Application Insights-hulpprogramma's.

De provider voor logboekregistratie is opgenomen als een afhankelijkheid van Microsoft.ApplicationInsights.AspNetCore, het pakket dat alle beschikbare telemetrie biedt voor ASP.NET Core. Als u dit pakket gebruikt, hoeft u het providerpakket niet te installeren.

Het Microsoft.ApplicationInsights.Web pakket is bedoeld voor ASP.NET 4.x, niet ASP.NET Core.

Zie de volgende bronnen voor meer informatie:

• Overzicht van Application Insights
• Application Insights voor ASP.NET Core-toepassingen: begin hier als u het volledige scala aan Application Insights-telemetrie wilt implementeren, samen met logboekregistratie.
• ApplicationInsightsLoggerProvider voor .NET ILogger-logboeken: begin hier als u de logboekregistratieprovider wilt implementeren zonder de rest van Application Insights-telemetrie.
• Application Insights-logboekregistratieadapters
• Installeer, configureer en initialiseer de interactieve zelfstudie over de Application Insights SDK .

Externe logboekregistratieproviders

Frameworks voor logboekregistratie van derden die werken met ASP.NET Core:

• elmah.io (GitHub-opslagplaats)
• Gelf (GitHub-opslagplaats)
• JSNLog- (GitHub-opslagplaats)
• KissLog.net (GitHub-opslagplaats)
• Log4Net- (GitHub-opslagplaats)
• NLog (GitHub-opslagplaats)
• PLogger (GitHub-opslagplaats)
• Sentry (GitHub-opslagplaats)
• Serilog (GitHub-opslagplaats)
• Stackdriver (Github-opslagplaats)

Sommige frameworks van derden kunnen semantische logboekregistratie uitvoeren, ook wel gestructureerde logboekregistratie genoemd.

Het gebruik van een framework van derden is vergelijkbaar met het gebruik van een van de ingebouwde providers:

1. Voeg een NuGet-pakket toe aan uw project.
2. Roep een ILoggerFactory extensiemethode aan die wordt geleverd door het logboekregistratieframework.

Zie de documentatie van elke provider voor meer informatie. Externe logboekregistratieproviders worden niet ondersteund door Microsoft.

Geen asynchrone logboekregistratiemethoden

Logboekregistratie moet zo snel zijn dat het de prestatiekosten van asynchrone code niet waard is. Als een logboekgegevensarchief 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. Zie Richtlijnen voor het aanmelden bij een berichtenwachtrij voor trage gegevensarchieven (dotnet/AspNetCore.Docs #11801) voor meer informatie.

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. Bijvoorbeeld, de File Configuration Provider laadt standaard de loggingconfiguratie opnieuw. Als de configuratie in de code wordt gewijzigd terwijl een app wordt uitgevoerd, kan de app IConfigurationRoot.Reload aanroepen om de logconfiguratie van de app bij te werken.

ILogger en ILoggerFactory

ILogger<TCategoryName> en ILoggerFactory interfaces en implementaties zijn opgenomen in de .NET SDK. Ze zijn ook beschikbaar in de volgende NuGet-pakketten:

• De interfaces bevinden zich in Microsoft.Extensions.Logging.Abstractions.
• De standaard implementaties bevinden zich in Microsoft.Extensions.Logging.

Regels voor logboekfilters toepassen in code

De voorkeursmethode voor het instellen van logboekfilterregels is het gebruik van Configuratie.

In het volgende voorbeeld ziet u hoe u filterregels registreert in code:

using Microsoft.Extensions.Logging.Console;
using Microsoft.Extensions.Logging.Debug;

var builder = WebApplication.CreateBuilder();
builder.Logging.AddFilter("System", LogLevel.Debug);
builder.Logging.AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information);
builder.Logging.AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace);

logging.AddFilter("System", LogLevel.Debug) hiermee geeft u het System categorie- en logboekniveau Debugop. Het filter wordt toegepast op alle providers omdat er geen specifieke provider is geconfigureerd.

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

• De Debug logboekregistratieprovider.
• Logboekniveau Information en hoger.
• Alle categorieën beginnen met "Microsoft".

Automatisch scope loggen met SpanId, TraceId, ParentId, Baggage, en Tags.

De loggingbibliotheken maken impliciet een bereikobject met SpanId, TraceId, ParentId, Baggage, en Tags. Dit gedrag wordt geconfigureerd via ActivityTrackingOptions.

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddSimpleConsole(options =>
{
    options.IncludeScopes = true;
});

builder.Logging.Configure(options =>
{
    options.ActivityTrackingOptions = ActivityTrackingOptions.SpanId
                                       | ActivityTrackingOptions.TraceId
                                       | ActivityTrackingOptions.ParentId
                                       | ActivityTrackingOptions.Baggage
                                       | ActivityTrackingOptions.Tags;
});
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Als de traceparent http-verzoekheader is ingesteld, toont ParentId in het logboekbereik de W3C parent-id van de inkomende traceparent header en geeft SpanId in het logboekbereik de bijgewerkte parent-id voor de volgende uitgaande stap/span weer. Zie Muteren van het traceparent-veld voor meer informatie.

Maak een aangepaste logger

Zie Een aangepaste logboekregistratieprovider implementeren in .NET om een aangepaste logboekregistratie te maken.

Aanvullende bronnen

• Prestaties van logboekregistratie verbeteren met brongeneratoren
• Achter [LogProperties] en de nieuwe brongenerator voor telemetrieregistratie
• Microsoft.Extensions.Logging-bron op GitHub
• Voorbeeldcode bekijken of downloaden (hoe u kunt downloaden).
• Logboekregistratie met hoge prestaties
• Logboekfouten moeten worden gemaakt in de dotnet/runtime GitHub-opslagplaats.
• ASP.NET Core Blazor logboekregistratie

Door Kirk Larkin, Juergen Gutsch en Rick Anderson

In dit onderwerp wordt de logboekregistratie in .NET beschreven, zoals deze van toepassing is op ASP.NET Core-apps. Zie Logboekregistratie in .NET voor gedetailleerde informatie over logboekregistratie in .NET. Zie Blazorvoor meer informatie over logboekregistratie in Blazor apps.

Voorbeeldcode bekijken of downloaden (hoe u kunt downloaden).

Providers voor logboekregistratie

Logboekregistratieproviders slaan logboeken op, met uitzondering van de Console provider die logboeken weergeeft. De Azure Application Insights-provider slaat bijvoorbeeld logboeken op in Azure Application Insights. Meerdere providers kunnen worden ingeschakeld.

De standaardsjablonen voor ASP.NET Core-web-app:

• Gebruik de Generic Host.
• Roep CreateDefaultBuilderaan, waarmee de volgende logboekregistratieproviders worden toegevoegd:
  • Console
  • Debug
  • EventSource
  • Gebeurtenislogboek: alleen Windows

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

In de voorgaande code ziet u de Program klasse die is gemaakt met de ASP.NET Core-web-app-sjablonen. De volgende secties bevatten voorbeelden op basis van de ASP.NET Core-web-app-sjablonen, die gebruikmaken van de algemene host. Niet-hostconsole-apps worden verderop in dit document besproken.

Als u de standaardset logboekregistratieproviders wilt overschrijven die zijn toegevoegd door Host.CreateDefaultBuilder, roept ClearProviders u de vereiste logboekregistratieproviders aan en voegt u deze toe. Bijvoorbeeld de volgende code:

• Roept ClearProviders aan om alle ILoggerProvider exemplaren van de builder te verwijderen.
• Hiermee voeg je de Console logprovider toe.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Zie voor aanvullende providers:

• Ingebouwde providers voor logboekregistratie
• externe logboekregistratieproviders.

Logboeken maken

Als u logboeken wilt maken, gebruikt u een ILogger<TCategoryName> object van afhankelijkheidsinjectie (DI).

Het volgende voorbeeld:

• Hiermee maakt u een logger, ILogger<AboutModel> die gebruikmaakt van een logboekcategorie van de volledig gekwalificeerde naam van het type AboutModel. De logboekcategorie is een tekenreeks die aan elk logboek is gekoppeld.
• Roept LogInformation aan om u aan te melden op Information niveau. Het logboekniveau geeft de ernst van de vastgelegde gebeurtenis aan.

public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }
    public string Message { get; set; }

    public void OnGet()
    {
        Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
        _logger.LogInformation(Message);
    }
}

Niveaus en categorieën worden verderop in dit document uitgebreid beschreven.

Zie Blazor voor meer informatie over .

Logboeken maken in Main en Opstarten laat zien hoe u logboeken maakt in Main en Startup.

Logboekregistratie configureren

Configuratie van logboeken wordt doorgaans geleverd door het gedeelte Logging van appsettings.{Environment}.json bestanden. Het volgende appsettings.Development.json bestand wordt gegenereerd door de ASP.NET Core-web-app-sjablonen:

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

In de voorgaande JSON:

• De "Default", "Microsoft"en "Microsoft.Hosting.Lifetime" categorieën worden opgegeven.
• De "Microsoft" categorie is van toepassing op alle categorieën die beginnen met "Microsoft". Deze instelling is bijvoorbeeld van toepassing op de "Microsoft.AspNetCore.Routing.EndpointMiddleware" categorie.
• De "Microsoft" categorie logt op logniveau Warning en hoger.
• De "Microsoft.Hosting.Lifetime" categorie is specifieker dan de "Microsoft" categorie, dus de "Microsoft.Hosting.Lifetime" categorie wordt gelogd op het logniveau 'Informatie' 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": { // All providers, LogLevel applies to all the enabled providers.
      "Default": "Error", // Default logging, Error and higher.
      "Microsoft": "Warning" // All Microsoft* categories, Warning and higher.
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information", // Overrides preceding LogLevel:Default setting.
        "Microsoft.Hosting": "Trace" // Debug:Microsoft.Hosting category.
      }
    },
    "EventSource": { // EventSource provider
      "LogLevel": {
        "Default": "Warning" // All categories of EventSource provider.
      }
    }
  }
}

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 logboekbereiken voor meer informatie

Het volgende appsettings.json bestand bevat standaard alle providers die zijn ingeschakeld:

{
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Error",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information" // Overrides preceding LogLevel:Default setting.
      }
    },
    "Console": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "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.
• Elke alias van een standaardprovider wordt gebruikt. Elke provider definieert een alias die kan worden gebruikt in de configuratie in plaats van de volledig gekwalificeerde typenaam. De ingebouwde providersaliassen 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.

Het :-scheidingsteken werkt niet met hiërarchische sleutels van omgevingsvariabelen op alle platformen. Het :-scheidingsteken wordt bijvoorbeeld niet ondersteund door Bash. Het dubbele onderstrepingsteken, __, is:

• Ondersteund door alle platforms.
• Automatisch vervangen door dubbelpunt, :.

De volgende opdrachten:

• Stel de omgevingssleutel Logging:LogLevel:Microsoft in op een waarde in Information Windows.
• Test de instellingen bij het gebruik van een app die is gemaakt met de ASP.NET Core-webtoepassingssjablonen. De dotnet run opdracht moet in de projectmap worden uitgevoerd nadat set is gebruikt.

set Logging__LogLevel__Microsoft=Information
dotnet run

De voorgaande omgevingsinstelling:

• Is alleen ingesteld in processen die worden gestart vanuit het opdrachtvenster waarin ze zijn ingesteld.
• Wordt niet gelezen door browsers die zijn gestart met Visual Studio.

Met de volgende setx-opdracht wordt ook de omgevingssleutel en -waarde ingesteld in Windows. In tegenstelling tot set, setx instellingen blijven behouden. De /M switch stelt de variabele in de systeemomgeving in. Als /M niet wordt gebruikt, wordt een omgevingsvariabele voor de gebruiker ingesteld.

setx Logging__LogLevel__Microsoft Information /M

Houd rekening met het volgende appsettings.json bestand:

"Logging": {
    "Console": {
      "LogLevel": {
        "Microsoft.Hosting.Lifetime": "Trace"
      }
    }
}

Met de volgende opdracht wordt de voorgaande configuratie in de omgeving ingesteld:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

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 Azure Apps: App-configuratie overschrijven met behulp van Azure Portal voor meer informatie.

Zie omgevingsvariabelen voor meer informatie over het instellen van ASP.NET Core-configuratiewaarden met behulp van omgevingsvariabelen. Zie Configuratie in ASP.NET Core voor meer informatie over het gebruik van andere configuratiebronnen, waaronder de opdrachtregel, Azure Key Vault, Azure App Configuration, andere bestandsindelingen en meer.

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 u MinimumLevel.

Uitvoer van logboekregistratie van dotnet run en Visual Studio

Logboeken die zijn gemaakt met de standaardproviders voor logboekregistratie , worden weergegeven:

• In Visual Studio
  • In het debug-uitvoervenster tijdens het foutopsporen.
  • In het venster ASP.NET Core Web Server.
• In het consolevenster wanneer de app wordt uitgevoerd met dotnet run.

Logboeken die beginnen met 'Microsoft'-categorieën zijn afkomstig uit ASP.NET Core-frameworkcode. ASP.NET Core en toepassingscode gebruiken dezelfde API en providers voor logboekregistratie.

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 klassenaam. In een controller kan de naam bijvoorbeeld zijn "TodoApi.Controllers.TodoController". De ASP.NET Core-web-apps gebruiken ILogger<T> om automatisch een ILogger exemplaar op te halen dat gebruikmaakt van de volledig gekwalificeerde typenaam van T als categorie:

public class PrivacyModel : PageModel
{
    private readonly ILogger<PrivacyModel> _logger;

    public PrivacyModel(ILogger<PrivacyModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.PrivacyModel called.");
    }
}

Als u de categorie expliciet wilt opgeven, roept u het volgende ILoggerFactory.CreateLoggeraan:

public class ContactModel : PageModel
{
    private readonly ILogger _logger;

    public ContactModel(ILoggerFactory logger)
    {
        _logger = logger.CreateLogger("TodoApi.Pages.ContactModel.MyCategory");
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.ContactModel called.");
    }

Het aanroepen van CreateLogger met een vaste naam kan nuttig zijn wanneer het in meerdere methoden wordt gebruikt, zodat de gebeurtenissen per categorie kunnen worden georganiseerd.

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

Logboekniveau

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

LogLevel	Value	Method	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.
Debug	1	LogDebug	Voor foutopsporing en ontwikkeling. Wees voorzichtig bij de productie vanwege het grote volume.
Information	2	LogInformation	Houdt de algemene stroom van de app bij. Kan een langetermijnwaarde hebben.
Warning	3	LogWarning	Voor abnormale of onverwachte gebeurtenissen. Bevat meestal fouten of voorwaarden die ervoor zorgen dat de app niet mislukt.
Error	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.
Critical	5	LogCritical	Voor fouten die onmiddellijk aandacht vereisen. Voorbeelden: scenario's voor gegevensverlies, onvoldoende schijfruimte.
None	6		Hiermee geeft u op dat een categorie voor logboekregistratie geen berichten mag schrijven.

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 logmethode aan en geven de LogLevel op. De volgende twee aanroepen voor logboekregistratie zijn bijvoorbeeld functioneel equivalent en produceren hetzelfde logboek:

[HttpGet]
public IActionResult Test1(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);

    _logger.Log(LogLevel.Information, MyLogEvents.TestItem, routeInfo);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItem is de gebeurtenis-id. MyLogEvents maakt deel uit van de voorbeeld-app en wordt weergegeven in de sectie Logboekgebeurtenis-id .

MyDisplayRouteInfo en ToCtxString worden geleverd door het NuGet-pakket Rick.Docs.Samples.RouteInfo . De methodes geven route-informatie weer Controller en Razor Page.

De volgende code creëert Information en Warning logboeken.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

In de voorgaande code is de eerste Log{LogLevel} parameterMyLogEvents.GetItem de 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 document uitgelegd in de sectie berichtsjabloon .

Roep de juiste Log{LogLevel} methode aan om te bepalen hoeveel logboekuitvoer naar een bepaald opslagmedium wordt geschreven. Voorbeeld:

• In productie:
  • Loggen op de Trace- of Information-niveaus produceert veel gedetailleerde logboekberichten. Als u de kosten wilt beheersen en niet de limieten voor gegevensopslag wilt overschrijden, log dan Trace- en Information-niveau berichten naar een gegevensarchief met een hoog volume en lage kosten. Overweeg het beperken Trace van en Information 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 Information berichten toe bij het oplossen van problemen. Als u de uitvoer wilt beperken, stelt u deze in Trace of Information alleen voor de categorieën die worden onderzocht.

ASP.NET Core schrijft logboeken voor framework-gebeurtenissen. Denk bijvoorbeeld aan de logboekuitvoer voor:

• Een Razor Pagina-app die is gemaakt met de ASP.NET Core-sjablonen.
• Logging ingesteld op Logging:Console:LogLevel:Microsoft:Information
• Navigatie naar de Privacy pagina:

info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
      Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
      Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
      Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
      Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
      Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
      Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 149.3023ms 200 text/html; charset=utf-8

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

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

Logboekgebeurtenis-ID

Elk logboek kan een gebeurtenis-id opgeven. De voorbeeld-app gebruikt de MyLogEvents klasse om gebeurtenis-id's te definiëren:

public class MyLogEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems     = 1001;
    public const int GetItem       = 1002;
    public const int InsertItem    = 1003;
    public const int UpdateItem    = 1004;
    public const int DeleteItem    = 1005;

    public const int TestItem      = 3000;

    public const int GetItemNotFound    = 4000;
    public const int UpdateItemNotFound = 4001;
}

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Een gebeurtenis-id koppelt een set gebeurtenissen. Alle logboeken met betrekking tot het weergeven van een lijst met items op een pagina kunnen bijvoorbeeld 1001 zijn.

De logboekregistratieprovider kan de gebeurtenis-id opslaan 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: TodoApi.Controllers.TodoItemsController[1002]
      Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
      Get(1) 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.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

De volgorde van de parameters, niet de namen van de tijdelijke aanduidingen, bepaalt welke parameters worden gebruikt om waarden voor tijdelijke aanduidingen in logboekberichten op te geven. In de volgende code staan de parameternamen in verkeerde volgorde in de tijdelijke aanduidingen van de berichtsjabloon.

var apples = 1;
var pears = 2;
var bananas = 3;

_logger.LogInformation("Parameters: {pears}, {bananas}, {apples}", apples, pears, bananas);

De parameters worden echter toegewezen aan de tijdelijke aanduidingen in de volgorde: apples, pears, bananas. Het logboekbericht weerspiegelt de volgorde van de parameters:

Parameters: 1, 2, 3

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. Denk bijvoorbeeld aan de volgende logmethode:

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

Bijvoorbeeld wanneer u zich aanmeldt bij Azure Table Storage:

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

Uitzonderingen in logboeken

De logboekregistratiemethoden hebben overbelastingen die een uitzonderingsparameter gebruiken:

[HttpGet("{id}")]
public IActionResult TestExp(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    try
    {
        if (id == 3)
        {
            throw new Exception("Test exception");
        }
    }
    catch (Exception ex)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, ex, "TestExp({Id})", id);
        return NotFound();
    }

    return ControllerContext.MyDisplayRouteInfo();
}

MyDisplayRouteInfo en ToCtxString worden geleverd door het NuGet-pakket Rick.Docs.Samples.RouteInfo . De methodes geven route-informatie weer Controller en Razor Page.

Uitzonderingslogboekregistratie is providerspecifiek.

Standaardlogboekniveau

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

Denk bijvoorbeeld aan de volgende web-app:

• Gemaakt met de ASP.NET web-app-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:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Over het algemeen moeten logboekniveaus worden opgegeven in de configuratie en niet in code.

Filterfunctie

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

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
            {
                logging.AddFilter((provider, category, logLevel) =>
                {
                    if (provider.Contains("ConsoleLoggerProvider")
                        && category.Contains("Controller")
                        && logLevel >= LogLevel.Information)
                    {
                        return true;
                    }
                    else if (provider.Contains("ConsoleLoggerProvider")
                        && category.Contains("Microsoft")
                        && logLevel >= LogLevel.Information)
                    {
                        return true;
                    }
                    else
                    {
                        return false;
                    }
                });
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

In de voorgaande code worden consolelogs weergegeven wanneer de categorie Controller of Microsoft bevat en het logniveau Information of hoger is.

Over het algemeen moeten logboekniveaus worden opgegeven in de configuratie en niet in code.

ASP.NET Kern en EF Core categorieën

De volgende tabel bevat enkele categorieën die worden gebruikt door ASP.NET Core en Entity Framework Core, met opmerkingen over de logboeken:

Category	Notes
Microsoft.AspNetCore	Algemene ASP.NET Kerndiagnose.
Microsoft.AspNetCore.DataProtection	Welke sleutels werden overwogen, gevonden en gebruikt.
Microsoft.AspNetCore.HostFiltering	Hosts zijn toegestaan.
Microsoft.AspNetCore.Hosting	Hoe lang HTTP-aanvragen namen om te voltooien en op welk tijdstip ze zijn gestart. Welke hosting-opstartassembly's zijn geladen.
Microsoft.AspNetCore.Mvc	MVC en Razor diagnostiek. Modelbinding, filteruitvoering, compilatie weergeven, actieselectie.
Microsoft.AspNetCore.Routing	Overeenkomende informatie routeren.
Microsoft.AspNetCore.Server	Verbindingsstart, stop en actief blijven antwoorden. HTTPS-certificaatgegevens.
Microsoft.AspNetCore.StaticFiles	Bestanden worden geleverd.
Microsoft.EntityFrameworkCore	Algemene diagnostische gegevens van Entity Framework Core. Databaseactiviteit en -configuratie, wijzigingsdetectie, migraties.

Als u meer categorieën in het consolevenster wilt weergeven, stelt u appsettings.Development.json het volgende in:

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

Logboekbereiken

Een bereik kan een set logische bewerkingen groeperen. 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:

• Console
• AzureAppServicesFile en AzureAppServicesBlob

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

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    TodoItem todoItem;
    var transactionId = Guid.NewGuid().ToString();
    using (_logger.BeginScope(new List<KeyValuePair<string, object>>
        {
            new KeyValuePair<string, object>("TransactionId", transactionId),
        }))
    {
        _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

        todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            _logger.LogWarning(MyLogEvents.GetItemNotFound, 
                "Get({Id}) NOT FOUND", id);
            return NotFound();
        }
    }

    return ItemToDTO(todoItem);
}

Ingebouwde providers voor logboekregistratie

ASP.NET Core bevat de volgende providers voor logboekregistratie als onderdeel van het gedeelde framework:

• Console
• Debug
• EventSource
• EventLog

De volgende providers voor logboekregistratie worden geleverd door Microsoft, maar niet als onderdeel van het gedeelde framework. Ze moeten worden geïnstalleerd als een extra NuGet.

• AzureAppServicesFile en AzureAppServicesBlob
• ApplicationInsights

ASP.NET Core bevat geen logboekregistratieprovider voor het schrijven van logboeken naar bestanden. Als u logboeken naar bestanden wilt schrijven vanuit een ASP.NET Core-app, kunt u overwegen een externe logboekregistratieprovider te gebruiken.

Zie stdoutASP.NET Core Module (ANCM) voor IIS oplossen voor informatie over logboekregistratie en fouten opsporen in logboekregistratie met de ASP.NET Core-module.

Console

De Console provider registreert uitvoer naar de console. Voor meer informatie over het weergeven van Console logboeken tijdens de ontwikkeling, zie Uitvoer van dotnet run en Visual Studio.

Debug

De Debug provider schrijft logboekuitvoer met behulp van de System.Diagnostics.Debug klasse. Oproepen aan System.Diagnostics.Debug.WriteLine om te schrijven naar de Debug provider.

In Linux is de locatie van het Debug providerlogboek distributieafhankelijk en kan dit een van de volgende zijn:

• /var/log/message
• /var/log/syslog

Bron van gebeurtenis

De EventSource provider schrijft naar een platformoverschrijdende gebeurtenisbron met de naam Microsoft-Extensions-Logging. In Windows gebruikt de provider ETW-.

hulpprogramma's voor dotnet-tracering

Het dotnet-trace hulpprogramma is een platformoverschrijdend CLI-hulpprogramma waarmee .NET Core-traceringen van een actief proces kunnen worden verzameld. Het hulpprogramma verzamelt Microsoft.Extensions.Logging.EventSource providergegevens met behulp van een LoggingEventSource.

Zie dotnet-trace voor installatie-instructies.

Gebruik de dotnet-traceringsprogramma's om een tracering van een app te verzamelen:

1. Voer de app uit met de dotnet run opdracht.

2. Bepaal de proces-id (PID) van de .NET Core-app:

   dotnet trace ps
   

   Zoek de PID voor het proces met dezelfde naam als de assembly van de app.

3. Voer de dotnet trace opdracht uit.

   Algemene opdrachtsyntaxis:

   dotnet trace collect -p {PID} 
       --providers Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
           :FilterSpecs=\"
               {Logger Category 1}:{Category Level 1};
               {Logger Category 2}:{Category Level 2};
               ...
               {Logger Category N}:{Category Level N}\"
   

   Wanneer u een PowerShell-opdrachtshell gebruikt, plaatst u de --providers waarde tussen enkele aanhalingstekens ('):

   dotnet trace collect -p {PID} 
       --providers 'Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
           :FilterSpecs=\"
               {Logger Category 1}:{Category Level 1};
               {Logger Category 2}:{Category Level 2};
               ...
               {Logger Category N}:{Category Level N}\"'
   

   Voeg op niet-Windows-platforms de -f speedscope optie toe om de indeling van het uitvoertraceringsbestand te wijzigen in speedscope.

   In de volgende tabel wordt het trefwoord gedefinieerd:

   Keyword	Description
   1	Logboekmeta-gebeurtenissen over de LoggingEventSource. Er worden geen gebeurtenissen vastgelegd van ILogger.
   2	Hiermee wordt de Message-gebeurtenis ingeschakeld wanneer ILogger.Log() wordt aangeroepen. Biedt informatie op een programmatische (niet opgemaakte) manier.
   4	Hiermee wordt de FormatMessage-gebeurtenis ingeschakeld wanneer ILogger.Log() wordt aangeroepen. Biedt de opgemaakte tekenreeksversie van de informatie.
   8	Hiermee wordt de MessageJson-gebeurtenis ingeschakeld wanneer ILogger.Log() wordt aangeroepen. Geeft een JSON-weergave van de argumenten.

   De volgende tabel bevat de providerniveaus:

   Providerniveau	Description
   0	LogAlways
   1	Critical
   2	Error
   3	Warning
   4	Informational
   5	Verbose

   De parsering voor een categorieniveau kan een tekenreeks of een getal zijn:

   Categorie benoemde waarde	Numerieke waarde
   Trace	0
   Debug	1
   Information	2
   Warning	3
   Error	4
   Critical	5

   Het niveau van de provider en het categorieniveau:

   • Zijn in omgekeerde volgorde.
   • De tekenreeksconstanten zijn niet allemaal identiek.

   Als er geen FilterSpecs zijn opgegeven, probeert de EventSourceLogger implementatie het providerniveau te converteren naar een categorieniveau en wordt deze toegepast op alle categorieën.

   Providerniveau	Categorieniveau
   Verbose(5)	Debug(1)
   Informational(4)	Information(2)
   Warning(3)	Warning(3)
   Error(2)	Error(4)
   Critical(1)	Critical(5)

   Als FilterSpecs worden verstrekt, wordt voor elke categorie die in de lijst is opgenomen het daar gecodeerde categorieniveau gebruikt, terwijl alle andere categorieën worden uitgefilterd.

   In de volgende voorbeelden wordt ervan uitgegaan:

   • Een app is actief en voert een oproep naar logger.LogDebug("12345") uit.
   • De proces-id (PID) is ingesteld via set PID=12345, waar 12345 is de werkelijke PID.

   Kijk eens naar de volgende opdracht:

   dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5
   

   De bovenstaande opdracht:

   • Registreert foutopsporingsberichten.
   • Past geen FilterSpecs.
   • Specificeert niveau 5 dat de categorie Debug toewijst.

   Kijk eens naar de volgende opdracht:

   dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:5\"
   

   De bovenstaande opdracht:

   • Registreert geen foutopsporingsberichten omdat categorieniveau 5 is Critical.
   • Biedt een FilterSpecs.

   Met de volgende opdracht worden foutopsporingsberichten vastgelegd omdat categorieniveau 1 aangeeft Debug.

   dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:1\"
   

   Met de volgende opdracht worden foutopsporingsberichten vastgelegd omdat de categorie aangeeft Debug.

   dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:Debug\"
   

   FilterSpecs-vermeldingen voor {Logger Category} en {Category Level} vertegenwoordigen aanvullende logboekfiltercondities. Scheid FilterSpecs vermeldingen met het ; puntkommateken.

   Voorbeeld van een Windows-opdrachtprompt:

   dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:2:FilterSpecs=\"Microsoft.AspNetCore.Hosting*:4\"
   

   Met de voorgaande opdracht wordt het volgende geactiveerd:

   • De logboekregistratie van de gebeurtenisbron voor het produceren van opgemaakte tekenreeksen (4) voor fouten (2).
   • Microsoft.AspNetCore.Hosting logboekregistratie op logboekregistratieniveau Informational (4).

4. Stop de dotnet trace-tooling door op Enter of Ctrl+C te drukken.

   De tracering wordt opgeslagen met de naam trace.nettrace in de map waarin de dotnet trace opdracht wordt uitgevoerd.

5. Open de trace met Perfview. Open het trace.nettrace-bestand en verken de traceringsevenementen.

Als de app de host niet opbouwt met CreateDefaultBuilder, voegt u de gebeurtenisbronprovider toe aan de logconfiguratie van de app.

Voor meer informatie, zie:

• Tracering voor prestatieanalyse-hulpprogramma (dotnet-trace) (.NET Core-documentatie)
• Tracering voor hulpprogramma voor prestatieanalyse (dotnet-trace) (documentatie voor dotnet/diagnostics GitHub-opslagplaats)
• LoggingEventSource-klasse (.NET API-browser)
• EventLevel
• LoggingEventSource-referentiebron (3.0): als u een referentiebron voor een andere versie wilt verkrijgen, wijzigt u de vertakking in release/{Version}, waar {Version} is de versie van ASP.NET Core die u wilt gebruiken.
• Perfview: handig voor het weergeven van gebeurtenisbrontraceringen.

Perfview

Gebruik het hulpprogramma PerfView om logboeken te verzamelen en weer te geven. Er zijn andere hulpprogramma's voor het weergeven van ETW-logboeken, maar PerfView biedt de beste ervaring voor het werken met de ETW-gebeurtenissen die worden verzonden door ASP.NET Core.

Als u PerfView wilt configureren voor het verzamelen van gebeurtenissen die door deze provider zijn geregistreerd, voegt u de tekenreeks *Microsoft-Extensions-Logging toe aan de lijst Aanvullende providers . Mis het * aan het begin van de tekenreeks niet.

Windows EventLog

De EventLog-provider verzendt logboekuitvoer naar het Windows-gebeurtenislogboek. In tegenstelling tot de andere providers erft de EventLog provider niet de standaardinstellingen voor een niet-provider. Als EventLog er geen logboekinstellingen zijn opgegeven, worden deze standaard ingesteld op LogLevel.Warning.

Als u gebeurtenissen wilt vastleggen die lager zijn dan LogLevel.Warning, stelt u het logboekniveau expliciet in. In het volgende voorbeeld wordt het standaardlogboekniveau van het gebeurtenislogboek ingesteld op LogLevel.Information:

"Logging": {
  "EventLog": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

AddEventLog-overbelasting kan EventLogSettingsdoorgeven. Als null niet is opgegeven, worden de volgende standaardinstellingen gebruikt:

• LogName: "Toepassing"
• SourceName: '.NET Runtime'
• MachineName: de naam van de lokale computer wordt gebruikt.

Met de volgende code wordt de SourceName gewijzigd van de standaardwaarde van ".NET Runtime" in MyLogs:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
            {
                logging.AddEventLog(eventLogSettings =>
                {
                    eventLogSettings.SourceName = "MyLogs"; 
                });
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Azure App Service

Het Microsoft.Extensions.Logging.AzureAppServices providerpakket schrijft logboeken naar tekstbestanden in het bestandssysteem van een Azure App Service-app en naar blobopslag in een Azure Storage-account.

Het providerpakket is niet opgenomen in het gedeelde framework. Als u de provider wilt gebruiken, voegt u het providerpakket toe aan het project.

Als u providerinstellingen wilt configureren, gebruikt u AzureFileLoggerOptions en AzureBlobLoggerOptions, zoals wordt weergegeven in het volgende voorbeeld:

public class Scopes
{
    public class Program
    {
        public static void Main(string[] args)
        {
            CreateHostBuilder(args).Build().Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
                .ConfigureServices(serviceCollection => serviceCollection
                    .Configure<AzureFileLoggerOptions>(options =>
                    {
                        options.FileName = "azure-diagnostics-";
                        options.FileSizeLimit = 50 * 1024;
                        options.RetainedFileCountLimit = 5;
                    })
                    .Configure<AzureBlobLoggerOptions>(options =>
                    {
                        options.BlobName = "log.txt";
                    }))
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
    }
}

Wanneer de app is geïmplementeerd in Azure App Service, worden de instellingen in de App Service-logboeken sectie van de pagina App Service van Azure Portal gebruikt. Wanneer de volgende instellingen worden bijgewerkt, worden de wijzigingen onmiddellijk van kracht zonder dat de app opnieuw hoeft te worden opgestart of opnieuw hoeft te worden geïmplementeerd.

• Toepassingslogboekregistratie (bestandssysteem)
• Logboekregistratie van toepassingen (blob)

De standaardlocatie voor logboekbestanden bevindt zich in de map D:\home\LogFiles\Application en de standaardbestandsnaam is diagnostics-yyyymmdd.txt. De standaardlimiet voor de bestandsgrootte is 10 MB en het standaard maximum aantal bewaarde bestanden is 2. De standaard-blobnaam is {app-name}{timestamp}/jjjj/mm/dd/hh/{guid}-applicationLog.txt.

Deze provider registreert alleen wanneer het project wordt uitgevoerd in de Azure-omgeving.

Azure-logboekstreaming

Azure-logboekstreaming biedt ondersteuning voor het weergeven van logboekactiviteiten in realtime vanuit:

• De app-server
• De webserver
• Tracering van mislukte aanvragen

Om Azure-logstreaming te configureren:

• Navigeer naar de App Service-logboeken pagina vanaf de portalpagina van de app.
• Stel application logging (bestandssysteem) in op On.
• Kies het logboek niveau. Deze instelling is alleen van toepassing op Azure-logboekstreaming.

Navigeer naar de pagina Logstream om logs weer te geven. De vastgelegde berichten worden vastgelegd met de ILogger interface.

Azure Application Insights

Het Microsoft.Extensions.Logging.ApplicationInsights providerpakket schrijft logboeken naar Azure Application Insights-. Application Insights is een service die een web-app bewaakt en hulpprogramma's biedt voor het opvragen en analyseren van de telemetriegegevens. Als u deze provider gebruikt, kunt u uw logboeken opvragen en analyseren met behulp van de Application Insights-hulpprogramma's.

De logboekregistratieprovider is opgenomen als een afhankelijkheid van Microsoft.ApplicationInsights.AspNetCore. Dit is het pakket dat alle beschikbare telemetrie voor ASP.NET Core biedt. Als u dit pakket gebruikt, hoeft u het providerpakket niet te installeren.

Het microsoft.ApplicationInsights.Web-pakket is bedoeld voor ASP.NET 4.x, niet ASP.NET Core.

Zie de volgende bronnen voor meer informatie:

• Overzicht van Application Insights
• Application Insights voor ASP.NET Core-toepassingen : begin hier als u het volledige scala aan Application Insights-telemetrie wilt implementeren, samen met logboekregistratie.
• ApplicationInsightsLoggerProvider voor .NET Core ILogger-logboeken: begin hier als u de logboekregistratieprovider wilt implementeren zonder de rest van application Insights-telemetrie.
• Application Insights-logboekregistratieadapters.
• Installeer, configureer en initialiseer de interactieve zelfstudie over de Application Insights SDK .

Externe logboekregistratieproviders

Frameworks voor logboekregistratie van derden die werken met ASP.NET Core:

• elmah.io (GitHub-opslagplaats)
• Gelf (GitHub-opslagplaats)
• JSNLog- (GitHub-opslagplaats)
• KissLog.net (GitHub-opslagplaats)
• Log4Net- (GitHub-opslagplaats)
• NLog (GitHub-opslagplaats)
• PLogger (GitHub-opslagplaats)
• Sentry (GitHub-opslagplaats)
• Serilog (GitHub-opslagplaats)
• Stackdriver (Github-opslagplaats)

Sommige frameworks van derden kunnen semantische logboekregistratie uitvoeren, ook wel gestructureerde logboekregistratie genoemd.

Het gebruik van een framework van derden is vergelijkbaar met het gebruik van een van de ingebouwde providers:

1. Voeg een NuGet-pakket toe aan uw project.
2. Roep een ILoggerFactory extensiemethode aan die wordt geleverd door het logboekregistratieframework.

Zie de documentatie van elke provider voor meer informatie. Externe logboekregistratieproviders worden niet ondersteund door Microsoft.

Niet-gehoste console-app

Zie het bestand van de Program.cs (achtergrondtaken met gehoste services in ASP.NET Core) voor een voorbeeld van het gebruik van de algemene host in een niet-webconsole-app.

Logboekcode voor apps zonder Generic Host verschilt in de manier waarop providers worden toegevoegd en logboekregistraties worden gemaakt.

Providers voor logboekregistratie

Roep in een niet-hostconsole-app de extensiemethode van Add{provider name} de provider aan tijdens het maken van een LoggerFactory:

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

Logboeken maken

Als u logboeken wilt maken, gebruikt u een ILogger<TCategoryName> object. Gebruik de LoggerFactory om een ILogger te maken.

In het volgende voorbeeld wordt een logboekregistratie gemaakt met LoggingConsoleApp.Program als categorie.

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

In het volgende voorbeeld wordt de logger gebruikt om logboeken met Information als het niveau te maken. Het logboekniveau geeft de ernst van de vastgelegde gebeurtenis aan.

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

Niveaus en categorieën worden uitgebreid beschreven in dit document.

Logboek tijdens de bouw van de host

Logboekregistratie tijdens het bouwen van de host wordt niet rechtstreeks ondersteund. Er kan echter een afzonderlijke logger worden gebruikt. In het volgende voorbeeld wordt een Serilog-logger gebruikt om gegevens vast te leggen CreateHostBuilder. AddSerilog maakt gebruik van de statische configuratie die is opgegeven in Log.Logger:

using System;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var builtConfig = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .AddCommandLine(args)
            .Build();

        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
            .WriteTo.File(builtConfig["Logging:FilePath"])
            .CreateLogger();

        try
        {
            return Host.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    services.AddRazorPages();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    config.AddConfiguration(builtConfig);
                })
                .ConfigureLogging(logging =>
                {   
                    logging.AddSerilog();
                })
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host builder error");

            throw;
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }
}

Een service configureren die afhankelijk is van ILogger

Constructorinjectie van een logger in Startup werkt in eerdere versies van ASP.NET Core omdat er een afzonderlijke DI-container wordt gemaakt voor de Web Host. Zie de breaking change aankondiging voor de Generic Host voor informatie over waarom er slechts één container wordt aangemaakt.

Als u een service wilt configureren die afhankelijk is van ILogger<T>, gebruikt u constructorinjectie of geeft u een fabrieksmethode op. De factorymethode wordt alleen aanbevolen als er geen andere optie is. Denk bijvoorbeeld aan een service die een ILogger<T> exemplaar van DI nodig heeft:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddRazorPages();

    services.AddSingleton<IMyService>((container) =>
    {
        var logger = container.GetRequiredService<ILogger<MyService>>();
        return new MyService() { Logger = logger };
    });
}

De voorgaande gemarkeerde code is een Func<T,TResult> code die wordt uitgevoerd wanneer de DI-container voor het eerst een exemplaar MyServicevan moet maken. U hebt op deze manier toegang tot alle geregistreerde services.

Logboeken maken in Main

De volgende code logt in Main door een ILogger exemplaar vanuit DI te verkrijgen nadat de host is opgebouwd.

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

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

    host.Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Logboeken maken bij opstarten

Met de volgende code worden logboeken geschreven in Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env,
                      ILogger<Startup> logger)
{
    if (env.IsDevelopment())
    {
        logger.LogInformation("In Development.");
        app.UseDeveloperExceptionPage();
    }
    else
    {
        logger.LogInformation("Not Development.");
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapRazorPages();
    });
}

Het schrijven van logboeken vóór voltooiing van de DI-containerinstallatie in de Startup.ConfigureServices methode wordt niet ondersteund:

• Loggerinjectie in de Startup constructor wordt niet ondersteund.
• Loggerinjectie in de Startup.ConfigureServices methodehandtekening wordt niet ondersteund

De reden voor deze beperking is dat logboekregistratie afhankelijk is van DI en configuratie, wat weer afhankelijk is van DI. De DI-container wordt pas ingesteld wanneer ConfigureServices is voltooid.

Zie voor informatie over het configureren van een service die afhankelijk is van ILogger<T> of waarom constructorinjectie van een logger in Startup in eerdere versies werkte, Een service configureren die afhankelijk is van ILogger

Geen asynchrone logboekregistratiemethoden

Logboekregistratie moet zo snel zijn dat het de prestatiekosten van asynchrone code niet waard is. Als een logboekgegevensarchief 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. Zie dit GitHub-probleem voor meer informatie.

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. Bijvoorbeeld, de File Configuration Provider laadt standaard de loggingconfiguratie opnieuw. Als de configuratie in de code wordt gewijzigd terwijl een app wordt uitgevoerd, kan de app IConfigurationRoot.Reload aanroepen om de logconfiguratie van de app bij te werken.

ILogger en ILoggerFactory

ILogger<TCategoryName> en ILoggerFactory interfaces en implementaties zijn opgenomen in de .NET Core SDK. Ze zijn ook beschikbaar in de volgende NuGet-pakketten:

• De interfaces bevinden zich in Microsoft.Extensions.Logging.Abstractions.
• De standaard implementaties bevinden zich in Microsoft.Extensions.Logging.

Regels voor logboekfilters toepassen in code

De voorkeursmethode voor het instellen van logboekfilterregels is het gebruik van Configuratie.

In het volgende voorbeeld ziet u hoe u filterregels registreert in code:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
               logging.AddFilter("System", LogLevel.Debug)
                  .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)
                  .AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace))
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

logging.AddFilter("System", LogLevel.Debug) hiermee geeft u het System categorie- en logboekniveau Debugop. Het filter wordt toegepast op alle providers omdat er geen specifieke provider is geconfigureerd.

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

• De Debug logboekregistratieprovider.
• Logboekniveau Information en hoger.
• Alle categorieën beginnen met "Microsoft".

Automatisch logboekbereik met SpanId, TraceId en ParentId

De logbibliotheken maken impliciet een scopeobject met SpanId, TraceId, en ParentId. Dit gedrag wordt geconfigureerd via ActivityTrackingOptions.

  var loggerFactory = LoggerFactory.Create(logging =>
  {
      logging.Configure(options =>
      {
          options.ActivityTrackingOptions = ActivityTrackingOptions.SpanId
                                              | ActivityTrackingOptions.TraceId
                                              | ActivityTrackingOptions.ParentId;
      }).AddSimpleConsole(options =>
      {
          options.IncludeScopes = true;
      });
  });

Als de traceparent http-verzoekheader is ingesteld, toont ParentId in het logboekbereik de W3C parent-id van de inkomende traceparent header en geeft SpanId in het logboekbereik de bijgewerkte parent-id voor de volgende uitgaande stap/span weer. Zie Muteren van het traceparent-veld voor meer informatie.

Maak een aangepaste logger

Zie Een aangepaste logboekregistratieprovider implementeren in .NET om een aangepaste logboekregistratie te maken.

Aanvullende bronnen

• Logboekregistratie met hoge prestaties
• Logfouten moeten worden geregistreerd in de github.com/dotnet/runtime/ opslagplaats.
• ASP.NET Core Blazor logboekregistratie