Naplózás a .NET Core-ban és a ASP.NET Core-ban

Által Kirk Larkin, Juergen Gutsch, és Rick Anderson

Ez a cikk a .NET-ben való naplózást ismerteti, mivel az ASP.NET Core-alkalmazásokra vonatkozik. A .NET-ben való naplózással kapcsolatos részletes információkért lásd Naplózás a .NET-ben.

Amennyiben Blazor naplózási útmutatóra van szüksége, amely kiegészíti vagy felülírja az ebben a csomópontban található útmutatást, lásd a ASP.NET Core Blazor naplózási.

Naplózási szolgáltatásokat nyújtók

A naplózási szolgáltatók naplókat tárolnak, kivéve a naplókat megjelenítő Console szolgáltatót. Az Azure Application Insights-szolgáltató például naplókat tárol Azure Application Insights. Több szolgáltató is engedélyezhető.

Az alapértelmezett ASP.NET Core-webalkalmazás-sablonok meghívják WebApplication.CreateBuilder, amely a következő naplózási szolgáltatókat adja hozzá:

• konzol
• Hibakeresés
• EventSource
• Csak Windows: EventLog

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

Az előző kód a ASP.NET Core-webalkalmazás-sablonokkal létrehozott Program.cs fájlt jeleníti meg. A következő szakaszok a ASP.NET Core-webalkalmazás-sablonok alapján nyújtanak példákat.

Az alábbi kód felülírja a WebApplication.CreateBuilderáltal hozzáadott alapértelmezett naplózási szolgáltatókat:

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

Másik lehetőségként az előző naplózási kód a következőképpen írható:

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

További szolgáltatók:

• beépített naplózási szolgáltatók
• Külső szolgáltatók naplózása.

Naplók létrehozása

Naplók létrehozásához használjon egy ILogger<TCategoryName> objektumot függőséginjektálási (DI).

A következő példa:

• Létrehoz egy naplózót, ILogger<AboutModel>, amely a AboutModeltípus teljes minősített nevét használja, a log kategóriáját alkalmazva. A naplókategória egy sztring, amely az egyes naplókhoz van társítva.
• Meghívja LogInformation, hogy Information szinten jelentkezzen be. A Napló szint a naplózott esemény súlyosságát jelzi.

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

A szintek és a kategóriák részletesebb magyarázata a dokumentum következő részeiben található.

A Blazorkapcsolatos információkért lásd: ASP.NET Core Blazor naplózási.

Naplózás konfigurálása

A naplózási konfigurációt általában a appsettings.{ENVIRONMENT}.json fájlok Logging szakasza biztosítja, ahol a {ENVIRONMENT} helyőrző a környezet. A ASP.NET Core-webalkalmazás-sablonok a következő appsettings.Development.json fájlt generálják:

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

Az előző JSON-ban:

• A "Default" és "Microsoft.AspNetCore" kategóriák meg vannak adva.
• A "Microsoft.AspNetCore" kategória az "Microsoft.AspNetCore"kezdetű összes kategóriára vonatkozik. Ez a beállítás például a "Microsoft.AspNetCore.Routing.EndpointMiddleware" kategóriára vonatkozik.
• A "Microsoft.AspNetCore" kategória naplói a Warning és a magasabb naplózási szinteken kerülnek rögzítésre.
• Nincs megadva egy adott naplószolgáltató, ezért LogLevel az összes engedélyezett naplózási szolgáltatóra vonatkozik, kivéve a Windows EventLog.

A Logging tulajdonság LogLevel és naplószolgáltató tulajdonságokkal rendelkezhet. A LogLevel meghatározza a minimális szintet naplózására a kiválasztott kategóriákhoz. Az előző JSON-ban Information és Warning naplószintek vannak megadva. LogLevel a napló súlyosságát jelzi, és 0 és 6 között mozog:

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

Ha egy LogLevel van megadva, a naplózás engedélyezve van a megadott szintű és magasabb szintű üzenetek esetében. Az előző JSON-ban a Default kategória naplózása Information és magasabb értékre történik. A rendszer például naplózza Information, Warning, Errorés Critical üzeneteket. Ha nincs megadva LogLevel, a naplózás alapértelmezés szerint a Information szintre kerül. További információ: naplószintek.

A szolgáltatói tulajdonság megadhat egy LogLevel tulajdonságot. LogLevel szolgáltató alatt megadja az adott szolgáltatóhoz naplózni kívánt szinteket, és felülbírálja a nem szolgáltatói naplóbeállításokat. Fontolja meg a következő appsettings.json fájlt:

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

A Logging.{PROVIDER NAME}.LogLevel beállításai felülírják a Logging.LogLevelbeállításait, ahol a {PROVIDER NAME} helyőrző a szolgáltató neve. Az előző JSON-ban a Debug szolgáltató alapértelmezett naplószintjét Information-re állították.

Logging:Debug:LogLevel:Default:Information

Az előző beállítás minden Logging:Debug: kategória Information naplószintét adja meg, kivéve Microsoft.Hosting. Ha egy adott kategória szerepel a listában, az adott kategória felülírja az alapértelmezett kategóriát. Az előző JSON-ban a Logging:Debug:LogLevel kategóriák "Microsoft.Hosting" és "Default" felülbírálják a Logging:LogLevelbeállításait.

Az alábbiak bármelyikéhez megadható a minimális naplószint:

• Konkrét szolgáltatók: Például Logging:EventSource:LogLevel:Default:Information
• Konkrét kategóriák: Például Logging:LogLevel:Microsoft:Warning
• Minden szolgáltató és minden kategória: Logging:LogLevel:Default:Warning

A minimális szint alatti naplók nem:

• Átadva a szolgáltatónak.
• Naplózott vagy megjelenített.

Az összes napló letiltásához állítsa be a LogLevel.None. LogLevel.None értéke 6, ami magasabb, mint LogLevel.Critical (5).

Ha egy szolgáltató támogatja napló hatóköreit, IncludeScopes jelzi, hogy engedélyezve vannak-e. További információkért lásd: naplóterületeket.

Az alábbi appsettings.json fájl az alapértelmezés szerint engedélyezett összes szolgáltatót tartalmazza:

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

Az előző példában:

• A kategóriák és szintek nem javasolt értékek. A minta az összes alapértelmezett szolgáltató megjelenítésére szolgál.
• A Logging.{PROVIDER NAME}.LogLevel beállításai felülírják a Logging.LogLevelbeállításait, ahol a {PROVIDER NAME} helyőrző a szolgáltató neve. A Debug.LogLevel.Default szintje például felülírja a LogLevel.Default.
• A rendszer minden alapértelmezett szolgáltatót alias használ. Minden szolgáltató meghatároz egy alias, amely a konfigurációban használható a teljes típusnév helyett. A beépített szolgáltatók aliasai a következők:
  • Console
  • Debug
  • EventSource
  • EventLog
  • AzureAppServicesFile
  • AzureAppServicesBlob
  • ApplicationInsights

Bejelentkezés Program.cs

Az alábbi példa meghívja Builder.WebApplication.LoggerProgram.cs és naplózza a tájékoztató üzeneteket:

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

Az alábbi példa meghívja a(z) AddConsole a(z) Program.cs-ban, és naplózza a(z) /Test végpontot.

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

Az alábbi példa meghívja AddSimpleConsoleProgram.cs, letiltja a színkimenetet, és naplózza a /Test végpontot:

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

Naplószint beállítása parancssor, környezeti változók és egyéb konfiguráció szerint

A naplószintet bármelyik konfigurációszolgáltatóállíthatja be.

A : elválasztó nem működik a környezeti változók hierarchikus kulcsaival minden platformon. A : elválasztójel például nem elérhető a Bash-ban. A dupla aláhúzás, __a következőképpen:

• Minden platform támogatja.
• Automatikusan kicserélődik egy kettősponttal, :.

A következő parancsok:

• Állítsa be a Logging:LogLevel:Microsoft környezeti kulcsot Information értékre Windows rendszerben.
• Tesztelje a beállításokat a ASP.NET Core-webalkalmazás-sablonokkal létrehozott alkalmazás használatakor. A dotnet run parancsot a sethasználata után a projektkönyvtárban kell futtatni.

set Logging__LogLevel__Microsoft=Information
dotnet run

Az előző környezeti beállítás:

• Csak a parancsablakból indított folyamatokban van beállítva.
• A Visual Studióval indított böngészők nem olvassák.

A következő setx parancs a windowsos környezetkulcsot és -értéket is beállítja. A setellentétben a setx beállítások megmaradnak. A /M kapcsoló beállítja a változót a rendszerkörnyezetben. Ha /M nincs használatban, a rendszer beállít egy felhasználói környezeti változót.

setx Logging__LogLevel__Microsoft Information /M

Fontolja meg a következő appsettings.json fájlt:

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

A következő parancs állítja be az előző konfigurációt a környezetben:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

Az Azure App ServiceBeállítások Konfiguráció lapon válassza Új alkalmazásbeállítás lehetőséget. Az Azure App Service alkalmazásbeállításai a következők:

• Inaktív állapotban titkosítva és titkosított csatornán keresztül továbbítva.
• Környezeti változókként van közzétéve.

További információ: Azure Apps: Alkalmazáskonfiguráció felülbírálása az Azure Portalhasználatával.

További információ a ASP.NET alapkonfigurációs értékek környezeti változók használatával történő beállításáról: környezeti változók. További információ az egyéb konfigurációs források, például a parancssor, az Azure Key Vault, az Azure App Configuration, az egyéb fájlformátumok és egyebek használatáról: Configuration in ASP.NET Core.

A szűrési szabályok alkalmazása

Amikor létrehoz egy ILogger<TCategoryName> objektumot, a ILoggerFactory objektum szolgáltatónként egyetlen szabályt választ ki, amelyet az adott naplózóra alkalmazni szeretne. Az ILogger-példány által írt összes üzenet a kiválasztott szabályok alapján lesz szűrve. Az elérhető szabályok közül az egyes szolgáltatók és kategóriapárok legspecifikusabb szabálya van kiválasztva.

A következő algoritmust használják minden szolgáltatóhoz, amikor egy adott kategóriához ILogger jön létre:

• Válassza ki a szolgáltatónak vagy aliasának megfelelő összes szabályt. Ha nem található egyezés, jelölje ki az összes szabályt egy üres szolgáltatóval.
• Az előző lépés eredményéből válassza ki a leghosszabb egyező kategóriaelőtaggal rendelkező szabályokat. Ha nem található egyezés, jelölje ki az összes olyan szabályt, amely nem ad meg kategóriát.
• Ha több szabály van kiválasztva, vegye a utolsó szabályt.
• Ha nincsenek kijelölve szabályok, használja a MinimumLevel.

Naplózási kimenet a dotnet-futtatásból és a Visual Studióból

A alapértelmezett naplózási szolgáltatókkal létrehozott naplók jelennek meg:

• A Visual Studióban
  • Hibakereséskor a hibakeresési kimeneti ablakban.
  • A ASP.NET Core Web Server ablakban.
• A konzolablakban, amikor az alkalmazás dotnet run-val van futtatva.

A "Microsoft" kategóriákkal kezdődő naplók a .NET-ből származnak. A .NET és az alkalmazáskód ugyanazt a naplózási API-t és -szolgáltatókat használja.

Naplókategória

ILogger objektum létrehozásakor kategória van megadva. Ez a kategória szerepel a ILoggeradott példánya által létrehozott minden egyes naplóüzenetben. A kategória karakterlánc tetszőleges, de a konvenció a teljes osztálynév használata. Egy vezérlőben például a név "TodoApi.Controllers.TodoController"lehet. A ASP.NET Core-webalkalmazások ILogger<T> használatával automatikusan lekérnek egy ILogger-példányt, amely kategóriaként a T teljes típusnevét használja:

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

Ha további kategorizálásra van szükség, a konvenció egy hierarchikus nevet használ egy alkategóriának a teljes osztálynévhez való hozzáfűzésével, és explicit módon adja meg a kategóriát a 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.");
    }

A rögzített névvel rendelkező CreateLogger hívása akkor lehet hasznos, ha több metódusban használják, így az események kategóriák szerint rendezhetők.

ILogger<T> egyenértékű azzal, hogy a CreateLogger-et a Tteljes típusnevével hívjuk meg.

Naplószint

Az alábbi táblázat a LogLevel értékeket, a kényelmi Log{LogLevel} bővítménymetódusokat és a javasolt használatot sorolja fel:

LogLevel	Érték	Módszer	Leírás
Trace	0	LogTrace	A legrészletesebb üzeneteket tartalmazza. Ezek az üzenetek bizalmas alkalmazásadatokat tartalmazhatnak. Ezek az üzenetek alapértelmezés szerint le vannak tiltva, és nem engedélyezhetők a termelési környezetben.
Debug	1	LogDebug	Hibakereséshez és fejlesztéshez. Nagy mennyiség miatt óvatosan használja a gyártási környezetben.
Information	2	LogInformation	Nyomon követi az alkalmazás általános folyamatát. Hosszú távú érték is lehet.
Warning	3	LogWarning	Rendellenes vagy váratlan események esetén. Általában olyan hibákat vagy feltételeket tartalmaznak, amelyek nem okozzák az alkalmazás meghibásodását.
Error	4	LogError	Azon hibák és kivételek esetén, amelyek nem kezelhetőek. Ezek az üzenetek az aktuális művelet vagy kérés hibáját jelzik, nem pedig alkalmazásszintű hibát.
Critical	5	LogCritical	Azonnali figyelmet igénylő hibák esetén. Példák: adatvesztési forgatókönyvek, lemezterületen kívül.
None	6		Azt határozza meg, hogy egy naplózási kategória ne írjon üzeneteket.

Az előző táblázatban a LogLevel a legalacsonyabbtól a legmagasabb súlyosságig szerepel.

A Log metódus első paramétere, LogLevel, a napló súlyosságát jelzi. Ahelyett, hogy a Log(LogLevel, ...)-t hívják, a legtöbb fejlesztő a Log{LOG LEVEL} kiterjesztési módszereket hívja meg, ahol a {LOG LEVEL} helyőrző a naplózási szint. A következő két naplózási hívás például funkcionálisan egyenértékű, és ugyanazt a naplót hozza létre:

[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 az eseményazonosító. MyLogEvents része a mintaalkalmazásnak, és a naplóesemény-azonosító szakaszban jelenik meg.

MyDisplayRouteInfo és ToCtxString a Rick.Docs.Samples.RouteInfo NuGet csomag biztosítja. A metódusok Controller és Razor Page útvonaladatokat jelenítenek meg.

A következő kód Information és Warning naplókat hoz létre:

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

Az előző kódban az első Log{LOG LEVEL} paraméter (MyLogEvents.GetItem) a naplóesemény-azonosító. A második paraméter egy üzenetsablon, amely a fennmaradó metódusparaméterek által biztosított argumentumértékek helyőrzőit tartalmazza. A metódusparamétereket a dokumentum későbbi részében üzenetsablon ismerteti.

Hívja meg a megfelelő Log{LOG LEVEL} metódust annak szabályozásához, hogy mennyi naplókimenet legyen megírva egy adott tárolóeszközre. Például:

• Gyártásban:
  • A Trace, Debugvagy Information szintű naplózás nagy mennyiségű részletes naplóüzenetet eredményez. A költségek szabályozásához és az adattárolási korlátok átlépésének elkerüléséhez naplózza Trace, Debugvagy Information szintű üzeneteket egy nagy kapacitású, alacsony költségű adattárolóba. Fontolja meg a Trace, Debugvagy Information adott kategóriákra való korlátozását.
  • A Warning szinttől Critical szintig terjedő naplózásnak kevés naplóüzenetet kell létrehoznia.
    • A költségek és a tárolási korlátok általában nem jelentenek problémát.
    • A kevés napló nagyobb rugalmasságot biztosít az adattárak választásában.
• Fejlesztés alatt:
  • Állítsa be a Warning.
  • Hibaelhárításkor Trace, Debugvagy Information üzeneteket adhat hozzá. A kimenet korlátozásához állítsa be Trace, Debugvagy Information csak a vizsgált kategóriákra.

ASP.NET Core naplókat ír a keretrendszereseményekhez. Vegyük például a következő naplókimenetet:

• A ASP.NET Core-sablonokkal létrehozott Razor Pages-alkalmazás.
• A naplózás Logging:Console:LogLevel:Microsoft:Information-ra van állítva.
• Navigálás a Privacy lapra:

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

A következő JSON-készlet Logging:Console:LogLevel:Microsoft:Information:

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

Naplóesemény azonosítója

Minden napló megadhat egy eseményazonosítót. A mintaalkalmazás a MyLogEvents osztály használatával határozza meg az eseményazonosítókat:

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

Az eseményazonosító események egy készletét társítja. Előfordulhat például, hogy a lapon lévő elemek listájának megjelenítéséhez kapcsolódó összes napló 1001 lehet.

A naplózási szolgáltató tárolhatja az eseményazonosítót egy azonosító mezőben, a naplózási üzenetben, vagy egyáltalán nem. A hibakeresési szolgáltató nem jeleníti meg az eseményazonosítókat. A konzolszolgáltató zárójelben jeleníti meg az eseményazonosítókat a kategória után:

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

Egyes naplózási szolgáltatók egy mezőben tárolják az eseményazonosítót, amely lehetővé teszi az azonosítóra való szűrést.

Naplóüzenet-sablon

Minden napló API egy üzenetsablont használ. Az üzenetsablon tartalmazhat helyőrzőket, amelyek argumentumai meg vannak adva. Használjon helyőrzőneveket, ne pedig számokat.

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

A paraméterek sorrendje, nem pedig a helyőrzők nevei határozzák meg, hogy mely paraméterek használhatók helyőrző értékek megadására a naplóüzenetekben. Az alábbi kódban a paraméternevek sorrenden kívül vannak az üzenetsablon helyőrzőiben:

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

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

A paraméterek azonban a következő sorrendben vannak hozzárendelve a helyőrzőkhöz: apples, pears, bananas. A naplóüzenet aparaméterek sorrendjét tükrözi:

Parameters: 1, 2, 3

Ezzel a módszerrel a naplózási szolgáltatók szemantikai vagy strukturált naplózásiimplementálhatók. Maguk az argumentumok a naplózási rendszernek lesznek átadva, nem csak a formázott üzenetsablonnak. Ez lehetővé teszi, hogy a naplózási szolgáltatók mezőként tárolják a paraméterértékeket. Vegyük például a következő naplózó metódust:

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

Például az Azure Table Storage-ba való naplózáskor:

• Minden Azure Table-entitás rendelkezhet ID és RequestTime tulajdonságokkal.
• A tulajdonságokkal rendelkező táblák leegyszerűsítik a naplózott adatok lekérdezését. Egy lekérdezés például egy adott RequestTime tartomány összes naplóját megkeresheti anélkül, hogy elemeznie kellene a szöveges üzenetből eltelt időt.

Naplózási kivételek

A naplózó metódusok túlterheléssel rendelkeznek, amelyek kivételparamétert vesznek fel:

[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 és ToCtxString a Rick.Docs.Samples.RouteInfo NuGet csomag biztosítja. A metódusok Controller és Razor Page útvonaladatokat jelenítenek meg.

A kivételnaplózás szolgáltatóspecifikus.

Alapértelmezett naplószint

Ha az alapértelmezett naplószint nincs beállítva, az alapértelmezett naplószint értéke Information.

Vegyük például a következő webalkalmazást:

• A ASP.NET webalkalmazás-sablonokkal készült.
• appsettings.json és appsettings.Development.json törölve vagy átnevezve.

Az előző beállítással az adatvédelemre vagy a kezdőlapra lépve számos Trace, Debugés Information üzenet jelenik meg a kategórianévben Microsoft.

Az alábbi kód állítja be az alapértelmezett naplószintet, ha az alapértelmezett naplószint nincs beállítva a konfigurációban:

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

A naplószinteket általában a konfigurációban kell megadni, és nem a kódban.

Szűrőfüggvény

A rendszer meghív egy szűrőfüggvényt minden olyan szolgáltatóhoz és kategóriához, amely nem rendelkezik hozzájuk konfiguráció vagy kód alapján hozzárendelt szabályokkal:

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

Az előző kód akkor jeleníti meg a konzolnaplókat, ha a kategória Controller vagy Microsoft tartalmaz, és a naplószint Information vagy magasabb.

A naplószinteket általában a konfigurációban kell megadni, és nem a kódban.

ASP.NET Core-kategóriák

Az alábbi táblázat az ASP.NET Core által használt kategóriákat tartalmazza.

Kategória	Jegyzetek
Microsoft.AspNetCore	Általános ASP.NET alapvető diagnosztikák.
Microsoft.AspNetCore.DataProtection	Mely kulcsokat vették figyelembe, találták és használták.
Microsoft.AspNetCore.HostFiltering	Engedélyezett házigazdák.
Microsoft.AspNetCore.Hosting	Mennyi ideig tartottak a HTTP-kérések befejeződése és mikor kezdődtek. Melyik indítási szerelvényeket üzemelteti a rendszer.
Microsoft.AspNetCore.Mvc	MVC és Razor diagnosztika. Modellkötés, szűrők végrehajtása, nézet fordítása, művelet kiválasztása.
Microsoft.AspNetCore.Routing	Útvonalegyeztetési információk.
Microsoft.AspNetCore.Server	"Kapcsolatindító, leállító és életben tartó válaszok." HTTPS-tanúsítvány adatai.
Microsoft.AspNetCore.StaticFiles	Kiszolgált fájlok.

Ha további kategóriákat szeretne megtekinteni a konzolablakban, állítsa appsettings.Development.json a következőkre:

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

Az entitás-keretrendszer kategóriáinak listáját az EF-üzenetkategóriákcímű témakörben találja.

Naplózási tartományok

A hatókörök logikai műveletek halmazát csoportosíthatják. Ezzel a csoportosítással ugyanazokat az adatokat csatolhatja a csoport részeként létrehozott naplókhoz. A tranzakció feldolgozása során létrehozott naplók például tartalmazhatják a tranzakcióazonosítót.

Hatókör:

• A BeginScope metódus által visszaadott IDisposable típus.
• Addig tart, amíg el nem dobják.

A következő szolgáltatók támogatják a hatóköröket:

• Console
• AzureAppServicesFile és AzureAppServicesBlob

A naplózóhívások becsomagolása egy using blokkba történik egy hatókör használatával.

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

Beépített naplózási szolgáltatók

ASP.NET Core a következő naplózási szolgáltatókat tartalmazza a megosztott keretrendszer részeként:

• Console
• Debug
• EventSource
• EventLog

Az alábbi naplózási szolgáltatókat a Microsoft szállítja, de nem a megosztott keretrendszer részeként. Ezeket további nugetként kell telepíteni.

• AzureAppServicesFile és AzureAppServicesBlob
• ApplicationInsights

ASP.NET Core nem tartalmaz naplózási szolgáltatót a naplók fájlokba való írásához. Ha naplókat szeretne írni egy ASP.NET Core-alkalmazásból származó fájlokba, fontolja meg egy külső naplózási szolgáltatóhasználatát.

Az ASP.NET Core modullal végzett stdout és hibakeresési naplózásról, lásd: Az Azure App Service alkalmazásban és az IIS-ben az ASP.NET Core hibaelhárítása és ASP.NET Core modul (ANCM) az IIS-hez.

Konzol

A Console szolgáltató naplózza a kimenetet a konzolon. További információ a Console naplók fejlesztés közbeni megtekintéséről: lásd a dotnet run és a Visual Studionaplózási kimenetét.

Hibakeresés

A Debug szolgáltató naplókimenetet ír a System.Diagnostics.Debug osztály használatával. A System.Diagnostics.Debug.WriteLine hívások a Debug szolgáltatóhoz íródnak.

Linuxon a Debug szolgáltató naplójának helye disztribúciófüggő, és az alábbiak egyike lehet:

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

Eseményforrás

A EventSource szolgáltató Microsoft-Extensions-Loggingnevű platformfüggetlen eseményforrásba ír. Windows rendszeren a szolgáltató ETWhasznál.

dotnet-trace eszköz

A dotnet-trace eszköz egy platformfüggetlen cli globális eszköz, amely lehetővé teszi egy futó folyamat .NET Core-nyomkövetéseinek gyűjtését. Az eszköz Microsoft.Extensions.Logging.EventSource szolgáltatói adatokat gyűjt a LoggingEventSourcehasználatával.

A telepítési utasításokért lásd: dotnet-trace.

A dotnet-trace eszközzel nyomkövetést gyűjthet egy alkalmazásból:

1. Futtassa az alkalmazást a(z) dotnet run parancs használatával.

2. A .NET Core-alkalmazás folyamatazonosítójának (PID) meghatározása:

   dotnet-trace ps
   

   Keresse meg annak a folyamatnak a PID-jét, amelynek neve megegyezik az alkalmazás szerelvényével.

3. Hajtsa végre a dotnet-trace parancsot.

   Általános parancsszintaxis:

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

   PowerShell-parancshéj használatakor a --providers értéket egyetlen idézőjelbe (') foglalja:

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

   A nem Windows platformokon adja hozzá a -f speedscope beállítást a kimeneti nyomkövetési fájl formátumának a speedscope-re változtatásához.

   A kulcsszót az alábbi táblázat határozza meg:

   Kulcsszó	Leírás
   1	Metaesemények naplózása a LoggingEventSource-ról. Az eseményeket nem naplózza a ILogger-ból.
   2	Bekapcsolja a Message eseményt ILogger.Log() meghívásakor. Programozott (nem formázott) módon nyújt információkat.
   4	Bekapcsolja a FormatMessage eseményt ILogger.Log() meghívásakor. Az információk formázott sztringverzióját adja meg.
   8	Bekapcsolja a MessageJson eseményt ILogger.Log() meghívásakor. JSON-ábrázolást biztosít az argumentumokról.

   Az alábbi táblázat a szolgáltatói szinteket sorolja fel:

   Szolgáltatói szint	Leírás
   0	LogAlways
   1	Critical
   2	Error
   3	Warning
   4	Informational
   5	Verbose

   A kategóriaszint értelmezése lehet karakterlánc vagy szám.

   Kategória nevesített érték	Számérték
   Trace	0
   Debug	1
   Information	2
   Warning	3
   Error	4
   Critical	5

   A szolgáltatói szint és a kategóriaszint:

   • Fordított sorrendben vannak.
   • A sztringállandók nem azonosak.

   Ha nincs megadva FilterSpecs, akkor a EventSourceLogger implementáció megkísérli a szolgáltatói szintet kategóriaszintté alakítani, és minden kategóriára alkalmazza.

   Szolgáltatói szint	Kategóriaszint
   Verbose(5)	Debug(1)
   Informational(4)	Information(2)
   Warning(3)	Warning(3)
   Error(2)	Error(4)
   Critical(1)	Critical(5)

   Ha FilterSpecs van megadva, a listában szereplő kategóriák az ott kódolt kategóriaszintet használják, az összes többi kategóriát pedig kiszűri a rendszer.

   A következő példák feltételezik:

   • Egy alkalmazás fut, és meghívja logger.LogDebug("12345").
   • A folyamatazonosítót (PID) a set PID=12345-n keresztül állították be, ahol a 12345 a tényleges folyamatazonosító (PID).

   Vegye figyelembe a következő parancsot:

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

   Az előző parancs:

   • Rögzíti a hibakeresési üzeneteket.
   • Nem alkalmazza a FilterSpecs-t.
   • Az 5. szintet adja meg, amely a Hibakeresés kategóriát leképezi.

   Vegye figyelembe a következő parancsot:

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

   Az előző parancs:

   • Nem rögzíti a hibakeresési üzeneteket, mert az 5. szintű kategória Critical.
   • FilterSpecsbiztosít valamit.

   Az alábbi parancs rögzíti a hibakeresési üzeneteket, mert a kategória szintje 1, amely Debug-t jelöl.

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

   Az alábbi parancs rögzíti a hibakeresési üzeneteket, mert a kategória Debughatároz meg.

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

   FilterSpecs {Logger Category} és {Category Level} bejegyzései további naplószűrési feltételeket jelölnek. Különítse el FilterSpecs bejegyzéseket a ; pontosvesszővel.

   Példa Windows-parancshéj használatával:

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

   Az előző parancs aktiválódik:

   • Az eseményforrás naplózója formázott karakterláncokat (4) hoz létre a hibákhoz (2).
   • Microsoft.AspNetCore.Hosting naplózás Informational naplózási szinten (4).

4. Állítsa le a dotnet-trace eszközt az Enter billentyű vagy Ctrl+Cbillentyű lenyomásával.

   A nyomkövetést a rendszer abban a mappában trace.nettrace névvel menti, amelyben a dotnet-trace parancs végrehajtása történik.

5. Nyissa meg a nyomkövetést Perfview. Nyissa meg a trace.nettrace fájlt, és vizsgálja meg a nyomkövetési eseményeket.

Ha az alkalmazás nem építi fel a WebApplication.CreateBuildergazdagépet, adja hozzá az Event Source szolgáltatót az alkalmazás naplózási konfigurációjába.

További információ:

• Trace for performance analysis utility (dotnet-trace) (.NET Core-dokumentáció)
• Trace for performance analysis utility (dotnet-trace) (dotnet/diagnostics GitHub-adattár dokumentációja)
• LoggingEventSource
• EventLevel
• Perfview: Hasznos eseményforrás-nyomkövetések megtekintéséhez.

Perfview

A naplók gyűjtéséhez és megtekintéséhez használja a PerfView segédprogramot. Vannak más eszközök is az ETW-naplók megtekintéséhez, de a PerfView biztosítja a legjobb élményt az ASP.NET Core által kibocsátott ETW-eseményekhez.

Ha konfigurálni szeretné a PerfView-t a szolgáltató által naplózott események gyűjtéséhez, adja hozzá a *Microsoft-Extensions-Logging sztringet a További szolgáltatók listához. Ne felejtse el a * elején a karakterláncot.

Windows EventLog

A EventLog szolgáltató naplókimenetet küld a Windows-eseménynaplónak. A többi szolgáltatótól eltérően a EventLog szolgáltató nem örökölni az alapértelmezett nem szolgáltatói beállításokat. Ha EventLog naplóbeállítások nincsenek megadva, alapértelmezés szerint LogLevel.Warning.

A LogLevel.Warningalatti események naplózásához explicit módon állítsa be a naplószintet. Az alábbi példa beállítja az eseménynapló alapértelmezett naplószintjét LogLevel.Informationértékre:

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

A AddEventLog túlterhelések be tudnak menni EventLogSettings-be. Ha null vagy nincs megadva, a rendszer a következő alapértelmezett beállításokat használja:

• LogName: "Alkalmazás"
• SourceName: ".NET Runtime"
• MachineName: A rendszer a helyi gép nevét használja.

Az alábbi kód a SourceName az alapértelmezett ".NET Runtime" értékről MyLogsértékre módosítja:

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

Azure App Service

A Microsoft.Extensions.Logging.AzureAppServices szolgáltatói csomag naplókat ír egy Azure App Service-alkalmazás fájlrendszerében lévő szövegfájlokba, és Blob Storage- egy Azure Storage-fiókban.

A szolgáltatói csomag nem szerepel a megosztott keretrendszerben. A szolgáltató használatához adja hozzá a szolgáltatói csomagot a projekthez.

A szolgáltatói beállítások konfigurálásához használja a AzureFileLoggerOptions és a AzureBlobLoggerOptions, ahogyan az alábbi példában látható:

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

Az Azure App Service-ben való üzembe helyezéskor az alkalmazás az Azure Portal App Service oldalának App Service naplók szekciójában található beállításokat használja. A következő beállítások frissítésekor a módosítások azonnal érvénybe lépnek az alkalmazás újraindítása vagy újbóli üzembe helyezése nélkül.

• alkalmazásnaplózás (fájlrendszer)
• alkalmazásnaplózás (Blob)

A naplófájlok alapértelmezett helye a D:\\home\\LogFiles\\Application mappában található, az alapértelmezett fájlnév pedig diagnostics-yyyymmdd.txt. Az alapértelmezett fájlméretkorlát 10 MB, a megtartott fájlok alapértelmezett maximális száma pedig 2. Az alapértelmezett blobnév {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Ez a szolgáltató csak akkor naplóz, ha a projekt az Azure-környezetben fut.

Azure-naplóstreamelés

Az Azure-naplóstreamelés támogatja a naplótevékenység valós idejű megtekintését a következőből:

• Az alkalmazáskiszolgáló
• A webkiszolgáló
• Sikertelen kérelemkövetés

Az Azure-naplóstreamelés konfigurálása:

• Az alkalmazás portállapjáról navigáljon az Alkalmazásszolgáltatás-naplók lapra.
• Állítsa be a alkalmazásnaplózást (fájlrendszer)állapotba.
• Válassza ki a naplószintet. Ez a beállítás csak az Azure-naplóstreamelésre vonatkozik.

A naplók megtekintéséhez lépjen a Naplóstream oldalra. A naplózott üzeneteket a rendszer a ILogger felülettel naplózza.

Azure Application Insights

A Microsoft.Extensions.Logging.ApplicationInsights csomag naplókat ír a Azure Application Insights-be. Az Application Insights egy webalkalmazást figyelő szolgáltatás, amely eszközöket biztosít a telemetriai adatok lekérdezéséhez és elemzéséhez. Ha ezt a szolgáltatót használja, az Application Insights eszközeivel lekérdezheti és elemezheti a naplókat.

A naplózási szolgáltató a Microsoft.ApplicationInsights.AspNetCorefüggőségeként szerepel, amely az ASP.NET Core összes elérhető telemetriáját biztosító csomag. Ha ezt a csomagot használja, nem kell telepítenie a szolgáltatói csomagot.

A Microsoft.ApplicationInsights.Web csomag ASP.NET 4.x-hez készült, nem ASP.NET Core-hoz.

További információ:

• Application Insights áttekintése
• Application Insights ASP.NET Core-alkalmazásokhoz: Itt kezdheti, ha az Application Insights telemetriai adatainak teljes skáláját szeretné implementálni a naplózással együtt.
• ApplicationInsightsLoggerProvider for .NET Core ILogger logs: Kezdje itt, ha a naplózási szolgáltatót az Application Insights többi telemetriai adatai nélkül szeretné implementálni.
• "Application Insights" naplózási adapterek
• Az Application Insights SDK telepítése, konfigurálása és inicializálása interaktív oktatóanyag.

Külső naplózási szolgáltatók

A ASP.NET Core használatával működő külső naplózási keretrendszerek:

• elmah.io (GitHub-adattár)
• Gelf (GitHub-adattár)
• JSNLog (GitHub-adattár)
• KissLog.net (GitHub-adattár)
• Log4Net (GitHub-adattár)
• NLog (GitHub-adattár)
• PLogger (GitHub-adattár)
• Sentry (GitHub-adattár)
• Serilog (GitHub-adattár)
• Stackdriver (GitHub-adattár)

Egyes külső keretrendszerek képesek szemantikai naplózást, más néven strukturált naplózási.

A külső keretrendszerek használata hasonló az egyik beépített szolgáltatóhoz:

1. NuGet-csomag hozzáadása a projekthez.
2. Hívja meg a naplózási keretrendszer által biztosított ILoggerFactory bővítménymetódust.

További információkért tekintse meg az egyes szolgáltatók dokumentációját. A Microsoft nem támogatja a külső naplózási szolgáltatókat.

Nincs aszinkron naplózó metódus

A naplózásnak olyan gyorsnak kell lennie, hogy nem éri meg az aszinkron kód teljesítményköltségét. Ha egy naplózási adattár lassú, ne írjon közvetlenül hozzá. Érdemes lehet először egy gyorstárolóba írni a naplóüzeneteket, majd később áthelyezni őket a lassú tárolóba. Ha például az SQL Serverre jelentkezik be, ne tegye ezt közvetlenül egy Log metódusban, mivel a Log metódusok szinkronban vannak. Ehelyett szinkronizálva adjon hozzá naplóüzeneteket egy memórián belüli üzenetsorhoz, és egy háttérmunkás húzza ki az üzeneteket az üzenetsorból, hogy elvégezhesse az adatok SQL Serverbe való leküldésének aszinkron munkáját. További információ: Útmutató a lassú adattárak üzenetsorába való bejelentkezéshez (dotnet/AspNetCore.Docs #11801).

Naplószintek módosítása futó alkalmazásokban

A Naplózási API nem tartalmaz olyan forgatókönyvet, amely megváltoztathatja a naplószinteket egy alkalmazás futtatása közben. Egyes konfigurációszolgáltatók azonban képesek újra betölteni a konfigurációt, ami azonnali hatással van a naplózási konfigurációra. Például a fájlkonfigurációs szolgáltató, alapértelmezés szerint újra betölti a naplózási konfigurációt. Ha egy alkalmazás futtatása közben a konfiguráció módosul a kódban, az alkalmazás meghívhatja IConfigurationRoot.Reload az alkalmazás naplózási konfigurációjának frissítéséhez.

ILogger és ILoggerFactory

A .NET Core SDK tartalmazza a ILogger<TCategoryName> és ILoggerFactory interfészeket és implementációkat. A következő NuGet-csomagokban is elérhetők:

• Az interfészek Microsoft.Extensions.Logging.Abstractions-ban vannak.
• Az alapértelmezett implementációk a Microsoft.Extensions.Logging.

Naplószűrő szabályok alkalmazása a kódban

A naplószűrő szabályok beállítására előnyben részesített módszer a Konfigurációshasználata.

Az alábbi példa bemutatja, hogyan regisztrálhat szűrőszabályokat a kódban:

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) meghatározza a System kategóriát és a naplószintet Debug. A szűrő az összes szolgáltatóra vonatkozik, mert egy adott szolgáltató nincs konfigurálva.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) a következőt adja meg:

• A Debug naplózási szolgáltató.
• Naplózási szint Information és magasabb.
• Az összes kategória, amely "Microsoft"-val kezdődik.

A hatókör automatikus naplózása SpanId, TraceId, ParentId, Baggageés Tagshasználatával .

A naplózó könyvtárak implicit módon létrehoznak egy hatókör objektumot SpanId, TraceId, ParentId,Baggageés Tags. Ez a viselkedés ActivityTrackingOptionskeresztül van konfigurálva.

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

Ha a traceparent http-kérelem fejléce be van állítva, a napló hatókörében lévő ParentId a beérkező traceparent fejlécből származó W3C parent-id mutatja, a napló hatókörében lévő SpanId pedig a következő kimenő lépés/időtartam frissített parent-id mutatja. További információért lásd: A traceparent mezőmutációja.

Egyéni naplózó létrehozása

Egyéni naplózó létrehozásához lásd: Egyéni naplózási szolgáltató implementálása a .NET-.

További erőforrások

• A naplózási teljesítmény javítása forrásgenerátorokkal
• [LogProperties] és az új telemetriai naplózási forrásgenerátor mögött
• Microsoft.Extensions.Logging forrás a GitHubon
• Mintakód megtekintése vagy letöltése (hogyan lehet letölteni).
• Nagy teljesítményű naplózás
• A naplózási hibákat a dotnet/runtime GitHub-adattárban kell létrehozni.
• ASP.NET Core Blazor naplózás

Által Kirk Larkin, Juergen Gutsch, és Rick Anderson

Ez a témakör a .NET-ben való naplózást ismerteti, mivel az ASP.NET Core-alkalmazásokra vonatkozik. A .NET-ben való naplózással kapcsolatos részletes információkért lásd: Naplózás a .NET. A Blazor-alkalmazásokba való bejelentkezésről további információt a ASP.NET Core Blazor naplózásicímű témakörben talál.

Mintakód megtekintése vagy letöltése (hogyan lehet letölteni).

Naplózási szolgáltatók

A naplózási szolgáltatók naplókat tárolnak, kivéve a naplókat megjelenítő Console szolgáltatót. Az Azure Application Insights-szolgáltató például naplókat tárol az Azure Application Insightsban. Több szolgáltató is engedélyezhető.

Az alapértelmezett ASP.NET Core-webalkalmazás-sablonok:

• Használja az Általános gazdagép.
• Hívja meg CreateDefaultBuilder, amely a következő naplózási szolgáltatókat adja hozzá:
  • konzol
  • Debugolás
  • EventSource
  • EventLog: csak 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>();
            });
}

Az előző kód a ASP.NET Core-webalkalmazás-sablonokkal létrehozott Program osztályt jeleníti meg. A következő szakaszok példákkal szolgálnak az ASP.NET Core webalkalmazás-sablonok alapján, amelyek az általános hostot használják. Nem hosztolt konzolalkalmazásokat a dokumentum későbbi részében tárgyaljuk.

A Host.CreateDefaultBuilderáltal hozzáadott alapértelmezett naplózási szolgáltatók felülbírálásához hívja meg ClearProviders, és adja hozzá a szükséges naplózási szolgáltatókat. Például a következő kód:

• Meghívja ClearProviders, hogy távolítsa el az összes ILoggerProvider példányt az építőből.
• Hozzáadja a konzol naplózási szolgáltatóját.

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

További szolgáltatók:

• beépített naplózási szolgáltatók
• külső naplózási szolgáltatók.

Naplók létrehozása

Naplók létrehozásához a függőségi injektálási (DI) rendszerből származó ILogger<TCategoryName> objektumot használható.

A következő példa:

• Létrehoz egy naplózót , amely a típus teljes minősített nevének napló kategóriáját használja. A naplókategória egy sztring, amely az egyes naplókhoz van társítva.
• Meghívja LogInformation, hogy Information szinten jelentkezzen be. A Napló szint a naplózott esemény súlyosságát jelzi.

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

Szintek és kategóriák a dokumentum későbbi részében részletesebben ismertetésre kerülnek.

A Blazorkapcsolatos információkért tekintse meg a ASP.NET Core Blazor naplózás.

Naplók létrehozása a fő- és indítási bemutatja, hogyan hozhat létre naplókat Main és Startup.

Naplózás konfigurálása

A naplózási konfigurációt általában a appsettings.{Environment}.json fájlok Logging szakasza biztosítja. A ASP.NET Core-webalkalmazás-sablonok a következő appsettings.Development.json fájlt generálják:

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

Az előző JSON-ban:

• A "Default", "Microsoft"és "Microsoft.Hosting.Lifetime" kategóriák meg vannak adva.
• A "Microsoft" kategória az "Microsoft"kezdetű összes kategóriára vonatkozik. Ez a beállítás például a "Microsoft.AspNetCore.Routing.EndpointMiddleware" kategóriára vonatkozik.
• A "Microsoft" kategória naplózása a Warning vagy magasabb szinten naplóz.
• A "Microsoft.Hosting.Lifetime" kategória pontosabb, mint a "Microsoft" kategória, ezért a "Microsoft.Hosting.Lifetime" kategóriát az "Információ" szintű és annál magasabb szintű naplózásnál rögzítjük.
• Nincs megadva egy adott naplószolgáltató, ezért LogLevel az összes engedélyezett naplózási szolgáltatóra vonatkozik, kivéve a Windows EventLog.

A Logging tulajdonság LogLevel és naplószolgáltatói tulajdonságokkal rendelkezhet. A LogLevel meghatározza a kiválasztott kategóriákhoz naplózandó minimális szintű. Az előző JSON-ban Information és Warning naplószintek vannak megadva. LogLevel a napló súlyosságát jelzi, és 0 és 6 között mozog:

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

Ha egy LogLevel van megadva, a naplózás engedélyezve van a megadott szintű és magasabb szintű üzenetek esetében. Az előző JSON-ban a Default kategória naplózása Information és magasabb értékre történik. A rendszer például naplózza Information, Warning, Errorés Critical üzeneteket. Ha nincs megadva LogLevel, a naplózás alapértelmezés szerint a Information szintre kerül. További információkért lásd: naplószintek.

A szolgáltatói tulajdonság megadhat egy LogLevel tulajdonságot. LogLevel szolgáltató alatt megadja az adott szolgáltatóhoz naplózni kívánt szinteket, és felülbírálja a nem szolgáltatói naplóbeállításokat. Fontolja meg a következő appsettings.json fájlt:

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

Logging.{providername}.LogLevel beállításai felülírják a Logging.LogLevelbeállításait. Az előző JSON-ban a Debug szolgáltató alapértelmezett naplózási szintje Information.

Logging:Debug:LogLevel:Default:Information

Az előző beállítás minden Logging:Debug: kategória Information naplószintét adja meg, kivéve Microsoft.Hosting. Ha egy adott kategória szerepel a listában, az adott kategória felülírja az alapértelmezett kategóriát. Az előző JSON-ban a Logging:Debug:LogLevel kategóriák "Microsoft.Hosting" és "Default" felülbírálják a Logging:LogLevel beállításait.

A minimális naplózási szint meg lehet adni az alábbiak bármelyikéhez:

• Konkrét szolgáltatók: Például Logging:EventSource:LogLevel:Default:Information
• Konkrét kategóriák: Például Logging:LogLevel:Microsoft:Warning
• Minden szolgáltató és minden kategória: Logging:LogLevel:Default:Warning

A naplók, amelyek a minimális szint alatt vannak, nem:

• Átadva a szolgáltatónak.
• Naplózott vagy megjelenített.

Az összes napló letiltásához adja meg LogLevel.None. LogLevel.None értéke 6, ami magasabb, mint LogLevel.Critical (5).

Ha egy szolgáltató támogatja napló hatóköreit, IncludeScopes jelzi, hogy engedélyezve vannak-e. További információért lásd a naplózási hatóköröket

Az alábbi appsettings.json fájl az alapértelmezés szerint engedélyezett összes szolgáltatót tartalmazza:

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

Az előző példában:

• A kategóriák és szintek nem javasolt értékek. A minta az összes alapértelmezett szolgáltató megjelenítésére szolgál.
• A Logging.{providername}.LogLevel beállításai felülírják a Logging.LogLevelbeállításait. A Debug.LogLevel.Default szintje például felülírja a LogLevel.Default.
• A rendszer minden alapértelmezett szolgáltatót alias használ. Minden szolgáltató meghatároz egy alias, amely a konfigurációban használható a teljes típusnév helyett. A beépített szolgáltatók aliasai a következők:
  • Konzol
  • Hibakeresés
  • EventSource
  • EventLog
  • AzureAppServicesFile
  • AzureAppServicesBlob
  • ApplicationInsights

Naplószint beállítása parancssor, környezeti változók és egyéb konfiguráció szerint

A naplószintet bármelyik konfigurációszolgáltatóállíthatja be.

A : elválasztó nem működik a környezeti változók hierarchikus kulcsaival minden platformon. A Bashpéldául nem támogatja a : elválasztójelet. A dupla aláhúzás, __, a következő:

• Minden platform támogatja.
• Automatikusan felváltja egy kettőspont, :.

A következő parancsok:

• Állítsa a Logging:LogLevel:Microsoft környezeti kulcsot a Information értékre Windows rendszeren.
• Tesztelje a beállításokat a ASP.NET Core-webalkalmazás-sablonokkal létrehozott alkalmazás használatakor. A dotnet run parancsot a sethasználata után a projektkönyvtárban kell futtatni.

set Logging__LogLevel__Microsoft=Information
dotnet run

Az előző környezeti beállítás:

• Csak a parancsablakból indított folyamatokban van beállítva.
• A Visual Studióval indított böngészők nem olvassák.

A következő setx parancs a windowsos környezetkulcsot és -értéket is beállítja. A setellentétben a setx beállítások megmaradnak. A /M kapcsoló beállítja a változót a rendszerkörnyezetben. Ha /M nincs használatban, a rendszer beállít egy felhasználói környezeti változót.

setx Logging__LogLevel__Microsoft Information /M

Fontolja meg a következő appsettings.json fájlt:

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

A következő parancs állítja be az előző konfigurációt a környezetben:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

Az Azure App ServiceBeállítások > Konfiguráció lapon válassza az Új alkalmazásbeállítás lehetőséget. Az Azure App Service alkalmazásbeállításai a következők:

• Inaktív állapotban titkosítva és titkosított csatornán keresztül továbbítva.
• Környezeti változókként vannak megadva.

További információ: Azure Apps: Alkalmazáskonfiguráció felülbírálása az Azure Portalhasználatával.

További információ a ASP.NET alapkonfigurációs értékek környezeti változók használatával történő beállításáról: környezeti változók. További információ az egyéb konfigurációs források, például a parancssor, az Azure Key Vault, az Azure App Configuration, az egyéb fájlformátumok és egyebek használatáról: Configuration in ASP.NET Core.

A szűrési szabályok alkalmazása

Amikor létrehoz egy ILogger<TCategoryName> objektumot, a ILoggerFactory objektum szolgáltatónként egyetlen szabályt választ ki, amelyet az adott naplózóra alkalmazni szeretne. Az ILogger-példány által írt összes üzenet a kiválasztott szabályok alapján lesz szűrve. Az elérhető szabályok közül az egyes szolgáltatók és kategóriapárok legspecifikusabb szabálya van kiválasztva.

A következő algoritmust használják minden szolgáltatóhoz, amikor egy adott kategóriához ILogger jön létre:

• Válassza ki a szolgáltatónak vagy aliasának megfelelő összes szabályt. Ha nem található egyezés, jelölje ki azokat a szabályokat, amelyekhez nincs hozzárendelt szolgáltató.
• Az előző lépés eredményéből válassza ki a leghosszabb egyező kategóriaelőtaggal rendelkező szabályokat. Ha nem található egyezés, jelölje ki az összes olyan szabályt, amely nem ad meg kategóriát.
• Ha több szabály van kijelölve, az utolsó egyet vegye figyelembe.
• Ha nincsenek kijelölve szabályok, használja a MinimumLevel.

Naplózási kimenet a dotnet run parancsból és a Visual Studióból

A alapértelmezett naplózási szolgáltatókkal létrehozott naplók jelennek meg:

• A Visual Studióban
  • Hibakereséskor a hibakeresési kimeneti ablakban.
  • A ASP.NET Core Web Server ablakban.
• A konzolablakban, amikor az alkalmazás a dotnet run-val fut.

A "Microsoft" kategóriákkal kezdődő naplók ASP.NET Core-keretrendszerkódból származnak. ASP.NET Core- és alkalmazáskód ugyanazt a naplózási API-t és -szolgáltatókat használja.

Naplókategória

ILogger objektum létrehozásakor kategória van megadva. Ez a kategória szerepel a ILoggeradott példánya által létrehozott minden egyes naplóüzenetben. A kategóriasztring tetszőleges, de a konvenció az osztálynév használata. Egy vezérlőben például a név "TodoApi.Controllers.TodoController"lehet. A ASP.NET Core-webalkalmazások ILogger<T> használatával automatikusan lekérnek egy ILogger-példányt, amely kategóriaként a T teljes típusnevét használja:

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

A kategória explicit megadásához hívja meg a 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.");
    }

A rögzített névvel rendelkező CreateLogger hívása akkor lehet hasznos, ha több metódusban használják, így az események kategóriák szerint rendezhetők.

ILogger<T> egyenértékű azzal, hogy megadjuk Tteljes típusnevét a CreateLogger hívásában.

Naplószint

Az alábbi táblázat a LogLevel értékeket, a kényelmi Log{LogLevel} bővítménymetódusokat és a javasolt használatot sorolja fel:

LogLevel	Érték	Módszer	Leírás
nyomkövetés	0	LogTrace	A legrészletesebb üzeneteket tartalmazza. Ezek az üzenetek bizalmas alkalmazásadatokat tartalmazhatnak. Ezek az üzenetek alapértelmezés szerint le vannak tiltva, és nem szabad engedélyezni őket az éles környezetben.
hibakeresési	1	LogDebug	Hibakereséshez és fejlesztéshez. A nagy mennyiség miatt óvatosan használja termelési környezetben.
Információ	2	LogInformation	Nyomon követi az alkalmazás általános folyamatát. Hosszú távú érték is lehet.
Figyelmeztetés	3	LogWarning	Rendellenes vagy váratlan események esetén. Általában olyan hibákat vagy feltételeket tartalmaznak, amelyek nem okozzák az alkalmazás meghibásodását.
hiba	4	LogError	Olyan hibák és kivételek esetén, amelyek nem kezelhetők. Ezek az üzenetek az aktuális művelet vagy kérés hibáját jelzik, nem pedig alkalmazásszintű hibát.
kritikus	5	LogCritical	Azonnali figyelmet igénylő hibák esetén. Példák: adatvesztési forgatókönyvek, lemezterületen kívül.
Nincs	6		Azt határozza meg, hogy a naplózási kategória ne írjon üzeneteket.

Az előző táblázatban a LogLevel a legalacsonyabbtól a legmagasabb súlyosságig szerepel.

A Log metódus első paramétere, LogLevel, a napló súlyosságát jelzi. Ahelyett, hogy a Log(LogLevel, ...)-t hívnák meg, a fejlesztők többsége a Log{LogLevel} kiterjesztési metódusokat hívja meg. A Log{LogLevel} bővítménymetódusok meghívják a Log metódust, és megadják a LogLevel. A következő két naplózási hívás például funkcionálisan egyenértékű, és ugyanazt a naplót hozza létre:

[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 az eseményazonosító. MyLogEvents része a mintaalkalmazásnak, és a naplóesemény-azonosító szakaszban jelenik meg.

MyDisplayRouteInfo és ToCtxString a Rick.Docs.Samples.RouteInfo NuGet csomag biztosítja. A metódusok Controller és Razor Page útvonaladatokat jelenítenek meg.

A következő kód Information és Warning naplókat hoz létre:

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

Az előző kódban az első Log{LogLevel} paraméter (MyLogEvents.GetItem) a naplóesemény-azonosító. A második paraméter egy üzenetsablon, amely a fennmaradó metódusparaméterek által biztosított argumentumértékek helyőrzőit tartalmazza. A metódusparamétereket a dokumentum későbbi részében üzenetsablon ismerteti.

Hívja meg a megfelelő Log{LogLevel} metódust annak szabályozásához, hogy mennyi naplókimenet legyen megírva egy adott tárolóeszközre. Például:

• Éles üzem:
  • A Trace vagy Information szintű naplózás nagy mennyiségű részletes naplóüzenetet eredményez. A költségek ellenőrzése és az adattárolási korlátok elkerülése érdekében naplózza a Trace és Information szintű üzeneteket egy nagy mennyiségű, alacsony költségű adattárba. Fontolja meg a Trace és Information adott kategóriákra való korlátozását.
  • A Warning és Critical szinteken történő naplózásnak kevés naplóüzenetet kell létrehoznia.
    • A költségek és a tárolási korlátok általában nem jelentenek problémát.
    • A kevés napló nagyobb rugalmasságot biztosít az adattárak választásában.
• Fejlesztés alatt:
  • Állítsa be a Warning.
  • Hibaelhárításkor Trace vagy Information üzeneteket adhat hozzá. A kimenet korlátozásához állítsa be Trace vagy Information csak a vizsgált kategóriákra.

ASP.NET Core naplókat ír a keretrendszereseményekhez. Vegyük például a következő naplókimenetet:

• A ASP.NET Core-sablonokkal létrehozott Razor Pages-alkalmazás.
• Naplózás beállítása Logging:Console:LogLevel:Microsoft:Information
• Navigálás a Privacy lapra:

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

A következő JSON beállítja Logging:Console:LogLevel:Microsoft:Information:

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

Naplóesemény azonosítója

Minden napló megadhat egy eseményazonosítót. A mintaalkalmazás a MyLogEvents osztály használatával határozza meg az eseményazonosítókat:

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

Az eseményazonosító események egy készletét társítja. Előfordulhat például, hogy a lapon lévő elemek listájának megjelenítéséhez kapcsolódó összes napló 1001 lehet.

A naplózási szolgáltató tárolhatja az eseményazonosítót egy azonosító mezőben, a naplózási üzenetben, vagy egyáltalán nem. A hibakeresési szolgáltató nem jeleníti meg az eseményazonosítókat. A konzolszolgáltató zárójelben jeleníti meg az eseményazonosítókat a kategória után:

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

Egyes naplózási szolgáltatók egy mezőben tárolják az eseményazonosítót, amely lehetővé teszi az azonosítóra való szűrést.

Naplóüzenet-sablon

Minden napló API egy üzenetsablont használ. Az üzenetsablon tartalmazhat helyőrzőket, amelyek argumentumai meg vannak adva. Használja a helyőrzők nevét, és ne a számokat.

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

A paraméterek sorrendje, nem pedig a helyőrzők nevei határozzák meg, hogy mely paraméterek használhatók helyőrző értékek megadására a naplóüzenetekben. Az alábbi kódban a paraméternevek sorrenden kívül vannak az üzenetsablon helyőrzőiben:

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

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

A paraméterek azonban a következő sorrendben vannak hozzárendelve a helyőrzőkhöz: apples, pears, bananas. A naplóüzenet aparaméterek sorrendjét tükrözi:

Parameters: 1, 2, 3

Ezzel a módszerrel a naplózási szolgáltatók szemantikai vagy strukturált naplózásiimplementálhatók. Maguk az argumentumok a naplózási rendszernek lesznek átadva, nem csak a formázott üzenetsablonnak. Ez lehetővé teszi, hogy a naplózási szolgáltatók mezőként tárolják a paraméterértékeket. Vegyük például a következő naplózó metódust:

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

Például az Azure Table Storage-ba való naplózáskor:

• Minden Azure Table-entitás rendelkezhet ID és RequestTime tulajdonságokkal.
• A tulajdonságokkal rendelkező táblák leegyszerűsítik a naplózott adatok lekérdezését. Egy lekérdezés például egy adott RequestTime tartomány összes naplóját megkeresheti anélkül, hogy elemeznie kellene a szöveges üzenetből eltelt időt.

Naplózási kivételek

A naplózó metódusok túlterheléssel rendelkeznek, amelyek kivételparamétert vesznek fel:

[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 és ToCtxString a Rick.Docs.Samples.RouteInfo NuGet csomag biztosítja. A metódusok Controller és Razor Page útvonaladatokat jelenítenek meg.

A kivételnaplózás szolgáltatóspecifikus.

Alapértelmezett naplószint

Ha az alapértelmezett naplószint nincs beállítva, az alapértelmezett naplószint értéke Information.

Vegyük például a következő webalkalmazást:

• A ASP.NET webalkalmazás-sablonokkal készült.
• appsettings.json és appsettings.Development.json törölve vagy átnevezve.

Az előző beállítással, amikor az adatvédelmi vagy a kezdőlap oldalra navigálunk, számos Trace, Debugés Information üzenet jelenik meg, a Microsoft kategórianév alatt.

Az alábbi kód állítja be az alapértelmezett naplószintet, ha az alapértelmezett naplószint nincs beállítva a konfigurációban:

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

A naplószinteket általában a konfigurációban kell megadni, és nem a kódban.

Szűrőfüggvény

A rendszer meghív egy szűrőfüggvényt minden olyan szolgáltatóhoz és kategóriához, amely nem rendelkezik hozzájuk konfiguráció vagy kód alapján hozzárendelt szabályokkal:

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

Az előző kód akkor jeleníti meg a konzolnaplókat, ha a kategória Controller vagy Microsoft tartalmaz, és a naplószint Information vagy magasabb.

A naplószinteket általában a konfigurációban kell megadni, és nem a kódban.

ASP.NET Core és EF Core kategóriák

Az alábbi táblázat a ASP.NET Core és az Entity Framework Core által használt kategóriákat tartalmazza a naplókkal kapcsolatos megjegyzésekkel:

Kategória	Jegyzetek
Microsoft.AspNetCore	Általános ASP.NET alapvető diagnosztikák.
Microsoft.AspNetCore.DataProtection	Mely kulcsokat vették figyelembe, találták és használták.
Microsoft.AspNetCore.HostFiltering	Gazdagépek engedélyezve.
Microsoft.AspNetCore.Hosting	Mennyi ideig tartottak a HTTP-kérések befejeződése és mikor kezdődtek. Melyik indítási szerelvényeket üzemelteti a rendszer.
Microsoft.AspNetCore.Mvc	MVC és Razor diagnosztika. Modell összekapcsolás, Szűrők végrehajtása, Nézetfordítás, Akció kiválasztása.
Microsoft.AspNetCore.Routing	Útvonalegyeztetési információk.
Microsoft.AspNetCore.Server	Kapcsolat indítására, leállítására és életben tartására vonatkozó válaszok. HTTPS-tanúsítvány adatai.
Microsoft.AspNetCore.StaticFiles	Kiszolgált fájlok.
Microsoft.EntityFrameworkCore	Általános Entity Framework Core-diagnosztikák. Adatbázis-tevékenység és -konfiguráció, változásészlelés, migrálás.

Ha további kategóriákat szeretne megtekinteni a konzolablakban, állítsa appsettings.Development.json a következőkre:

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

Naplózási hatáskörök

A hatókörök logikai műveletek halmazát csoportosíthatják. Ezzel a csoportosítással ugyanazokat az adatokat csatolhatja a csoport részeként létrehozott naplókhoz. A tranzakció feldolgozása során létrehozott naplók például tartalmazhatják a tranzakcióazonosítót.

Hatókör:

• A BeginScope metódus által visszaadott IDisposable típus.
• Addig tart, amíg el nem távolítják.

A következő szolgáltatók támogatják a hatóköröket:

• Console
• AzureAppServicesFile és AzureAppServicesBlob

Használjon hatókört a naplózóhívások using blokkban való becsomagolásával.

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

Beépített naplózási szolgáltatók

ASP.NET Core a következő naplózási szolgáltatókat tartalmazza a megosztott keretrendszer részeként:

• konzol
• hibakeresés
• EventSource
• EventLog

Az alábbi naplózási szolgáltatókat a Microsoft szállítja, de nem a megosztott keretrendszer részeként. Ezeket további nugetként kell telepíteni.

• AzureAppServicesFile és AzureAppServicesBlob
• ApplicationInsights

ASP.NET Core nem tartalmaz naplózási szolgáltatót a naplók fájlokba való írásához. Ha naplókat szeretne írni egy ASP.NET Core-alkalmazásból származó fájlokba, fontolja meg egy külső naplózási szolgáltatóhasználatát.

Az ASP.NET Core modul stdout-al és hibakeresési naplózásával kapcsolatos információkért tekintse meg az Azure App Service és IIS ASP.NET Core hibaelhárítását valamint az IIS ASP.NET Core modul (ANCM) útmutatót.

Konzol

A Console szolgáltató naplózza a kimenetet a konzolon. További információért a Console naplók fejlesztési környezetben történő megtekintéséről, tekintse meg a dotnet run és a Visual Studionaplózási kimenetét.

Hibakeresés

A Debug szolgáltató naplókimenetet ír a System.Diagnostics.Debug osztály használatával. A Debug szolgáltatót érintik a System.Diagnostics.Debug.WriteLine írására irányuló hívások.

Linuxon a Debug szolgáltató naplójának helye disztribúciófüggő, és az alábbiak egyike lehet:

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

Eseményforrás

A EventSource szolgáltató Microsoft-Extensions-Loggingnevű platformfüggetlen eseményforrásba ír. Windows rendszeren a szolgáltató ETWhasznál.

dotnet nyomkövető eszközök

A dotnet-trace eszköz egy platformfüggetlen cli globális eszköz, amely lehetővé teszi egy futó folyamat .NET Core-nyomkövetéseinek gyűjtését. Az eszköz Microsoft.Extensions.Logging.EventSource szolgáltatói adatokat gyűjt egy LoggingEventSourcehasználatával.

A telepítési utasításokért tekintse meg dotnet-trace.

A dotnet nyomkövetési eszközével nyomkövetést gyűjthet egy alkalmazásból:

1. Futtassa az alkalmazást a dotnet run paranccsal.

2. A .NET Core-alkalmazás folyamatazonosítójának (PID) meghatározása:

   dotnet trace ps
   

   Keresse meg annak a folyamatnak a PID-jét, amelynek neve megegyezik az alkalmazás szerelvényével.

3. Hajtsa végre a dotnet trace parancsot.

   Általános parancsszintaxis:

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

   PowerShell-parancshéj használatakor a --providers értéket egyetlen idézőjelbe (') foglalja:

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

   A nem Windows rendszerű platformokon adja hozzá a -f speedscope beállítást a kimeneti nyomkövetési fájl formátumának speedscope-re történő megváltoztatásához.

   A kulcsszót az alábbi táblázat határozza meg:

   Kulcsszó	Leírás
   1	A LoggingEventSource-vel kapcsolatos metaesemények naplózása. Nem naplózza a ILoggereseményeket.
   2	Bekapcsolja a Message eseményt ILogger.Log() meghívásakor. Programozott (nem formázott) módon nyújt információkat.
   4	Bekapcsolja a FormatMessage eseményt ILogger.Log() meghívásakor. Az információk formázott sztringverzióját adja meg.
   8	Bekapcsolja a MessageJson eseményt ILogger.Log() meghívásakor. JSON-ábrázolást biztosít az argumentumokról.

   Az alábbi táblázat a szolgáltatói szinteket sorolja fel:

   Szolgáltatói szint	Leírás
   0	LogAlways
   1	Critical
   2	Error
   3	Warning
   4	Informational
   5	Verbose

   Egy kategóriaszint elemzése lehet akár karakterlánc, akár szám.

   Kategória nevesített érték	Számérték
   Trace	0
   Debug	1
   Information	2
   Warning	3
   Error	4
   Critical	5

   A szolgáltatói szint és a kategóriaszint:

   • Fordított sorrendben vannak.
   • A karakterlánc-állandók nem mind azonosak.

   Ha nincs megadva FilterSpecs, akkor a EventSourceLogger implementáció megkísérli a szolgáltatói szintet kategóriaszintté alakítani, és minden kategóriára alkalmazza.

   Szolgáltatói szint	Kategóriaszint
   Verbose(5)	Debug(1)
   Informational(4)	Information(2)
   Warning(3)	Warning(3)
   Error(2)	Error(4)
   Critical(1)	Critical(5)

   Ha FilterSpecs van megadva, a listában szereplő kategóriák az ott kódolt kategóriaszintet használják, az összes többi kategóriát pedig kiszűri a rendszer.

   A következő példák feltételezik:

   • Egy alkalmazás fut, és meghívja logger.LogDebug("12345").
   • A folyamatazonosító (PID) set PID=12345lett beállítva, ahol 12345 a tényleges PID.

   Vegye figyelembe a következő parancsot:

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

   Az előző parancs:

   • Rögzíti a hibakeresési üzeneteket.
   • Nem alkalmazza a FilterSpecs-t.
   • Az 5. szintet adja meg, amely a Debug kategóriához tartozik.

   Vegye figyelembe a következő parancsot:

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

   Az előző parancs:

   • Nem rögzíti a hibakeresési üzeneteket, mert az 5. kategóriaszint Critical.
   • Egy FilterSpecsbiztosít.

   Az alábbi parancs a hibakeresési üzeneteket rögzíti, mert az 1-es kategóriaszint adja meg Debug.

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

   Az alábbi parancs rögzíti a hibakeresési üzeneteket, mert a kategória Debughatároz meg.

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

   FilterSpecs {Logger Category} és {Category Level} bejegyzései további naplószűrési feltételeket jelölnek. Különítse el FilterSpecs bejegyzéseket a ; pontosvesszővel.

   Példa Windows-parancshéj használatával:

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

   Az előző parancs aktiválódik:

   • Az eseményforrás naplózási eszköz formázott karakterláncokat (4) hoz létre a hibákhoz (2).
   • A Microsoft.AspNetCore.Hosting naplózás a Informational naplózási szinten (4) történik.

4. Állítsa le a dotnet nyomkövetési eszközét az Enter billentyű vagy a Ctrl+C billentyűkombináció lenyomásával.

   A nyomkövetés trace.nettrace néven lesz mentve abban a mappában, amelyben a dotnet trace parancs végrehajtása történik.

5. Nyissa meg a Perfview nyomkövetési eszközt . Nyissa meg a trace.nettrace fájlt, és vizsgálja meg a nyomkövetési eseményeket.

Ha az alkalmazás nem építi fel a gazdagépet a CreateDefaultBuilderhasználatával, adja hozzá az eseményforrást az alkalmazás naplózási konfigurációjához.

További információ:

• Nyomkövetés teljesítményelemzési segédprogramhoz (dotnet-trace) (.NET Core-dokumentáció)
• Nyomkövetés teljesítményanalízis segédprogramhoz (dotnet-trace) (dotnet/diagnostics GitHub-adattár dokumentációja)
• LoggingEventSource osztály (.NET API Browser)
• EventLevel
• LoggingEventSource referenciaforrás (3.0): Ha másik verzióhoz szeretne referenciaforrást beszerezni, módosítsa az ágat release/{Version}értékre, ahol {Version} az ASP.NET Core kívánt verziója.
• Perfview: Hasznos eseményforrás-nyomkövetések megtekintéséhez.

Perfview

A naplók gyűjtéséhez és megtekintéséhez használja a PerfView segédprogramot. Vannak más eszközök is az ETW-naplók megtekintéséhez, de a PerfView biztosítja a legjobb élményt az ASP.NET Core által kibocsátott ETW-eseményekhez.

Ha konfigurálni szeretné a PerfView-t a szolgáltató által naplózott események gyűjtéséhez, adja hozzá a *Microsoft-Extensions-Logging sztringet a További szolgáltatók listához. Ne hagyja ki a * a szöveg elején.

Windows eseménynapló

A EventLog szolgáltató naplókimenetet küld a Windows-eseménynaplónak. A többi szolgáltatótól eltérően a EventLog szolgáltató nem örökölni az alapértelmezett nem szolgáltatói beállításokat. Ha naplóbeállítások nincsenek megadva, akkor alapértelmezetten a LogLevel.Warningszintre állnak .

A LogLevel.Warningalatti események naplózásához explicit módon állítsa be a naplószintet. Az alábbi példa beállítja az eseménynapló alapértelmezett naplószintjét LogLevel.Information-ra:

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

A AddEventLog túlterhelések be tudják fogadni a EventLogSettingsparamétereket. Ha null vagy nincs megadva, a rendszer a következő alapértelmezett beállításokat használja:

• LogName: "Alkalmazás"
• SourceName: ".NET Runtime"
• MachineName: A rendszer a helyi gép nevét használja.

Az alábbi kód a SourceName az alapértelmezett ".NET Runtime" értékről MyLogsértékre módosítja:

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

A Microsoft.Extensions.Logging.AzureAppServices szolgáltatói csomag naplókat ír egy Azure App Service-alkalmazás fájlrendszerében lévő szövegfájlokba, és egy Azure Storage-fiókban blobtároló.

A szolgáltatói csomag nem szerepel a megosztott keretrendszerben. A szolgáltató használatához adjon hozzá egy megfelelő csomagot a projekthez.

A szolgáltatói beállítások konfigurálásához használja a AzureFileLoggerOptions és a AzureBlobLoggerOptions, ahogyan az alábbi példában látható:

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

Az Azure App Service-be való telepítéskor az alkalmazás az Azure-portál App Service oldalának App Service-naplók szakaszában található beállításokat használja. A következő beállítások frissítésekor a módosítások azonnal érvénybe lépnek az alkalmazás újraindítása vagy újbóli üzembe helyezése nélkül.

• alkalmazásnaplózás (fájlrendszer)
• alkalmazásnaplózás (Blob)

A naplófájlok alapértelmezett helye a D:\home\LogFiles\Application mappában található, az alapértelmezett fájlnév pedig diagnostics-yyyymmdd.txt. Az alapértelmezett fájlméretkorlát 10 MB, a megtartott fájlok alapértelmezett maximális száma pedig 2. Az alapértelmezett blobnév {app-name}{timestamp}/yyyyy/mm/dd/hh/{guid}-applicationLog.txt.

Ez a szolgáltató csak akkor naplóz, ha a projekt az Azure-környezetben fut.

Azure-naplóstreamelés

Az Azure-naplóstreamelés támogatja a naplótevékenység valós idejű megtekintését a következőből:

• Az alkalmazáskiszolgáló
• A webkiszolgáló
• Sikertelen kérelemkövetés

Az Azure-naplóstreamelés konfigurálása:

• Navigáljon a App Service-naplók lapra az alkalmazás portállapjáról.
• Állítsa alkalmazásnaplózási (fájlrendszer).
• Válassza ki a napló szintet. Ez a beállítás csak az Azure-naplóstreamelésre vonatkozik.

A naplók megtekintéséhez lépjen a Naplóstream oldalra. A naplózott üzeneteket a rendszer a ILogger felülettel naplózza.

Azure Application Insights

A Microsoft.Extensions.Logging.ApplicationInsights csomag naplókat ír azAzure Application Insights szolgáltatásba. Az Application Insights egy webalkalmazást figyelő szolgáltatás, amely eszközöket biztosít a telemetriai adatok lekérdezéséhez és elemzéséhez. Ha ezt a szolgáltatót használja, az Application Insights eszközeivel lekérdezheti és elemezheti a naplókat.

A naplózási szolgáltató a Microsoft.ApplicationInsights.AspNetCorefüggősége, amely az ASP.NET Core összes elérhető telemetriáját biztosító csomag. Ha ezt a csomagot használja, nem kell telepítenie a szolgáltatói csomagot.

A Microsoft.ApplicationInsights.Web csomag ASP.NET 4.x verzióhoz készült, nem pedig ASP.NET Core-hoz.

További információ:

• Application Insights áttekintése
• Application Insights ASP.NET Core-alkalmazásokhoz – Itt kezdheti el, ha az Application Insights telemetriai adatainak teljes körét szeretné implementálni a naplózással együtt.
• ApplicationInsightsLoggerProvider for .NET Core ILogger logs – Itt kezdheti el, ha a naplózási szolgáltatót az Application Insights többi telemetriai adatai nélkül szeretné implementálni.
• Application Insights-naplózási adapterek.
• Az Application Insights SDK telepítése, konfigurálása és inicializálása interaktív oktatóanyag.

Külső naplózási szolgáltatók

A ASP.NET Core használatával működő külső naplózási keretrendszerek:

• elmah.io (GitHub-adattár)
• Gelf (GitHub-adattár)
• JSNLog (GitHub-adattár)
• KissLog.net (GitHub-adattár)
• Log4Net (GitHub-adattár)
• NLog (GitHub-adattár)
• PLogger (GitHub-adattár)
• Sentry (GitHub-adattár)
• Serilog (GitHub-adattár)
• Stackdriver (GitHub-adattár)

Egyes külső keretrendszerek képesek végrehajtani szemantikai naplózást, más néven strukturált naplózást.

A külső keretrendszerek használata hasonló az egyik beépített szolgáltatóhoz:

1. NuGet-csomag hozzáadása a projekthez.
2. Hívja meg a naplózási keretrendszer által biztosított ILoggerFactory bővítménymetódust.

További információkért tekintse meg az egyes szolgáltatók dokumentációját. A Microsoft nem támogatja a külső naplózási szolgáltatókat.

Nem hoszt konzolalkalmazás

Az általános gazdagép nem webkonzol-alkalmazásokban való használatára vonatkozó példát a Háttérfeladatok mintaalkalmazásProgram.cs fájljában tekintheti meg (Háttérfeladatok az ASP.NET Coreüzemeltetett szolgáltatásaival).

Az általános gazdagép nélküli alkalmazások naplózási kódja eltér a szolgáltatók hozzáadásának módjától, és naplózók létrehozása.

Naplózási szolgáltatók

Egy különálló konzolalkalmazásban hívja meg a szolgáltató Add{provider name} kiterjesztési metódusát, miközben létrehoz egy LoggerFactory-et.

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

Naplók létrehozása

Naplók létrehozásához használjon ILogger<TCategoryName> objektumot. Használja a LoggerFactory-t egy ILoggerlétrehozásához.

Az alábbi példa létrehoz egy naplózót, amelynek a kategóriája LoggingConsoleApp.Program.

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

Az alábbi példában a naplózót használjuk a Information szinttel rendelkező naplók létrehozásához. A Napló szint a naplózott esemény súlyosságát jelzi.

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

szintek és kategóriákat részletesebben ebben a dokumentumban ismertetjük.

Naplózás a gazdagép építése alatt

A gazdagép építése során végzett naplózás közvetlenül nem támogatott. Azonban külön naplózó is használható. Az alábbi példában egy Serilog-naplózót használunk a CreateHostBuildervaló bejelentkezéshez. AddSerilog a Log.Loggermegadott statikus konfigurációt használja:

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

Az ILoggertől függő szolgáltatás konfigurálása

A naplózó konstruktoros injektálása a Startup-ba az ASP.NET Core korábbi verzióiban működik, mivel a Web Host számára külön DI konténer jön létre. További információkért arról, hogy miért csak egy tároló kerül létrehozásra a Generic Hosthoz, tekintse meg a kompatibilitástörő változás bejelentését.

A ILogger<T>függő szolgáltatás konfigurálásához konstruktorinjektálást használjon, vagy adjon meg egy gyári módszert. A gyári módszer megközelítése csak akkor ajánlott, ha nincs más lehetőség. Vegyük például azt a szolgáltatást, amely a DI által biztosított ILogger<T>-példányt igényli:

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

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

Az előző kiemelt kód egy Func<T,TResult>, amely az első alkalommal fut, amikor a DI-tárolónak létre kell készítenie a MyServiceegy példányát. A regisztrált szolgáltatások bármelyikét így érheti el.

Naplók létrehozása a Mainban

A következő kód naplózása Main betöltése után egy ILogger példány lekérésével a DI-ből a gazdagép létrehozása után történik.

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

Naplók létrehozása indításkor

A következő kód naplókat ír 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();
    });
}

A naplók írása a DI-tároló beállítása előtt a Startup.ConfigureServices metódusban nem támogatott:

• A Startup konstruktorba történő loggerinjektálás nem támogatott.
• A Startup.ConfigureServices metódus aláírásába történő logger-injektálás nem támogatott

Ennek a korlátozásnak az az oka, hogy a naplózás a diától és a konfigurációtól függ, ami viszont a DI-től függ. A DI-tároló nincs beállítva, amíg ConfigureServices be nem fejeződik.

A ILogger<T>-ra támaszkodó szolgáltatás konfigurálásával vagy a Startup-be történő naplózó konstruktorinjektálásának okával kapcsolatos információkért a korábbi verziókban lásd: Az ILogger- függő szolgáltatás konfigurálása.

Nincs aszinkron naplózó metódus

A naplózásnak olyan gyorsnak kell lennie, hogy nem éri meg az aszinkron kód teljesítményköltségét. Ha egy naplózási adattár lassú, ne írjon közvetlenül hozzá. Érdemes lehet először egy gyorstárolóba írni a naplóüzeneteket, majd később áthelyezni őket a lassú tárolóba. Ha például az SQL Serverre jelentkezik be, ne tegye ezt közvetlenül egy Log metódusban, mivel a Log metódusok szinkronban vannak. Ehelyett szinkronizálva adjon hozzá naplóüzeneteket egy memórián belüli üzenetsorhoz, és egy háttérmunkás húzza ki az üzeneteket az üzenetsorból, hogy elvégezhesse az adatok SQL Serverbe való leküldésének aszinkron munkáját. További információ: GitHub-probléma.

Naplószintek módosítása futó alkalmazásokban

A Naplózási API nem tartalmaz olyan forgatókönyvet, amely megváltoztathatja a naplószinteket egy alkalmazás futtatása közben. Egyes konfigurációszolgáltatók azonban képesek újra betölteni a konfigurációt, ami azonnali hatással van a naplózási konfigurációra. Például a fájlkonfigurációs szolgáltató, alapértelmezés szerint újra betölti a naplózási konfigurációt. Ha egy alkalmazás futtatása közben a konfiguráció módosul a kódban, az alkalmazás meghívhatja IConfigurationRoot.Reload az alkalmazás naplózási konfigurációjának frissítéséhez.

ILogger és ILoggerFactory

A .NET Core SDK tartalmazza a ILogger<TCategoryName> és ILoggerFactory interfészeket és implementációkat. A következő NuGet-csomagokban is elérhetők:

• A felületek a Microsoft.Extensions.Logging.Abstractionstalálhatók.
• Az alapértelmezett implementációk a Microsoft.Extensions.Loggingtalálhatók.

Naplószűrő szabályok alkalmazása a kódban

A naplószűrő szabályok beállításának előnyben részesített módszere Konfigurációshasználata.

Az alábbi példa bemutatja, hogyan regisztrálhat szűrőszabályokat a kódban:

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) meghatározza a System kategóriát és a Debugnaplószintet. A szűrő az összes szolgáltatóra vonatkozik, mert egy adott szolgáltató nincs konfigurálva.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) a következőt adja meg:

• A Debug naplózási szolgáltató.
• Naplószint Information és magasabb.
• Az összes "Microsoft"-val kezdődő kategória.

Hatókör automatikus naplózása SpanId, TraceId és ParentId azonosítóval

A naplózási könyvtárak implicit módon létrehoznak egy hatókörobjektumot a SpanId, TraceIdés ParentIdmellett. Ez a viselkedés ActivityTrackingOptionskeresztül van konfigurálva.

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

Ha a traceparent http-kérelem fejléce be van állítva, a napló hatókörében lévő ParentId megjeleníti a W3C parent-id a bejövő traceparent fejlécből, míg a napló hatókörében lévő SpanId pedig megmutatja a következő kimenő lépés/időtartam frissített parent-id-jét. További információkért lásd: A traceparent mezőmódosítása.

Egyéni naplózó létrehozása

Egyéni naplózó létrehozásához lásd: Egyéni naplózási szolgáltató implementálása a .NET-.

További erőforrások

• Nagy teljesítményű naplózás
• A naplózási hibákat a github.com/dotnet/runtime/ adattárban kell létrehozni.
• ASP.NET Core Blazor naplózás