Provider di registrazione in .NET

  • Articolo

I provider di registrazione salvano in modo permanente i log, ad eccezione del provider Console, che visualizza solo i log come output standard. Ad esempio, il provider Azure Application Insights archivia i log in Azure Application Insights. È possibile abilitare più provider.

Modelli di app ruolo di lavoro .NET predefiniti:

using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Application code should start here.

await host.RunAsync();

Il codice precedente mostra la classe Program creata con i modelli di app ruolo di lavoro.NET. Le sezioni successive forniscono esempi basati sui modelli di app ruolo di lavoro .NET, che usano l'host generico.

Pe sostituire il set predefinito di provider di registrazione aggiunti da Host.CreateApplicationBuilder, chiamare ClearProviders e aggiungere i provider di registrazione desiderati. Ad esempio, il seguente codice:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.ClearProviders();
builder.Logging.AddConsole();

Per altri provider, vedere:

Configurare un servizio che dipende da ILogger

Per configurare un servizio che dipende da ILogger<T>, usare l'inserimento del costruttore o fornire un metodo factory. L'approccio con il metodo factory è consigliato solo se non sono disponibili altre opzioni. Si consideri ad esempio un servizio che necessita di un'istanza ILogger<T> fornita dall'inserimento delle dipendenze:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSingleton<IExampleService>(
    container => new DefaultExampleService
    {
        Logger = container.GetRequiredService<ILogger<IExampleService>>()
    });

Il codice precedente è un Func<IServiceProvider, IExampleService> che viene eseguito la prima volta che il contenitore di inserimento delle dipendenze deve costruire un'istanza di IExampleService. È possibile accedere a uno dei servizi registrati in questo modo.

Provider di registrazione predefiniti

Le estensioni Microsoft includono i provider di registrazione seguenti come parte delle librerie di runtime:

I provider di registrazione seguenti vengono forniti da Microsoft, ma non come parte delle librerie di runtime. Devono essere installati come pacchetti NuGet aggiuntivi.

Console

Il provider Console registra l'output nella console.

Debug

Il provider Debug scrive l'output del log usando la classe System.Diagnostics.Debug, in particolare tramite il metodo Debug.WriteLine e solo quando il debugger è collegato. DebugLoggerProvider crea istanze di DebugLogger, ovvero implementazioni dell'interfaccia ILogger.

Origine evento

Il provider EventSource scrive in un'origine evento multipiattaforma con il nome Microsoft-Extensions-Logging. In Windows il provider usa ETW.

Strumento dotnet trace

Lo strumento dotnet-trace è uno strumento globale dell'interfaccia della riga di comando multipiattaforma che consente la raccolta di tracce di .NET Core di un processo in esecuzione. Lo strumento raccoglie i dati del provider Microsoft.Extensions.Logging.EventSource usando un LoggingEventSource.

Per istruzioni di installazione, vedere dotnet-trace. Per un'esercitazione diagnostica con dotnet-trace, vedere Eseguire il debug di un utilizzo elevato della CPU in .NET Core.

Registro eventi di Windows

Il provider EventLog invia l'output di log al Registro eventi di Windows. A differenza degli altri provider, il provider EventLognon eredita le impostazioni predefinite non specifiche del provider. Se non si specificano le impostazioni di log EventLog, l'impostazione predefinita è LogLevel.Warning.

Per registrare eventi di livello inferiore a LogLevel.Warning, impostare in modo esplicito il livello di log. L'esempio seguente imposta il livello di log predefinito del registro eventi su LogLevel.Information:

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

Gli overload AddEventLog possono passare EventLogSettings. Se null o non specificato, vengono usate le impostazioni predefinite seguenti:

  • LogName: "Application"
  • SourceName: ".NET Runtime"
  • MachineName: viene usato il nome del computer locale.

Il codice seguente modifica SourceName dal valore predefinito ".NET Runtime" a CustomLogs:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.AddEventLog(
    config => config.SourceName = "CustomLogs");

using IHost host = builder.Build();

host.Run();

Servizio app di Azure

Il pacchetto di provider Microsoft.Extensions.Logging.AzureAppServices scrive i log in file di testo nel file system di un'app del Servizio app di Azure e nell'archivio di BLOB in un account di archiviazione di Azure.

Il pacchetto del provider non è incluso nelle librerie di runtime. Per usare il provider, aggiungere il relativo pacchetto al progetto.

Per configurare le impostazioni del provider, usare AzureFileLoggerOptions e AzureBlobLoggerOptions, come illustrato nell'esempio seguente:

using Microsoft.Extensions.Logging.AzureAppServices;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args)

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

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Se distribuita in Servizio app di Azure, l'app usa le impostazioni nella sezione Log del servizio app della pagina Servizio app del portale di Azure. Quando le impostazioni seguenti vengono aggiornate, le modifiche hanno effetto immediatamente senza richiedere un riavvio o la ridistribuzione dell'app.

Il percorso predefinito per i file di log si trova nella cartella D:\home\LogFiles\Application. Le impostazioni predefinite aggiuntive variano in base al provider:

  • Registrazione applicazioni (file system): il nome del file system predefinito è diagnostics-aaaammgg.txt. Il limite predefinito per le dimensioni del file è 10 MB e il numero massimo predefinito di file conservati è 2.
  • Registrazione applicazioni (BLOB): il nome del BLOB predefinito è {app-name}/aaaa/mm/gg/hh/{guid}_applicationLog.txt.

Questo provider registra solo quando viene eseguito il progetto nell'ambiente di Azure.

Flusso di registrazione di Azure

Lo streaming di log di Azure supporta la visualizzazione dell'attività di registrazione in tempo reale da:

  • Server applicazioni
  • Server Web
  • Traccia delle richieste non riuscite

Per configurare il flusso di registrazione di Azure:

  • Passare alla pagina Log del servizio app dalla pagina del portale dell'app.
  • Impostare Registrazione applicazioni (file system) su Attiva.
  • Scegliere il livello di registrazione in Livello. Questa impostazione si applica solo al flusso di registrazione di Azure.

Passare alla pagina Flusso di registrazione per visualizzare i log. I messaggi registrati vengono registrati con l'interfaccia ILogger.

Azure Application Insights

Il pacchetto di provider Microsoft.Extensions.Logging.ApplicationInsights scrive log in Azure Application Insights. Application Insights è un servizio che monitora un'app Web e fornisce gli strumenti per l'esecuzione di query sui dati di telemetria e la loro analisi. Se si usa questo provider, è possibile eseguire query sui log e analizzarli usando gli strumenti di Application Insights.

Per ulteriori informazioni, vedi le seguenti risorse:

Considerazioni sulla progettazione del provider di registrazione

Se si prevede di sviluppare una propria implementazione dell'interfaccia ILoggerProvider e un'implementazione personalizzata corrispondente di ILogger, tenere presenti i punti seguenti:

  • Il metodo ILogger.Log è sincrono.
  • È necessario non presupporre la durata dello stato del log e degli oggetti.

Un'implementazione di ILoggerProvider creerà un ILogger tramite il relativo metodo ILoggerProvider.CreateLogger. Se l'implementazione cerca di accodare i messaggi di registrazione in modo non bloccante, i messaggi devono prima di tutto essere materializzati o lo stato dell'oggetto usato per materializzare una voce di log deve essere serializzato. In questo modo si evitano potenziali eccezioni da oggetti eliminati.

Per altre informazioni, vedere Implementare un provider di registrazione personalizzato in .NET.

Provider di registrazione di terze parti

Ecco alcuni framework di registrazione di terze parti che funzionano con vari carichi di lavoro .NET:

Alcuni framework di terze parti possono eseguire la registrazione semantica, nota anche come registrazione strutturata.

L'uso di un framework di terze parti è simile a quello di uno dei provider predefiniti:

  1. Aggiungere un pacchetto NuGet al progetto.
  2. Chiamare un metodo di estensione ILoggerFactory o ILoggingBuilder fornito dal framework di registrazione.

Per altre informazioni, vedere la documentazione di ogni provider. I provider di registrazione di terze parti non sono supportati da Microsoft.

Vedi anche