Training
Module
Alfanumerieke gegevens opmaken voor weergave in C# - Training
Verken basismethoden in C# om alfanumerieke gegevens op te maken.
Deze browser wordt niet meer ondersteund.
Upgrade naar Microsoft Edge om te profiteren van de nieuwste functies, beveiligingsupdates en technische ondersteuning.
.NET biedt ondersteuning voor hoge prestaties, gestructureerde logboekregistratie via de ILogger API om het gedrag van toepassingen te bewaken en problemen te diagnosticeren. Logboeken kunnen naar verschillende bestemmingen worden geschreven door verschillende logboekregistratieproviders te configureren. Basisproviders voor logboekregistratie zijn ingebouwd en er zijn ook veel externe providers beschikbaar.
In dit eerste voorbeeld ziet u de basisbeginselen, maar deze is alleen geschikt voor een triviale console-app. Deze voorbeeldconsole-app is afhankelijk van de volgende NuGet-pakketten:
In de volgende sectie ziet u hoe u de code kunt verbeteren, rekening houdend met schalen, prestaties, configuratie en typische programmeerpatronen.
using Microsoft.Extensions.Logging;
using ILoggerFactory factory = LoggerFactory.Create(builder => builder.AddConsole());
ILogger logger = factory.CreateLogger("Program");
logger.LogInformation("Hello World! Logging is {Description}.", "fun");
Het voorgaande voorbeeld:
ILoggerFactory
configuraties die bepalen waar logboekberichten worden verzonden, worden opgeslagen. In dit geval configureert u de provider voor consolelogboekregistratie, zodat logboekberichten naar de console worden geschreven.string
categorie die is gekoppeld aan elk bericht dat door het ILogger
object is geregistreerd. Het wordt gebruikt om logboekberichten van dezelfde klasse (of categorie) samen te groeperen bij het zoeken of filteren van logboeken.Information
niveau te registreren. Het logboekniveau geeft de ernst van de vastgelegde gebeurtenis aan en wordt gebruikt om minder belangrijke logboekberichten te filteren. De logboekvermelding bevat ook een berichtsjabloon "Hello World! Logging is {Description}."
en een sleutel-waardepaar Description = fun
. De sleutelnaam (of tijdelijke aanduiding) komt van het woord in de accolades in de sjabloon en de waarde komt uit het resterende methodeargument.Dit projectbestand voor dit voorbeeld bevat twee NuGet-pakketten:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net8.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.0" />
<PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.0" />
</ItemGroup>
</Project>
Tip
Alle voorbeeldbroncode voor logboekregistratie is beschikbaar in de voorbeeldenbrowser om te downloaden. Zie Bladeren in codevoorbeelden: Logboekregistratie in .NET voor meer informatie.
Er zijn verschillende wijzigingen die u in het vorige voorbeeld moet aanbrengen wanneer u zich aanmeldt in een minder triviaal scenario:
Als uw toepassing gebruikmaakt van afhankelijkheidsinjectie (DI) of een host zoals ASP. WebApplication of Generic Host van NET moet u deze gebruiken ILoggerFactory
en ILogger
objecten uit hun respectieve DI-containers in plaats van ze rechtstreeks te maken. Zie Integratie met DI en Hosts voor meer informatie.
Het genereren van compileertijdbronnen voor logboekregistratie is meestal een beter alternatief voor ILogger
extensiemethoden zoals LogInformation
. Het genereren van logboekregistratiebronnen biedt betere prestaties, sterker typen en vermijdt het verspreiden van string
constanten in uw methoden. Het nadeel is dat het gebruik van deze techniek wat meer code vereist.
using Microsoft.Extensions.Logging;
internal partial class Program
{
static void Main(string[] args)
{
using ILoggerFactory factory = LoggerFactory.Create(builder => builder.AddConsole());
ILogger logger = factory.CreateLogger("Program");
LogStartupMessage(logger, "fun");
}
[LoggerMessage(Level = LogLevel.Information, Message = "Hello World! Logging is {Description}.")]
static partial void LogStartupMessage(ILogger logger, string description);
}
Type
om deze naamgeving eenvoudig te maken.using Microsoft.Extensions.Logging;
internal class Program
{
static void Main(string[] args)
{
using ILoggerFactory factory = LoggerFactory.Create(builder => builder.AddConsole());
ILogger logger = factory.CreateLogger<Program>();
logger.LogInformation("Hello World! Logging is {Description}.", "fun");
}
}
using Microsoft.Extensions.Logging;
using OpenTelemetry.Logs;
using ILoggerFactory factory = LoggerFactory.Create(builder =>
{
builder.AddOpenTelemetry(logging =>
{
logging.AddOtlpExporter();
});
});
ILogger logger = factory.CreateLogger("Program");
logger.LogInformation("Hello World! Logging is {Description}.", "fun");
Als uw toepassing gebruikmaakt van afhankelijkheidsinjectie (DI) of een host zoals ASP. WebApplication of Generic Host van NET moet u en objecten uit de DI-container gebruiken ILoggerFactory
ILogger
in plaats van ze rechtstreeks te maken.
In dit voorbeeld wordt een ILogger-object in een gehoste app opgehaald met behulp van ASP.NET Minimale API's:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<ExampleHandler>();
var app = builder.Build();
var handler = app.Services.GetRequiredService<ExampleHandler>();
app.MapGet("/", handler.HandleRequest);
app.Run();
partial class ExampleHandler(ILogger<ExampleHandler> logger)
{
public string HandleRequest()
{
LogHandleRequest(logger);
return "Hello World";
}
[LoggerMessage(LogLevel.Information, "ExampleHandler.HandleRequest was called")]
public static partial void LogHandleRequest(ILogger logger);
}
Het voorgaande voorbeeld:
ExampleHandler
en toegewezen om de ExampleHandler.HandleRequest
functie uit te voeren.ILogger<ExampleHandler>
. ILogger<TCategoryName> is afgeleid van ILogger en geeft aan welke categorie het ILogger
object heeft. De DI-container zoekt een ILogger
met de juiste categorie en levert deze als het constructorargument. Als die categorie nog niet ILogger
bestaat, wordt deze automatisch gemaakt vanuit de ILoggerFactory
serviceprovider.logger
parameter die in de constructor is ontvangen, is gebruikt voor logboekregistratie in de HandleRequest
functie.Hostbouwers initialiseren de standaardconfiguratie en voegen vervolgens een geconfigureerd ILoggerFactory
object toe aan de DI-container van de host wanneer de host wordt gebouwd. Voordat de host wordt gebouwd, kunt u de configuratie van logboekregistratie aanpassen via HostApplicationBuilder.Logging, WebApplicationBuilder.Loggingof vergelijkbare API's op andere hosts. Hosts passen ook logboekconfiguratie van standaardconfiguratiebronnen toe als appsettings.json en omgevingsvariabelen. Zie Configuratie in .NET voor meer informatie.
In dit voorbeeld wordt de vorige uitgebreid om de ILoggerFactory
aangeboden door WebApplicationBuilder
. Er wordt OpenTelemetry toegevoegd als een logboekregistratieprovider die de logboeken via OTLP (OpenTelemetry protocol) verzendt:
var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddOpenTelemetry(logging => logging.AddOtlpExporter());
builder.Services.AddSingleton<ExampleHandler>();
var app = builder.Build();
Als u een DI-container zonder host gebruikt, gebruikt AddLogging u deze om de container te configureren en toe te voegen ILoggerFactory
.
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
// Add services to the container including logging
var services = new ServiceCollection();
services.AddLogging(builder => builder.AddConsole());
services.AddSingleton<ExampleService>();
IServiceProvider serviceProvider = services.BuildServiceProvider();
// Get the ExampleService object from the container
ExampleService service = serviceProvider.GetRequiredService<ExampleService>();
// Do some pretend work
service.DoSomeWork(10, 20);
class ExampleService(ILogger<ExampleService> logger)
{
public void DoSomeWork(int x, int y)
{
logger.LogInformation("DoSomeWork was called. x={X}, y={Y}", x, y);
}
}
Het voorgaande voorbeeld:
ILoggerFactory
geconfigureerde schrijfbewerking naar de consoleExampleService
toegevoegd aan de containerExampleService
DI-container die ook automatisch een ILogger<ExampleService>
te gebruiken als constructorargument heeft gemaakt.ExampleService.DoSomeWork
Aangeroepen waarmee een ILogger<ExampleService>
bericht is vastgelegd in de console.Configuratie van logboekregistratie wordt ingesteld in code of via externe bronnen, zoals configuratiebestanden en omgevingsvariabelen. Het gebruik van externe configuratie is nuttig indien mogelijk, omdat deze kan worden gewijzigd zonder de toepassing opnieuw te bouwen. Sommige taken, zoals het instellen van logboekregistratieproviders, kunnen echter alleen worden geconfigureerd vanuit code.
Voor apps die een host gebruiken, wordt de configuratie van logboekregistratie meestal aangeboden door de "Logging"
sectie appsettings.{Environment}
.json-bestanden. Voor apps die geen host gebruiken, worden externe configuratiebronnen expliciet ingesteld of geconfigureerd in code .
De volgende appsettings. Development.json bestand wordt gegenereerd door de .NET Worker-servicesjablonen:
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
}
}
In de voorgaande JSON:
"Default"
categorieën en "Microsoft"
"Microsoft.Hosting.Lifetime"
logboekniveaus worden opgegeven."Default"
waarde wordt toegepast op alle categorieën die niet anders zijn opgegeven, waardoor alle standaardwaarden voor alle categorieën "Information"
effectief worden gemaakt. U kunt dit gedrag overschrijven door een waarde voor een categorie op te geven."Microsoft"
categorie is van toepassing op alle categorieën die beginnen met "Microsoft"
."Microsoft"
categorielogboeken op logboekniveau van Warning
en hoger."Microsoft.Hosting.Lifetime"
categorie is specifieker dan de "Microsoft"
categorie, dus de "Microsoft.Hosting.Lifetime"
categorielogboeken op logboekniveau "Information"
en hoger.LogLevel
geldt dit voor alle ingeschakelde logboekregistratieproviders, met uitzondering van het Windows-gebeurtenislogboek.De Logging
eigenschap kan eigenschappen van de provider hebben LogLevel en vastleggen. Hiermee LogLevel
geeft u het minimumniveau op dat moet worden vastgelegd voor geselecteerde categorieën. In de voorgaande JSON Information
worden logboekniveaus Warning
opgegeven. LogLevel
geeft de ernst van het logboek aan en varieert van 0 tot 6:
Trace
= 0, Debug
= 1, Information
= 2, Warning
= 3, Error
= 4, Critical
= 5 en None
= 6.
Wanneer een LogLevel
opgegeven is, wordt logboekregistratie ingeschakeld voor berichten op het opgegeven niveau en hoger. In de voorgaande JSON wordt de Default
categorie geregistreerd voor Information
en hoger. Bijvoorbeeld, Information
, Warning
en Error
Critical
berichten worden vastgelegd. Als er geen LogLevel
is opgegeven, wordt logboekregistratie standaard ingesteld op het Information
niveau. Zie Logboekniveaus voor meer informatie.
Een providereigenschap kan een LogLevel
eigenschap opgeven. LogLevel
onder een provider geeft de niveaus op die moeten worden vastgelegd voor die provider en overschrijft de logboekinstellingen die niet van de provider zijn. Houd rekening met het volgende appsettings.json-bestand :
{
"Logging": {
"LogLevel": {
"Default": "Error",
"Microsoft": "Warning"
},
"Debug": {
"LogLevel": {
"Default": "Information",
"Microsoft.Hosting": "Trace"
}
},
"EventSource": {
"LogLevel": {
"Default": "Warning"
}
}
}
}
Instellingen in Logging.{ProviderName}.LogLevel
onderdrukkingsinstellingen in Logging.LogLevel
. In de voorgaande JSON is het standaardlogboekniveau van de Debug
provider ingesteld op Information
:
Logging:Debug:LogLevel:Default:Information
Met de voorgaande instelling wordt het Information
logboekniveau voor elke Logging:Debug:
categorie opgegeven, behalve Microsoft.Hosting
. Wanneer een specifieke categorie wordt weergegeven, overschrijft de specifieke categorie de standaardcategorie. In de voorgaande JSON worden de Logging:Debug:LogLevel
categorieën "Microsoft.Hosting"
overschreven en "Default"
worden de instellingen overschreven in Logging:LogLevel
Het minimale logboekniveau kan worden opgegeven voor een van de volgende:
Logging:EventSource:LogLevel:Default:Information
Logging:LogLevel:Microsoft:Warning
Logging:LogLevel:Default:Warning
Logboeken onder het minimumniveau zijn niet:
Als u alle logboeken wilt onderdrukken, geeft u LogLevel.None op. LogLevel.None
heeft een waarde van 6, die hoger is dan LogLevel.Critical
(5).
Als een provider logboekbereiken ondersteunt, IncludeScopes
geeft u aan of deze zijn ingeschakeld. Zie logboekbereiken voor meer informatie
Het volgende appsettings.json bestand bevat instellingen voor alle ingebouwde providers:
{
"Logging": {
"LogLevel": {
"Default": "Error",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Warning"
},
"Debug": {
"LogLevel": {
"Default": "Information"
}
},
"Console": {
"IncludeScopes": true,
"LogLevel": {
"Microsoft.Extensions.Hosting": "Warning",
"Default": "Information"
}
},
"EventSource": {
"LogLevel": {
"Microsoft": "Information"
}
},
"EventLog": {
"LogLevel": {
"Microsoft": "Information"
}
},
"AzureAppServicesFile": {
"IncludeScopes": true,
"LogLevel": {
"Default": "Warning"
}
},
"AzureAppServicesBlob": {
"IncludeScopes": true,
"LogLevel": {
"Microsoft": "Information"
}
},
"ApplicationInsights": {
"LogLevel": {
"Default": "Information"
}
}
}
}
In het voorgaande voorbeeld:
Logging.{ProviderName}.LogLevel
onderdrukkingsinstellingen in Logging.LogLevel
. Het niveau in het niveau overschrijft Debug.LogLevel.Default
bijvoorbeeld het niveau in LogLevel.Default
.Console
Debug
EventSource
EventLog
AzureAppServicesFile
AzureAppServicesBlob
ApplicationInsights
Logboekniveau kan worden ingesteld door een van de configuratieproviders. U kunt bijvoorbeeld een persistente omgevingsvariabele met de naam Logging:LogLevel:Microsoft
maken met een waarde van Information
.
Maak en wijs persistente omgevingsvariabele toe op basis van de waarde van het logboekniveau.
:: Assigns the env var to the value
setx "Logging__LogLevel__Microsoft" "Information" /M
Lees de omgevingsvariabele in een nieuw exemplaar van de opdrachtprompt.
:: Prints the env var value
echo %Logging__LogLevel__Microsoft%
De voorgaande omgevingsinstelling blijft behouden in de omgeving. Als u de instellingen wilt testen wanneer u een app gebruikt die is gemaakt met de .NET Worker-servicesjablonen, gebruikt u de dotnet run
opdracht in de projectmap nadat de omgevingsvariabele is toegewezen.
dotnet run
Tip
Nadat u een omgevingsvariabele hebt ingesteld, start u uw IDE (Integrated Development Environment) opnieuw op om ervoor te zorgen dat nieuw toegevoegde omgevingsvariabelen beschikbaar zijn.
Selecteer op Azure-app Service de optie Nieuwe toepassingsinstelling op de pagina Instellingenconfiguratie>. Azure-app servicetoepassingsinstellingen zijn:
Gebruik de ILoggingBuilder API om logboekregistratie in code te configureren. Dit kan vanaf verschillende locaties worden geopend:
ILoggerFactory
rechtstreeks maakt, configureert u in LoggerFactory.Create.In dit voorbeeld ziet u hoe u de provider voor consolelogboekregistratie en verschillende filters instelt.
using Microsoft.Extensions.Logging;
using var loggerFactory = LoggerFactory.Create(static builder =>
{
builder
.AddFilter("Microsoft", LogLevel.Warning)
.AddFilter("System", LogLevel.Warning)
.AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
.AddConsole();
});
ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogDebug("Hello {Target}", "Everyone");
In het voorgaande voorbeeld AddFilter wordt het logboekniveau aangepast dat is ingeschakeld voor verschillende categorieën. AddConsole wordt gebruikt om de provider voor consolelogboekregistratie toe te voegen. Logboeken met Debug
ernst zijn standaard niet ingeschakeld, maar omdat de configuratie de filters heeft aangepast, wordt het foutopsporingsbericht Hallo iedereen weergegeven op de console.
Wanneer een ILogger<TCategoryName> object wordt gemaakt, selecteert het ILoggerFactory object één regel per provider die op die logboekregistratie moet worden toegepast. Alle berichten die door een ILogger
exemplaar zijn geschreven, worden gefilterd op basis van de geselecteerde regels. De meest specifieke regel voor elk provider- en categoriepaar is geselecteerd op basis van de beschikbare regels.
Het volgende algoritme wordt gebruikt voor elke provider wanneer een ILogger
wordt gemaakt voor een bepaalde categorie:
Wanneer een ILogger
object wordt gemaakt, wordt er een categorie opgegeven. Deze categorie is opgenomen in elk logboekbericht dat is gemaakt door dat exemplaar van ILogger
. De categorietekenreeks is willekeurig, maar de conventie is het gebruik van de volledig gekwalificeerde klassenaam. In een toepassing met een service die is gedefinieerd als het volgende object, kan de categorie bijvoorbeeld zijn "Example.DefaultService"
:
namespace Example
{
public class DefaultService : IService
{
private readonly ILogger<DefaultService> _logger;
public DefaultService(ILogger<DefaultService> logger) =>
_logger = logger;
// ...
}
}
Als verdere categorisatie gewenst is, is het de conventie om een hiërarchische naam te gebruiken door een subcategorie toe te voegen aan de volledig gekwalificeerde klassenaam en expliciet de categorie op te geven met behulp van LoggerFactory.CreateLogger:
namespace Example
{
public class DefaultService : IService
{
private readonly ILogger _logger;
public DefaultService(ILoggerFactory loggerFactory) =>
_logger = loggerFactory.CreateLogger("Example.DefaultService.CustomCategory");
// ...
}
}
Bellen CreateLogger
met een vaste naam kan handig zijn bij gebruik in meerdere klassen/typen, zodat de gebeurtenissen op categorie kunnen worden georganiseerd.
ILogger<T>
is gelijk aan het aanroepen CreateLogger
met de volledig gekwalificeerde typenaam van T
.
De volgende tabel bevat de LogLevel waarden, de gemaksextensiemethode Log{LogLevel}
en het voorgestelde gebruik:
Logniveau | Weergegeven als | Wijze | Description |
---|---|---|---|
Trace | 0 | LogTrace | De meest gedetailleerde berichten bevatten. Deze berichten kunnen gevoelige app-gegevens bevatten. Deze berichten zijn standaard uitgeschakeld en mogen niet worden ingeschakeld in productie. |
Fouten opsporen | 1 | LogDebug | Voor foutopsporing en ontwikkeling. Wees voorzichtig bij de productie vanwege het grote volume. |
Informatie | 2 | LogInformation | Houdt de algemene stroom van de app bij. Kan een langetermijnwaarde hebben. |
Waarschuwing | 3 | LogWarning | Voor abnormale of onverwachte gebeurtenissen. Bevat meestal fouten of voorwaarden die ervoor zorgen dat de app niet mislukt. |
Fout | 4 | LogError | Voor fouten en uitzonderingen die niet kunnen worden verwerkt. Deze berichten geven een fout aan in de huidige bewerking of aanvraag, niet een fout in de hele app. |
Kritiek | 5 | LogCritical | Voor fouten die onmiddellijk aandacht vereisen. Voorbeelden: scenario's voor gegevensverlies, onvoldoende schijfruimte. |
Geen | 6 | Hiermee geeft u op dat er geen berichten moeten worden geschreven. |
In de vorige tabel wordt de LogLevel
tabel van laag naar hoog weergegeven.
De eerste parameter van de logmethode , LogLevelgeeft de ernst van het logboek aan. In plaats van aan te roepen Log(LogLevel, ...)
, noemen de meeste ontwikkelaars de extensiemethoden Log{LogLevel} . De Log{LogLevel}
extensiemethoden roepen de Log
methode aan en geven de LogLevel
. De volgende twee aanroepen voor logboekregistratie zijn bijvoorbeeld functioneel equivalent en produceren hetzelfde logboek:
public void LogDetails()
{
var logMessage = "Details for log.";
_logger.Log(LogLevel.Information, AppLogEvents.Details, logMessage);
_logger.LogInformation(AppLogEvents.Details, logMessage);
}
AppLogEvents.Details
is de gebeurtenis-id en wordt impliciet vertegenwoordigd door een constante Int32 waarde. AppLogEvents
is een klasse die verschillende benoemde id-constanten weergeeft en wordt weergegeven in de sectie Logboekgebeurtenis-id .
De volgende code maakt Information
en Warning
registreert:
public async Task<T> GetAsync<T>(string id)
{
_logger.LogInformation(AppLogEvents.Read, "Reading value for {Id}", id);
var result = await _repository.GetAsync(id);
if (result is null)
{
_logger.LogWarning(AppLogEvents.ReadNotFound, "GetAsync({Id}) not found", id);
}
return result;
}
In de voorgaande code is de eerste Log{LogLevel}
parameter, AppLogEvents.Read
de gebeurtenis-id van het logboek. De tweede parameter is een berichtsjabloon met tijdelijke aanduidingen voor argumentwaarden die worden geleverd door de resterende methodeparameters. De methodeparameters worden verderop in dit artikel uitgelegd in de sectie berichtsjabloon .
Configureer het juiste logboekniveau en roep de juiste Log{LogLevel}
methoden aan om te bepalen hoeveel logboekuitvoer naar een bepaald opslagmedium wordt geschreven. Voorbeeld:
Trace
niveaus Debug
produceert een groot aantal gedetailleerde logboekberichten. Als u de kosten wilt beheren en niet de limieten voor gegevensopslag wilt overschrijden, kunt u berichten vastleggen Trace
en Debug
e-mail op een hoog volume, laaggeprijsd gegevensarchief. Overweeg het beperken Trace
van en Debug
tot specifieke categorieën.Warning
Critical
niveaus moet enkele logboekberichten opleveren.
Warning
.Debug
berichten bij Trace
het oplossen van problemen. Als u de uitvoer wilt beperken, stelt u deze in Trace
of Debug
alleen voor de categorieën die worden onderzocht.De volgende JSON-sets Logging:Console:LogLevel:Microsoft:Information
:
{
"Logging": {
"LogLevel": {
"Microsoft": "Warning"
},
"Console": {
"LogLevel": {
"Microsoft": "Information"
}
}
}
}
Elk logboek kan een gebeurtenis-id opgeven, het EventId is een structuur met een Id
en optionele Name
leeseigenschappen. De voorbeeldbroncode gebruikt de AppLogEvents
klasse om gebeurtenis-id's te definiëren:
using Microsoft.Extensions.Logging;
internal static class AppLogEvents
{
internal static EventId Create = new(1000, "Created");
internal static EventId Read = new(1001, "Read");
internal static EventId Update = new(1002, "Updated");
internal static EventId Delete = new(1003, "Deleted");
// These are also valid EventId instances, as there's
// an implicit conversion from int to an EventId
internal const int Details = 3000;
internal const int Error = 3001;
internal static EventId ReadNotFound = 4000;
internal static EventId UpdateNotFound = 4001;
// ...
}
Een gebeurtenis-id koppelt een set gebeurtenissen. Alle logboeken met betrekking tot het lezen van waarden uit een opslagplaats kunnen bijvoorbeeld zijn 1001
.
De logboekregistratieprovider kan de gebeurtenis-id registreren in een id-veld, in het logboekbericht of helemaal niet. De foutopsporingsprovider toont geen gebeurtenis-id's. De consoleprovider toont gebeurtenis-id's tussen vierkante haken na de categorie:
info: Example.DefaultService.GetAsync[1001]
Reading value for a1b2c3
warn: Example.DefaultService.GetAsync[4000]
GetAsync(a1b2c3) not found
Sommige logboekproviders slaan de gebeurtenis-id op in een veld, waardoor de id kan worden gefilterd.
Elke logboek-API maakt gebruik van een berichtsjabloon. De berichtsjabloon kan tijdelijke aanduidingen bevatten waarvoor argumenten worden opgegeven. Gebruik namen voor de tijdelijke aanduidingen, niet voor getallen. De volgorde van tijdelijke aanduidingen, niet hun namen, bepaalt welke parameters worden gebruikt om hun waarden op te geven. In de volgende code zijn de parameternamen niet op volgorde in de berichtsjabloon:
string p1 = "param1";
string p2 = "param2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);
Met de voorgaande code wordt een logboekbericht gemaakt met de parameterwaarden in volgorde:
Parameter values: param1, param2
Notitie
Houd rekening met het gebruik van meerdere tijdelijke aanduidingen binnen één berichtsjabloon, omdat deze zijn gebaseerd op rangschikken. De namen worden niet gebruikt om de argumenten uit te lijnen op de tijdelijke aanduidingen.
Met deze aanpak kunnen logboekproviders semantische of gestructureerde logboekregistratie implementeren. De argumenten zelf worden doorgegeven aan het logboekregistratiesysteem, niet alleen de opgemaakte berichtsjabloon. Hierdoor kunnen logboekproviders de parameterwaarden opslaan als velden. Houd rekening met de volgende loggermethode:
_logger.LogInformation("Getting item {Id} at {RunTime}", id, DateTime.Now);
Bijvoorbeeld wanneer u zich aanmeldt bij Azure Table Storage:
RunTime
eigenschappen hebbenID
.RunTime
bereik vinden zonder de time-out van het tekstbericht te hoeven parseren.Logboekberichtsjablonen ondersteunen de opmaak van tijdelijke aanduidingen. Sjablonen kunnen elke geldige indeling voor het opgegeven typeargument opgeven. Denk bijvoorbeeld aan de volgende Information
sjabloon voor logboekberichten:
_logger.LogInformation("Logged on {PlaceHolderName:MMMM dd, yyyy}", DateTimeOffset.UtcNow);
// Logged on January 06, 2022
In het voorgaande voorbeeld is het DateTimeOffset
exemplaar het type dat overeenkomt met de PlaceHolderName
sjabloon voor het logboekbericht. Deze naam kan alles zijn, omdat de waarden ordinaal zijn. De MMMM dd, yyyy
notatie is geldig voor het DateTimeOffset
type.
Zie Tekenreeksen voor aangepaste datum- en tijdnotatie voor meer informatie DateTime
over en DateTimeOffset
opmaak.
In de volgende voorbeelden ziet u hoe u een berichtsjabloon opmaken met behulp van de syntaxis van de {}
tijdelijke aanduiding. Daarnaast wordt een voorbeeld van het ontsnappen van de syntaxis van de {}
tijdelijke aanduiding weergegeven met de uitvoer. Ten slotte wordt tekenreeksinterpolatie met tijdelijke aanduidingen voor tijdelijke aanduidingen ook weergegeven:
logger.LogInformation("Number: {Number}", 1); // Number: 1
logger.LogInformation("{{Number}}: {Number}", 3); // {Number}: 3
logger.LogInformation($"{{{{Number}}}}: {{Number}}", 5); // {Number}: 5
Tip
De logboekregistratiemethoden hebben overbelastingen die een uitzonderingsparameter gebruiken:
public void Test(string id)
{
try
{
if (id is "none")
{
throw new Exception("Default Id detected.");
}
}
catch (Exception ex)
{
_logger.LogWarning(
AppLogEvents.Error, ex,
"Failed to process iteration: {Id}", id);
}
}
Uitzonderingslogboekregistratie is providerspecifiek.
Als het standaardlogboekniveau niet is ingesteld, is Information
de standaardwaarde voor het logboekniveau .
Denk bijvoorbeeld aan de volgende werkservice-app:
Met de voorgaande installatie produceert het navigeren naar de privacy- of startpagina veel Trace
, Debug
en Information
berichten met Microsoft
de categorienaam.
Met de volgende code wordt het standaardlogboekniveau ingesteld wanneer het standaardlogboekniveau niet is ingesteld in de configuratie:
HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Logging.SetMinimumLevel(LogLevel.Warning);
using IHost host = builder.Build();
await host.RunAsync();
Er wordt een filterfunctie aangeroepen voor alle providers en categorieën waaraan geen regels zijn toegewezen door configuratie of code:
HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Logging.AddFilter((provider, category, logLevel) =>
{
return provider.Contains("ConsoleLoggerProvider")
&& (category.Contains("Example") || category.Contains("Microsoft"))
&& logLevel >= LogLevel.Information;
});
using IHost host = builder.Build();
await host.RunAsync();
In de voorgaande code worden consolelogboeken weergegeven wanneer de categorie het logboekniveau bevat Example
of Microsoft
hoger is Information
.
Een bereik groept een set logische bewerkingen. Deze groepering kan worden gebruikt om dezelfde gegevens toe te voegen aan elk logboek dat is gemaakt als onderdeel van een set. Elk logboek dat is gemaakt als onderdeel van het verwerken van een transactie, kan bijvoorbeeld de transactie-id bevatten.
Een bereik:
De volgende providers ondersteunen bereiken:
Gebruik een bereik door logboekoproepen in een using
blok te verpakken:
public async Task<T> GetAsync<T>(string id)
{
T result;
var transactionId = Guid.NewGuid().ToString();
using (_logger.BeginScope(new List<KeyValuePair<string, object>>
{
new KeyValuePair<string, object>("TransactionId", transactionId),
}))
{
_logger.LogInformation(
AppLogEvents.Read, "Reading value for {Id}", id);
var result = await _repository.GetAsync(id);
if (result is null)
{
_logger.LogWarning(
AppLogEvents.ReadNotFound, "GetAsync({Id}) not found", id);
}
}
return result;
}
Met de volgende JSON worden bereiken voor de consoleprovider ingeschakeld:
{
"Logging": {
"Debug": {
"LogLevel": {
"Default": "Information"
}
},
"Console": {
"IncludeScopes": true,
"LogLevel": {
"Microsoft": "Warning",
"Default": "Information"
}
},
"LogLevel": {
"Default": "Debug"
}
}
}
Met de volgende code worden bereiken voor de consoleprovider ingeschakeld:
HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Logging.ClearProviders();
builder.Logging.AddConsole(options => options.IncludeScopes = true);
using IHost host = builder.Build();
await host.RunAsync();
De volgende code meldt zich aan Main
door een ILogger
exemplaar van DI op te halen na het bouwen van de host:
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using IHost host = Host.CreateApplicationBuilder(args).Build();
var logger = host.Services.GetRequiredService<ILogger<Program>>();
logger.LogInformation("Host created.");
await host.RunAsync();
De voorgaande code is afhankelijk van twee NuGet-pakketten:
Het projectbestand ziet er ongeveer als volgt uit:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net7.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.Hosting" Version="7.0.1" />
<PackageReference Include="Microsoft.Extensions.Logging" Version="7.0.0" />
</ItemGroup>
</Project>
Logboekregistratie moet zo snel zijn dat het de prestatiekosten van asynchrone code niet waard is. Als een gegevensarchief voor logboekregistratie traag is, moet u er niet rechtstreeks naar schrijven. U kunt de logboekberichten in eerste instantie naar een snelle opslag schrijven en deze later verplaatsen naar het trage archief. Als u zich bijvoorbeeld aanmeldt bij SQL Server, doet u dit niet rechtstreeks in een Log
methode, omdat de Log
methoden synchroon zijn. Voeg in plaats daarvan synchroon logboekberichten toe aan een wachtrij in het geheugen en laat een achtergrondmedewerker de berichten uit de wachtrij halen om het asynchrone werk van het pushen van gegevens naar SQL Server uit te voeren.
De Logboekregistratie-API bevat geen scenario om logboekniveaus te wijzigen terwijl een app wordt uitgevoerd. Sommige configuratieproviders kunnen de configuratie echter opnieuw laden, wat direct van kracht wordt op de configuratie van logboekregistratie. De configuratie van de bestandsconfiguratieprovider laadt bijvoorbeeld standaard de configuratie van logboekregistratie opnieuw. Als de configuratie in code wordt gewijzigd terwijl een app wordt uitgevoerd, kan de app IConfigurationRoot.Reload aanroepen om de logboekregistratieconfiguratie van de app bij te werken.
ILoggerFactory De ILogger<TCategoryName> interfaces en implementaties zijn opgenomen in de meeste .NET SDK's als impliciete pakketreferentie. Ze zijn ook expliciet beschikbaar in de volgende NuGet-pakketten wanneer anders impliciet wordt verwezen:
Zie .NET SDK: tabel naar impliciete naamruimte voor meer informatie over welke .NET SDK impliciete pakketverwijzingen bevat.
.NET-feedback
.NET is een open source project. Selecteer een koppeling om feedback te geven:
Training
Module
Alfanumerieke gegevens opmaken voor weergave in C# - Training
Verken basismethoden in C# om alfanumerieke gegevens op te maken.