Loggning i .NET och ASP.NET Core

Av Kirk Larkin, Juergen Gutsch och Rick Anderson

I den här artikeln beskrivs loggning i .NET när det gäller ASP.NET Core-appar. Detaljerad information om loggning i .NET finns i Loggning i .NET.

För loggningsvägledningBlazor, som kompletterar eller ersätter vägledningen i den här noden, se ASP.NET Core-loggningBlazor.

Loggningsproviders

Loggningsproviders lagrar loggar, förutom providern Console som visar loggar. Azure Application Insights-providern lagrar till exempel loggar i Azure Application Insights. Flera leverantörer kan aktiveras.

Standard ASP.NET Core-webbappmallar anropar WebApplication.CreateBuilder, vilket lägger till följande loggningsproviders:

• Console
• Debug
• EventSource
• EventLog: Endast 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();

Föregående kod visar filen Program.cs som skapats med ASP.NET Core-webbappmallar. Nästa avsnitt innehåller exempel baserat på ASP.NET Core-webbappmallar.

Följande kod åsidosätter standarduppsättningen loggningsleverantörer som lagts till av WebApplication.CreateBuilder:

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();

Du kan också skriva föregående loggningskod på följande sätt:

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

Ytterligare leverantörer finns i:

• Inbyggda loggningsproviders
• tredjepartsloggningsleverantörer.

Skapa loggar

Om du vill skapa loggar använder du ett ILogger<TCategoryName> objekt från beroendeinmatning (DI).

Följande exempel:

• Skapar en logger, ILogger<AboutModel>, som använder en loggkategori med det fullständigt kvalificerade namnet av typen AboutModel. Loggkategorin är en sträng som är associerad med varje logg.
• Anropar LogInformation för att logga på Information nivån. Loggnivån anger allvarlighetsgraden för den loggade händelsen.

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

Nivåer och kategorier förklaras mer detaljerat senare i det här dokumentet.

Information om Blazorfinns i ASP.NET Core-loggningBlazor.

Konfigurera loggning

Loggningskonfiguration anges ofta i Logging-avsnittet av appsettings.{ENVIRONMENT}.json-filer, där {ENVIRONMENT}-platshållaren är miljön. Följande appsettings.Development.json fil genereras av ASP.NET Core-webbappmallar:

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

I JSON-koden ovan:

• Kategorierna "Default" och "Microsoft.AspNetCore" anges.
• Kategorin "Microsoft.AspNetCore" gäller för alla kategorier som börjar med "Microsoft.AspNetCore". Den här inställningen gäller till exempel för "Microsoft.AspNetCore.Routing.EndpointMiddleware" kategorin.
• Kategorin "Microsoft.AspNetCore" loggar på loggnivå Warning och högre.
• En specifik loggprovider har inte angetts, så LogLevel den gäller för alla aktiverade loggningsproviders förutom Windows EventLog.

Egenskapen Logging kan ha både LogLevel och egenskaper för loggprovidern. LogLevel Anger den lägsta nivå som ska loggas för valda kategorier. I den föregående JSON anges loggnivåer för Information och Warning. LogLevel anger loggens allvarlighetsgrad och sträcker sig från 0 till 6:

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

När en LogLevel har angetts aktiveras loggning för meddelanden på den angivna nivån och högre. I föregående JSON Default loggas kategorin för Information och högre. Till exempel loggas Information, Warning, Error och Critical meddelanden. Om inget LogLevel anges, ställs loggning in på Information-nivån som standard. Mer information finns i Loggnivåer.

En provideregenskap kan ange en LogLevel egenskap. LogLevel under en leverantör anger nivåer för loggning för den leverantören och åsidosätter de logginställningar som inte är för leverantörer. Överväg följande appsettings.json fil:

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

Inställningar i Logging.{PROVIDER NAME}.LogLevel åsidosätter inställningar i Logging.LogLevel, där {PROVIDER NAME}-platshållaren är namnet på leverantören. I föregående JSON Debug är providerns standardloggnivå inställd Informationpå :

Logging:Debug:LogLevel:Default:Information

Föregående inställning anger Information loggnivån för varje Logging:Debug: kategori utom Microsoft.Hosting. När en specifik kategori visas åsidosätter den specifika kategorin standardkategorin. I föregående JSON åsidosätter Logging:Debug:LogLevel kategorierna "Microsoft.Hosting" och "Default" inställningarna i Logging:LogLevel.

Minsta loggnivå kan anges för något av följande:

• Specifika leverantörer: Till exempel Logging:EventSource:LogLevel:Default:Information
• Specifika kategorier: Till exempel Logging:LogLevel:Microsoft:Warning
• Alla leverantörer och alla kategorier: Logging:LogLevel:Default:Warning

Loggar under miniminivån är inte:

• Skickas till providern.
• Loggas eller visas.

Om du vill utelämna alla loggar anger du LogLevel.None. LogLevel.None har värdet 6, vilket är högre än LogLevel.Critical (5).

Om en leverantör stöder loggomfattningar anger IncludeScopes om de är aktiverade. Mer information finns i loggområden.

Följande appsettings.json fil innehåller alla providers som är aktiverade som standard:

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

I föregående exempel:

• Kategorierna och nivåerna är inte föreslagna värden. Exemplet tillhandahålls för att visa alla standardprovidrar.
• Inställningar i Logging.{PROVIDER NAME}.LogLevel åsidosätter inställningar i Logging.LogLevel, där {PROVIDER NAME}-platshållaren är namnet på leverantören. Nivån i Debug.LogLevel.Default åsidosätter till exempel nivån i LogLevel.Default.
• Varje standard-provider-alias används. Varje provider definierar ett alias som kan användas i konfigurationen i stället för det fullständigt kvalificerade typnamnet. De inbyggda providersaliasen är:
  • Console
  • Debug
  • EventSource
  • EventLog
  • AzureAppServicesFile
  • AzureAppServicesBlob
  • ApplicationInsights

Logga in Program.cs

I följande exempel anropas Builder.WebApplication.Logger i Program.cs och loggar informationsmeddelanden:

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();

Följande exempel anropar AddConsole i Program.cs och loggar slutpunkten /Test:

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();

I följande exempel anropas AddSimpleConsole i Program.cs. Färgutdata inaktiveras, och slutpunkten loggas /Test.

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();

Ange loggnivå efter kommandorad, miljövariabler och annan konfiguration

Loggnivån kan anges av någon av konfigurationsprovidrar.

Den : avgränsaren fungerar inte med hierarkiska nycklar för miljövariabler på alla plattformar. Till exempel stöds inte :-avgränsaren av Bash. Det dubbla understrecket, __, är:

• Stöds av alla plattformar.
• Ersätts automatiskt av ett kolon, :.

Följande kommandon:

• Ange miljönyckeln Logging:LogLevel:Microsoft till värdet Information för i Windows.
• Testa inställningarna när du använder en app som skapats med ASP.NET Core-webbprogrammallar. Kommandot dotnet run måste köras i projektkatalogen när du har använt set.

set Logging__LogLevel__Microsoft=Information
dotnet run

Föregående miljöinställning:

• Anges endast i processer som startats från det kommandofönster som de angavs i.
• Läses inte av webbläsare som startas med Visual Studio.

Följande setx-kommando anger även miljönyckeln och värdet i Windows. set Till skillnad från setxsparas inställningarna. Växeln /M anger variabeln i systemmiljön. Om /M inte används anges en användarmiljövariabel.

setx Logging__LogLevel__Microsoft Information /M

Överväg följande appsettings.json fil:

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

Följande kommando anger föregående konfiguration i miljön:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

I Azure App Service väljer du Ny programinställning på sidan Konfiguration>inställningar. Azure App Service-programinställningar är:

• Krypterad i vila och överförs via en krypterad kanal.
• Exponeras som miljövariabler.

Mer information finns i Azure Apps: Åsidosätt appkonfiguration med hjälp av Azure-portalen.

Mer information om hur du ställer in ASP.NET Grundläggande konfigurationsvärden med hjälp av miljövariabler finns i miljövariabler. Information om hur du använder andra konfigurationskällor, inklusive kommandoraden, Azure Key Vault, Azure App Configuration, andra filformat med mera finns i Konfiguration i ASP.NET Core.

Så här tillämpas filtreringsregler

När ett ILogger<TCategoryName> objekt skapas, väljer det ILoggerFactory objektet en enda regel per provider som ska tillämpas på den loggaren. Alla meddelanden som skrivs av en ILogger instans filtreras baserat på de valda reglerna. Den mest specifika regeln för varje provider och kategoripar väljs från de tillgängliga reglerna.

Följande algoritm används för varje provider när en ILogger skapas för en viss kategori:

• Välj alla regler som matchar providern eller dess alias. Om ingen matchning hittas väljer du alla regler med en tom leverantör.
• Från resultatet av föregående steg väljer du regler med det längsta matchande kategoriprefixet. Om ingen matchning hittas väljer du alla regler som inte anger en kategori.
• Om flera regler har valts tar du den sista .
• Om inga regler har valts använder du MinimumLevel.

Logga utdata från dotnet run och Visual Studio

Loggar som skapats med standardloggningsprovidrar visas:

• I Visual Studio
  • I fönstret för felsökningsutdata under felsökning.
  • I ASP.NET Core-webbserverns fönster.
• I konsolfönstret när appen körs med dotnet run.

Loggar som börjar med "Microsoft"-kategorier kommer från .NET. .NET och programkod använder samma loggnings-API och -providers.

Loggkategori

När ett ILogger objekt skapas anges en kategori . Den kategorin ingår i varje loggmeddelande som skapas av den instansen av ILogger. Kategoristrängen är godtycklig, men konventionen är att använda det fullständigt kvalificerade klassnamnet. I en kontrollant kan till exempel namnet vara "TodoApi.Controllers.TodoController". ASP.NET Core-webbappar använder ILogger<T> för att automatiskt hämta en ILogger-instans som använder det fullständigt kvalificerade typnamnet T som kategori.

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.");
    }
}

Om ytterligare kategorisering önskas är konventionen att använda ett hierarkiskt namn genom att lägga till en underkategori i det fullständigt kvalificerade klassnamnet och uttryckligen ange kategorin med hjälp av 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.");
    }

Att anropa CreateLogger med ett fast namn kan vara användbart när det används i flera metoder så att händelserna kan ordnas efter kategori.

ILogger<T> motsvarar anrop CreateLogger med det fullständigt kvalificerade typnamnet T.

Loggnivå

I följande tabell visas LogLevel värdena, metoden för bekvämlighetstillägg Log{LogLevel} och den föreslagna användningen:

LogLevel	Value	Method	Description
Trace	0	LogTrace	Innehåller de mest detaljerade meddelandena. Dessa meddelanden kan innehålla känsliga appdata. Dessa meddelanden är inaktiverade som standard och bör inte aktiveras i produktion.
Debug	1	LogDebug	För felsökning och utveckling. Använd med försiktighet i produktionen på grund av den höga volymen.
Information	2	LogInformation	Spårar appens allmänna flöde. Kan ha ett långsiktigt värde.
Warning	3	LogWarning	För onormala eller oväntade händelser. Innehåller vanligtvis fel eller villkor som inte gör att appen misslyckas.
Error	4	LogError	För fel och undantag som inte kan hanteras. Dessa meddelanden anger ett fel i den aktuella åtgärden eller begäran, inte ett appomfattande fel.
Critical	5	LogCritical	För haverier som kräver omedelbar uppmärksamhet. Exempel: scenarier för dataförlust, slut på diskutrymme.
None	6		Anger att en loggningskategori inte ska skriva meddelanden.

I föregående tabell LogLevel visas från lägsta till högsta allvarlighetsgrad.

Metodens Log första parameter, LogLevel, anger loggens allvarlighetsgrad. I stället för att anropa Log(LogLevel, ...), kallar de flesta utvecklare tilläggsmetoderna Log{LOG LEVEL}, där {LOG LEVEL} platshållaren är loggnivån. Följande två loggningsanrop är till exempel funktionellt likvärdiga och skapar samma logg:

[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 är händelse-ID:t. MyLogEvents är en del av exempelappen och visas i avsnittet Logghändelse-ID .

MyDisplayRouteInfo och ToCtxString tillhandahålls av NuGet-paketet Rick.Docs.Samples.RouteInfo . Metoderna Controller och Razor Page visar ruttinformation.

Följande kod skapar Information och Warning loggar:

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

I föregående kod är den första Log{LOG LEVEL} parameternMyLogEvents.GetItemlogghändelse-ID. Den andra parametern är en meddelandemall med platshållare för argumentvärden som tillhandahålls av de återstående metodparametrarna. Metodparametrarna förklaras i meddelandemallsavsnittet senare i det här dokumentet.

Anropa lämplig Log{LOG LEVEL} metod för att styra hur mycket loggutdata som skrivs till ett visst lagringsmedium. Till exempel:

• I produktion:
  • Loggning på Tracenivåerna , Debugeller Information ger en stor mängd detaljerade loggmeddelanden. För att kontrollera kostnader och inte överskrida datalagringsgränserna, logga meddelanden på Trace, Debug eller Information nivå till ett datalager med hög volym och låg kostnad. Överväg att begränsa Trace, Debug eller Information till specifika kategorier.
  • Loggning på Warning genom Critical nivåer bör ge få loggmeddelanden.
    • Kostnader och lagringsgränser är vanligtvis inte ett problem.
    • Få loggar ger mer flexibilitet i val av datalager.
• Under utveckling:
  • Ställ in på Warning.
  • Lägg till Trace, Debugeller Information meddelanden vid felsökning. Om du vill begränsa utdata anger du Trace, Debugeller Information endast för de kategorier som undersöks.

ASP.NET Core skriver loggar för ramverkshändelser. Tänk till exempel på loggutdata för:

• En Razor Pages-app som skapats med mallarna ASP.NET Core.
• Loggning inställd på Logging:Console:LogLevel:Microsoft:Information.
• Navigering till sidan Privacy :

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

Följande JSON-uppsättningar Logging:Console:LogLevel:Microsoft:Information:

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

Logghändelse-ID

Varje logg kan ange ett händelse-ID. Exempelappen MyLogEvents använder klassen för att definiera händelse-ID:t:

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

Ett händelse-ID associerar en uppsättning händelser. Till exempel kan alla loggar som är relaterade till att visa en lista med objekt på en sida vara 1001.

Loggningsprovidern kan lagra händelse-ID i ett ID-fält, i loggningsmeddelandet eller inte alls. Felsökningsprovidern visar inte händelse-ID:t. Konsolprovidern visar händelse-ID:t inom hakparenteser efter kategorin:

info: TodoApi.Controllers.TodoItemsController[1002]
      Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
      Get(1) NOT FOUND

Vissa loggningsleverantörer lagrar händelse-ID:t i ett fält, vilket möjliggör filtrering på ID:t.

Loggmeddelandemall

Varje logg-API använder en meddelandemall. Meddelandemallen kan innehålla platshållare för vilka argument anges. Använd namn för platshållarna, inte siffror.

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

Ordningen på parametrarna, inte deras platshållarnamn, avgör vilka parametrar som används för att tillhandahålla platshållarvärden i loggmeddelanden. I följande kod är parameternamnen i fel ordning i platshållarna för meddelandemallen.

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

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

Parametrarna tilldelas dock till platshållarna i ordningen: apples, pears, . bananas Loggmeddelandet visar parametrarnas ordning:

Parameters: 1, 2, 3

Med den här metoden kan loggningsproviders implementera semantisk eller strukturerad loggning. Själva argumenten skickas till loggningssystemet, inte bara den formaterade meddelandemallen. Detta gör det möjligt för loggningsprovidrar att lagra parametervärdena som fält. Tänk till exempel på följande loggermetod:

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

När du till exempel loggar till Azure Table Storage:

• Varje Azure Table-entitet kan ha ID och RequestTime egenskaper.
• Tabeller med egenskaper förenklar frågor om loggade data. En fråga kan till exempel hitta alla loggar inom ett visst RequestTime intervall utan att behöva parsa tidsgränsen för textmeddelandet.

Loggfel

Loggningsmetoderna har överlagringar som tar en undantagsparameter:

[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 och ToCtxString tillhandahålls av NuGet-paketet Rick.Docs.Samples.RouteInfo . Metoderna Controller och Razor Page visar ruttinformation.

Undantagsloggning är providerspecifik.

Standardloggnivå

Om standardloggnivån inte har angetts är Informationstandardvärdet för loggnivå .

Tänk till exempel på följande webbapp:

• Skapat med ASP.NET webbappmallar.
• appsettings.json och appsettings.Development.json har tagits bort eller bytt namn.

Med den föregående konfigurationen genererar navigering till sekretess- eller startsidan många Trace, Debugoch Information meddelanden med Microsoft i kategorinamnet.

Följande kod anger standardloggnivån när standardloggnivån inte har angetts i konfigurationen:

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

I allmänhet bör loggnivåer anges i konfigurationen och inte i kod.

Filterfunktion

En filterfunktion anropas för alla leverantörer och kategorier som inte har regler tilldelade till sig genom konfiguration eller kod:

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

Föregående kod visar konsolloggar när kategorin innehåller Controller eller Microsoft och loggnivån är Information eller högre.

I allmänhet bör loggnivåer anges i konfigurationen och inte i kod.

ASP.NET Core-kategorier

Följande tabell innehåller vissa kategorier som används av ASP.NET Core.

Category	Notes
Microsoft.AspNetCore	Allmän ASP.NET Core-diagnostik.
Microsoft.AspNetCore.DataProtection	Vilka nycklar som övervägdes, hittades och användes.
Microsoft.AspNetCore.HostFiltering	Värdar tillåts.
Microsoft.AspNetCore.Hosting	Hur lång tid det tog att slutföra HTTP-begäranden och vilken tid de startade. Vilka hosting-startupkomponenter som laddades in.
Microsoft.AspNetCore.Mvc	MVC och Razor diagnostik. Modellbindning, filterkörning, visa kompilering, åtgärdsval.
Microsoft.AspNetCore.Routing	Ruttmatchningsinformation.
Microsoft.AspNetCore.Server	Starta, stoppa och håll igång svar. HTTPS-certifikatinformation.
Microsoft.AspNetCore.StaticFiles	Filer som hanteras.

Om du vill visa fler kategorier i konsolfönstret anger du appsettings.Development.json följande:

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

En lista över Entity Framework-kategorier finns i EF-meddelandekategorier.

Loggomfattningar

Ett omfång kan gruppera en uppsättning logiska åtgärder. Den här grupperingen kan användas för att koppla samma data till varje logg som skapas som en del av en uppsättning. Varje logg som skapas som en del av bearbetningen av en transaktion kan till exempel innehålla transaktions-ID:t.

Ett omfång:

• Är en IDisposable typ som returneras av BeginScope metoden.
• Varar tills den tas bort.

Följande leverantörer stödjer omfång:

• Console
• AzureAppServicesFile och AzureAppServicesBlob

Använd ett omfång genom att omsluta loggningsanrop i ett using block:

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

Inbyggda loggningstjänster

ASP.NET Core innehåller följande loggningsproviders som en del av det delade ramverket:

• Console
• Debug
• EventSource
• EventLog

Följande loggningsproviders levereras av Microsoft, men inte som en del av det gemensamma ramverket. De måste installeras som ytterligare NuGet-paket.

• AzureAppServicesFile och AzureAppServicesBlob
• ApplicationInsights

ASP.NET Core innehåller ingen loggningsprovider för att skriva loggar till filer. Om du vill skriva loggar till filer från en ASP.NET Core-app bör du överväga att använda en loggningsprovider från tredje part.

Information om stdout och felsökning av loggning med ASP.NET Core-modulen finns i Felsöka ASP.NET Core i Azure App Service och IIS ochASP.NET Core Module (ANCM) för IIS.

Console

Console-providerloggar utdata till konsolen. Mer information om hur du visar Console loggar under utveckling finns i Loggning av utdata från dotnet run och Visual Studio.

Debug

Providern Debug skriver loggutdata med hjälp System.Diagnostics.Debug av klassen . Anrop till System.Diagnostics.Debug.WriteLine skriver till Debug-providern.

I Linux Debug är providerloggplatsen distributionsberoende och kan vara något av följande:

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

Händelsekälla

EventSource-providern skriver till en plattformsoberoende händelsekälla med namnet Microsoft-Extensions-Logging. I Windows använder providern ETW-.

dotnet-trace-verktyg

Verktyget dotnet-trace är ett plattformsoberoende globalt CLI-verktyg som möjliggör insamling av .NET-spårningar av en process som körs. Verktyget samlar in Microsoft.Extensions.Logging.EventSource leverantörsdata med hjälp av en LoggingEventSource.

Installationsinstruktioner finns i dotnet-trace.

Använd verktygen dotnet-trace för att samla in en spårning från en app:

1. Kör appen med dotnet run kommandot .

2. Fastställa processidentifieraren (PID) för .NET-appen:

   dotnet-trace ps
   

   Leta reda på PID för den process som har samma namn som appens sammansättning.

3. dotnet-trace Kör kommandot .

   Allmän kommandosyntax:

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

   När du använder ett PowerShell-kommandoskal, inneslut --providers värdet med enkla citattecken ('):

   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}\"'
   

   På andra plattformar än Windows lägger du till -f speedscope alternativet för att ändra formatet för utdataspårningsfilen till speedscope.

   I följande tabell definieras nyckelordet:

   Keyword	Description
   1	Logga metahändelser om LoggingEventSource. Loggar inte händelser från ILogger.
   2	Aktiverar Message händelsen när ILogger.Log() anropas. Ger information på ett programmatiskt (inte formaterat) sätt.
   4	Aktiverar FormatMessage händelsen när ILogger.Log() anropas. Innehåller den formaterade strängversionen av informationen.
   8	Aktiverar MessageJson händelsen när ILogger.Log() anropas. Tillhandahåller en JSON-representation av argumenten.

   I följande tabell visas providernivåerna:

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

   Parsningen för en kategorinivå kan vara antingen en sträng eller ett tal:

   Kategori för namngivet värde	Numeriskt värde
   Trace	0
   Debug	1
   Information	2
   Warning	3
   Error	4
   Critical	5

   Providernivå och kategorinivå:

   • Är i omvänd ordning.
   • Strängkonstanterna är inte alla identiska.

   Om nej FilterSpecs anges försöker implementeringen EventSourceLogger konvertera providernivån till en kategorinivå och tillämpa den på alla kategorier.

   Providernivå	Kategorinivå
   Verbose(5)	Debug(1)
   Informational(4)	Information(2)
   Warning(3)	Warning(3)
   Error(2)	Error(4)
   Critical(1)	Critical(5)

   Om FilterSpecs det anges använder alla kategorier som ingår i listan den kategorinivå som kodas där, och alla andra kategorier filtreras bort.

   Följande exempel förutsätter:

   • En app är igång och anropar logger.LogDebug("12345").
   • Process-ID :t (PID) har angetts via set PID=12345, där 12345 är den faktiska PID:en.

   Ta följande kommando som exempel:

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

   Kommandot ovan:

   • Samlar in felsökningsmeddelanden.
   • Tillämpar inte en FilterSpecs.
   • Anger nivå 5 som mappar kategorin Felsökning.

   Ta följande kommando som exempel:

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

   Kommandot ovan:

   • Samlar inte in felsökningsmeddelanden eftersom kategorinivå 5 är Critical.
   • Tillhandahåller en FilterSpecs.

   Följande kommando samlar in felsökningsmeddelanden eftersom kategorinivå 1 anger Debug.

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

   Följande kommando samlar in felsökningsmeddelanden eftersom kategorin anger Debug.

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

   FilterSpecs inträden för {Logger Category} och {Category Level} representerar ytterligare loggfiltreringsvillkor. Avgränsa FilterSpecs poster med ; semikolontecknet.

   Exempel med ett Windows-kommandogränssnitt:

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

   Föregående kommando aktiveras:

   • Händelsekällans logg genererar formaterade strängar (4) för fel (2).
   • Microsoft.AspNetCore.Hosting loggning på Informational loggningsnivå (4).

4. Stoppa verktyget dotnet-trace genom att trycka på Enter-tangenten eller Ctrl+C.

   Spårningen sparas med namnet trace.nettrace i mappen där dotnet-trace kommandot körs.

5. Öppna spårningen med Perfview. trace.nettrace Öppna filen och utforska spårningshändelserna.

Lägg till leverantören för händelsekälla i appens loggningskonfiguration om appen inte skapar värden med WebApplication.CreateBuilder.

Mer information finns i:

• Spårning för prestandaanalysverktyg (dotnet-trace) (.NET-dokumentation)
• Spårningsverktyg för prestandaanalys (dotnet-trace) (i GitHub-repositoryt för dotnet/diagnostics)
• LoggingEventSource
• EventLevel
• Perfview: Användbart för att visa spårningar av händelsekälla.

Perfview

Använd verktyget PerfView för att samla in och visa loggar. Det finns andra verktyg för att visa ETW-loggar, men PerfView ger den bästa upplevelsen för att arbeta med ETW-händelser som genereras av ASP.NET Core.

Om du vill konfigurera PerfView för att samla in händelser som loggats av den här providern lägger du till strängen *Microsoft-Extensions-Logging i listan Ytterligare providers . Missa inte * vid strängens början.

Windows EventLog

EventLog-providern skickar loggutdata till Windows-händelseloggen. Till skillnad från de andra leverantörerna ärver EventLog providern inte ärver standardinställningarna för icke-provider. Om EventLog logginställningar inte har angetts används LogLevel.Warningsom standard.

Om du vill logga händelser som är lägre än LogLevel.Warninganger du uttryckligen loggnivån. I följande exempel anges standardloggnivån för händelseloggen till LogLevel.Information:

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

AddEventLog överlagringar kan skicka in EventLogSettings. Om null eller inte anges används följande standardinställningar:

• LogName: "Applikation"
• SourceName: ".NET Runtime"
• MachineName: Namnet på den lokala datorn används.

Följande kod ändrar SourceName från standardvärdet för ".NET Runtime" till MyLogs:

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

Azure App Service

Leverantörspaketet Microsoft.Extensions.Logging.AzureAppServices skriver loggar till textfiler i filsystemet i en Azure App Service-app samt till bloblagring i ett Azure Storage-konto.

Providerpaketet ingår inte i det delade ramverket. Om du vill använda providern lägger du till providerpaketet i projektet.

Om du vill konfigurera providerinställningar använder du AzureFileLoggerOptions och AzureBlobLoggerOptions, enligt följande exempel:

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

När den distribueras till Azure App Service använder appen inställningarna i avsnittet App Service-loggar på sidan App Service i Azure-portalen. När följande inställningar uppdateras börjar ändringarna gälla omedelbart utan att appen behöver startas om eller distribueras om.

• Applikationsloggning (filsystem)
• Applikationsloggning (Blob)

Standardplatsen för loggfiler finns i D:\\home\\LogFiles\\Application mappen och standardfilnamnet är diagnostics-yyyymmdd.txt. Standardgränsen för filstorlek är 10 MB och det maximala standardantalet filer som behålls är 2. Standardblobnamnet är {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Den här providern loggar bara när projektet körs i Azure-miljön.

Azure-loggströmning

Azure-loggströmning stöder visning av loggaktivitet i realtid från:

• Appservern
• Webbservern
• Misslyckade förfrågningars spårning

Så här konfigurerar du Azure-loggströmning:

• Gå till loggsidan App Service från appens portalsida.
• Ange Application Logging (Filesystem) till På.
• Välj loggen nivå. Den här inställningen gäller endast för Azure-loggströmning.

Gå till sidan Log Stream för att visa loggar. De loggade meddelandena loggas med ILogger-gränssnittet.

Azure Application Insights

Providerpaketet Microsoft.Extensions.Logging.ApplicationInsights skriver loggar till Azure Application Insights. Application Insights är en tjänst som övervakar en webbapp och tillhandahåller verktyg för att fråga och analysera telemetridata. Om du använder den här providern kan du fråga och analysera dina loggar med hjälp av Application Insights-verktygen.

Loggningsprovidern ingår som ett beroende av Microsoft.ApplicationInsights.AspNetCore, vilket är det paket som tillhandahåller all tillgänglig telemetri för ASP.NET Core. Om du använder det här paketet behöver du inte installera providerpaketet.

Paketet Microsoft.ApplicationInsights.Web gäller ASP.NET 4.x, inte ASP.NET Core.

Mer information finns i följande resurser:

• Översikt över Application Insights
• Application Insights för ASP.NET Core-program: Börja här om du vill implementera hela utbudet av Application Insights-telemetri tillsammans med loggning.
• ApplicationInsightsLoggerProvider för .NET ILogger-loggar: Börja här om du vill implementera loggningsprovidern utan resten av Application Insights-telemetrin.
• Application Insights-loggningsadapter
• Installera, konfigurera och initiera den interaktiva självstudiekursen för Application Insights SDK .

Leverantörer av loggning från tredje part

Loggningsramverk från tredje part som fungerar med ASP.NET Core:

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

Vissa ramverk från tredje part kan utföra semantisk loggning, även kallat strukturerad loggning.

Att använda ett ramverk från tredje part liknar att använda någon av de inbyggda leverantörerna:

1. Lägg till ett NuGet-paket i projektet.
2. Anropa en ILoggerFactory tilläggsmetod som tillhandahålls av loggningsramverket.

Mer information finns i dokumentationen för varje leverantör. Loggningsleverantörer från tredje part stöds inte av Microsoft.

Inga asynkrona loggningsmetoder

Loggning bör vara så snabb att det inte är värt prestandakostnaden för asynkron kod. Om ett loggningsdatalager är långsamt ska du inte skriva till det direkt. Överväg att skriva loggmeddelandena till snabb lagring först och sedan flytta dem till långsam lagring senare. När du till exempel loggar till SQL Server ska du inte göra det direkt i en Log metod, eftersom Log metoderna är synkrona. Lägg i stället synkront till loggmeddelanden i en minnesintern kö och låt en bakgrundsarbetare hämta meddelandena från kön för att utföra det asynkrona arbetet med att skicka data till SQL Server. Mer information finns i Vägledning om hur du loggar till en meddelandekö för långsamma datalager (dotnet/AspNetCore.Docs #11801).

Ändra loggnivåer i en app som körs

Loggnings-API:et innehåller inget scenario för att ändra loggnivåer när en app körs. Vissa konfigurationsprovidrar kan dock läsa in konfigurationen igen, vilket omedelbart påverkar loggningskonfigurationen. Filkonfigurationsprovidern läser till exempel in loggningskonfigurationen igen som standard. Om konfigurationen ändras i kod medan en app körs kan appen anropa IConfigurationRoot.Reload för att uppdatera appens loggningskonfiguration.

ILogger och ILoggerFactory

Gränssnitten ILogger<TCategoryName> och implementeringarna ILoggerFactory ingår i .NET SDK. De är också tillgängliga i följande NuGet-paket:

• Gränssnitten finns i Microsoft.Extensions.Logging.Abstractions.
• Standardimplementeringarna finns i Microsoft.Extensions.Logging.

Tillämpa loggfilterregler i kod

Den bästa metoden för att ange loggfilterregler är att använda Konfiguration.

I följande exempel visas hur du registrerar filterregler i kod:

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) anger System kategorin och loggnivån Debug. Filtret tillämpas på alla leverantörer eftersom en specifik provider inte har konfigurerats.

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

• Loggningsprovider Debug.
• Loggnivå Information och högre.
• Alla kategorier börjar med "Microsoft".

Logga automatiskt omfånget med SpanId, TraceId, ParentId, Baggageoch Tags.

Loggningsbiblioteken skapar implicit ett omfångsobjekt med SpanId, TraceId, ParentId,Baggageoch Tags. Det här beteendet konfigureras 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();

traceparent Om http-begärandehuvudet är inställt visar ParentId i loggområdet W3C parent-id från den inkommande traceparent rubriken och SpanId i loggområdet visar den uppdaterade parent-id för nästa utgående steg/spännvidd. Mer information finns i Mutating the traceparent Field.

Skapa en anpassad loggning

Information om hur du skapar en anpassad loggning finns i Implementera en anpassad loggningsprovider i .NET.

Ytterligare resurser

• Förbättra loggningsprestanda med källgeneratorer
• Bakom [LogProperties] och den nya generatorn för telemetriloggningskällan
• Microsoft.Extensions.Logging-källa på GitHub
• Visa eller ladda ned exempelkod (hur du laddar ned).
• Högpresterande loggning
• Loggningsbuggar bör skapas på dotnet/runtime GitHub-lagringsplatsen.
• ASP.NET Core Blazor loggning

Av Kirk Larkin, Juergen Gutsch och Rick Anderson

I det här avsnittet beskrivs loggning i .NET när det gäller ASP.NET Core-appar. Detaljerad information om loggning i .NET finns i Loggning i .NET. Mer information om loggning i appar finns i BlazorASP.NET Core-loggningBlazor.

Visa eller ladda ned exempelkod (hur du laddar ned).

Loggningsproviders

Loggningsproviders lagrar loggar, förutom providern Console som visar loggar. Azure Application Insights-providern lagrar till exempel loggar i Azure Application Insights. Flera leverantörer kan aktiveras.

Standardmallar för ASP.NET Core-webbappar:

• Använd allmän värd.
• Anropa CreateDefaultBuilder, som lägger till följande loggningstjänster:
  • Console
  • Debug
  • EventSource
  • EventLog: Endast 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>();
            });
}

Föregående kod visar klassen Program som skapats med ASP.NET Core-webbappmallar. De närmaste avsnitten innehåller exempel baserade på ASP.NET Core-webbappmallar, som använder en generisk värd. Konsolappar som inte är värdar beskrivs senare i det här dokumentet.

Om du vill åsidosätta standarduppsättningen med loggningsproviders som lagts till av Host.CreateDefaultBuilderanropar ClearProviders du och lägger till de loggningsprovidrar som krävs. Till exempel följande kod:

• Anropar ClearProviders för att ta bort alla ILoggerProvider instanser från byggaren.
• Lägger till Console loggningsprovider.

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

Ytterligare leverantörer finns i:

• Inbyggda loggningsproviders
• tredjepartsloggningsleverantörer.

Skapa loggar

Om du vill skapa loggar använder du ett ILogger<TCategoryName> objekt från beroendeinmatning (DI).

Följande exempel:

• Skapar en logger, ILogger<AboutModel>, som använder en loggkategori med det fullständigt kvalificerade namnet av typen AboutModel. Loggkategorin är en sträng som är associerad med varje logg.
• Anropar LogInformation för att logga på Information nivån. Loggnivån anger allvarlighetsgraden för den loggade händelsen.

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

Nivåer och kategorier förklaras mer detaljerat senare i det här dokumentet.

Information om Blazorfinns i ASP.NET Core-loggningBlazor.

Skapa loggar i Main och Startup visar hur du skapar loggar i Main och Startup.

Konfigurera loggning

Loggningskonfiguration tillhandahålls ofta av avsnittet Logging i appsettings.{Environment}.json filer. Följande appsettings.Development.json fil genereras av ASP.NET Core-webbappmallar:

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

I JSON-koden ovan:

• Kategorierna "Default", "Microsoft"och "Microsoft.Hosting.Lifetime" anges.
• Kategorin "Microsoft" gäller för alla kategorier som börjar med "Microsoft". Den här inställningen gäller till exempel för "Microsoft.AspNetCore.Routing.EndpointMiddleware" kategorin.
• Kategorin "Microsoft" loggar på loggnivå Warning och högre.
• Kategorin "Microsoft.Hosting.Lifetime" är mer specifik än kategorin "Microsoft", så "Microsoft.Hosting.Lifetime"-kategorin loggar vid loggnivå "information" och högre.
• En specifik loggprovider har inte angetts, så LogLevel den gäller för alla aktiverade loggningsproviders förutom Windows EventLog.

Egenskapen Logging kan ha både LogLevel och egenskaper för loggprovidern. LogLevel Anger den lägsta nivå som ska loggas för valda kategorier. I den föregående JSON anges loggnivåer för Information och Warning. LogLevel anger loggens allvarlighetsgrad och sträcker sig från 0 till 6:

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

När en LogLevel har angetts aktiveras loggning för meddelanden på den angivna nivån och högre. I föregående JSON Default loggas kategorin för Information och högre. Till exempel loggas Information, Warning, Error och Critical meddelanden. Om inget LogLevel anges, ställs loggning in på Information-nivån som standard. Mer information finns i Loggnivåer.

En provideregenskap kan ange en LogLevel egenskap. LogLevel under en leverantör anger nivåer för loggning för den leverantören och åsidosätter de logginställningar som inte är för leverantörer. Överväg följande appsettings.json fil:

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

Inställningar i Logging.{providername}.LogLevel överrider inställningar i Logging.LogLevel. I föregående JSON Debug är providerns standardloggnivå inställd Informationpå :

Logging:Debug:LogLevel:Default:Information

Föregående inställning anger Information loggnivån för varje Logging:Debug: kategori utom Microsoft.Hosting. När en specifik kategori visas åsidosätter den specifika kategorin standardkategorin. I föregående JSON åsidosätter Logging:Debug:LogLevel kategorierna "Microsoft.Hosting" och "Default" inställningarna i Logging:LogLevel

Minsta loggnivå kan anges för något av följande:

• Specifika leverantörer: Till exempel Logging:EventSource:LogLevel:Default:Information
• Specifika kategorier: Till exempel Logging:LogLevel:Microsoft:Warning
• Alla leverantörer och alla kategorier: Logging:LogLevel:Default:Warning

Loggar under miniminivån är inte:

• Skickas till providern.
• Loggas eller visas.

Om du vill ignorera alla loggar anger du LogLevel.None. LogLevel.None har värdet 6, vilket är högre än LogLevel.Critical (5).

Om en leverantör stöder loggomfattningar anger IncludeScopes om de är aktiverade. Mer information finns i loggomfattningar

Följande appsettings.json fil innehåller alla providers som är aktiverade som standard:

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

I föregående exempel:

• Kategorierna och nivåerna är inte föreslagna värden. Exemplet tillhandahålls för att visa alla standardprovidrar.
• Inställningar i Logging.{providername}.LogLevel överrider inställningar i Logging.LogLevel. Nivån i Debug.LogLevel.Default åsidosätter till exempel nivån i LogLevel.Default.
• Varje standard-provider-alias används. Varje provider definierar ett alias som kan användas i konfigurationen i stället för det fullständigt kvalificerade typnamnet. De inbyggda providersaliasen är:
  • Console
  • Debug
  • EventSource
  • EventLog
  • AzureAppServicesFile
  • AzureAppServicesBlob
  • ApplicationInsights

Ange loggnivå efter kommandorad, miljövariabler och annan konfiguration

Loggnivån kan anges av någon av konfigurationsprovidrar.

Den : avgränsaren fungerar inte med hierarkiska nycklar för miljövariabler på alla plattformar. Till exempel stöds inte :-avgränsaren av Bash. Det dubbla understrecket, __, är:

• Stöds av alla plattformar.
• Ersätts automatiskt av ett kolon, :.

Följande kommandon:

• Ange miljönyckeln Logging:LogLevel:Microsoft till värdet Information för i Windows.
• Testa inställningarna när du använder en app som skapats med ASP.NET Core-webbprogrammallar. Kommandot dotnet run måste köras i projektkatalogen när du har använt set.

set Logging__LogLevel__Microsoft=Information
dotnet run

Föregående miljöinställning:

• Anges endast i processer som startats från det kommandofönster som de angavs i.
• Läses inte av webbläsare som startas med Visual Studio.

Följande setx-kommando anger även miljönyckeln och värdet i Windows. set Till skillnad från setxsparas inställningarna. Växeln /M anger variabeln i systemmiljön. Om /M inte används anges en användarmiljövariabel.

setx Logging__LogLevel__Microsoft Information /M

Överväg följande appsettings.json fil:

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

Följande kommando anger föregående konfiguration i miljön:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

I Azure App Service väljer du Ny programinställning på sidan Konfiguration>inställningar. Azure App Service-programinställningar är:

• Krypterad i vila och överförs via en krypterad kanal.
• Exponeras som miljövariabler.

Mer information finns i Azure Apps: Åsidosätt appkonfiguration med hjälp av Azure-portalen.

Mer information om hur du ställer in ASP.NET Grundläggande konfigurationsvärden med hjälp av miljövariabler finns i miljövariabler. Information om hur du använder andra konfigurationskällor, inklusive kommandoraden, Azure Key Vault, Azure App Configuration, andra filformat med mera finns i Konfiguration i ASP.NET Core.

Så här tillämpas filtreringsregler

När ett ILogger<TCategoryName> objekt skapas, väljer det ILoggerFactory objektet en enda regel per provider som ska tillämpas på den loggaren. Alla meddelanden som skrivs av en ILogger instans filtreras baserat på de valda reglerna. Den mest specifika regeln för varje provider och kategoripar väljs från de tillgängliga reglerna.

Följande algoritm används för varje provider när en ILogger skapas för en viss kategori:

• Välj alla regler som matchar providern eller dess alias. Om ingen matchning hittas väljer du alla regler med en tom leverantör.
• Från resultatet av föregående steg väljer du regler med det längsta matchande kategoriprefixet. Om ingen matchning hittas väljer du alla regler som inte anger en kategori.
• Om flera regler har valts tar du den sista .
• Om inga regler har valts använder du MinimumLevel.

Logga utdata från dotnet run och Visual Studio

Loggar som skapats med standardloggningsprovidrar visas:

• I Visual Studio
  • I fönstret för felsökningsutdata under felsökning.
  • I ASP.NET Core-webbserverns fönster.
• I konsolfönstret när appen körs med dotnet run.

Loggar som börjar med "Microsoft"-kategorier kommer från ASP.NET Core Framework-kod. ASP.NET Core och programkod använder samma loggnings-API och -providers.

Loggkategori

När ett ILogger objekt skapas anges en kategori . Den kategorin ingår i varje loggmeddelande som skapas av den instansen av ILogger. Kategoristrängen är godtycklig, men konventionen är att använda klassnamnet. I en kontrollant kan till exempel namnet vara "TodoApi.Controllers.TodoController". ASP.NET Core-webbappar använder ILogger<T> för att automatiskt hämta en ILogger-instans som använder det fullständigt kvalificerade typnamnet T som kategori.

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.");
    }
}

Om du uttryckligen vill ange kategorin anropar du 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.");
    }

Att anropa CreateLogger med ett fast namn kan vara användbart när det används i flera metoder så att händelserna kan ordnas efter kategori.

ILogger<T> motsvarar anrop CreateLogger med det fullständigt kvalificerade typnamnet T.

Loggnivå

I följande tabell visas LogLevel värdena, metoden för bekvämlighetstillägg Log{LogLevel} och den föreslagna användningen:

LogLevel	Value	Method	Description
Trace	0	LogTrace	Innehåller de mest detaljerade meddelandena. Dessa meddelanden kan innehålla känsliga appdata. Dessa meddelanden är inaktiverade som standard och bör inte aktiveras i produktion.
Debug	1	LogDebug	För felsökning och utveckling. Använd med försiktighet i produktionen på grund av den höga volymen.
Information	2	LogInformation	Spårar appens allmänna flöde. Kan ha ett långsiktigt värde.
Warning	3	LogWarning	För onormala eller oväntade händelser. Innehåller vanligtvis fel eller villkor som inte gör att appen misslyckas.
Error	4	LogError	För fel och undantag som inte kan hanteras. Dessa meddelanden anger ett fel i den aktuella åtgärden eller begäran, inte ett appomfattande fel.
Critical	5	LogCritical	För haverier som kräver omedelbar uppmärksamhet. Exempel: scenarier för dataförlust, slut på diskutrymme.
None	6		Anger att en loggningskategori inte ska skriva några meddelanden.

I föregående tabell LogLevel visas från lägsta till högsta allvarlighetsgrad.

Log-metodens första parameter, LogLevel, anger loggens allvarlighetsgrad. I stället för att anropa Log(LogLevel, ...) använder de flesta utvecklare Log{LogLevel}-utökningmetoderna. Tilläggsmetoderna Log{LogLevel}anropar log-metoden och anger LogLevel. Följande två loggningsanrop är till exempel funktionellt likvärdiga och skapar samma logg:

[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 är händelse-ID:t. MyLogEvents är en del av exempelappen och visas i avsnittet Logghändelse-ID .

MyDisplayRouteInfo och ToCtxString tillhandahålls av NuGet-paketet Rick.Docs.Samples.RouteInfo . Metoderna Controller och Razor Page visar ruttinformation.

Följande kod skapar Information och Warning loggar:

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

I föregående kod är den första Log{LogLevel} parameternMyLogEvents.GetItemlogghändelse-ID. Den andra parametern är en meddelandemall med platshållare för argumentvärden som tillhandahålls av de återstående metodparametrarna. Metodparametrarna förklaras i meddelandemallsavsnittet senare i det här dokumentet.

Anropa lämplig Log{LogLevel} metod för att styra hur mycket loggutdata som skrivs till ett visst lagringsmedium. Till exempel:

• I produktion:
  • Loggning på Trace nivåerna eller Information ger en stor mängd detaljerade loggmeddelanden. För att kontrollera kostnader och inte överskrida datalagringsgränser, logga meddelanden på nivåerna Trace och Information till en högvolym, lågkostnadsdatalagring. Överväg att Trace begränsa och Information till specifika kategorier.
  • Loggning på Warning genom Critical nivåer bör ge få loggmeddelanden.
    • Kostnader och lagringsgränser är vanligtvis inte ett problem.
    • Få loggar ger mer flexibilitet i val av datalager.
• Under utveckling:
  • Ställ in på Warning.
  • Lägg till Trace eller Information meddelanden vid felsökning. För att begränsa utdata, ange bara Trace eller Information för de kategorier som är föremål för undersökning.

ASP.NET Core skriver loggar för ramverkshändelser. Tänk till exempel på loggutdata för:

• En Razor Pages-app som skapats med mallarna ASP.NET Core.
• Loggning inställd på Logging:Console:LogLevel:Microsoft:Information
• Navigering till sidan Privacy :

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

Följande JSON-uppsättningar Logging:Console:LogLevel:Microsoft:Information:

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

Logghändelse-ID

Varje logg kan ange ett händelse-ID. Exempelappen MyLogEvents använder klassen för att definiera händelse-ID:t:

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

Ett händelse-ID associerar en uppsättning händelser. Till exempel kan alla loggar som är relaterade till att visa en lista med objekt på en sida vara 1001.

Loggningsprovidern kan lagra händelse-ID i ett ID-fält, i loggningsmeddelandet eller inte alls. Felsökningsprovidern visar inte händelse-ID:t. Konsolprovidern visar händelse-ID:t inom hakparenteser efter kategorin:

info: TodoApi.Controllers.TodoItemsController[1002]
      Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
      Get(1) NOT FOUND

Vissa loggningsleverantörer lagrar händelse-ID:t i ett fält, vilket möjliggör filtrering på ID:t.

Loggmeddelandemall

Varje logg-API använder en meddelandemall. Meddelandemallen kan innehålla platshållare för vilka argument anges. Använd namn för platshållarna, inte siffror.

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

Ordningen på parametrarna, inte deras platshållarnamn, avgör vilka parametrar som används för att tillhandahålla platshållarvärden i loggmeddelanden. I följande kod är parameternamnen i fel ordning i platshållarna för meddelandemallen.

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

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

Parametrarna tilldelas dock till platshållarna i ordningen: apples, pears, . bananas Loggmeddelandet visar parametrarnas ordning:

Parameters: 1, 2, 3

Med den här metoden kan loggningsproviders implementera semantisk eller strukturerad loggning. Själva argumenten skickas till loggningssystemet, inte bara den formaterade meddelandemallen. Detta gör det möjligt för loggningsprovidrar att lagra parametervärdena som fält. Tänk till exempel på följande loggermetod:

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

När du till exempel loggar till Azure Table Storage:

• Varje Azure Table-entitet kan ha ID och RequestTime egenskaper.
• Tabeller med egenskaper förenklar frågor om loggade data. En fråga kan till exempel hitta alla loggar inom ett visst RequestTime intervall utan att behöva parsa tidsgränsen för textmeddelandet.

Loggfel

Loggningsmetoderna har överlagringar som tar en undantagsparameter:

[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 och ToCtxString tillhandahålls av NuGet-paketet Rick.Docs.Samples.RouteInfo . Metoderna Controller och Razor Page visar ruttinformation.

Undantagsloggning är providerspecifik.

Standardloggnivå

Om standardloggnivån inte har angetts är Informationstandardvärdet för loggnivå .

Tänk till exempel på följande webbapp:

• Skapat med ASP.NET webbappmallar.
• appsettings.json och appsettings.Development.json har tagits bort eller bytt namn.

Med den föregående konfigurationen genererar navigering till sekretess- eller startsidan många Trace, Debugoch Information meddelanden med Microsoft i kategorinamnet.

Följande kod anger standardloggnivån när standardloggnivån inte har angetts i konfigurationen:

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

I allmänhet bör loggnivåer anges i konfigurationen och inte i kod.

Filterfunktion

En filterfunktion anropas för alla leverantörer och kategorier som inte har regler tilldelade till sig genom konfiguration eller kod:

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

Föregående kod visar konsolloggar när kategorin innehåller Controller eller Microsoft och loggnivån är Information eller högre.

I allmänhet bör loggnivåer anges i konfigurationen och inte i kod.

ASP.NET Core och EF Core kategorier

Följande tabell innehåller några kategorier som används av ASP.NET Core och Entity Framework Core, med anteckningar om loggarna:

Category	Notes
Microsoft.AspNetCore	Allmän ASP.NET Core-diagnostik.
Microsoft.AspNetCore.DataProtection	Vilka nycklar som övervägdes, hittades och användes.
Microsoft.AspNetCore.HostFiltering	Värdar tillåts.
Microsoft.AspNetCore.Hosting	Hur lång tid det tog att slutföra HTTP-begäranden och vilken tid de startade. Vilka hosting-startupkomponenter som laddades in.
Microsoft.AspNetCore.Mvc	MVC och Razor diagnostik. Modellbindning, filterkörning, visa kompilering, åtgärdsval.
Microsoft.AspNetCore.Routing	Ruttmatchningsinformation.
Microsoft.AspNetCore.Server	Starta, stoppa och håll igång svar. HTTPS-certifikatinformation.
Microsoft.AspNetCore.StaticFiles	Filer som hanteras.
Microsoft.EntityFrameworkCore	Generell Entity Framework Core-diagnostik. Databasaktivitet och konfiguration, ändringsidentifiering, migreringar.

Om du vill visa fler kategorier i konsolfönstret anger du appsettings.Development.json följande:

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

Loggomfattningar

Ett omfång kan gruppera en uppsättning logiska åtgärder. Den här grupperingen kan användas för att koppla samma data till varje logg som skapas som en del av en uppsättning. Varje logg som skapas som en del av bearbetningen av en transaktion kan till exempel innehålla transaktions-ID:t.

Ett omfång:

• Är en IDisposable typ som returneras av BeginScope metoden.
• Varar tills den tas bort.

Följande leverantörer stödjer omfång:

• Console
• AzureAppServicesFile och AzureAppServicesBlob

Använd ett omfång genom att omsluta loggningsanrop i ett using block:

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

Inbyggda loggningstjänster

ASP.NET Core innehåller följande loggningsproviders som en del av det delade ramverket:

• Console
• Debug
• EventSource
• EventLog

Följande loggningsproviders levereras av Microsoft, men inte som en del av det gemensamma ramverket. De måste installeras som ytterligare NuGet-paket.

• AzureAppServicesFile och AzureAppServicesBlob
• ApplicationInsights

ASP.NET Core innehåller ingen loggningsprovider för att skriva loggar till filer. Om du vill skriva loggar till filer från en ASP.NET Core-app bör du överväga att använda en loggningsprovider från tredje part.

Information om stdout och felsökning av loggning med ASP.NET Core-modulen finns i Felsöka ASP.NET Core i Azure App Service och IIS ochASP.NET Core Module (ANCM) för IIS.

Console

Console-providerloggar utdata till konsolen. Mer information om hur du visar Console loggar under utveckling finns i Loggning av utdata från dotnet run och Visual Studio.

Debug

Providern Debug skriver loggutdata med hjälp System.Diagnostics.Debug av klassen . Anrop till System.Diagnostics.Debug.WriteLine skriver till Debug-providern.

I Linux Debug är providerloggplatsen distributionsberoende och kan vara något av följande:

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

Händelsekälla

EventSource-providern skriver till en plattformsoberoende händelsekälla med namnet Microsoft-Extensions-Logging. I Windows använder providern ETW-.

dotnet-spårverktyg

Verktyget dotnet-trace är ett plattformsoberoende globalt CLI-verktyg som möjliggör insamling av .NET Core-spårningar av en process som körs. Verktyget samlar in Microsoft.Extensions.Logging.EventSource leverantörsdata med hjälp av en LoggingEventSource.

Installationsinstruktioner finns i dotnet-trace.

Använd dotnet-spårningsverktyget för att samla in en spårning från en app:

1. Kör appen med dotnet run kommandot .

2. Fastställa processidentifieraren (PID) för .NET Core-appen:

   dotnet trace ps
   

   Leta reda på PID för den process som har samma namn som appens sammansättning.

3. dotnet trace Kör kommandot .

   Allmän kommandosyntax:

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

   När du använder ett PowerShell-kommandoskal, inneslut --providers värdet med enkla citattecken ('):

   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}\"'
   

   På andra plattformar än Windows lägger du till -f speedscope alternativet för att ändra formatet för utdataspårningsfilen till speedscope.

   I följande tabell definieras nyckelordet:

   Keyword	Description
   1	Logga metahändelser om LoggingEventSource. Loggar inte händelser från ILogger.
   2	Aktiverar Message händelsen när ILogger.Log() anropas. Ger information på ett programmatiskt (inte formaterat) sätt.
   4	Aktiverar FormatMessage händelsen när ILogger.Log() anropas. Innehåller den formaterade strängversionen av informationen.
   8	Aktiverar MessageJson händelsen när ILogger.Log() anropas. Tillhandahåller en JSON-representation av argumenten.

   I följande tabell visas providernivåerna:

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

   Parsningen för en kategorinivå kan vara antingen en sträng eller ett tal:

   Kategori för namngivet värde	Numeriskt värde
   Trace	0
   Debug	1
   Information	2
   Warning	3
   Error	4
   Critical	5

   Providernivå och kategorinivå:

   • Är i omvänd ordning.
   • Strängkonstanterna är inte alla identiska.

   Om nej FilterSpecs anges försöker implementeringen EventSourceLogger konvertera providernivån till en kategorinivå och tillämpa den på alla kategorier.

   Providernivå	Kategorinivå
   Verbose(5)	Debug(1)
   Informational(4)	Information(2)
   Warning(3)	Warning(3)
   Error(2)	Error(4)
   Critical(1)	Critical(5)

   Om FilterSpecs det anges använder alla kategorier som ingår i listan den kategorinivå som kodas där, och alla andra kategorier filtreras bort.

   Följande exempel förutsätter:

   • En app är igång och anropar logger.LogDebug("12345").
   • Process-ID :t (PID) har angetts via set PID=12345, där 12345 är den faktiska PID:en.

   Ta följande kommando som exempel:

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

   Kommandot ovan:

   • Samlar in felsökningsmeddelanden.
   • Tillämpar inte en FilterSpecs.
   • Anger nivå 5 som mappar kategorin Felsökning.

   Ta följande kommando som exempel:

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

   Kommandot ovan:

   • Samlar inte in felsökningsmeddelanden eftersom kategorinivå 5 är Critical.
   • Tillhandahåller en FilterSpecs.

   Följande kommando samlar in felsökningsmeddelanden eftersom kategorinivå 1 anger Debug.

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

   Följande kommando samlar in felsökningsmeddelanden eftersom kategorin anger Debug.

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

   FilterSpecs inträden för {Logger Category} och {Category Level} representerar ytterligare loggfiltreringsvillkor. Avgränsa FilterSpecs poster med ; semikolontecknet.

   Exempel med ett Windows-kommandogränssnitt:

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

   Föregående kommando aktiveras:

   • Händelsekällans logg genererar formaterade strängar (4) för fel (2).
   • Microsoft.AspNetCore.Hosting loggning på Informational loggningsnivå (4).

4. Stoppa dotnet-spårningsverktyget genom att trycka på Retur eller Ctrl+C.

   Spårningen sparas med namnet trace.nettrace i mappen där dotnet trace kommandot körs.

5. Öppna spårningen med Perfview. Öppna filen trace.nettrace och utforska spårningshändelserna.

Lägg till leverantören för händelsekälla i appens loggningskonfiguration om appen inte skapar värden med CreateDefaultBuilder.

Mer information finns i:

• Spårning för prestandaanalysverktyg (dotnet-trace) (.NET Core-dokumentation )
• Spårning för prestandaanalysverktyg (dotnet-trace) (dokumentation för GitHub-repositoriet dotnet/diagnostik)
• LoggingEventSource-klass (.NET API Browser)
• EventLevel
• LoggingEventSource-referenskälla (3.0): Om du vill hämta referenskällan för en annan version ändrar du grenen till release/{Version}, där {Version} är den version av ASP.NET Core som önskas.
• Perfview: Användbart för att visa spårningar av händelsekälla.

Perfview

Använd verktyget PerfView för att samla in och visa loggar. Det finns andra verktyg för att visa ETW-loggar, men PerfView ger den bästa upplevelsen för att arbeta med ETW-händelser som genereras av ASP.NET Core.

Om du vill konfigurera PerfView för att samla in händelser som loggats av den här providern lägger du till strängen *Microsoft-Extensions-Logging i listan Ytterligare providers . Missa inte * vid strängens början.

Windows EventLog

EventLog-providern skickar loggutdata till Windows-händelseloggen. Till skillnad från de andra leverantörerna ärver EventLog providern inte ärver standardinställningarna för icke-provider. Om EventLog logginställningarna inte har angetts, är de som standard till LogLevel.Warning.

Om du vill logga händelser som är lägre än LogLevel.Warninganger du uttryckligen loggnivån. I följande exempel anges standardloggnivån för händelseloggen till LogLevel.Information:

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

AddEventLog-överlagringar kan skickas EventLogSettings. Om null eller inte anges används följande standardinställningar:

• LogName: "Applikation"
• SourceName: ".NET Runtime"
• MachineName: Namnet på den lokala datorn används.

Följande kod ändrar SourceName från standardvärdet för ".NET Runtime" till 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

Microsoft.Extensions.Logging.AzureAppServices-providerpaketet skriver loggar till textfiler i en Azure App Service-apps filsystem och till bloblagring i ett Azure Storage-konto.

Providerpaketet ingår inte i det delade ramverket. Om du vill använda providern lägger du till providerpaketet i projektet.

Om du vill konfigurera providerinställningar använder du AzureFileLoggerOptions och AzureBlobLoggerOptions, enligt följande exempel:

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

När den distribueras till Azure App Service använder appen inställningarna i avsnittet App Service-loggar på sidan App Service i Azure-portalen. När följande inställningar uppdateras börjar ändringarna gälla omedelbart utan att appen behöver startas om eller distribueras om.

• Applikationsloggning (filsystem)
• Applikationsloggning (Blob)

Standardplatsen för loggfiler finns i mappen D:\home\LogFiles\Application och standardfilnamnet är diagnostics-yyyymmdd.txt. Standardgränsen för filstorlek är 10 MB och det maximala standardantalet filer som behålls är 2. Standardblobnamnet är {app-name}{timestamp}/åååå/mm/dd/hh/{guid}-applicationLog.txt.

Den här providern loggar bara när projektet körs i Azure-miljön.

Azure-loggströmning

Azure-loggströmning stöder visning av loggaktivitet i realtid från:

• Appservern
• Webbservern
• Misslyckade förfrågningars spårning

Så här konfigurerar du Azure-loggströmning:

• Gå till loggsidan App Service från appens portalsida.
• Ange Application Logging (Filesystem) till På.
• Välj loggen nivå. Den här inställningen gäller endast för Azure-loggströmning.

Gå till sidan Log Stream för att visa loggar. De loggade meddelandena loggas med ILogger-gränssnittet.

Azure Application Insights

Providerpaketet Microsoft.Extensions.Logging.ApplicationInsights skriver loggar till Azure Application Insights. Application Insights är en tjänst som övervakar en webbapp och tillhandahåller verktyg för att fråga och analysera telemetridata. Om du använder den här providern kan du fråga och analysera dina loggar med hjälp av Application Insights-verktygen.

Loggningsprovidern ingår som ett beroende av Microsoft.ApplicationInsights.AspNetCore, vilket är paketet som tillhandahåller all tillgänglig telemetri för ASP.NET Core. Om du använder det här paketet behöver du inte installera providerpaketet.

Microsoft.ApplicationInsights.Web-paketet är avsett för ASP.NET 4.x, inte ASP.NET Core.

Mer information finns i följande resurser:

• Översikt över Application Insights
• Application Insights för ASP.NET Core-program – Börja här om du vill implementera hela utbudet av Application Insights-telemetri tillsammans med loggning.
• ApplicationInsightsLoggerProvider för .NET Core ILogger-loggar – Börja här om du vill implementera loggningsprovidern utan resten av Application Insights-telemetrin.
• Application Insights-loggningsadapter.
• Installera, konfigurera och initiera den interaktiva självstudiekursen för Application Insights SDK .

Leverantörer av loggning från tredje part

Loggningsramverk från tredje part som fungerar med ASP.NET Core:

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

Vissa ramverk från tredje part kan utföra semantisk loggning, även kallat strukturerad loggning.

Att använda ett ramverk från tredje part liknar att använda någon av de inbyggda leverantörerna:

1. Lägg till ett NuGet-paket i projektet.
2. Anropa en ILoggerFactory tilläggsmetod som tillhandahålls av loggningsramverket.

Mer information finns i dokumentationen för varje leverantör. Loggningsleverantörer från tredje part stöds inte av Microsoft.

Värdfri konsolapp

Ett exempel på hur du använder den generiska värdtjänsten i en icke-webbkonsolapplikation finns i Program.cs-filen för exempelappen Bakgrundsuppgifter (Bakgrundsuppgifter med värdbaserade tjänster i ASP.NET Core).

Loggningskoden för appar utan allmän värd skiljer sig åt i hur leverantörer läggs till och loggare skapas.

Loggningsproviders

I en konsolapp utan värd anropar du providerns Add{provider name} tilläggsmetod när du skapar en 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");
    }
}

Skapa loggar

Om du vill skapa loggar använder du ett ILogger<TCategoryName> objekt. Använd LoggerFactory för att skapa en ILogger.

I följande exempel skapas en logger med LoggingConsoleApp.Program som kategori.

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

I följande exempel används loggern för att skapa loggar med Information som nivå. Loggnivån anger allvarlighetsgraden för den loggade händelsen.

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

Nivåer och kategorier beskrivs mer detaljerat i det här dokumentet.

Logg under värdbygget

Loggning under värduppbyggnad stöds inte direkt. En separat logger kan dock användas. I följande exempel används en Serilog-loggare för att logga in CreateHostBuilder. AddSerilog använder den statiska konfiguration som anges i 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();
        }
    }
}

Konfigurera en tjänst som är beroende av ILogger

Konstruktorinmatning av en logger i Startup fungerar i tidigare versioner av ASP.NET Core eftersom en separat DI-container skapas för Webbvärden. Information om varför endast en container skapas för Generic Host finns i tillkännagivandet om ändringar som bryter kompatibilitet.

För att konfigurera en tjänst som är beroende av ILogger<T>, använd konstruktionsinjektion eller tillhandahåll en fabriksmetod. Metoden fabriksmetod rekommenderas endast när det inte finns något annat alternativ. Tänk dig till exempel en tjänst som behöver en ILogger<T> instans som tillhandahålls av DI:

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

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

Föregående markerade kod är en Func<T,TResult> som körs första gången DI-containern behöver konstruera en instans av MyService. Du kan komma åt någon av de registrerade tjänsterna på det här sättet.

Skapa loggar i Main

Följande kod loggar in Main genom att hämta en instans av ILogger från DI efter att ha byggt värden:

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

Skapa loggar i Start

Följande kod skriver loggar i 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();
    });
}

Det går inte att skriva loggar innan di-containerkonfigurationen Startup.ConfigureServices i metoden har slutförts:

• Loggerinmatning i Startup konstruktorn stöds inte.
• Inloggningsinmatning i metodsignaturen Startup.ConfigureServices stöds inte

Orsaken till den här begränsningen är att loggning är beroende av DI och konfiguration, vilket i sin tur beror på DI. DI-containern konfigureras inte förrän ConfigureServices har slutförts.

Information om hur du konfigurerar en tjänst som är beroende av ILogger<T> eller varför konstruktorinmatning av en logger i Startup fungerade i tidigare versioner, se Konfigurera en tjänst som är beroende av ILogger

Inga asynkrona loggningsmetoder

Loggning bör vara så snabb att det inte är värt prestandakostnaden för asynkron kod. Om ett loggningsdatalager är långsamt ska du inte skriva till det direkt. Överväg att skriva loggmeddelandena till snabb lagring först och sedan flytta dem till långsam lagring senare. När du till exempel loggar till SQL Server ska du inte göra det direkt i en Log metod, eftersom Log metoderna är synkrona. Lägg i stället synkront till loggmeddelanden i en minnesintern kö och låt en bakgrundsarbetare hämta meddelandena från kön för att utföra det asynkrona arbetet med att skicka data till SQL Server. Mer information finns i det här GitHub-problemet.

Ändra loggnivåer i en app som körs

Loggnings-API:et innehåller inget scenario för att ändra loggnivåer när en app körs. Vissa konfigurationsprovidrar kan dock läsa in konfigurationen igen, vilket omedelbart påverkar loggningskonfigurationen. Filkonfigurationsprovidern läser till exempel in loggningskonfigurationen igen som standard. Om konfigurationen ändras i kod medan en app körs kan appen anropa IConfigurationRoot.Reload för att uppdatera appens loggningskonfiguration.

ILogger och ILoggerFactory

ILogger<TCategoryName>- och ILoggerFactory-gränssnitten och implementationerna ingår i .NET Core SDK. De är också tillgängliga i följande NuGet-paket:

• Gränssnitten finns i Microsoft.Extensions.Logging.Abstractions.
• Standardimplementeringarna finns i Microsoft.Extensions.Logging.

Tillämpa loggfilterregler i kod

Den bästa metoden för att ange loggfilterregler är att använda Konfiguration.

I följande exempel visas hur du registrerar filterregler i kod:

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) anger System kategorin och loggnivån Debug. Filtret tillämpas på alla leverantörer eftersom en specifik provider inte har konfigurerats.

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

• Loggningsprovider Debug.
• Loggnivå Information och högre.
• Alla kategorier börjar med "Microsoft".

Logga automatiskt omfång med SpanId, TraceId och ParentId

Loggningsbiblioteken skapar implicit ett omfångsobjekt med SpanId, TraceIdoch ParentId. Det här beteendet konfigureras via ActivityTrackingOptions.

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

traceparent Om http-begärandehuvudet är inställt visar ParentId i loggområdet W3C parent-id från den inkommande traceparent rubriken och SpanId i loggområdet visar den uppdaterade parent-id för nästa utgående steg/spännvidd. Mer information finns i Mutating the traceparent Field.

Skapa en anpassad loggning

Information om hur du skapar en anpassad loggning finns i Implementera en anpassad loggningsprovider i .NET.

Ytterligare resurser

• Högpresterande loggning
• Loggningsbuggar bör skapas på den github.com/dotnet/runtime/ lagringsplatsen.
• ASP.NET Core Blazor loggning